🧠 Memory MCP Server

A high-performance, pure Rust Model Context Protocol (MCP) server that provides persistent, semantic, and graph-based memory for AI agents.

Works perfectly with:

• Claude Desktop
• Claude Code (CLI)
• Gemini CLI
• OpenAI Codex (CLI / IDE)
• Cursor
• OpenCode
• Cline / Roo Code
• Any other MCP-compliant client.

🏆 The "All-in-One" Advantage

Unlike other memory solutions that require a complex stack (Python + Vector DB + Graph DB), this project is a single, self-contained executable.

• ✅ No External Database (SurrealDB is embedded)
• ✅ No API Keys, No Cloud, No Python — Everything runs 100% locally via an embedded ONNX runtime. The embedding model is baked into the binary and runs on CPU. Nothing leaves your machine.
• ✅ Zero Setup (Just run one Docker container or binary)

It combines:

1. Vector Search (FastEmbed) for semantic similarity.
2. Knowledge Graph (PetGraph) for entity relationships.
3. Code Indexing with symbol graph (calls, extends, implements) for deep codebase understanding.
4. Hybrid Retrieval (Reciprocal Rank Fusion) for best results.

🏗️ Architecture

graph TD
    User[AI Agent / IDE]
    
    subgraph "Memory MCP Server"
        MS[MCP Server]
        
        subgraph "Core Engines"
            ES[Embedding Service]
            GS[Graph Service]
            CS[Codebase Service]
        end
        
        MS -- "Store / Search" --> ES
        MS -- "Relate Entities" --> GS
        MS -- "Index" --> CS
        
        ES -- "Vectorize Text" --> SDB[(SurrealDB Embedded)]
        GS -- "Knowledge Graph" --> SDB
        CS -- "AST Chunks" --> SDB
    end

    User -- "MCP Protocol" --> MS

Click here for the Detailed Architecture Documentation

MCP Protocol & Transports

The server uses rmcp 3.2 and supports both protocol lifecycles:

• MCP 2026-07-28 stateless requests: clients may begin with server/discover; every request carries the protocol version and client metadata in _meta. The process stores no MCP session, Mcp-Session-Id, or mutable currentProject.
• MCP 2025-11-25 compatibility: clients using the legacy initialize/initialized lifecycle remain supported.

This binary exposes MCP over stdio. Run one process per local workspace and mount that workspace at /project when using Docker. Streamable HTTP is not enabled or advertised by this release, so it introduces no HTTP session management or shared-server authentication surface. Code indexing receives an explicit path through index_project; code search can be narrowed with project_id when one process contains multiple indexed projects. Roots negotiation is not used.

🤖 Agent Integration (System Prompt)

Memory is useless if your agent doesn't check it. To get the "Long-Term Memory" effect, you must instruct your agent to follow a strict protocol.

We provide a battle-tested Memory Protocol (AGENTS.md) that you can adapt.

🛡️ Core Workflows (Context Protection)

The protocol implements specific flows to handle Context Window Compaction and Session Restarts:

1. 🚀 Session Startup: The agent must search for TASK: in_progress immediately. This restores the full context of what was happening before the last session ended or the context was compacted.
2. ⏳ Auto-Continue: A safety mechanism where the agent presents the found task to the user and waits (or auto-continues), ensuring it doesn't hallucinate a new task.
3. 🔄 Triple Sync: Updates Memory, Todo List, and Files simultaneously. If one fails (e.g., context lost), the others serve as backups.
4. 🧱 Prefix System: All memories use prefixes (TASK:, DECISION:, RESEARCH:) so semantic search can precisely target the right type of information, reducing noise.

These workflows turn the agent from a "stateless chatbot" into a "stateful worker" that survives restarts and context clearing.

Recommended System Prompt Snippet

Instead of scattering instructions across IDE-specific files (like .cursorrules), establish AGENTS.md as the Single Source of Truth.

Instruct your agent (in its base system prompt) to:

1. Read AGENTS.md at the start of every session.
2. Follow the protocols defined therein.

Here is a minimal reference prompt to bootstrap this behavior:

# 🧠 Memory & Protocol
You have access to a persistent memory server and a protocol definition file.

1.  **Protocol Adherence**:
    - READ `AGENTS.md` immediately upon starting.
    - Strictly follow the "Session Startup" and "Sync" protocols defined there.

2.  **Context Restoration**:
    - Run `search_text("TASK: in_progress")` to restore context.
    - Do NOT ask the user "what should I do?" if a task is already in progress.

Why this matters?

