Marm Memory

MARM: Local-First Persistent Multi-Agent Memory Layer for MCP Clients v2.20.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 to contribute, or join the MARM Discord to share workflows, get setup help, and connect with other builders.

Table of Contents

• [Why MARM MCP](#why-marm-mcp)
• [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)
• [MARM Dashboard](#marm-dashboard)
• [Architecture & Internals](#architecture--internals)
• [Troubleshooting](#troubleshooting)
• [Contributing](#contributing)
• [Project Documentation](#project-documentation)

Why MARM MCP

Your AI forgets everything. MARM MCP doesn't.

Claude Code, Codex, Gemini, Qwen, Cursor, VS Code agents, and any other MCP client share the same memory server, so decisions, context, notebooks, and code structure survive across sessions, across agents, and across projects. Cross-session context is the whole point: long-running multi-agent work stops drifting because every agent recalls the same history.

MARM is built around three focused surfaces: 7 core memory tools for daily agent context, 5 code-graph tools for repo intelligence, and 2 concept-graph tools that turn stored memories into a queryable knowledge graph. All 14 are bundled over both HTTP and STDIO transports. The server handles the heavy work behind those tools: protocol delivery, hybrid semantic + full-text retrieval, serialized writes, rate-limit presets, write-time consolidation, agent-assisted compaction, and lazy graph startup. Agents get a compact memory workflow plus codebase and concept lookup when they need it, without rereading the whole project or flooding the model with duplicate context.

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, --swarm, --swarm-max, and --trusted | 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, dashboard 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.

npx degit Lyellr88/marm-memory/skills

Then tell your agent: "Use the marm-init skill to set up MARM."

Manual pip install

pip install marm-mcp-server

| If you are... | Start the server | Connect your MCP client | |---------------|------------------|-------------------------| | Solo developer / researcher | python -m marm_mcp_server | "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 | python -m marm_mcp_server --swarm | "agent" mcp add --transport http marm-memory http://localhost:8001/mcp | | Private high-throughput swarm | python -m marm_mcp_server --swarm-max | "agent" mcp add --transport http marm-memory http://localhost:8001/mcp | | Trusted private lab/server | python -m marm_mcp_server --trusted | "agent" mcp add --transport http marm-memory http://localhost:8001/mcp |

Performance & Scaling Benchmarks

MARM is tuned for fast recall first, even as memory grows and long memories are chunked behind the scenes.

1. Retrieval Latency Scaling

| Session Size ($N$) | Min Latency | Median Latency | p95 Latency | | :--- | :--- | :--- | :--- | | N = 100 | 12.3 ms | 13.8 ms | 15.0 ms | | N = 500 | 13.3 ms | 14.1 ms | 16.4 ms | | N = 1,000 | 14.5 ms | 16.2 ms | 17.1 ms | | N = 2,000 | 15.9 ms | 18.4 ms | 20.8 ms | | N = 4,000 | 17.6 ms | 20.8 ms | 22.5 ms |

2. Encoder + Concurrency

• Cold model load: 972ms
• Warm encode: median 10.3ms, p95 11.2ms
• Concurrent recall: 10 gathered recalls completed in 394.7ms vs 436.6ms serial. The current path is intentionally serialized around shared encoder/SQLite work, so this is stable under load rather than true parallel speedup.

3. Write-Time Ingestion Cost

• Consolidation off: median 10.3ms, p95 11.6ms
• Consolidation on: median 42.0ms, p95 46.3ms
• Tradeoff: write-time dedupe/clustering adds 4.1x 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.4 ms | 15.1 ms | 2.2 ms | 1.1x | | N = 1,000 | 23.6 ms | 16.2 ms | 2.7 ms | 8.8x | | N = 4,000 | 93.8 ms | 18.3 ms | 4.9 ms | 19.0x | | N = 10,000 | 242.7 ms | 19.7 ms | 5.4 ms | 45.1x |

Benchmarks used a throwaway real SQLite database and the live fastembed-backed all-MiniLM-L6-v2 encoder on local hardware. Reproduce them: [marm-mcp-server/scripts/bench_hotpath.py](marm-mcp-server/scripts/bench_hotpath.py)

5. 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

pip install marm-mcp-server

| If you are... | Start the server | Connect your MCP client | |---------------|------------------|-------------------------| | Solo developer / researcher | python -m marm_mcp_server | "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 | python -m marm_mcp_server --swarm | "agent" mcp add --transport http marm-memory http://localhost:8001/mcp | | Private high-throughput swarm | python -m marm_mcp_server --swarm-max | "agent" mcp add --transport http marm-memory http://localhost:8001/mcp | | Trusted private lab/server | python -m marm_mcp_server --trusted | "agent" mcp add --transport http marm-memory http://localhost:8001/mcp |

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 --swarm (200 RPM) or --swarm-max (600 RPM) when starting the server. --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.

Local pip HTTP (zero config)

> "agent" refers to claude, gemini, grok, qwen, or any MCP client. Codex uses --url instead of --transport to add MCP tools.

pip install marm-mcp-server
python -m marm_mcp_server
# Stuck on client setup? Open a Q&A thread: https://github.com/Lyellr88/marm-memory/discussions
# most agents use this --transport command
"agent" mcp add --transport http marm-memory http://localhost:8001/mcp
codex mcp add marm-memory --url http://localhost:8001/mcp

Default pip/local startup is zero-config: MARM binds to localhost and does not require a key unless you expose it with SERVER_HOST=0.0.0.0.

Local pip STDIO

pip install marm-mcp-server
python -m marm_mcp_server.server_stdio
# most agents use this --transport command
"agent" mcp add --transport stdio marm-memory-stdio marm-mcp-stdio
codex mcp add marm-memory-stdio -- marm-mcp-stdio

Replace marm-mcp-stdio with python -m marm_mcp_server.server_stdio if using a virtualenv or a path-based setup. Works with Claude Code, Cursor, VS Code, Qwen, and Gemini CLI. STDIO stays a single local process with no port and no API key, and exposes the same 14 tools as HTTP.

Local Python swarm modes (HTTP & STDIO)

Use HTTP when multiple agents need to share one live MARM server. STDIO is still best for private single-agent use because each client owns its own local process.

# HTTP shared server, normal multi-agent use
python -m marm_mcp_server --swarm

# HTTP shared server, heavier private swarm
python -m marm_mcp_server --swarm-max

# HTTP trusted private lab/server, rate limiting disabled
python -m marm_mcp_server --trusted

# STDIO remains keyless/private and does not use swarm flags
marm-mcp-stdio

---

Docker HTTP (key required)

> Docker HTTP requires an API key because it exposes MARM as a network server; STDIO stays local to the client process and does not need one.

# Step 1: generate key (do not add  around the key)
docker run --rm lyellr88/marm-mcp-server:latest --generate-key

# Step 2: run server
docker pull lyellr88/marm-mcp-server:latest
docker run -d --name marm-mcp-server \
  -p 127.0.0.1:8001:8001 \
  -e SERVER_HOST=0.0.0.0 \
  -e MARM_API_KEY=your-generated-key \
  -v ~/.marm:/home/marm/.marm \
  lyellr88/marm-mcp-server:latest

# Step 3: connect client
"agent" mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

# PowerShell: set this before starting/restarting Codex
$env:MARM_API_KEY="your-generated-key"
codex mcp add marm-memory --url http://localhost:8001/mcp --bearer-token-env-var MARM_API_KEY

# Quick auth smoke test
curl -i -H "Authorization: Bearer $env:MARM_API_KEY" http://127.0.0.1:8001/mcp

--bearer-token-env-var takes the environment variable name, not the raw key. Start or restart Codex from the same shell after setting $env:MARM_API_KEY. For local Docker smoke tests, MARM_API_KEY=test is fine and avoids shell escaping problems; use a generated key for real deployments. A 406 Not Acceptable from the smoke-test GET /mcp means auth reached the MCP endpoint; 401 Unauthorized means the key is missing or mismatched.

Docker HTTP swarm mode

# --swarm: write queue on, 200 RPM - recommended for multi-agent shared servers
docker run -d --name marm-mcp-server \
  -p 127.0.0.1:8001:8001 \
  -e SERVER_HOST=0.0.0.0 \
  -e MARM_API_KEY=your-generated-key \
  -v ~/.marm:/home/marm/.marm \
  lyellr88/marm-mcp-server:latest --swarm

Docker graph indexing: mount the repo

Docker graph tools run inside the container, so they cannot see host paths unless you mount them at docker run.

$env:MARM_API_KEY="test"

# The second -v line mounts your repo; adjust the host path to your project
docker run -d --name marm-mcp-server `
  -p 127.0.0.1:8001:8001 `
  -e SERVER_HOST=0.0.0.0 `
  -e MARM_API_KEY=$env:MARM_API_KEY `
  -v ~/.marm:/home/marm/.marm `
  -v C:\Users\lyell\Desktop\marm-memory:/workspace/marm-memory `
  lyellr88/marm-mcp-server:latest

Then index the container path, not the Windows host path:

marm_graph_index(repo_path="/workspace/marm-memory")

Graph tools must use the container path. Mounts cannot be added to an already-running container; stop and restart the container with the repo mount when you want Docker graph indexing.

Docker STDIO (no HTTP key)

Docker STDIO includes the same built-in marm-graph tools; no extra image or install step is required.

docker run --rm -i \
  -v ~/.marm:/home/marm/.marm \
  --entrypoint python \
  lyellr88/marm-mcp-server:latest \
  -m marm_mcp_server.server_stdio

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Lyellr88](https://github.com/Lyellr88)
- **Source:** [Lyellr88/marm-memory](https://github.com/Lyellr88/marm-memory)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.