Memory Mcp 1file

🏠 🍎 🪟 🐧 - A self-contained Memory server with single-binary architecture (embedded DB & models, no dependencies). Provides persistent semantic and graph-based memory for AI agents.

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

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

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

- ✅No External Database(SurrealDB is embedded)
- ✅No API Keys, No Cloud, No Python— Everything runs100% locallyvia 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)
- Vector Search(FastEmbed) for semantic similarity.
- Knowledge Graph(PetGraph) for entity relationships.
- Code Indexingwithsymbol graph(calls, extends, implements) for deep codebase understanding.
- Hybrid Retrieval(Reciprocal Rank Fusion) for best results.

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

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

# 🧠 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.

[!TIP]One volume persists everything: The single-v mcp-data:/datamount covers both the SurrealDB databaseandthe ~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/dataand is preserved automatically. Without a named volume, Docker creates a new anonymous volume on eachdocker 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/projectwith 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.
- Go toCursor Settings>Features>MCP Servers.
- Click+ Add New MCP Server.
- Type:stdio
- Name:memory
- Command:

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

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

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

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

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

- Go toCursor Settings>Features>MCP Servers.
- Click+ Add New MCP Server.
- Type:command
- Name:memory
- Command:npx -y memory-mcp-1file

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

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

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

Note:Unlike Docker,npx/bunxruns the binarylocally— it already has access to your filesystem, so no directory mounting is needed. To customize the data storage path, pass--data-dirvia args:

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

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

{ "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" ] } } }

- Semantic Memory: Stores text with vector embeddings (qwen3by 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, andDart/Flutter. Trackscalls, imports, extends, implements, and mixinrelationships between symbols.
- Temporal Validity: Memories can havevalid_fromandvalid_untildates.
- SurrealDB Backend: Fast, embedded, single-file database.

The server exposes18 toolsto the AI model, organized into logical categories.

You can switch the embedding model using the--modelarg orEMBEDDING_MODELenv var.

📉 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-dimargument 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 usese5_multi, which is fully open-source and downloads automatically without any authentication.

However, if you choose to useGemma(--model gemma), you must authenticate because it is a "Gated Model" with a proprietary license.
- Go togoogle/embeddinggemma-300mon Hugging Face.
- Log in and click"Agree to access repository".
- Generate an Access Token atHF Tokens(Read access is enough).
- 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

If you switch to a model with different dimensions (e.g., frome5_smalltoe5_multi),your existing database will be incompatible. You must delete the data directory (volume) and re-index your data.

Switching between models with the same dimensions (e.g.,e5_multi<->nomic) is theoretically possible but not recommended as semantic spaces differ.

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

Persistent memory layer for AI agents with semantic search, consolidation, and cross-session intelligence via MCP.