Frinus MCP Server

MCP (Model Context Protocol) server that exposes the Agents Memory Service to Claude agents. This server provides 14 tools for memory management, knowledge graph operations, working memory, stream capture, and user authentication.

Overview

The MCP Memory Server acts as a bridge between Claude agents and the Memory Service REST API. It enables agents to:

• Store and retrieve memories (episodic, semantic, procedural)
• Search memories using semantic similarity
• Manage working memory for session context
• Capture interactions to the memory stream for learning
• Register agents and projects in the knowledge graph

Requirements

• Node.js 18+
• Memory Service running at http://localhost:8001 (configurable via MEMORY_SERVICE_URL)

Installation

npm install
npm run build

Usage

Running the Server

# Development mode
npm run dev

# Production mode
npm run build
npm start

Environment Variables

Claude Desktop Configuration

Add to your Claude Desktop config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "frinus": {
      "command": "node",
      "args": ["/path/to/mcp/dist/index.js"],
      "env": {
        "MEMORY_SERVICE_URL": "http://localhost:8001",
        "FRINUS_API_KEY": "sk-mem-your-key-here"
      }
    }
  }
}

Tools Reference

Memory Tools

1. memory_store

Store a memory in the memory service.

Parameters:

Memory Types:

• episodic: Specific experiences and events (what happened)
• semantic: General knowledge and facts (what I know)
• procedural: How to do things (step-by-step procedures)

Example:

{
  "agent_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "content": "To deploy the service, run 'kubectl apply -f deployment.yaml' in the k8s directory",
  "memory_type": "procedural",
  "scope": "project",
  "importance": 0.8,
  "project_id": "44444444-4444-4444-4444-444444444444"
}

2. memory_search

Search memories by semantic similarity.

Parameters:

Example:

{
  "query": "how to deploy kubernetes",
  "project_id": "44444444-4444-4444-4444-444444444444",
  "memory_types": ["procedural"],
  "limit": 5
}

3. memory_get_context

Get relevant context for a task. Use this at the start of a task to retrieve memories that can help.

Parameters:

Example:

{
  "agent_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "task_description": "Update the payment API documentation",
  "project_id": "44444444-4444-4444-4444-444444444444",
  "max_tokens": 3000
}

4. memory_list

List memories for an agent, optionally filtered by type.

Parameters:

Example:

{
  "agent_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "memory_type": "semantic",
  "limit": 20
}

Graph Tools

5. graph_register_agent

Register an agent in the knowledge graph.

Parameters:

Example:

{
  "agent_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "name": "Documentation Specialist",
  "agent_type": "documentation"
}

6. graph_register_project

Register a project in the knowledge graph.

Parameters:

Example:

{
  "project_id": "44444444-4444-4444-4444-444444444444",
  "name": "CenterPag Payment Platform"
}

7. graph_assign_agent_project

Assign an agent to a project with a role.

Parameters:

Example:

{
  "agent_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "project_id": "44444444-4444-4444-4444-444444444444",
  "role": "executor"
}

Working Memory Tools

Working memory provides short-term context persistence during sessions. It follows Miller's Law (7 items max) and auto-evicts older items.

8. working_memory_get

Get working memory for a context. CRITICAL: Always call this at the START of any task.

Parameters:

Context ID Formats:

• agent:{uuid} - Agent's working memory
• project:{uuid} - Project's working memory
• skill:{uuid} - Skill's working memory

Example:

{
  "context_id": "agent:ffffffff-ffff-ffff-ffff-ffffffffffff"
}

9. working_memory_add

Add or update working memory for a context.

Parameters:

Example:

{
  "context_id": "agent:ffffffff-ffff-ffff-ffff-ffffffffffff",
  "content": "Currently updating MCP server documentation. Completed: README overview, Tools 1-7. Next: Working memory and stream tools.",
  "agent_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "project_id": "44444444-4444-4444-4444-444444444444",
  "ttl_seconds": 3600
}

10. working_memory_clear

Clear all working memory for a context. Use with caution.

Parameters:

Example:

{
  "context_id": "agent:ffffffff-ffff-ffff-ffff-ffffffffffff"
}

Stream Tools

The memory stream captures all interactions for continuous learning. Important items are periodically promoted to long-term memory.

11. stream_capture

Capture interaction to memory stream for learning.

Parameters:

Directions:

• input: User/external input
• output: Agent response/action
• internal: Internal thought/decision

Example:

{
  "session_id": "doc-session-20260129",
  "content": "Created comprehensive MCP server documentation with all 12 tools",
  "direction": "output",
  "agent_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "importance": 0.8
}

12. stream_stats

Get memory stream statistics.

Parameters: None

Response includes:

• total: Total items in stream
• unprocessed: Items pending processing
• consolidated: Items promoted to long-term memory
• forgotten: Items discarded
• avg_importance: Average importance score

Example:

{}

User Authentication Tools

13. user_login

Login/identify user for personalized memories.

Parameters:

Example:

{
  "email": "igor.tavares@monetizze.com.br",
  "username": "igor"
}

Response:

Logged in as igor.tavares@monetizze.com.br. Found 3 personal memories.

14. user_get_context

Get combined user + project context.

Parameters:

Example:

{
  "project_id": "44444444-4444-4444-4444-444444444444"
}

Response includes:

• User memories (scope: user)
• Project memories (scope: project)
• Combined context

Architecture

+------------------+       +-------------------+       +------------------+
|   Claude Agent   | <---> |  MCP Memory       | <---> |  Memory Service  |
|   (via MCP)      |       |  Server (stdio)   |       |  (REST API)      |
+------------------+       +-------------------+       +------------------+
                                                              |
                                    +-------------------------+
                                    |                         |
                            +-------v------+          +-------v------+
                            | PostgreSQL   |          |    Neo4j     |
                            | + pgvector   |          | (Knowledge   |
                            | (Memories)   |          |  Graph)      |
                            +--------------+          +--------------+

Development

Project Structure

mcp/
  src/
    index.ts        # Main server with all tool definitions
  dist/             # Compiled JavaScript
  package.json
  tsconfig.json

Building

npm run build

Type Checking

The project uses TypeScript 5.6+ with ES modules.

Memory Types Explained

Scope Levels

Best Practices

1. Always read working memory first: Call working_memory_get at the start of every task
2. Update working memory when done: Save progress with working_memory_add
3. Capture important interactions: Use stream_capture for learnings
4. Use appropriate memory types: Match content to episodic/semantic/procedural
5. Set importance scores: Higher scores (0.7+) for critical information

License

MIT