pomazanbohdan/memory-mcp-1file

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
> **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:
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.