Skip to content

MCP_SERVER_SETUP.md

Latest commit

 

History

History
269 lines (209 loc) · 5.88 KB

MCP_SERVER_SETUP.md

File metadata and controls

269 lines (209 loc) · 5.88 KB
Raw

MCP Server Setup for A-MEM

📋 Overview

The A-MEM MCP Server provides tools for the Agentic Memory System.

🛠️ Available Tools (15 Total)

Core Memory Operations

1. create_atomic_note

Stores a new piece of information in the memory system.

Parameters:

  • content (string, required): The text of the note/memory
  • source (string, optional): Source of the information (default: "user_input")

Example:

{
  "content": "Python async/await enables non-blocking I/O operations",
  "source": "user_input"
}

2. retrieve_memories

Searches for relevant memories based on semantic similarity.

Parameters:

  • query (string, required): The search query
  • max_results (integer, optional): Maximum number of results (default: 5, max: 20)

Example:

{
  "query": "Python async programming",
  "max_results": 5
}

3. get_memory_stats

Returns statistics about the memory system.

Parameters: None

Example:

{}

4. delete_atomic_note

Deletes a note from the memory system. Removes the note from Graph and Vector Store as well as all associated connections.

Parameters:

  • note_id (string, required): The UUID of the note to be deleted

Example:

{
  "note_id": "732c8c3b-7c71-42a6-9534-a611b4ffe7bf"
}

5. add_file

Stores the content of a file (e.g., .md) as a note in the memory system. Supports automatic chunking for large files (>16KB).

Parameters:

  • file_path (string, optional): Path to the file to be stored (relative or absolute)
  • file_content (string, optional): Alternatively: Direct file content as string (when file_path is not provided)
  • chunk_size (integer, optional): Maximum size per chunk in bytes (default: 15000, max: 16384)

Note: Either file_path OR file_content must be provided.

Example:

{
  "file_path": "documentation.md",
  "chunk_size": 15000
}

Or with direct content:

{
  "file_content": "# Documentation\n\nThis is the content...",
  "chunk_size": 15000
}

6. reset_memory

Resets the complete memory system (Graph + Vector Store). Deletes all notes, edges, and embeddings.

⚠️ WARNING: This action cannot be undone!

Parameters: None

Example:

{}

🚀 Installation & Start

1. Install Dependencies

pip install -r requirements.txt

2. Start MCP Server

python mcp_server.py

Or directly:

python -m src.a_mem.main

📝 Cursor/IDE Configuration

Cursor IDE

Add the following configuration to your MCP configuration file:

  • Windows: %USERPROFILE%\.cursor\mcp.json (or C:\Users\<username>\.cursor\mcp.json)
  • macOS: ~/.cursor/mcp.json
  • Linux: ~/.cursor/mcp.json
{
  "mcpServers": {
    "a-mem": {
      "command": "python",
      "args": ["-m", "src.a_mem.main"],
      "cwd": "/path/to/a-mem-mcp-server"
    }
  }
}

Important: Adjust cwd to the absolute path to your project directory!

Visual Studio Code

If an MCP Extension is available, use VSCode Settings (JSON) or an mcp.json file in the project root:

{
  "mcpServers": {
    "a-mem": {
      "command": "python",
      "args": ["-m", "src.a_mem.main"],
      "cwd": "${workspaceFolder}"
    }
  }
}

🔧 Configuration

The server uses configuration from src/a_mem/config.py and .env file.

Environment Variables (.env)

Copy .env.example to .env and adjust the values:

Ollama (default):

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_LLM_MODEL=qwen3:4b
OLLAMA_EMBEDDING_MODEL=nomic-embed-text:latest

OpenRouter:

LLM_PROVIDER=openrouter
OPENROUTER_API_KEY=your_api_key_here
OPENROUTER_LLM_MODEL=openai/gpt-4o-mini
OPENROUTER_EMBEDDING_MODEL=openai/text-embedding-3-small

Graph Backend Selection:

# Default: NetworkX (no installation needed)
GRAPH_BACKEND=networkx

# For better performance (3x-100x faster):
# pip install rustworkx
GRAPH_BACKEND=rustworkx

# For persistent storage (production):
# Experimental - Not fully tested (see docs/FALKORDB_POC_README.md)
# Linux/macOS: pip install falkordblite
# Windows: pip install falkordb redis (see docs/WINDOWS_FALKORDB_SETUP.md)
# GRAPH_BACKEND=falkordb  # ⚠️ Experimental - Use at your own risk

Ollama Setup (when LLM_PROVIDER=ollama)

Make sure Ollama is running and both models are installed:

ollama pull qwen3:4b
ollama pull nomic-embed-text:latest

📊 Example Usage

Create Memory:

# Via MCP Tool
create_atomic_note(
    content="Python async/await Patterns",
    source="user_input"
)

Search Memory:

# Via MCP Tool
retrieve_memories(
    query="Python concurrency",
    max_results=5
)

Get Statistics:

# Via MCP Tool
get_memory_stats()

Delete Note:

# Via MCP Tool
delete_atomic_note(
    note_id="732c8c3b-7c71-42a6-9534-a611b4ffe7bf"
)

Import File:

# Via MCP Tool - Automatic chunking for large files
add_file(
    file_path="documentation.md",
    chunk_size=15000
)

Reset Memory System:

# Via MCP Tool - ⚠️ DELETES EVERYTHING!
reset_memory()

✅ Status

The MCP Server is fully implemented and uses:

  • ✅ Local Ollama (qwen3:4b for LLM, nomic-embed-text for embeddings) or OpenRouter (cloud)
  • ✅ Async I/O for performance
  • ✅ Memory Evolution in background
  • ✅ Graph-based linking
  • ✅ 15 MCP Tools (Core Memory, Note Management, Relations, Graph Operations, Maintenance, Research)
  • ✅ Graph Backend Selection (NetworkX, RustworkX, FalkorDB - experimental)
  • ✅ Parameter Validation (automatic validation of all tool parameters)
  • ✅ Safe Graph Wrapper (edge case handling and data sanitization)
  • ✅ Advanced Memory Enzymes (14+ maintenance operations: duplicate merging, edge validation, isolated node linking, keyword normalization, quality scoring, note validation, corrupted node repair, and more)