memory-mcp-1file

memory-mcp-1file is a high-performance MCP server that provides persistent memory for AI agents, written in pure Rust.

[Purpose] It solves the problem of AI agents losing state after session restarts or context compression, providing agents with persistent, semantic, and graph-based memory storage, turning them from "stateless chatbots" into "stateful workers" that survive restarts and retain the full context of the current task.

[Core advantages (All-in-One)] Unlike other memory solutions that require a complex tech stack of "Python + vector database + graph database," this project is a single self-contained executable: SurrealDB is embedded; no external database is needed; no API Key, no cloud, no Python are needed, and everything runs 100% locally through an embedded ONNX runtime, with the embedding model baked into the binary and running on the CPU, so data never leaves the local machine; zero configuration, just run a single Docker container or binary.

[Main capabilities]

• Semantic memory: stores text as vector embeddings (granite by default), supporting semantic-based retrieval.
• Graph memory: tracks entities (User, Project, Tech) and their relationships (uses, likes), supporting PageRank-based traversal.
• Code intelligence: indexes local project directories (AST-based chunking), supports Rust, Python, TypeScript, JavaScript, Go, Java, Dart/Flutter, and tracks calls, imports, extends, implements, and mixin relationships between symbols.
• Temporal validity: memories can carry valid_from and valid_until dates.
• Hybrid retrieval (Reciprocal Rank Fusion) for the best results.
• Backend: SurrealDB (fast, embedded, single-file database).

[Architecture and transport] The server uses rmcp 3.2 and supports two protocol lifecycles: MCP 2026-07-28 stateless requests (clients can start with server/discover, each request carries the protocol version and client metadata in _meta, and the process does not store MCP sessions, Mcp-Session-Id, or a mutable currentProject); MCP 2025-11-25 compatible (clients using the legacy initialize / initialized lifecycle are still supported). The binary exposes MCP over stdio, with one process per local workspace; when using Docker, mount the workspace to /project. This version does not enable or advertise Streamable HTTP, so it introduces no HTTP session management or shared server authentication surface. Code indexing receives explicit paths via index_project; when a single process contains multiple indexed projects, project_id can be used to narrow the scope of code search. Roots negotiation is not used.

[Usage]

1. General Docker configuration: -v mcp-data:/data persists the graph, embeddings, and cached model weights; -v $(pwd):/project:ro lets the server read and index code; --init ensures a clean shutdown. One volume persists everything: a single -v mcp-data:/data mount covers both the SurrealDB database and the approximately 1.2 GB embedding model (stored in /data/models/). If a named volume is not used, Docker creates a new anonymous volume on every docker run, causing the model to be re-downloaded each time (about 1.2 GB).
2. Cursor: in Cursor Settings > Features > MCP Servers, click + Add New MCP Server, with the 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 (update the project path when switching workspaces that require code indexing).
3. NPX / Bunx (no Docker required): can be run directly via npx or bunx, and the npm package automatically downloads a precompiled binary adapted to the platform. In claude_desktop_config.json, configure the command npx -y memory-mcp-1file; unlike Docker, npx / bunx in thisRunning the binary natively already gives access to the file system, with no need to mount a directory. The data storage path can be customized by passing --data-dir via args.
4. Codex: The repository contains a trusted project .codex/config.toml, starts memory-mcp-1file@0.9.2 via local STDIO, stores data in .codex/data, and exposes a project allowlist of 16 tools. The destructive tools delete_memory, delete_project, and reset_all_memory are intentionally excluded from the project configuration. The native Codex index is restricted to the current repository by MEMORY_MCP_ALLOWED_INDEX_ROOT. Project-level Codex configuration is loaded only after you explicitly trust the repository; on Windows, verify the package independently before running. Setting required = true makes Memory MCP startup failures visible rather than running silently. The tool allowlist controls which MCP tools Codex loads; it is not a process sandbox. Trust the repository and the npm package before enabling this configuration.
5. Gemini configuration: Can be added to ~/.gemini/settings.json, or use Docker.

