Marm

Contributions welcome! Browse open issues to contribute, or join the MARM Discord to share workflows, get setup help, and connect with other builders.

IMPORTANT

Project Status: Brief Personal Pause

I took a short personal break from active development to focus on matters outside the project. This project isn't abandoned, and I plan to return soon to keep building and refining it.

Thank you for your patience, support, and continued interest. I’ll resume work soon and share updates as progress continues.

Table of Contents

• Quick Start
• Why MARM Memory
• MARM Console
• Performance & Scaling Benchmarks
• MCP Client Setup
• Runtime CLI Commands
• Complete MCP Tool Suite
• Using MARM: Talk, Don't Call Tools
• Understanding MARM Memory
• Knowledge Graphs: Code & Concepts
• Architecture & Internals
• Troubleshooting
• Contributing
• Project Documentation

Quick Start

1. Install and initialize with your preferred agent profiles:

pip install marm-mcp-server
marm-memory init --g-claude --g-codex --g-antigravity

Also available: --g-cursor, --g-grok, --g-hermes, --g-opencode, --g-devin, --g-cline, --g-qwen, --g-kiro and --g-zed. Run without flags to install into your current project folder instead of home

1. Hand off to your AI companion. Tell your agent:

"Use the marm-init skill to set up MARM."

1. Interact: Your agent will handle the entire setup (Python/Docker, HTTP/STDIO, keys, and client configs) interactively right inside your chat.

Manual setup

Prefer to wire it up yourself:

Replace "agent" with your client’s CLI command (for example, claude, agy, or qwen). For Codex, use codex mcp add marm-memory --url http://localhost:8001/mcp instead.

• ⚡ Fastest HTTP Startup: Run marm-memory fast-start-http to spin up the local runtime, launch the console, and open it in your browser immediately.
• 🖥️ Web Console: Run marm-memory console to view the local UI app instantly (no Node.js required).
• ⚙️ Lifecycle Management: Manage the background daemon using status, logs --follow, restart, and stop.
• 💡 Quick Flags: Use --no-console or --no-browser to restrict startups. Run marm-memory --help for full command lists.

Why MARM Memory

Your AI forgets everything. MARM Memory doesn't.

marm-memory gives your agents a private, shared memory for the context that normally gets lost between chats: decisions, research, fixes, notes, and project history. Switch from Claude Code to Codex or Gemini without losing the context already gathered.

It brings three things together:

• 🧠 Core Memory (8 tools) stores conversations, notes, notebook entries, and summaries so they stay searchable.
• 💻 Code Graph (6 tools) maps your repository so agents can find symbols, follow code paths, and understand the project without rereading it all. Point it at a repo once and it keeps itself current as you work.
• 🧩 Concept Graph (2 tools) connects people, decisions, errors, and ideas from your stored memories, with links back to relevant code when available. It builds itself as you store memories.

All 16 tools work over HTTP and STDIO. Your agents share the same local memory across sessions instead of starting from scratch each time. The bundled Console App provides a local control plane for memory, graphs, code context, distillation, runtime controls, and the integrated terminal. Indexing a repository creates its independent Code Graph, which you can explore from Knowledge Graph → Code Explorer even before storing any memories.

How It Works

See Performance & Scaling Benchmarks for retrieval latency, concurrency, and write-cost numbers, and Architecture & Internals for the mechanisms behind each layer.

MARM Console: Your Local Control Plane

Run marm-memory console to open the bundled web app at http://127.0.0.1:8002. It ships with MARM, needs no Node.js installation, stays on your machine, and works with the same local stores and MCP runtime your agents use.

Runtime CLI Commands

marm-memory is the local runtime manager installed with the Python package. These are the normal operational commands; use marm-memory <command> --help for flags and command-specific examples.

Daily runtime work

marm-memory fast-start-http                # start HTTP, Console, and open the browser
marm-memory fast-start-http --client cursor # also connect one client (add --transport stdio for STDIO)
marm-memory start                          # start or reuse the managed HTTP runtime
marm-memory start --profile swarm          # shared multi-agent preset
marm-memory stop                           # stop the managed runtime safely
marm-memory restart                        # restart the managed runtime
marm-memory status                         # inspect runtime, database, queue, and graph status
marm-memory logs --follow                  # follow bounded runtime logs
marm-memory console                        # start or reuse the bundled local Console

Transports and setup

marm-memory http                           # run HTTP in the foreground
marm-memory stdio                          # run the strict local MCP STDIO transport
marm-memory init                           # install the MARM skill into detected agents (project scan)
marm-memory init --g-claude                # install the skill into the home-folder claude directory
marm-memory doctor                         # diagnose the local install
marm-memory key init                       # create or reuse ~/.marm/.env without displaying the key
marm-memory key path                       # print the managed key-file path
marm-memory key reveal                     # explicitly display the managed key
marm-memory console --import-key           # open an authenticated local Console session
marm-memory upgrade --check                # compare the installed package with PyPI
marm-memory uninstall                      # preview package removal; always preserves ~/.marm

Knowledge, projects, and maintenance

marm-memory knowledge status               # Indexers, models, and how far behind automatic indexing is
marm-memory knowledge build --all          # Rebuild the whole concept graph (new memories index themselves)
marm-memory knowledge auto off             # Stop indexing memories automatically (on, off, status)
marm-memory projects list                  # List all tracked workspaces
marm-memory projects index <path>          # Add a repo to the code graph (kept current after that)
marm-memory projects status                # Inspect target repo graph readiness
marm-memory projects auto off              # Stop re-indexing repos automatically (on, off, status)
marm-memory maintenance status             # Check internal database optimization state
marm-memory maintenance embeddings migrate # Upgrade old 384-dim vectors to 512-dim
marm-memory maintenance chunks rechunk     # Recalibrate long memory text splits

