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

Quick Start
Why MARM Memory
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

Install and initialize with your preferred agent profiles:

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

Also available: --g-qwen and --g-kiro. Run without flags to install into your current project folder instead of home

Hand off to your AI companion. Tell your agent:

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

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, gemini, or qwen). For Codex, use codex mcp add marm-memory --url http://localhost:8001/mcp instead.

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`

⚡ 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 (7 tools) stores conversations, notes, notebook entries, and summaries so they stay searchable.
💻 Code Graph (5 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 14 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 browsable view of Memories, the Knowledge Graph, and Indexed Projects, including progress for graph builds and repository indexing.

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 for retrieval latency, concurrency, and write-cost numbers, and Architecture & Internals for the mechanisms behind each layer.

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 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) and reports two runs, for the reason given there.

1. Retrieval Latency Scaling

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

Session Size ($N$)	Min Latency	Median Latency	p95 Latency
N = 100	7.4 ms	7.9 ms	9.4 ms
N = 250	11.9 ms	13.5 ms	15.4 ms
N = 500	10.9 ms	11.8 ms	13.4 ms
N = 1,000	13.3 ms	13.5 ms	15.6 ms
N = 2,000	17.5 ms	18.2 ms	19.6 ms
N = 4,000	23.8 ms	25.9 ms	30.9 ms

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.

Session Size ($N$)	Full Semantic Scan	Production Hybrid	Speedup	FTS candidates
N = 100	3.3 ms	6.6 ms	0.5x	85 / 200
N = 500	16.3 ms	11.6 ms	1.4x	200 / 200
N = 1,000	31.1 ms	14.7 ms	2.1x	200 / 200
N = 2,000	63.5 ms	19.0 ms	3.3x	200 / 200
N = 4,000	127.2 ms	29.1 ms	4.4x	200 / 200
N = 10,000	316.7 ms	53.8 ms	5.9x	200 / 200

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

Configuration	Any evidence hit	All evidence hit	Mean evidence recall
MiniLM baseline	37.5%	29.5%	not published
Jina v2 Small (v2.29.0)	53.0%	43.4%	47.6%
Recent (v2.33.1)	62.9 - 63.5%	53.1 - 53.5%	57.4 - 57.9%

Performance gains are isolated to the blended retrieval pipeline and localized vector space, ensuring high multi-hop recall accuracy without relying on cloud-hosted LLM judges. Reproduce the full benchmark using 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.

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, 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 Gemini CLI. STDIO stays a single local process with no port and no API key, and exposes the same 14 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:

Flag	Purpose
`--data-dir <absolute path>`	Persistent host directory mounted at `/home/marm/.marm`. Defaults to `~/.marm`; this holds memory, indexes, logs, and the managed key file.
`--env-file <path>`	Explicit Docker env file. It must already contain `MARM_API_KEY`; without this flag, MARM uses `~/.marm/.env` and creates a key there only when `docker run` or `docker compose --yes` needs one.
`--port <number>`	Host HTTP port. Default: `8001`.
`--expose-network`	Bind the host port to `0.0.0.0` instead of loopback. This is deliberate network exposure; configure a firewall and TLS proxy.
`--profile standard\|swarm\|swarm-max\|trusted`	Select the same write-queue and rate-limit preset as native HTTP startup.
`--rate-limit-rpm <number>`	Override the selected profile's HTTP rate limit. `0` disables rate limiting.
`--repo <absolute path>`	Repeatable read-only repository mount for code indexing. MARM reports each corresponding `/workspace/repo-N` path to index inside the container.
`--tag <tag>`	Official image tag. Default: `latest`.
`--pull`	Pull the selected image before creating a new HTTP container.
`--name <name>`	Managed container name. MARM refuses to replace an existing container with that name.
`--memory <limit>` / `--cpus <limit>`	Optional Docker resource limits.
`--dry-run`	`docker run` only: print the planned command without creating a container or key file. `docker command` is always a preview.

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.

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"

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

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

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

{
  "mcpServers": {
    "marm-memory": {
      "httpUrl": "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"
      }
    }
  }
}

xAI connects from its own infrastructure, so localhost will not work. Expose MARM behind HTTPS and set MARM_API_KEY.

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

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 (14 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 (7 tools)

Tool	What it does	Key parameters
`marm_smart_recall`	Hybrid memory recall with an additive, bounded concept/code graph sidecar when a compatible graph exists	`query`, `limit`, `session_name`, `search_all`, `detail=1/2/3`, `project`, `platform`, `exact_mode`
`marm_log_entry`	Add structured session log entries; each entry is also embedded into semantic memory so `marm_smart_recall` can find it	`entry`, `session_name`
`marm_log_show`	Display all entries and sessions, with filtering	`session_name`
`marm_delete`	Delete a log session, log entry, or notebook entry	`type`, `target`, `session_name`, `project`, `platform`
`marm_summary`	Cached, paste-ready session summaries with intelligent truncation	`session_name`
`marm_notebook`	Session-scoped scratch pad plus promotion to a permanent, graph-linked doc	`action="add"\|"use"\|"show"\|"status"\|"clear"\|"save"`, `name`, `data`, `session_name`, `project`, `platform`
`marm_compaction`	Agent-assisted memory cleanup with a reviewable audit trail	`action="status"\|"candidates"\|"review"\|"stage"\|"apply"\|"discard"`

🕸️ Code Graph (5 tools)

Tool	What it does	Key parameters
`marm_graph_index`	Index a repo into the code-structure graph, check status, list projects, or turn automatic re-indexing on and off	`repo_path`, `project`, `action`
`marm_code_lookup`	Find symbols, text patterns, or a symbol's source; use instead of grep/glob	`kind="auto"\|"symbol"\|"text"\|"snippet"`
`marm_graph_trace`	Trace call paths and data flow from a function	`direction`, `mode`
`marm_graph_architecture`	Architecture overview: modules, node/edge breakdown, schema	`project`
`marm_graph_impact`	Blast radius of code changes: git diff → affected symbols + risk	`since`, `base_branch`, `depth`

🧩 Concept Graph (2 tools)

Tool	What it does	Key parameters
`marm_concept_build`	Rebuild the graph, or index memories stored before automatic indexing. New memories are indexed on their own	`session_name`, `project`, or `search_all=True` (one required)
`marm_concept_recall`	Explicitly query entities, relationships, and linked code symbols	`query`, `depth` (1-5), `direction`, `project`, `platform`

All 14 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 7 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-dev

Marm Memory

At a glance

README

Table of Contents