← Back to directory
M

MARM Memory MCP Server

Community
Local-first persistent memory and semantic recall for AI agents
GitHub source repository ↗
★ 350 Stars Category · Dev Tools Very popular
63FMRS · C

MARM Memory is a local-first MCP memory server that fuses session memory, a code graph, and a concept graph into one embedded SQLite store, exposing 14 tools over STDIO or HTTP. It suits self-hosters who want persistent context shared across multiple AI coding clients without sending memory to the cloud; recall uses an FTS5 exact lane plus semantic reranking, and the project's own benchmarks show recall latency scaling slowly with memory size. Note that it is not an official vendor product, and HTTP exposure, Docker mounts, and optional consolidation/compaction features add setup complexity and real performance tradeoffs, so verify keys, network binding, and data-directory permissions before deploying.

Reliability
10/20
Security and permissions
11/20
Maintenance
13/20
Documentation
15/20
Setup experience
14/20
Read the FMRS scoring method →

MARM Memory is a local-first MCP server that gives AI agents a permanent, private memory across Claude Code, Codex, Grok, Gemini, VS Code, and Cursor. It fuses session history, repository code indexing, and a concept graph into an embedded SQLite store, enabling zero-cloud, privacy-first context retention and instant recall, including for multi-agent swarms. The server exposes 14 MCP tools: 7 core memory tools (logging, hybrid recall, summaries, notebooks, log viewing, deletion, and compaction) plus 5 code-graph tools (repo indexing, symbol lookup, call tracing, architecture overview, change-impact analysis) and 2 concept-graph tools (entity/relationship build and query). Recall uses a hybrid pipeline of an FTS5 BM25 exact lane plus semantic reranking, with long memories chunked into overlapping rows and collapsed back to the parent memory. Both STDIO and HTTP transports are supported, with managed swarm, swarm-max, and trusted rate-limit profiles for shared deployments.

Tools

marm_log_entry
Log important information to MARM's memory system
marm_smart_recall
Hybrid memory recall with bounded concept and linked-code context when available
marm_summary
Generate intelligent summaries from memory data
marm_notebook
Unified notebook — add, use, show, status, clear, or save entries (action parameter required)
marm_log_show
Display memory log entries
marm_delete
Delete a log session, log entry, or notebook entry (type='log'|'notebook')
marm_compaction
Review, stage, apply, or discard agent-assisted memory compaction candidates
marm_graph_index
Index a repository into the bundled code graph, check index status, or list indexed projects
marm_code_lookup
Find symbols, source snippets, or text matches in an indexed repository
marm_graph_trace
Trace call paths or data flow through the indexed code graph
marm_graph_architecture
Return high-level architecture, node and edge summaries, modules, and graph schema
marm_graph_impact
Estimate change impact from git diff context and affected graph symbols
marm_concept_build
Extract entities and typed relationships from stored memories into the concept graph
marm_concept_recall
Explicitly query platform-aware concept entities, relationships, and linked code symbols

Setup

  1. Install the Python package: pip install marm-mcp-server (requires Python 3.10+).
  2. Initialize and write client configs: marm-memory init --g-claude --g-codex --g-gemini (also supports --g-qwen and --g-kiro; run without flags to install into the current project folder).
  3. Alternatively, tell your agent to use the marm-init skill, which handles Python/Docker, HTTP/STDIO, keys, and client configs interactively in chat.
  4. Manual start: run marm-memory start for HTTP, then connect the client, e.g. claude mcp add --transport http marm-memory http://localhost:8001/mcp; Codex uses codex mcp add marm-memory --url http://localhost:8001/mcp.
  5. Private STDIO mode: run marm-mcp-stdio (or python -m marm_mcp_server.server_stdio), then claude mcp add --transport stdio marm-memory-stdio marm-mcp-stdio.
  6. Docker HTTP requires a key: generate one with docker run --rm lyellr88/marm-mcp-server:latest --generate-key, run the container mounting ~/.marm:/home/marm/.marm with MARM_API_KEY set, then add the Authorization: Bearer header in your client.
  7. Docker STDIO needs no key: docker run --rm -i -v ~/.marm:/home/marm/.marm --entrypoint python lyellr88/marm-mcp-server:latest -m marm_mcp_server.server_stdio.
  8. Verify with curl http://localhost:8001/health.