Docker commands are documented separately below because they require explicit data mounts, network exposure, and key-handling choices.

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. Every timed path calls the shipped MARMMemory code, not a benchmark-local reimplementation. Sections 1-4 are timings from a single run of scripts/benchmarking/performance/bench_hotpath.py on local hardware; absolute milliseconds vary by machine, so treat the scaling shape as the signal. Section 5 is a separate accuracy benchmark (run_eval.py) measuring retrieval rather than speed, and its latest row is a controlled before and after, explained there.

1. Retrieval Latency Scaling

End-to-end recall_similar latency (includes query encoding).

Run-to-run variance at small $N$ is larger than the gap between adjacent sizes, which is why N = 250 reads slower than N = 500 here. Treat the trend from N = 1,000 upward as the real signal.

2. Encoder + Concurrency

• Cold model load: 893ms
• Warm encode: median 3.8ms, p95 4.3ms
• Concurrent recall: 10 gathered recalls completed in 151.5ms vs 176.0ms serial (gather/serial = 0.86). Do not read that as parallelism: repeated runs of this same benchmark land anywhere from 0.63 to 0.86, so the ratio is not stable enough to claim a speedup. The path is serialized around shared encoder and SQLite work by design, and any apparent gain is measurement noise.

3. Write-Time Ingestion Cost

• Consolidation off: median 6.5ms, p95 7.6ms
• Consolidation on: median 58.1ms, p95 106.5ms
• Tradeoff: write-time dedupe/clustering adds 9.0x median cost so recall stays fast and the store stays cleaner over time. Consolidation is off by default.

4. Recall Scaling: Full Scan vs Production Hybrid

Why recall stays flat as memory grows: Instead of scanning every vector, production recall uses an FTS keyword pre-filter to narrow the candidate pool, then re-ranks using a blended semantic + BM25 + temporal score. Both benchmark columns represent authentic asynchronous code paths timed with precomputed vectors to isolate retrieval speed from raw encoding overhead. Tests alternate execution to ensure completely unbiased cache conditions.

The full scan grows roughly linearly with $N$ while hybrid recall grows far more slowly, so the advantage still widens with session size. At very small $N$ the pre-filter is not worth its overhead and hybrid is slower.

5. LoCoMo Retrieval Accuracy

All 10 LoCoMo conversations are ingested through marm_log_entry (5,882 memories), then top-5 marm_smart_recall results are scored against 1,977 evidence-annotated questions. No answer-generation model or LLM judge is involved, so this measures whether the right memory is retrieved, not whether an agent answers correctly with it.

The last row is a controlled comparison, same build and data with the log lane as the only variable. That lane previously substring-matched the whole query against log topics and summaries, so a natural-language question never matched and it scored 0.0% on all 1,977 questions. It now tokenizes the query and reaches 53.3% on its own. Ranges rather than single figures because the semantic lane varies about half a point between runs, so a sub-point difference is not a result.

Multi-hop remains the weakest category at 44.9%, and single-hop evidence recall is 36.6% against a 66.2% any-hit rate, so the lane often surfaces some of a question's evidence rather than all of it. Reproduce with run_eval.py. It also reports MRR and nDCG@k for the ranked semantic lane; set MARM_RECALL_REFERENCE_TIME on the server so two runs rank near-ties identically.

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:

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.

MCP Client Setup for HTTP & STDIO

Manual pip install

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 for the full table.

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

pip install marm-mcp-server
marm-memory start
# 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.

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 Antigravity. STDIO stays a single local process with no port and no API key, and exposes the same 16 tools as HTTP.

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
marm-memory start --profile swarm

# HTTP shared server, heavier private swarm
marm-memory start --profile swarm-max

# HTTP trusted private lab/server, rate limiting disabled
marm-memory start --profile trusted

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

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.

If you installed MARM through pip, the product CLI can safely preview or run the same setup. It uses a loopback port by default, preserves ~/.marm, stores the generated key in ~/.marm/.env rather than shell history, and refuses to replace an existing container.

marm-memory docker command                 # preview the exact HTTP command
marm-memory docker run                     # create the managed HTTP container
marm-memory docker stdio-command           # print a Docker STDIO client command
marm-memory docker status
marm-memory docker logs --follow
marm-memory docker stop

# Optional: mount repositories read-only for code indexing.
marm-memory docker run --repo /absolute/path/to/repository

# Optional: preview or explicitly write a Compose configuration.
marm-memory docker compose
marm-memory docker compose --yes

The HTTP run, command, and compose commands accept the same operational flags:

For example:

# Shared local server with a custom data path and two repositories for indexing.
marm-memory docker command \
  --profile swarm \
  --data-dir /srv/marm-data \
  --repo /srv/projects/api \
  --repo /srv/projects/web

# Execute the reviewed command, pulling the image first.
marm-memory docker run --profile swarm --data-dir /srv/marm-data --pull

Docker STDIO is separate from Docker HTTP: marm-memory docker stdio-command uses docker run -i --rm, has no port and no bearer key, but still mounts the data directory so SQLite memory persists after the short-lived container exits. Use --data-dir and --tag with that command when needed. There are no separate docker key or docker mount commands; --env-file and --data-dir make those choices explicit in the generated HTTP command.

marm-memory docker pull only downloads an image. marm-memory docker maintenance embeddings migrate runs against the same data mount and refuses while the managed HTTP container is running. The helper is available only with the pip-installed marm-memory command; Docker-only users can use the raw commands below.

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

# --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 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 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

• Docker HTTP requires a key; Docker STDIO does not.
• If you get 401, verify key match and client restart after env var changes.
• For full key setup, rotation, and troubleshooting: INSTALL-DOCKER.md

Connect your client

Start the server (python -m marm_mcp_server), then wire up your client below. Every block assumes the default local install (no key). For Docker or exposed servers, add the Authorization: Bearer header shown in each client's collapsible.

