Skip to content

0004-mcp.md

Latest commit

 

History

History
423 lines (330 loc) · 9.66 KB

0004-mcp.md

File metadata and controls

423 lines (330 loc) · 9.66 KB
Raw

MCP (Model Context Protocol) API Reference

powermem provides an MCP server that exposes memory management capabilities as standardized tools and resources, enabling AI assistants and agents to interact with powermem's memory system through a unified interface.

What is MCP?

Model Context Protocol (MCP) is an open standard protocol that enables AI applications to securely access external tools, data sources, and services. The powermem MCP server allows AI assistants (like Claude Desktop, Cursor, Chatbox, etc.) to interact with powermem's memory system through a standardized interface.

Installation

The MCP server is included with powermem. No additional installation is required.

pip install powermem

Running the Server

As a Python Module (Recommended)

python -m powermem.mcp

With Configuration File

python -m powermem.mcp --config config.json

With Environment File

python -m powermem.mcp --env .env

Direct Python Script

python src/powermem/mcp/server.py

Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "powermem": {
      "command": "python",
      "args": [
        "-m",
        "powermem.mcp"
      ],
      "env": {
        "LLM_PROVIDER": "qwen",
        "LLM_API_KEY": "your_api_key",
        "LLM_MODEL": "qwen-plus",
        "EMBEDDING_PROVIDER": "qwen",
        "EMBEDDING_API_KEY": "your_api_key",
        "EMBEDDING_MODEL": "text-embedding-v4",
        "DATABASE_PROVIDER": "sqlite"
      }
    }
  }
}

Cursor / VS Code

Add to your MCP client configuration:

{
  "mcpServers": {
    "powermem": {
      "command": "python",
      "args": [
        "-m",
        "powermem.mcp"
      ],
      "env": {
        "DATABASE_PROVIDER": "sqlite",
        "LLM_PROVIDER": "openai",
        "LLM_API_KEY": "sk-...",
        "EMBEDDING_PROVIDER": "openai",
        "EMBEDDING_API_KEY": "sk-..."
      }
    }
  }
}

Using Configuration File

{
  "mcpServers": {
    "powermem": {
      "command": "python",
      "args": [
        "-m",
        "powermem.mcp",
        "--config",
        "/path/to/config.json"
      ]
    }
  }
}

Available Tools

The powermem MCP server provides the following tools:

add_memory

Add a new memory to the store. Supports text, message dict, or list of messages.

Parameters:

  • messages (str | dict | list): Memory content. Can be:
    • A string
    • A single message dict with role and content
    • A list of message dicts in OpenAI format
  • user_id (str, optional): User identifier (auto-generated if not provided)
  • agent_id (str, optional): Agent identifier for multi-agent scenarios
  • run_id (str, optional): Run/conversation identifier
  • metadata (dict, optional): Additional metadata dictionary
  • scope (str, optional): Memory scope (e.g., 'user', 'agent', 'session')
  • memory_type (str, optional): Memory type classification
  • filters (dict, optional): Filter metadata for advanced filtering

Example:

{
  "name": "add_memory",
  "arguments": {
    "messages": "User prefers coffee in the morning",
    "user_id": "user123",
    "metadata": {
      "category": "preference",
      "priority": "high"
    }
  }
}

search_memories

Search for memories using semantic similarity and keyword matching.

Parameters:

  • query (str, required): The search query text
  • user_id (str, optional): User identifier to filter memories
  • agent_id (str, optional): Agent identifier to filter memories
  • run_id (str, optional): Run/thread identifier to filter memories
  • limit (int, optional): Maximum number of results (default: 10)
  • filters (dict, optional): Metadata filters for advanced search
  • threshold (float, optional): Similarity threshold (0.0-1.0) for filtering results

Example:

{
  "name": "search_memories",
  "arguments": {
    "query": "user preferences",
    "user_id": "user123",
    "limit": 5,
    "threshold": 0.7
  }
}

get_memory

Retrieve a specific memory by its ID.

Parameters:

  • memory_id (int, required): The unique identifier of the memory
  • user_id (str, optional): User identifier for permission check
  • agent_id (str, optional): Agent identifier for permission check

Example:

{
  "name": "get_memory",
  "arguments": {
    "memory_id": 123,
    "user_id": "user123"
  }
}

update_memory

