MARM: Local-First Persistent Multi-Agent Memory Layer for MCP Clients v2.26.0
[](https://github.com/Lyellr88/marm-memory/blob/MARM-main/LICENSE)
[](https://www.python.org/)
[](https://fastapi.tiangolo.com/)
[](https://hub.docker.com/r/lyellr88/marm-mcp-server)
[](https://pepy.tech/projects/marm-mcp-server)
[](https://pypi.org/project/marm-mcp-server/)
[](https://registry.modelcontextprotocol.io/?q=marm-mcp)
[](https://discord.gg/nhyJWPz2cf)
[](https://github.com/Lyellr88/marm-memory/actions/workflows/publish-mcp.yml)
[](https://github.com/Lyellr88/marm-memory/security/code-scanning)
[](https://glama.ai/mcp/servers/Lyellr88/marm-memory)
> Contributions welcome! Browse [open issues](https://github.com/Lyellr88/marm-memory/issues) to contribute, or join the [MARM Discord](https://discord.gg/nhyJWPz2cf) to share workflows, get setup help, and connect with other builders.
## Important Messages
- marm-console now ships as the local web app for memory, knowledge, projects, and MCP-backed memory mutation actions. Packaging and one-command startup polish are still in progress.
- **Embedding upgrade:** v2.24 switches MARM to Jina v2 Small. Existing MiniLM data must be migrated before restart: stop MARM, run `marm-mcp-server --migrate-embeddings`, then restart. See [Upgrade Existing Embeddings](#upgrade-existing-embeddings).
- **Concept graph rebuild:** the platform-aware graph schema requires one full rebuild. After upgrading, run `marm_concept_build(search_all=True)` once. MARM backs up and rebuilds only the derived concept database; memories are not modified.
- I am waiting to get access back to my PYPI account, till restored pip will be behind a few versions. I will update the README when it is back up to date.
## Table of Contents
- [Why MARM Memory](#why-marm-memory)
- [Performance & Scaling Benchmarks](#performance--scaling-benchmarks)
- [Quick Start](#-quick-start-for-mcp-http--stdio)
- [Complete MCP Tool Suite](#complete-mcp-tool-suite-14-tools)
- [Using MARM: Talk, Don't Call Tools](#using-marm-talk-dont-call-tools)
- [Understanding MARM Memory](#understanding-marm-memory)
- [Knowledge Graphs: Code & Concepts](#knowledge-graphs-code--concepts)
- [Architecture & Internals](#architecture--internals)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [Project Documentation](#project-documentation)
## Why MARM Memory
**Your AI forgets everything. MARM Memory doesn't.**
marm-memory is a high-performance 3-in-1 AI Memory Framework that solves conversational drift, context pollution, and agent amnesia. Instead of juggling fragmented tools, it natively fuses three context layers into a single local runtime:
* 🧠 **Core Memory (7 Tools)** — long-term episodic memory, session logs, notebooks, and intelligent summaries via local vector embeddings and deterministic exact matching
* 💻 **Code Graph (5 Tools)** — instant repo indexing, symbol lookup, and tree-sitter syntax analysis, powered by the codebase-memory-mcp static binary wrapper
* 🧩 **Concept Graph (2 Tools)** — extracts entities and typed relationships from stored history, linking developer decisions straight back to source code symbols
One query resolves what was decided, why, and where it lives — no traffic-cop routing across isolated tools. Claude Code, Codex, Gemini, Qwen, Cursor, and VS Code agents share the same persistent memory server across sessions and long-running multi-agent projects, with all 14 tools bundled over both HTTP and STDIO.
Under the hood: a serialized SQLite WAL write queue kills multi-agent swarm contention, write-time consolidation merges duplicates, and hybrid semantic + full-text retrieval keeps recall sharp as memory grows. Agent-assisted compaction keeps context windows clean without losing traceability, and the local marm-console web app gives you real-time visual telemetry to browse and debug your entire memory layout.
### How It Works
| Layer | What it does | Why it matters |
|-------|--------------|----------------|
| **Memory model** | Sessions, structured logs, notebooks, summaries, and semantic memories | Keeps project history searchable instead of trapped in one chat |
| **Scale layer** | SQLite WAL mode, connection pooling, serialized write queue, and HTTP rate-limit presets | Lets one server support solo use, multi-agent work, and swarm-style bursts |
| **Intelligence layer** | FTS filter, semantic re-rank, bounded semantic fallback, auto-classification, write-time consolidation, and compaction candidates | Keeps recall useful as memory grows instead of letting duplicates pile up |
| **Code graph layer** | Repo indexing, symbol lookup, call tracing, architecture overview, and change-impact analysis | Gives agents project structure without rereading the whole codebase |
| **Concept graph layer** | Entity and relationship extraction from stored memories, with links back into the code graph | Connects decisions, errors, tools, and people across sessions instead of leaving them as flat text |
| **Token layer** | Lightweight 7-tool core surface (14 total with bundled graph tools), semantic re-rank before retrieval, and write-time deduplication | Reduces tokens sent to the model on every recall and cost stays predictable as memory scales |
| **Deployment layer** | Pip, Docker, STDIO, HTTP, and managed `swarm`, `swarm-max`, and `trusted` profiles | Lets you run private local memory or shared multi-agent memory with the same MCP surface |
See [Performance & Scaling Benchmarks](#performance--scaling-benchmarks) for retrieval latency, concurrency, and write-cost numbers, and [Architecture & Internals](#architecture--internals) for the mechanisms behind each layer.
### Start Now
**Recommended: guided setup with `marm-init`**
The easiest way to install MARM is to let your agent do the setup with you. `marm-init` turns the usual MCP setup mess into one guided conversation: Python or Docker, HTTP or STDIO, local or remote server, API keys, config paths, server startup, and multi-agent linking for Claude, Codex, Gemini, Qwen, Cursor, VS Code, and other MCP clients. No hunting through install docs, no guessing which config file your client uses, and no rewriting the same connection by hand for every agent.
```bash
npx degit Lyellr88/marm-memory/skills
```
Then tell your agent: **"Use the marm-init skill to set up MARM."**
**Manual pip install**
```bash
pip install marm-mcp-server
```
| If you are... | Start the server | Connect your MCP client |
|---------------|------------------|-------------------------|
| **Solo developer / researcher** | `marm-memory start` | `"agent" mcp add --transport http marm-memory http://localhost:8001/mcp` |
| **Private local STDIO user** | `marm-mcp-stdio` | `"agent" mcp add --transport stdio marm-memory-stdio marm-mcp-stdio` |
| **Multiple agents sharing memory** | `marm-memory start --profile swarm` | `"agent" mcp add --transport http marm-memory http://localhost:8001/mcp` |
| **Private high-throughput swarm** | `marm-memory start --profile swarm-max` | `"agent" mcp add --transport http marm-memory http://localhost:8001/mcp` |
| **Trusted private lab/server** | `marm-memory start --profile trusted` | `"agent" mcp add --transport http marm-memory http://localhost:8001/mcp` |
The managed runtime runs in the background by default. Use `marm-memory status`,
`marm-memory logs --follow`, `marm-memory restart`, and `marm-memory stop` for
normal lifecycle work. `marm-memory console` starts or reuses that runtime and
opens the bundled local web app without requiring Node.js.
### Upgrade Existing Embeddings
The Jina v2 Small default uses 512-dimensional embeddings; older `all-MiniLM-L6-v2` data is 384-dimensional and must be re-embedded after upgrading. Stop every MARM HTTP and STDIO process, then run:
```bash
marm-memory maintenance embeddings migrate
```
The command refuses to continue when it detects a live HTTP server, but STDIO processes cannot be detected reliably and must be stopped manually. It re-embeds memory, chunk, and any existing concept-graph embeddings (notebook scratch entries no longer carry embeddings), reports batch progress, verifies both databases, and exits. It is resumable: rerun the same command after an interruption. Do not run it against a live server.
## Performance & Scaling Benchmarks
MARM is tuned for fast recall first, even as memory grows and long memories are chunked behind the scenes.
These measurements use the fastembed-backed `jinaai/jina-embeddings-v2-small-en` encoder and a throwaway local SQLite database.
### 1. Retrieval Latency Scaling
| Session Size ($N$) | Min Latency | Median Latency | p95 Latency |
| :--- | :--- | :--- | :--- |
| **N = 100** | 6.6 ms | 7.4 ms | 8.0 ms |
| **N = 500** | 7.1 ms | 8.1 ms | 10.0 ms |
| **N = 1,000** | 7.6 ms | 8.5 ms | 9.0 ms |
| **N = 2,000** | 9.3 ms | 10.5 ms | 11.6 ms |
| **N = 4,000** | 11.5 ms | 12.1 ms | 13.4 ms |
### 2. Encoder + Concurrency
- **Cold model load:** `887ms`
- **Warm encode:** median `4.0ms`, p95 `4.4ms`
- **Concurrent recall:** 10 gathered recalls completed in `616.3ms` vs `440.7ms` serial. The current path is intentionally serialized around shared encoder/SQLite work, so gathering calls does not create parallel speedup.
### 3. Write-Time Ingestion Cost
- **Consolidation off:** median `6.8ms`, p95 `7.9ms`
- **Consolidation on:** median `51.3ms`, p95 `93.7ms`
- **Tradeoff:** write-time dedupe/clustering adds `7.6x` median cost so recall stays fast and cleaner over time.
### 4. Hybrid Search Scaling
| Session Size ($N$) | Pure Semantic | Production Hybrid | FTS Filter -> Rerank | Speedup vs Pure |
| :--- | :--- | :--- | :--- | :--- |
| **N = 100** | 2.3 ms | 7.9 ms | 1.9 ms | 1.2x |
| **N = 1,000** | 23.1 ms | 9.2 ms | 2.5 ms | 9.2x |
| **N = 4,000** | 106.5 ms | 13.2 ms | 4.7 ms | 22.8x |
| **N = 10,000** | 267.1 ms | 13.6 ms | 5.3 ms | 50.4x |
These Jina v2 Small benchmarks used a throwaway real SQLite database and the live configured encoder on local hardware. Reproduce them: [`scripts/benchmarking/performance/bench_hotpath.py`](scripts/benchmarking/performance/bench_hotpath.py)
### 5. LoCoMo Retrieval Accuracy
A fresh Jina v2 Small run ingested all 10 LoCoMo conversations through `marm_log_entry`, then scored top-5 `marm_smart_recall` results against 1,977 evidence-annotated questions. No answer-generation model or LLM judge was used.
| Encoder | Any evidence hit | All evidence hit | Mean evidence recall |
| :--- | :--- | :--- | :--- |
| **MiniLM baseline** | 37.5% | 29.5% | not previously published |
| **Jina v2 Small** | 53.0% | 43.4% | 47.6% |
The Jina run improved both hit metrics in this benchmark. This comparison does not isolate context length as the sole cause; model quality, 512-dimensional vectors, and reranking behavior changed together. Reproduce it with [`scripts/benchmarking/accuracy/locomo/run_eval.py`](scripts/benchmarking/accuracy/locomo/run_eval.py).
### 6. vs Competitors: Architecture
MARM targets a specific niche: local-first memory for MCP-connected coding agents, not general personalization memory or a full agent runtime. Here's how it differs architecturally from established names in AI agent memory:
| | MARM | Mem0 | Letta (MemGPT) | Zep / Graphiti | agentmemory |
|---|---|---|---|---|---|
| **Type** | Memory engine, MCP-native | Memory layer API | Full agent runtime | Temporal knowledge graph | Memory engine, MCP-native |
| **Required infrastructure** | No separate data service (embedded SQLite) | Vector DB (Qdrant/pgvector) | Postgres + vector DB | Neo4j | Separate `iii-engine` runtime |
| **Deployment** | Local-first by default; Docker for shared/remote | Cloud API or self-hosted | Self-hosted or cloud | Cloud or self-hosted | Local-first |
| **Retrieval model** | Hybrid: FTS5 BM25 exact lane + semantic rerank | Vector + graph + key-value | Vector archival store + agent-managed core memory | Temporal knowledge graph (fact validity windows) | BM25 + vector + graph (RRF fusion) |
| **Write capture** | Explicit tool calls from the connected agent | Explicit `add()` calls (some integrations auto-extract) | Agent self-edits its own memory | Explicit API calls | Hook-based, automatic (no explicit calls needed) |
| **Code structure awareness** | Bundled code graph + concept graph, fused with memory | Not built in | Not built in | Not built in | Not built in (pairs with a separate project) |
| **Framework lock-in** | None (any MCP client) | None | High (must run within Letta) | None | None (any MCP client) |
**Disclaimers & Accuracy:** Competitor landscapes evolve rapidly. The matrix above reflects core architectural traits as of Q3 2026, based on public documentation and READMEs, not internal testing of each system. If any data point regarding an alternative framework has changed or is misrepresented, please open an issue or submit a Pull Request to update the table. We actively welcome corrections from peer maintainers.
## 🚀 Quick Start for MCP (HTTP & STDIO)
**Manual pip install**
```bash
pip install marm-mcp-server
```
### Use this quick rule of thumb to choose your setup
- Local HTTP/STDIO = fastest single-machine setup.
- Docker HTTP = shared/always-on server (key required).
- Docker STDIO = private containerized local use (no HTTP key).
**Swarm / multi-agent note:** The write queue is enabled by default to serialize memory writes through one worker. For shared HTTP deployments, use `marm-memory start --profile swarm` (200 RPM) or `--profile swarm-max` (600 RPM). `--profile trusted` disables rate limiting entirely for private deployments. STDIO is still best for private single-agent/local use. See [Swarm & multi-agent presets](#swarm--multi-agent-presets) for the full table.