claude mcp add --transport http marm-memory http://localhost:8001/mcp

Claude Code supports HTTP, SSE, and STDIO through claude mcp add; use HTTP for MARM. For STDIO: claude mcp add --transport stdio marm-memory-stdio marm-mcp-stdio.

Add to .vscode/mcp.json in your workspace. Use marm-memory-local for direct Python installs; marm-memory-docker for Docker or exposed/key mode.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "marm-api-key",
      "description": "MARM API Key for Docker or exposed server mode",
      "password": true
    }
  ],
  "servers": {
    "marm-memory-local": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    },
    "marm-memory-docker": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer ${input:marm-api-key}"
      }
    }
  }
}

Open .vscode/mcp.json, click Start above the server you want, then use Copilot Agent or any extension that consumes VS Code's native MCP registry.

Add to .cursor/mcp.json in your workspace. Cursor uses mcpServers, not VS Code's servers root.

{
  "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}"
      }
    }
  }
}

For Docker/key mode, launch Cursor with MARM_API_KEY set in the environment.

The Cursor CLI (agent) reads the same mcp.json files, so a server added for the editor is already available there. Run agent mcp list to check. A server in the global ~/.cursor/mcp.json loads without approval. A server in a project's .cursor/mcp.json asks you to trust the folder and approve it on first use, and headless runs need --trust --approve-mcps. If it lists no servers, look in mcp.json for an entry with an unknown type such as streamable-http: the CLI drops the whole file when one entry fails to parse. Install it with curl https://cursor.com/install -fsS | bash on macOS, Linux and WSL, or irm 'https://cursor.com/install?win32=true' | iex in Windows PowerShell.

Codex uses codex mcp add or TOML config at ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows).

# Direct Python install - no key needed
codex mcp add marm-memory --url http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required (set MARM_API_KEY in your shell first)
codex mcp add marm-memory --url http://localhost:8001/mcp --bearer-token-env-var MARM_API_KEY

[mcp_servers."marm-memory"]
url = "http://localhost:8001/mcp"
enabled = true
bearer_token_env_var = "MARM_API_KEY"

Grok Build (grok), xAI's terminal coding agent, supports STDIO and HTTP MCP servers and reads ~/.grok/config.toml. MARM sets bearer_token_env_var, so the key stays in your environment and never lands in the file.

# Direct Python install - no key needed
grok mcp add --transport http marm-memory http://localhost:8001/mcp

Docker or SERVER_HOST=0.0.0.0 (key required): set MARM_API_KEY, then add this to ~/.grok/config.toml (or .grok/config.toml for one project):

[mcp_servers.marm-memory]
url = "http://localhost:8001/mcp"
bearer_token_env_var = "MARM_API_KEY"

Grok Build also reads MCP servers from ~/.claude.json, .cursor/mcp.json, and project .mcp.json, so MARM may already load if Claude Code or Cursor has it. Run grok mcp list to see what it loaded.

Hermes Agent (hermes) by Nous Research reads MCP servers from mcp_servers in config.yaml: ~/.hermes/config.yaml on macOS and Linux, %LOCALAPPDATA%\hermes\config.yaml on native Windows, or $HERMES_HOME/config.yaml if you set it. It supports STDIO and HTTP and expands ${VAR} in headers, so the key stays in your environment or ~/.hermes/.env and never lands in the file.

# STDIO - no key needed
hermes mcp add marm-memory --command marm-mcp-stdio

# HTTP, direct Python install - no key needed
hermes mcp add marm-memory --url http://localhost:8001/mcp

Docker or SERVER_HOST=0.0.0.0 (key required): set MARM_API_KEY, then add this under mcp_servers in config.yaml:

mcp_servers:
  marm-memory:
    url: "http://localhost:8001/mcp"
    headers:
      Authorization: "Bearer ${MARM_API_KEY}"

Run /reload-mcp in Hermes, or start a new session, to load it.

OpenCode (opencode, installed with npm install -g opencode-ai) reads MCP servers from mcp in opencode.json or opencode.jsonc: ~/.config/opencode/ on every platform including Windows (%USERPROFILE%\.config\opencode), or $XDG_CONFIG_HOME/opencode/ if you set it, and opencode.json in a project root for one project. It supports STDIO (type: local) and HTTP (type: remote) and expands {env:VAR} in headers, so the key stays in your environment and never lands in the file. Remote servers try OAuth by default, so MARM writes oauth: false. OpenCode 2 nests servers under mcp.servers and still reads the layout below, and MARM writes into whichever layout the file already uses. Connecting from the Console rewrites the file as plain JSON, so comments in a .jsonc file are not kept, and the original is saved beside it as .marm-backup. Start a new OpenCode session to load it, and run opencode mcp list to check.

STDIO, no key needed:

{
  "mcp": {
    "marm-memory": {
      "type": "local",
      "command": ["marm-mcp-stdio"]
    }
  }
}

HTTP, direct Python install (no key needed):

{
  "mcp": {
    "marm-memory": {
      "type": "remote",
      "url": "http://localhost:8001/mcp",
      "oauth": false
    }
  }
}

Docker or SERVER_HOST=0.0.0.0 (key required): set MARM_API_KEY, then add the same HTTP entry with a header:

{
  "mcp": {
    "marm-memory": {
      "type": "remote",
      "url": "http://localhost:8001/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MARM_API_KEY}"
      }
    }
  }
}

Devin CLI (devin) and the Devin Local agent in Devin Desktop, the IDE formerly called Windsurf, read MCP servers from the same mcp_config.json: ~/.config/devin/mcp_config.json on macOS and Linux (or $XDG_CONFIG_HOME/devin/mcp_config.json if you set it), %APPDATA%\devin\mcp_config.json on Windows. Connecting once covers both. The older Cascade agent in Devin Desktop keeps its MCP servers in its own file under ~/.codeium, which MARM does not write. Devin CLI v3000.3 or later reads this dedicated file, and older builds keep mcpServers in config.json and migrate it on startup. devin mcp add saves to a gitignored project file unless you pass -s user.

