Contributions welcome! Browse open issues to contribute, or join the MARM Discord to share workflows, get setup help, and connect with other builders.
Table of Contents
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 autom