Without this protocol, the agent loses context after compaction or session restarts. With this protocol, it maintains the full context of the current task, ensuring no steps or details are lost, even when the chat history is cleared.

🔌 Client Configuration

Universal Docker Configuration (Any IDE/CLI)

To use this MCP server with any client (Claude Code, OpenCode, Cline, etc.), use the following Docker command structure.

Key Requirements:

1. Memory Volume: -v mcp-data:/data (Persists your graph, embeddings, and cached model weights)
2. Project Volume: -v $(pwd):/project:ro (Allows the server to read and index your code)
3. Init Process: --init (Ensures the server shuts down cleanly)

[!TIP] One volume persists everything: The single -v mcp-data:/data mount covers both the SurrealDB database and the ~1.2 GB embedding model (stored under /data/models/). There is no need for a separate volume for /data/models — it is already a subdirectory of /data and is preserved automatically. Without a named volume, Docker creates a new anonymous volume on each docker run, causing the model to re-download (~1.2 GB) every time.

JSON Configuration (Claude Desktop, etc.)

Add this to your configuration file (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": [
        "run",
        "--init",
        "-i",
        "--rm",
        "--memory=3g",
        "-v", "mcp-data:/data",
        "-v", "/absolute/path/to/your/project:/project:ro",
        "ghcr.io/pomazanbohdan/memory-mcp-1file:latest"
      ]
    }
  }
}

Note: Replace /absolute/path/to/your/project with the actual path you want to index. In some environments (like Cursor or VSCode extensions), you might be able to use variables like ${workspaceFolder}, but absolute paths are most reliable for Docker.

Cursor (Specific Instructions)

1. Go to Cursor Settings > Features > MCP Servers.
2. Click + Add New MCP Server.
3. Type: stdio
4. Name: memory
5. Command:
   Terminal

   Copy

   docker run --init -i --rm --memory=3g -v mcp-data:/data -v "/Users/yourname/projects/current:/project:ro" ghcr.io/pomazanbohdan/memory-mcp-1file:latest
   

   (Remember to update the project path when switching workspaces if you need code indexing)

OpenCode / CLI

docker run --init -i --rm --memory=3g \
  -v mcp-data:/data \
  -v $(pwd):/project:ro \
  ghcr.io/pomazanbohdan/memory-mcp-1file:latest

NPX / Bunx (No Docker required)

You can run the server directly via npx or bunx. The npm package automatically downloads the correct pre-compiled binary for your platform.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Claude Code (CLI)

claude mcp add memory -- npx -y memory-mcp-1file

Cursor

1. Go to Cursor Settings > Features > MCP Servers.
2. Click + Add New MCP Server.
3. Type: command
4. Name: memory
5. Command: npx -y memory-mcp-1file

Or add to .cursor/mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Windsurf / VS Code

Add to your MCP settings:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Bun

{
  "mcpServers": {
    "memory": {
      "command": "bunx",
      "args": ["memory-mcp-1file"]
    }
  }
}

OpenAI Codex CLI (project-scoped)

This repository includes a trusted-project .codex/config.toml that starts memory-mcp-1file@0.9.2 over local STDIO, stores data in .codex/data, and exposes a 16-tool project allowlist. The destructive tools delete_memory, delete_project, and reset_all_memory are intentionally excluded from the project configuration. Native Codex indexing is constrained to the current repository by MEMORY_MCP_ALLOWED_INDEX_ROOT.

Project-scoped Codex configuration is loaded only after you explicitly trust the repository. On Windows, verify the package independently first:

npx -y memory-mcp-1file@0.9.2 -- --help

Then run codex from the repository and verify the server with:

/mcp

or:

codex mcp list
codex mcp get memory

The required = true setting makes a failed Memory MCP startup visible instead of silently running the project without its memory workflow. The tool allowlist controls which MCP tools Codex loads; it is not a process sandbox. Trust the repository and npm package before enabling this configuration.

Note: Unlike Docker, npx/bunx runs the binary locally — it already has access to your filesystem, so no directory mounting is needed. To customize the data storage path, pass --data-dir via args:

json

Copy

"args": ["-y", "memory-mcp-1file", "--", "--data-dir", "/path/to/data"]

Gemini CLI

Add to your ~/.gemini/settings.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": [
        "run", "--init", "-i", "--rm", "--memory=3g",
        "-v", "mcp-data:/data",
        "-v", "${workspaceFolder}:/project:ro",
        "ghcr.io/pomazanbohdan/memory-mcp-1file:latest"
      ]
    }
  }
}