# STDIO - no key needed
devin mcp add -s user marm-memory -- marm-mcp-stdio

# HTTP, direct Python install - no key needed
devin mcp add -s user marm-memory http://localhost:8001/mcp

Docker or SERVER_HOST=0.0.0.0 (key required): MARM has not confirmed that Devin expands environment variables in headers, so use STDIO, or add the key by hand under mcpServers in that file:

{
  "mcpServers": {
    "marm-memory": {
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

Zed reads MCP servers from context_servers in its user settings.json: ~/.config/zed/settings.json on macOS and Linux (or $XDG_CONFIG_HOME/zed/settings.json on Linux), %APPDATA%\Zed\settings.json on Windows. Run zed: open settings file from the command palette to open it. Zed has no add command, and MARM has not confirmed that Zed expands environment variables in headers, so keyed setups use STDIO. Connecting from the Console edits only the marm-memory entry as text, so comments and the rest of your settings stay as they were, and it restores the file if anything else changed. Zed lists the server under Settings, AI, MCP Servers, with a green dot when it is running. Zed's own agent reads the MARM skill from ~/.agents/skills once you install it from the Console.

STDIO, no key needed:

{
  "context_servers": {
    "marm-memory": {
      "command": "marm-mcp-stdio",
      "args": []
    }
  }
}

HTTP, direct Python install (no key needed):

{
  "context_servers": {
    "marm-memory": {
      "url": "http://localhost:8001/mcp"
    }
  }
}

Docker or SERVER_HOST=0.0.0.0 (key required): use STDIO, or paste the key into the entry by hand. Zed keeps it as plain text in settings.json:

{
  "context_servers": {
    "marm-memory": {
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

Cline CLI (cline, installed with npm install -g cline) reads MCP servers from ~/.cline/data/settings/cline_mcp_settings.json, the same file the Cline extensions in VS Code and JetBrains use (%USERPROFILE%\.cline on Windows, or $CLINE_DATA_DIR/settings if you set it). Cline's own MCP page still says ~/.cline/mcp.json, but the CLI never reads that file. HTTP entries need "type": "streamableHttp": leaving type out selects the legacy SSE transport. The extensions in VS Code and JetBrains show the server in their MCP Servers panel. Cline 4.x or later shares this file and moves an older file from VS Code's extension storage into it on first launch. Older builds keep reading their own file, so upgrade Cline first.

# STDIO - no key needed
cline mcp install marm-memory --yes -- marm-mcp-stdio

# HTTP, direct Python install - no key needed
cline mcp install marm-memory --yes --transport http http://localhost:8001/mcp

Docker or SERVER_HOST=0.0.0.0 (key required): MARM has not confirmed that Cline CLI expands environment variables in headers, so use STDIO, or add the key by hand under mcpServers in that file:

{
  "mcpServers": {
    "marm-memory": {
      "type": "streamableHttp",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

Antigravity CLI (agy) replaced Gemini CLI in June 2026. It supports STDIO and HTTP MCP servers. Use HTTP for MARM. The Antigravity IDE and 2.0 app read this same file (in the IDE, open "..." then MCP Servers, then Manage MCP Servers). Antigravity 2.x or later reads it. Older IDE builds used ~/.gemini/antigravity/mcp_config.json, and MARM writes that file only when it is the only one present.

# Direct Python install - no key needed
agy mcp add marm-memory --type http http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required
agy mcp add marm-memory --type http http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

Equivalent ~/.gemini/config/mcp_config.json (user scope) or project .agents/mcp_config.json. Antigravity reads serverUrl, not url or httpUrl, and does not expand ${VAR} in this file, so paste the real key:

{
  "mcpServers": {
    "marm-memory": {
      "serverUrl": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

# Direct Python install - no key needed
qwen mcp add --transport http marm-memory http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required
qwen mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

Equivalent .qwen/settings.json (project) or ~/.qwen/settings.json (user):

{
  "mcpServers": {
    "marm-memory": {
      "httpUrl": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

The Grok app (grok.com, iOS, Android) supports custom MCP servers: open grok.com/connectors, click New Connector, choose Custom, and enter your MARM URL. The xAI API supports Remote MCP Tools over Streamable HTTP or SSE only.

Both run on xAI's infrastructure, so localhost will not work. Expose MARM behind HTTPS (a tunnel or your own domain) and set MARM_API_KEY. MARM has not been tested through the app's connector form. For the API, send this tool payload:

{
  "type": "mcp",
  "server_url": "https://your-marm-domain.example.com/mcp",
  "server_label": "marm-memory",
  "authorization": "Bearer your-generated-key"
}

Full platform walkthroughs, key setup, and OS-specific notes: Windows · macOS · Linux · Docker/key mode · Other platforms

Using a client that isn't listed? Open an issue and let us know; client adapters are a first-class feature request.

Requirements

• Python: 3.10 or higher
• SQLite3: Included with Python (no separate install needed)
• Storage: ~100MB minimum for initial setup, scales with memory database size
• RAM: 512MB minimum (varies by concurrent clients and database size)
• OS: Windows, macOS, Linux

Data location

• Location: ~/.marm/ (Linux/macOS) or %USERPROFILE%\.marm\ (Windows)
• Contents: SQLite database with all memories, sessions, and notebooks; the concept graph lives in its own ~/.marm/index/ database
• Backup: Copy the entire ~/.marm/ directory to preserve all data
• Privacy: Everything stays on your machine, no cloud sync or external storage
• Knows which memories go unused: each memory records how often recall returned it and when, and the Console lists cold memories (GET /api/memories/cold?days=30) so old, never-recalled entries can be reviewed. Counting never slows or fails a recall and does not change ranking
• Credentials are redacted before storage: API keys, tokens, private keys and NAME=value secrets (a metadata field is read with its name, and a quoted value may hold spaces) in anything written to memory, the log, the notebook, or a review queue, and in every prompt sent to a local model, are replaced with [redacted:<kind>]; names and templates stay. A write that redacted something says so in its response as redacted: {count, kinds}, never the values. An identifier holding a credential (a session, project or platform name, a Session: marker, a notebook entry name) is refused rather than redacted, because a renamed identifier could not be looked up again. This is high-precision protection for common credential formats, not a guarantee that every secret is caught, and it applies to new writes only: existing data is not scanned or rewritten

Verify installation

Use the MCP server health endpoint for the fastest live check:

curl http://localhost:8001/health

Expected output includes server version, feature availability (semantic search status), database connection status, and service health status.

Complete MCP Tool Suite (16 Tools)

💡 Pro Tip: You don't need to manually call these tools! Just tell your AI agent what you want in natural language:

• "Claude, log this session as 'Project Alpha' and add this conversation as 'database design discussion'"
• "Remember this code snippet in your notebook for later"
• "Search for what we discussed about authentication yesterday"

The AI agent will automatically use the appropriate tools. Manual tool access is available for power users who want direct control.

🧠 Core Memory (8 tools)

🕸️ Code Graph (6 tools)

🧩 Concept Graph (2 tools)

All 16 tools are available on both HTTP and STDIO. Behind the tool surface, the server handles lifecycle setup, protocol refresh, docs indexing, date context, summary-cache maintenance, write queue handling, concept indexing, code re-indexing as repos change, project/platform attribution, and health checks automatically; none of those consume the agent's attention or tokens. The two graph engines start lazily on first use and never block the 8 core memory tools if they fail to start. See Architecture & Internals for the mechanisms.

Using MARM: Talk, Don't Call Tools

MARM handles lifecycle work internally. Docs and session state initialize on the first real tool call, and packaged docs are indexed into the marm_system memory namespace with source-file hash tracking, so your agent can answer MARM usage questions from memory itself.

Example Workflow: Cross-AI Research Project

A realistic workflow showing MARM in action. Scenario: you're researching authentication patterns for a new project using multiple AI clients.

Phase 1: Route Session (Claude)

You: "Claude, create a MARM session called 'auth-research-2025-01'"
Claude calls: marm_log_entry(entry="Session: auth-research")
Result: Session routed to auth-research-[today]. MARM lifecycle/docs initialize automatically.

Phase 2: Capture Research (Claude)

You: "Summarize OAuth2 vs JWT for API authentication and save it"
Claude calls: marm_log_entry(entry="Research: OAuth2 is token-based with refresh cycles, better for delegated access. JWT is stateless, good for microservices...", session_name="auth-research-2025-01")
Result: Research captured in the active session log and marked for summary-cache refresh

Phase 3: Add Reusable Reference (Claude)

You: "Save a JWT validation code snippet to my notebooks as 'jwt-validation-pattern'"
Claude calls: marm_notebook(action="add", name="jwt-validation-pattern", data="def verify_jwt(token):\n  # validation logic...")
Result: Reusable snippet stored for future projects

Phase 4: Recall Context (Gemini)

You: "Gemini, what authentication approaches did we research? Activate the JWT pattern."
Gemini calls: marm_smart_recall("authentication patterns", search_all=True)
Gemini calls: marm_notebook(action="use", names="jwt-validation-pattern")
Result: Gemini sees previous research + has JWT code available as context

Phase 5: Synthesis & Summary (Qwen)

You: "Qwen, pull everything from the auth research and create a summary"
Qwen calls: marm_smart_recall("authentication", session_name="auth-research-2025-01", limit=20)
Qwen calls: marm_summary(session_name="auth-research-2025-01")
Result: Qwen generates an implementation guide from all captured research

Phase 6: End Session (Claude)

You: "Log final decision - we're using JWT for APIs, and OAuth2 for user auth"
Claude calls: marm_log_entry(entry="DECISION: JWT for API auth, OAuth2 for user flows. Rationale: stateless APIs + delegated user access", session_name="auth-research-2025-01")
Result: Decision logged and searchable by all future AI clients

Result: Three different AI clients collaboratively researched a topic, shared insights, and documented decisions. All without re-explaining the project to each new AI.

Advanced patterns

Project Structure:
├── project-name-planning/          # Initial design and requirements
├── project-name-development/       # Implementation details
├── project-name-testing/           # QA and debugging notes
├── project-name-deployment/        # Production deployment
└── project-name-retrospective/     # Lessons learned

Knowledge base loop:

1. Capture: Use marm_log_entry for structured session learnings
2. Organize: Create themed sessions for knowledge areas
3. Synthesize: Regular marm_summary for knowledge consolidation
4. Apply: Convert summaries to marm_notebook(action="add", ...) entries

Multi-AI collaboration: each AI works in dedicated sessions on its strengths, uses marm_smart_recall to build on the others' work, then a collaborative session combines the insights.

• Session naming: Include the LLM name for cross-referencing
• Strategic logging: Focus on key decisions, solutions, discoveries, configurations
• Global search: Use search_all=True to search across all sessions
• Natural language search: "authentication problems with JWT tokens" beats "auth error"
• Layered recall depth: detail=1 returns a short summary view (~200 chars), detail=2 a larger context view (~500 chars), detail=3 full memory content
• Notebook stacking: Combine multiple entries for complex workflows
• Compaction: Let MARM surface compaction candidates, then use marm_compaction to stage, review, apply, or discard summaries
• Session lifecycle: Start → Work → Reference → Review staged compaction when MARM asks

Understanding MARM Memory

Two searches, two very different problems, one tool:

User: "I discussed machine learning algorithms yesterday"
MARM Search: Finds related memories about "ML models", "neural networks", "AI training"

User: "What was the COMPACTION_TRIGGER_COUNT setting?"
MARM Search: Finds the exact config memory even if the rest of the text differs

The first query is about meaning, so MARM reranks candidates with local vector embeddings — RAG-style semantic search without a hosted vector database. The second is syntax-shaped (a config key), so MARM detects that automatically and routes it through deterministic exact matching instead. This exact-retrieval lane is the difference between a memory system that works in demos and one that answers the questions developers actually ask: config keys, CLI flags, file paths, API names, error strings. Pure-semantic memory systems fail at exactly those queries.

MARM uses filter→rerank hybrid recall plus an exact retrieval lane:

1. Exact lane (exact_mode="auto", the default): config keys, CLI flags, file paths, API/tool names, dotted namespaces, HTTP routes, URLs, and quoted command strings are detected and routed through deterministic FTS5 BM25 with a LIKE fallback. No embeddings involved, so results are stable and literal.
2. Filter→rerank lane: natural-language queries first pull a bounded candidate set from the FTS index (FTS_CANDIDATE_LIMIT, default 200), then semantic embeddings rerank those candidates by meaning. Conservative temporal weighting gives fresher memories a modest boost when matches are otherwise close.
3. Bounded semantic fallback: when FTS coverage is weak or unusable, MARM falls back to a bounded semantic scan (RECALL_SCAN_LIMIT). If the response includes recall_scan_truncated=true, the fallback hit its cap; narrow the session/query or raise the env var for larger stores.
4. Chunk-aware scoring: long memories (roughly 180+ words) are embedded as overlapping chunk rows internally, and recall collapses chunk scores back to one parent memory using the best-matching chunk. Both the rerank lane and the fallback lane are chunk-aware.

This is why recall latency stays nearly flat as the store grows (see benchmarks): the semantic rerank always scores a bounded set instead of scanning every embedding.

Exact recall control: exact_mode="auto" is usually right. Use exact_mode="exact" when a query must match literal text such as RECALL_SCAN_LIMIT, --generate-key, or settings.py. Use exact_mode="semantic" when a syntax-looking query should still be treated as meaning-based recall.

Memory types & classification

1. Context Logs - Auto-classified conversation memories
2. Manual Entries - Explicitly saved important information
3. Notebook Entries - Reusable instructions and knowledge
4. Session Summaries - Compressed conversation history

MARM automatically categorizes content on write: Code (programming snippets and technical discussions), Project (work conversations and planning), Book (literature, learning materials, research), and General (everything else).

Project & platform attribution

MARM stores nullable project and platform columns on memories, log entries, and notebook entries. The project is detected from the working directory and the platform from the connecting client (Claude Code, VS Code, Cursor, ...); MARM_PROJECT and MARM_PLATFORM override detection. marm_smart_recall(project=..., platform=...) scopes recall without changing the default unfiltered behavior, so one shared server can hold several projects without cross-contamination.

Distilling a conversation into memory

Storing a memory is an explicit act, so the things worth keeping are the ones somebody remembered to keep. marm_distill works the other way round: hand it a stretch of raw conversation and it proposes the durable facts in it.

marm_distill(action="propose", session_name="release-notes", text="<the conversation so far>")
marm_distill(action="review")                       → the staged proposals and their verdicts
marm_distill(action="apply", proposal_id="...")     → writes that one as a memory
marm_distill(action="discard", proposal_id="...")   → rejects it, permanently

Every proposal is resolved against what is already stored and carries a verdict: new, duplicate, or near. near is the one that needs a person: it is close enough to a stored memory to be related, and a similarity score cannot say whether it refines that memory, contradicts it, or is simply adjacent. The proposal is shown beside the memory it resembles so a reviewer can decide which.

By default it proposes and never writes. propose stages into a review queue and only apply creates a memory; the one opt-in exception is review_mode="guardrails" with the operator's auto-apply switch on, which applies a proposal only when every deterministic check passes. That is deliberately the same shape as marm_compaction, and for the same reason: a similarity score is not evidence enough to write memory unattended, and anything that does so on such a score fills a store with near-misses faster than it fills it with facts. A discarded proposal is never proposed again, enforced by a unique constraint rather than by convention — re-offering something a reviewer already rejected is how a review queue stops being read. It also makes re-running propose over the same text a no-op, which is what makes it safe to call at the end of every session.

How the text is written. With no local model reachable, this selects sentences that already read like durable facts and normalises them, rather than composing new ones — so a fact spread across three turns, or implied but never stated, will not be proposed. It finds what was said plainly, not what was meant. That is a real limitation, and also a reasonable fit: a MARM memory is a headline, and a headline is usually a sentence someone already typed. Asked to (use_llm=true) with local generation enabled and a model reachable, it writes the fact instead and keeps the verbatim span it came from; a proposal's mode reports which of the two happened. See Optional local generation.

While proposals sit unreviewed, MARM can attach a review request to a tool response rather than waiting to be asked. The request names one proposal and asks for a decision on it — apply or discard — and only one is attached per cooldown window, server-wide, so a batch of proposals cannot put a request on every response. MARM_DISTILL_NUDGE=0 turns that off; the cooldown and budget are tunable in the configuration reference.

Knowledge Graphs: Code & Concepts

MARM ships two graph systems that complement the memory store: a code graph that understands your repository's structure, and a concept graph that understands what your stored memories are about. When both are indexed for the same project, concept entities cross-link to code symbols.

Code Graph: repo indexing and code lookup

marm-graph is bundled into both transports. It indexes a repository once, then lets agents ask code-structure questions without repeatedly scanning files:

Use marm_graph_index to index this repository.
Then use marm_code_context when the question is how something works or what a change would touch.
Use marm_code_lookup when you need a specific symbol, file, or source snippet.
Use marm_graph_trace for call paths, marm_graph_architecture for an overview, and marm_graph_impact for change-risk checks.

The recommended agent workflow: index once, then marm_code_context for a task-shaped question, marm_code_lookup before broad file reads, marm_graph_trace when callers/callees or data-flow context matters, marm_graph_architecture for orientation, and marm_graph_impact before risky refactors. One graph query replaces dozens of grep/read cycles, which is where the token savings come from.

Composed context: marm_code_context

The other five tools answer one question each, and an agent typically chains them: search for a name, trace its callers, read each file, then look for anything memory recorded about them. marm_code_context runs that chain server-side and returns the result as one payload:

marm_code_context(task="how does the write queue serialise concurrent writes?")

Six steps: seed with lexical and semantic search, expand along callers and callees, rank that subgraph with personalised PageRank, read the winners' source off disk, recall the memories and memory→symbol links attached to them, and budget the result down to a character limit with the decisive material first.

Step three is the one plain search cannot do. Lexical search answers "which symbols mention these words", which is not the question an agent is asking; a symbol nothing calls and nothing references ranks below one sitting at the centre of the relevant neighbourhood, even when both mention the terms equally. Step five is the one a pure code index structurally cannot do — it carries why the code is the way it is, not only what it says.

detail trades size for structure. 1 (the default) returns the markdown and notes: what an agent needs, and nothing twice. 2 adds symbol and memory metadata — names, files, lines, scores, and the provenance that records whether a symbol was seeded from the task or pulled in along a call edge — without repeating the source already in the markdown. 3 adds source and memory text as structured fields too, which is what a renderer wants and what the Console asks for. MARM_CODE_CONTEXT_DETAIL moves that default for every agent at once. include_graph is a separate switch on a different axis, off by default: it returns the ranked edge list for visualisation, which nothing else reads.

One constraint worth knowing: traces resolve by qualified name. A bare name matching two symbols comes back as status: "ambiguous" with no edges rather than a guess, which leaves ranking with nothing to work on and collapses the result to plain search order.

answer=true goes one step further and answers the task in prose from the composed context alone — see Optional local generation.

Once a repository is indexed, MARM keeps it current on its own. A filesystem watcher notices a save, a commit, a branch switch, or a merge and re-indexes shortly after, debounced so a burst of changes becomes one pass rather than one per file. A periodic reconciliation pass catches anything a watcher event missed and is the only trigger for a directory that is not a git repo. To index only on request instead:

marm-mcp-server projects auto off

An agent can do the same with marm_graph_index(action="auto_off"), and action="auto_status" reports what is being watched and when each project was last indexed. The switch persists across restarts and beats the GRAPH_AUTO_INDEX environment variable.

Under the hood, the engine is codebase-memory-mcp (MIT), a zero-dependency static binary that parses 158 languages through tree-sitter with Hybrid LSP type resolution for the major ones, indexes an average repository in seconds, and answers symbol search and call tracing in well under a second. Measured on a 149,107-node graph over the persistent connection MARM holds: symbol search 146ms, call tracing 67ms, and the full architecture overview 1.23s, which is the one query that is not sub-second. MARM pins a specific release, verifies its tool schema on startup, and routes the upstream tool set through 6 focused MCP tools so the model surface stays small. The graph backend starts lazily on first graph-tool use, so memory, logging, notebook, and summary tools still start fast. In Docker, the engine binary is baked into the image; local pip installs fetch it on first graph use (~269MB, one time).

Degraded mode: if the graph engine fails to start (no network for the first-run download, disk full, schema drift) or GRAPH_ENABLED=false is set, graph tools return {"status": "error", "message": "graph backend unavailable"} while the other 10 tools keep working normally. Graph failures can never take down memory.

Concept Graph: what your memories are about

MARM extracts a knowledge graph from the memories you store, producing typed entities (concepts, decisions, patterns, errors, tools, people, organizations) connected by typed relationships (fixes, implements, depends_on, uses, causes, replaces, extends). This happens on its own: storing a memory queues it, and a background worker adds it to the graph roughly 30 seconds later. marm_concept_build is still there for a full or scoped rebuild. Once there is a graph, marm_smart_recall adds bounded related entities, relationships, and linked code as a graph_context sidecar without changing primary memory ranking. marm_concept_recall remains available for explicit graph exploration:

marm_concept_recall(query="write queue")            → the entity, its relationships, linked code symbols
marm_concept_recall(query="related to SQLite", depth=3) → multi-hop traversal of everything connected

How to use it:

• Automatic by default: new memories reach the graph without a tool call. Set CONCEPT_AUTO_INDEX=false to go back to manual builds only, which stops the worker but keeps recording queue rows, so turning it back on picks up everything written while it was off; CONCEPT_INDEX_DEBOUNCE_SECONDS (30) and CONCEPT_INDEX_BATCH_SIZE (20) control the pace.
• Safe on both transports at once: a leased lock in the memory database keeps a rebuild in one process from dropping graph tables while another process is writing to them. A build that finds the graph busy says so instead of colliding.
• Failure never reaches your memories: indexing runs on a durable queue outside the write path. Extraction problems retry, a memory that fails repeatedly is parked with its error, and the memory itself stores and recalls normally throughout.
• Linked code says when it changed: each linked symbol carries a freshness of changed once its code differs from when MARM first linked it, so a memory about it may be out of date; unchanged; or unknown when no safe fingerprint could be taken. The fingerprint ignores whitespace, blank lines and re-indentation, so it is a practical source-change signal rather than semantic equivalence, and changed means the code may have moved on, not that the memory is wrong. A link is fingerprinted only after a completed re-index, and only when its file has not been saved since that index began; changed stays set once seen.
• Clearing a backlog costs some recall speed: entity extraction is CPU-bound, so while the worker is working through a queue, measured recall goes from ~8ms to ~16ms median on a real 768-memory corpus. Writes are unaffected. It only applies while a backlog is draining, which for most people is once, after the upgrade rebuild. Reproduce it with scripts/benchmarking/performance/bench_concept_worker.py --from-live.
• Build for the backlog: marm_concept_build scoped to a session_name, project, or search_all=True indexes memories stored before automatic indexing existed, and rebuilds after an upgrade that requires one.
• Upgrade twice so far: graphs built before platform attribution, or before compaction sources replaced summaries as the indexed rows, require marm_concept_build(search_all=True). A full build backs up and resets only the derived concept database; targeted builds refuse to guess platform ownership.
• Older names are flagged, not rewritten: graphs built before extraction stopped keeping markdown can still hold names such as . The Concept Graph Manager counts them with a read-only check and offers , which runs the usual reset and then a global build. Nothing is renamed in place.

This fills the cross-session structure gap that flat memory search leaves open: sessions organize memories, but the concept graph connects them, so "what depends on the write queue?" is answerable even when the answer spans five sessions from three different agents.

Architecture & Internals

Everything above runs on a small number of deliberate mechanisms. This section is the full map, so you (or your agent) never have to guess what the server is doing.

Storage engine

• SQLite in WAL mode at ~/.marm/marm_memory.db with a connection pool (5 connections). WAL keeps readers unblocked during writes, which matters when several agents recall while one writes.
• FTS5 full-text index (memories_fts) is maintained as an external-content table over the memories table and powers both the exact lane (BM25) and the filter stage of hybrid recall.
• Chunk storage: memories past ~180 words are split into overlapping 150-token chunks (50-token overlap) in a memory_chunks table, each with its own embedding. Recall scores chunks and collapses to the parent memory.
• Embeddings come from the fastembed-backed jinaai/jina-embeddings-v2-small-en encoder: 33M parameters, 512 dimensions, an 8,192-token context window, and an Apache-2.0 license. It does not require separate query/document text prefixes. The encoder is lazily loaded on first semantic use and serialized behind a lock so concurrent encodes can't corrupt each other. If it is unavailable, writes still succeed; memories are stored without embeddings until it loads. Semantic scoring runs as a single NumPy batch (matrix cosine) rather than a Python loop.
• The concept graph gets its own database (~/.marm/index/marm_index.db) and its own pool, reusing the same pool implementation but never sharing connections with the memory store. Deliberate isolation: an experimental graph build must not be able to stall the production WAL. The one exception is the indexing queue, which lives in the memory database on purpose so a memory and its indexing task commit together; the graph itself stays derived and disposable.

Write path

• Serialized write queue (enabled by default): all memory writes flow through one internal async worker, eliminating SQLite writer contention under multi-agent load. The queue is generic; compaction applies go through the same worker, so there is exactly one writer no matter which subsystem is writing. MAX_QUEUE_SIZE bounds it.
• Write-time consolidation (opt-in, CONSOLIDATION_ENABLED=1) runs two layers before a memory lands:
  • Layer 1, exact dedup: a SHA-256 hash of normalized content is checked within the session; hash hits are verified against the actual content before deduplicating, so a hash collision stores a new row instead of silently merging different content.
  • Layer 2, semantic merge: near-duplicates above CONSOLIDATION_THRESHOLD cosine similarity are merged rather than accumulated. This never blocks a write; if the encoder isn't available, the write proceeds unconsolidated.
  • The tradeoff is measured and published: roughly 9x median write cost (58ms vs 6.5ms) in exchange for a store that stays clean, because reads dominate memory workloads. See section 3 of the benchmarks above.
• Concept indexing is a durable outbox: a write records an indexing task in the same transaction as the memory, so a memory cannot exist without one. A background worker drains that queue and writes the concept graph. Nothing on the write path waits for extraction, and a process killed mid-extraction loses no work because the task is a row rather than an in-memory job. Both transports run a worker, so the two coordinate through a leased lock in the memory database rather than an in-process lock, which would not span them.
• Compaction (opt-in, COMPACTION_ENABLED=1) is Layer 3: after enough writes in a session, a background pass detects clusters of memories that restate each other: every pair must clear the cosine-similarity threshold and share most of its words, gated by minimum cluster size, minimum age, and an active-session grace period so it never compacts work in flight. MARM then injects a bounded request asking the connected agent to summarize each cluster: candidates → stage → review → apply or discard. Source memory IDs are preserved on apply, so compacted summaries stay traceable to their originals. Staged summaries expire (COMPACTION_STAGING_TTL_HOURS), nudges are capped and cooldown-limited, and the injection has a byte budget. The design is honest about what LLMs are for: MARM detects, the agent summarizes, and a human-reviewable stage/apply/discard loop gates the destructive step.

Recall path

Covered in Understanding MARM Memory: exact lane (FTS5 BM25 + LIKE fallback), filter→rerank (bounded FTS candidates → batch semantic rerank → temporal blend), bounded semantic fallback with an explicit truncation flag, and chunk-collapse scoring. Recall depth (detail=1/2/3) controls how much of each memory is returned, and every MCP response passes through a 1MB response limiter that truncates content intelligently instead of breaking the protocol.

Code graph subprocess protocol

The bundled graph engine runs as a supervised child process, not an import:

• Transport: newline-delimited JSON-RPC 2.0 over the child's stdio, with a verified handshake (initialize → capture server version → initialized notification).
• Envelope care: responses are scanned for the first JSON-parseable content item rather than assuming index 0, because the upstream binary can prepend an update notice. Tool errors arrive as result.isError, not JSON-RPC errors, and are converted to clean {"status": "error"} dicts with the upstream's own remediation hint attached.
• Serialization: one lock guards each write+read round trip on the single st