Skip to content

mcp.md

Latest commit

 

History

History
147 lines (118 loc) · 5.16 KB

mcp.md

File metadata and controls

147 lines (118 loc) · 5.16 KB

MCP Server Interface

Agent Memory Server offers an MCP (Model Context Protocol) server interface powered by FastMCP, providing tool-based memory management for LLMs and agents:

  • set_working_memory: Set working memory for a session (like PUT /v1/working-memory/{session_id} in the REST API). Stores structured memory records and JSON data in working memory with automatic promotion to long-term storage.
  • create_long_term_memories: Create long-term memories directly, bypassing working memory. Useful for bulk memory creation.
  • search_long_term_memory: Search across long-term memories using semantic, keyword, or hybrid search modes with advanced filtering options.
  • edit_long_term_memory: Update existing long-term memories with new or corrected information. Allows partial updates to specific fields while preserving other data.
  • delete_long_term_memories: Remove specific long-term memories by ID. Useful for cleaning up outdated or incorrect information.
  • get_long_term_memory: Retrieve specific memories by ID for detailed inspection or verification before editing.
  • memory_prompt: Generate prompts enriched with working memory session and long-term memories. Essential for retrieving relevant context before answering questions.

Available MCP Tools

The MCP server provides the following tools that AI agents can use to manage memories:

Memory Search and Retrieval

search_long_term_memory

  • Search for memories using semantic (vector), keyword (full-text), or hybrid (combined) search
  • Supports advanced filtering by user, session, namespace, topics, entities, and timestamps
  • Configurable query optimization and recency boost
  • Returns ranked results with relevance scores

get_long_term_memory

  • Retrieve specific memories by their unique ID
  • Useful for inspecting memory details before editing
  • Returns complete memory record with all metadata

memory_prompt

  • Generate AI prompts enriched with relevant memory context
  • Combines working memory and long-term memory search results
  • Essential for providing context to AI agents before responses

Memory Management

create_long_term_memories

  • Create new persistent memories directly
  • Bypasses working memory for bulk operations
  • Supports all memory types (semantic, episodic, message)
  • Automatic indexing and embedding generation

edit_long_term_memory

  • Update existing memories with corrections or new information
  • Supports partial updates (only change specific fields)
  • Automatic re-indexing and embedding regeneration
  • Preserves memory ID and creation timestamp

delete_long_term_memories

  • Remove specific memories by ID
  • Supports batch deletion of multiple memories
  • Useful for cleanup and data management

Working Memory

set_working_memory

  • Manage session-specific conversation state
  • Store messages, structured memories, and arbitrary data
  • Automatic promotion of memories to long-term storage
  • TTL-based expiration for session cleanup

Using the MCP Server with Claude Desktop, Cursor, etc.

You can use the MCP server that comes with this project in any application or SDK that supports MCP tools.

Claude

For Claude, the easiest way is to use uvx (recommended):

{
  "mcpServers": {
    "memory": {
      "command": "uvx",
      "args": ["--from", "agent-memory-server", "agent-memory", "mcp"],
      "env": {
        "DISABLE_AUTH": "true",
        "REDIS_URL": "redis://localhost:6379",
        "OPENAI_API_KEY": "<your-openai-key>"
      }
    }
  }
}

Notes:

  • API keys: Default models use OpenAI. Set OPENAI_API_KEY. To use Anthropic instead, set ANTHROPIC_API_KEY and also GENERATION_MODEL to an Anthropic model (e.g., claude-3-5-haiku-20241022).
  • Make sure your MCP host can find uvx (on its PATH or by using an absolute command path).
    • macOS: brew install uv
    • If not on PATH, set "command" to an absolute path (e.g., /opt/homebrew/bin/uvx on Apple Silicon, /usr/local/bin/uvx on Intel macOS). On Linux, ~/.local/bin/uvx is common. See https://docs.astral.sh/uv/getting-started/ for distro specifics
  • Set DISABLE_AUTH=false in production and configure proper auth per the Authentication guide.

If you’re running from a local checkout instead of PyPI, you can use uv run with a directory:

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/REPO/DIRECTORY/agent-memory-server",
        "run",
        "agent-memory",
        "mcp"
      ]
    }
  }
}

Alternative (Anthropic):

{
  "mcpServers": {
    "memory": {
      "command": "uvx",
      "args": ["--from", "agent-memory-server", "agent-memory", "mcp"],
      "env": {
        "DISABLE_AUTH": "true",
        "REDIS_URL": "redis://localhost:6379",
        "ANTHROPIC_API_KEY": "<your-anthropic-key>",
        "GENERATION_MODEL": "claude-3-5-haiku-20241022"
      }
    }
  }
}

Cursor

Cursor's MCP config is similar to Claude's, but it also supports SSE servers, so you can run the server in SSE mode and pass in the URL:

{
  "mcpServers": {
    "redis-memory-server": {
      "url": "http://localhost:9050/sse"
    }
  }
}