claude_desktop_config.json
{
  "mcpServers": {
    "marm-memory-local": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    },
    "marm-memory-docker": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MARM_API_KEY}"
      }
    }
  }
}

Fit and risk

Best for

  • Developers who want memory to stay entirely local instead of depending on a cloud vector database
  • Users who switch between multiple MCP clients and need context to carry over
  • Agent users who need code-structure awareness and change-impact analysis
  • Self-hosters comfortable running a Python package or Docker container

Not for

  • Teams that require an officially hosted cloud service or SLA
  • Pure API integrations that do not use an MCP client
  • Restricted environments that cannot run local processes or containers
  • Users expecting a fully managed zero-configuration cloud product

Required permissions

  • Read/write access to the local data directory (default ~/.marm/, or %USERPROFILE%\.marm\ on Windows) holding the SQLite memory database, index database, and logs
  • HTTP mode binds to localhost:8001 by default and can be exposed to the network with SERVER_HOST=0.0.0.0
  • Docker deployments need a mounted data volume, and code indexing needs read-only repo mounts
  • Network access on first code-graph use to download the graph engine binary (~269MB, one time)
  • Docker HTTP mode requires a MARM_API_KEY environment variable for Bearer authentication

Risks and side effects

  • Exposing the HTTP port with SERVER_HOST=0.0.0.0 without a firewall and TLS proxy can leave memory data reachable by unauthorized parties
  • Memories and code index data are stored as plaintext SQLite files that any process able to read the directory can access
  • In Docker, code-graph tools can only see mounted container paths; using host paths causes index failures
  • Enabling write-time consolidation (CONSOLIDATION_ENABLED=1) raises median write cost from about 6.5ms to 58.1ms
  • Recall latency temporarily increases while the concept-graph backlog drains (measured about 8ms to 16ms median on a real corpus)
  • Graph tools degrade with an error if the graph engine fails to start, for example with no network on first download, a full disk, or schema drift

Troubleshooting

  1. A 401 Unauthorized means the key is missing or mismatched; confirm MARM_API_KEY matches and restart the client after changing env vars
  2. In Docker HTTP smoke tests a 406 Not Acceptable on GET /mcp is expected and means auth reached the MCP endpoint
  3. Codex's --bearer-token-env-var takes the environment variable name, not the raw key; start or restart Codex from the same shell after setting it
  4. A recall response containing recall_scan_truncated=true means the semantic fallback hit the RECALL_SCAN_LIMIT cap; narrow the session/query or raise the env var
  5. If graph tools report graph backend unavailable, check network and disk space or confirm GRAPH_ENABLED is not false; the other 9 tools keep working
  6. When concept tools misbehave, run marm-memory knowledge status first and reinstall MARM if the bundled runtime is damaged
  7. Run marm-memory doctor to diagnose the local install and marm-memory upgrade --check to compare against PyPI

Use cases

Sharing one project memory and decision log across multiple AI clients such as Claude Code, Codex, and Gemini
Giving coding agents a structural index of a repository to cut repeated grep and full-file read token cost
Connecting decisions, errors, tools, and people across sessions through the concept graph
Running a local SQLite memory service in offline or privacy-sensitive environments with no cloud sync
Supporting multi-agent collaboration through swarm rate-limit profiles that serialize memory writes

Supported clients

Claude CodeFull support
VS Code / GitHub Copilot AgentFull support
CursorFull support
Codex CLIFull support
Gemini CLIFull support
Qwen CodeFull support
xAI / Grok Remote MCPPartial support