[Agent Integration (System Prompt)] Memory is only useful when the agent actively queries it. The repository provides a battle-tested Memory Protocol (AGENTS.md) for reference and adaptation. It is recommended to use AGENTS.md as the single source of truth, instructing the agent in its base system prompt to read AGENTS.md at the start of every session and follow the protocol within. The workflows implemented by the protocol include: at session startup, the agent must immediately search TASK: in_progress to restore the full context from the previous session or before context compression; the Auto-Continue safety mechanism, where the agent shows the user the tasks found and waits (or automatically continues), avoiding inventing new tasks; Triple Sync updates Memory, the Todo List, and files simultaneously, with the others serving as backups if one fails; the prefix system (TASK:, DECISION:, RESEARCH:) allows semantic search to precisely locate the correct type of information, reducing noise.

[Tools and Configuration] The server exposes 19 tools to AI models, divided into core memory management, search and retrieval, knowledge graph,Categories such as codebase intelligence, systems, and maintenance. Configuration is done via environment variables or CLI arguments.

[Available Models] The embedding model can be switched via the --model argument or the EMBEDDING_MODEL environment variable. When neither is provided, Granite is used. Configuration priority: explicit --model argument, EMBEDDING_MODEL, built-in Granite default. granite produces native 384-dimensional, L2-normalized CLS embeddings; the current Candle CPU path limits input to 512 tokens to constrain quadratic attention memory overhead, while the model itself supports up to 32K tokens. Models marked (MRL) support dynamically truncating the output embedding vector to smaller dimensions (such as 512, 256, 128) with minimal precision loss, which can save database storage and speed up vector search. Use the --mrl-dim argument to specify the target size; when omitted, it defaults to the model's native base dimension (e.g., 1024 for Qwen3). Warning: once the database is created with a specific dimension, it cannot be changed without erasing the data directory.

[Restricted Models and Authentication (Gemma)] Granite is used by default (Apache 2.0, automatically downloaded without authentication). If you choose Gemma (--model gemma), because it is a restricted model under a proprietary license, authentication is required: visit google/embeddinggemma-300m on Hugging Face, log in and click Agree to access repository, generate an access token in HF Tokens (read permission is sufficient), then start the server with the token.

[Model Switching and Data Compatibility] A fresh installation uses granite (384 dimensions) by default. An existing data directory created with e5_multi (768 dimensions) remains usable only when explicitly started with --model e5_multi. Switching to a model of a different dimension requires a new data directory (or clearing the volume) and a full reindex. Even switching to a model of the same dimension (such as between e5_multi and nomic) is not recommended, because their semantic spaces differ.

[Future Roadmap (Research and Ideas)] Based on analysis of advanced memory systems such as Hindsight, the team is exploring the following cognitive architecture features: 1) metacognitive reflection (consolidation), implementing a reflect background process or tool that periodically scans recent memories to deduplicate,resolve conflicts, and synthesize low-level facts into high-level insights; 2) temporal decay and "presence," integrating temporal decay into the RRF algorithm, giving a computational bonus to recent memories for queries that imply "current state," allowing agents to dynamically prioritize "working memory" over "historical archive"; 3) namespace memory repositories, code indexing already supports explicit project_id filtering, and in the future extending namespace/project scoping to memory and graph operations, so that one shared server can isolate multiple agent workspaces; 4) cognitive confidence scoring, adding a 0.0-1.0 confidence score to memory schemas, allowing storage of hypotheses (such as confidence 0.3), and retrieval tools can filter out low-confidence memories when answering factual questions.

[Limitations] Requires an MCP-compatible client; runs via stdio, one process per local workspace; Streamable HTTP is not enabled in this version; the database dimension cannot be changed once created, and switching models requires reindexing; Gemma models require Hugging Face authentication; Roots negotiation is not used. Other information such as pricing and billing models is not yet provided.