Update an existing memory's content and/or metadata.

Parameters:

  • memory_id (int, required): The unique identifier of the memory
  • content (str, required): The new content for the memory
  • user_id (str, optional): User identifier for permission check
  • agent_id (str, optional): Agent identifier for permission check
  • metadata (dict, optional): Metadata dictionary to update

Example:

{
  "name": "update_memory",
  "arguments": {
    "memory_id": 123,
    "content": "Updated memory content",
    "metadata": {
      "updated_at": "2024-01-01"
    }
  }
}

delete_memory

Delete a memory by its ID.

Parameters:

  • memory_id (int, required): The unique identifier of the memory
  • user_id (str, optional): User identifier for permission check
  • agent_id (str, optional): Agent identifier for permission check

Example:

{
  "name": "delete_memory",
  "arguments": {
    "memory_id": 123,
    "user_id": "user123"
  }
}

delete_all_memories

Delete all memories for a user and/or agent.

Parameters:

  • user_id (str, optional): User identifier to filter memories for deletion
  • agent_id (str, optional): Agent identifier to filter memories for deletion
  • run_id (str, optional): Run/thread identifier to filter memories for deletion

Example:

{
  "name": "delete_all_memories",
  "arguments": {
    "user_id": "user123"
  }
}

list_memories

List all memories with optional filters.

Parameters:

  • user_id (str, optional): User identifier to filter memories
  • agent_id (str, optional): Agent identifier to filter memories
  • run_id (str, optional): Run/thread identifier to filter memories
  • limit (int, optional): Maximum number of results (default: 100)
  • offset (int, optional): Offset for pagination (default: 0)
  • filters (dict, optional): Metadata filters for advanced filtering

Example:

{
  "name": "list_memories",
  "arguments": {
    "user_id": "user123",
    "limit": 50,
    "offset": 0
  }
}

Available Resources

powermem://memory

Access to the powermem memory store as a resource. Provides summary information about the memory store.

URI: powermem://memory

MIME Type: application/json

User ID Handling

The MCP server automatically handles user_id:

  • If provided: Uses the user_id from tool arguments
  • If not provided: Automatically retrieves or generates a default user_id
    1. First tries to get from ~/.powermem/config.json (via get_user_id())
    2. Falls back to "mcp_user" if config doesn't exist

This ensures all memories are properly associated with a user_id even when the client doesn't explicitly provide one.

Protocol Details

The server implements the MCP protocol over STDIO using JSON-RPC 2.0:

  • Protocol Version: 2024-11-05
  • Communication: STDIN/STDOUT (JSON-RPC 2.0)
  • Logging: STDERR

Configuration

The server uses powermem's standard configuration system. It will:

  1. Load configuration from the provided config file (if --config is used)
  2. Load configuration from .env file (if --env is used)
  3. Automatically load from .env in the current directory
  4. Fall back to default/mock providers if no configuration is found

See Configuration for configuration details.

Usage Examples

Adding a Memory via MCP

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_memory",
    "arguments": {
      "messages": "User prefers coffee in the morning",
      "user_id": "user123",
      "metadata": {
        "category": "preference",
        "priority": "high"
      }
    }
  }
}

Searching Memories via MCP

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_memories",
    "arguments": {
      "query": "user preferences",
      "user_id": "user123",
      "limit": 5
    }
  }
}

Getting a Memory via MCP

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_memory",
    "arguments": {
      "memory_id": 123
    }
  }
}

Troubleshooting

Server Not Starting

  • Ensure powermem is properly installed: pip install powermem or pip install -e .
  • Check that configuration is valid
  • Review STDERR for error messages

Tools Not Available

  • Verify the server initialized successfully
  • Check that the memory instance was created
  • Review logs for initialization errors

Connection Issues

  • Ensure STDIO communication is working
  • Check that JSON-RPC messages are properly formatted
  • Verify the client is configured correctly

User ID Issues

  • Check if ~/.powermem/config.json exists (auto-created on first run)
  • Verify user_id is consistent across tool calls (should be automatic)
  • If you need a specific user_id, you can pass it explicitly in tool arguments

Testing the Server

You can test the server manually using JSON-RPC requests:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | python -m powermem.mcp

Logging

The server logs to STDERR, so you can redirect logs:

python -m powermem.mcp 2> mcp.log