✨ Key Features

• Semantic Memory: Stores text with vector embeddings (granite by default) for "vibe-based" retrieval.
• Graph Memory: Tracks entities (User, Project, Tech) and their relations (uses, likes). Supports PageRank-based traversal.
• Code Intelligence: Indexes local project directories (AST-based chunking) for Rust, Python, TypeScript, JavaScript, Go, Java, and Dart/Flutter. Tracks calls, imports, extends, implements, and mixin relationships between symbols.
• Temporal Validity: Memories can have valid_from and valid_until dates.
• SurrealDB Backend: Fast, embedded, single-file database.

🛠️ Tools Available

The server exposes 19 tools to the AI model, organized into logical categories.

🧠 Core Memory Management

🔎 Search & Retrieval

🕸️ Knowledge Graph

💻 Codebase Intelligence

⚙️ System & Maintenance

⚙️ Configuration

Environment variables or CLI args:

🧠 Available Models

You can switch the embedding model using the --model arg or EMBEDDING_MODEL env var.

When neither option is provided, the binary uses Granite. Configuration precedence is: explicit --model argument, then EMBEDDING_MODEL, then the built-in Granite default.

granite produces native 384-dimensional, L2-normalized CLS embeddings. The current Candle CPU path caps inputs at 512 tokens to bound the quadratic attention memory cost; the model itself supports up to 32K tokens.

📉 Matryoshka Representation Learning (MRL)

Models marked with (MRL) support dynamically truncating the output embedding vector to a smaller dimension (e.g., 512, 256, 128) with minimal loss of accuracy. This saves database storage and speeds up vector search.

Use the --mrl-dim argument to specify the desired size. If omitted, the default is the model's native base dimension (e.g., 1024 for Qwen3).

Warning: Once your database is created with a specific dimension, you cannot change it without wiping the data directory.

🔒 Gated Models & Authentication (Gemma)

By default, the server uses Granite, an Apache 2.0 model that downloads automatically without any authentication.

However, if you choose to use Gemma (--model gemma), you must authenticate because it is a "Gated Model" with a proprietary license.

To use Gemma:

1. Go to google/embeddinggemma-300m on Hugging Face.
2. Log in and click "Agree to access repository".
3. Generate an Access Token at HF Tokens (Read access is enough).
4. Start the server with the token:

# Using environment variable
HF_TOKEN="hf_your_token_here" memory-mcp --model gemma

# Or via .env file (see .env.example)

[!WARNING] Changing Models & Data Compatibility

Fresh installations use granite (384 dimensions) by default. Existing data directories created with e5_multi (768 dimensions) remain usable only when starting explicitly with --model e5_multi.

Switching to a model with different dimensions requires a new data directory (or wiped volume) and a full re-index.

Even switching between models with the same dimensions (e.g., e5_multi <-> nomic) is not recommended because their semantic spaces differ.

🔮 Future Roadmap (Research & Ideas)

Based on analysis of advanced memory systems like Hindsight (see their documentation for details on these mechanisms), we are exploring these "Cognitive Architecture" features for future releases:

1. Meta-Cognitive Reflection (Consolidation)

• Problem: Raw memories accumulate noise over time (e.g., 10 separate memories about fixing the same bug).
• Solution: Implement a reflect background process (or tool) that periodicallly scans recent memories to:
  • De-duplicate redundant entries.
  • Resolve conflicts (if two memories contradict, keep the newer one or flag for review).
  • Synthesize low-level facts into high-level "Insights" (e.g., "User prefers Rust over Python" derived from 5 code choices).

2. Temporal Decay & "Presence"

• Problem: Old memories can sometimes drown out current context in semantic search.
• Solution: Integrate Time Decay into the Reciprocal Rank Fusion (RRF) algorithm.
  • Give a calculated boost to recent memories for queries implying "current state".
  • Allow the agent to prioritize "working memory" over "historical archives" dynamically.

3. Namespaced Memory Banks

• Current boundary: Code indexes already support explicit project_id filtering, while memory records remain process-wide.
• Future work: Extend namespace/project scoping to memory and graph operations so one shared server can isolate multiple agent workspaces.

4. Epistemic Confidence Scoring

• Problem: The agent treats a guess the same as a verified fact.
• Solution: Add a confidence score (0.0 - 1.0) to memory schemas.
  • Allows storing hypotheses ("I think the bug is in auth.rs", confidence: 0.3).
  • Retrieval tools can filter out low-confidence memories when answering factual questions.

License

MIT