lyellr88/marm-memory

Important Message - marm-console has been added but it is not fully active yet coming soon!

Table of Contents

• Why MARM Memory
• Performance & Scaling Benchmarks
• Quick Start
• Complete MCP Tool Suite
• Using MARM: Talk, Don’t Call Tools
• Understanding MARM Memory
• Knowledge Graphs: Code & Concepts
• MARM Dashboard
• Architecture & Internals
• Troubleshooting
• Contributing
• Project Documentation

Why MARM Memory

Your AI forgets everything. MARM Memory doesn’t.

marm-memory is a high-performance 3-in-1 AI Memory Framework that solves conversational drift, context pollution, and agent amnesia. Instead of juggling fragmented tools, it natively fuses three context layers into a single local runtime:

• 🧠 Core Memory (7 Tools) — long-term episodic memory, session logs, notebooks, and intelligent summaries via local vector embeddings and deterministic exact matching
• 💻 Code Graph (5 Tools) — instant repo indexing, symbol lookup, and tree-sitter syntax analysis, powered by the codebase-memory-mcp static binary wrapper
• 🧩 Concept Graph (2 Tools) — extracts entities and typed relationships from stored history, linking developer decisions straight back to source code symbols

One query resolves what was decided, why, and where it lives — no traffic-cop routing across isolated tools. Claude Code, Codex, Gemini, Qwen, Cursor, and VS Code agents share the same persistent memory server across sessions and long-running multi-agent projects, with all 14 tools bundled over both HTTP and STDIO.

Under the hood: a serialized SQLite WAL write queue kills multi-agent swarm contention, write-time consolidation merges duplicates, and hybrid semantic + full-text retrieval keeps recall sharp as memory grows. Agent-assisted compaction keeps context windows clean without losing traceability, and the local marm-console web app gives you real-time visual telemetry to browse and debug your entire memory layout.

How It Works

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

Start Now

Recommended: guided setup with marm-init

The easiest way to install MARM is to let your agent do the setup with you. marm-init turns the usual MCP setup mess into one guided conversation: Python or Docker, HTTP or STDIO, local or remote server, API keys, config paths, dashboard startup, and multi-agent linking for Claude, Codex, Gemini, Qwen, Cursor, VS Code, and other MCP clients. No hunting through install docs, no guessing which config file your client uses, and no rewriting the same connection by hand for every agent.

npx degit Lyellr88/marm-memory/skills

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

Manual pip install

pip install marm-mcp-server

Performance & Scaling Benchmarks

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

1. Retrieval Latency Scaling

2. Encoder + Concurrency

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

3. Write-Time Ingestion Cost

• Consolidation off: median 10.3ms, p95 11.6ms
• Consolidation on: median 42.0ms, p95 46.3ms
• Tradeoff: write-time dedupe/clustering adds 4.1x median cost so recall stays fast and cleaner over time.

4. Hybrid Search Scaling

Benchmarks used a throwaway real SQLite database and the live fastembed-backed all-MiniLM-L6-v2 encoder on local hardware. Reproduce them: scripts/benchmarking/performance/bench_hotpath.py

5. vs Competitors: Architecture

MARM targets a specific niche: local-first memory for MCP-connected coding agents, not general personalization memory or a full agent runtime. Here’s how it differs architecturally from established names in AI agent memory:

Disclaimers & Accuracy: Competitor landscapes evolve rapidly. The matrix above reflects core architectural traits as of Q3 2026, based on public documentation and READMEs, not internal testing of each system. If any data point regarding an alternative framework has changed or is misrepresented, please open an issue or submit a Pull Request to update the table. We actively welcome corrections from peer maintainers.

🚀 Quick Start for MCP (HTTP & STDIO)

Manual pip install

pip install marm-mcp-server

Use this quick rule of thumb to choose your setup

• Local HTTP/STDIO = fastest single-machine setup.
• Docker HTTP = shared/always-on server (key required).
• Docker STDIO = private containerized local use (no HTTP key).

Swarm / multi-agent note: The write queue is enabled by default to serialize memory writes through one worker. For shared HTTP deployments, use --swarm (200 RPM) or --swarm-max (600 RPM) when starting the server. --trusted disables rate limiting entirely for private deployments. STDIO is still best for private single-agent/local use. See Swarm & multi-agent presets for the full table.

---

---

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.

Full platform walkthroughs, key setup, and OS-specific notes: Windows · 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.

MARM Demo

MARM gives AI agents persistent long-term memory, shared cross-session context, write-queue safety, swarm presets, and hybrid semantic + exact recall so commands, config keys, and project meaning all stay reachable.

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)

🕸️ Code Graph (5 tools)

🧩 Concept Graph (2 tools)

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

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.

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.

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_lookup when you need symbols, files, or source snippets.
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_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. Re-index after meaningful code changes. One graph query replaces dozens of grep/read cycles, which is where the token savings come from.

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 structural queries in under a millisecond. MARM pins a specific release, verifies its tool schema on startup, and routes its 14 upstream tools through 5 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 9 tools keep working normally. Graph failures can never take down memory.

Concept Graph: what your memories are about

MARM can extract a knowledge graph from the memories you’ve already stored. marm_concept_build runs entity and relationship extraction over stored memory content, producing typed entities (concepts, decisions, patterns, errors, tools, people, organizations) connected by typed relationships (fixes, implements, depends_on, uses, causes, replaces, extends). marm_concept_recall then answers questions like:

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:

• Build first: call marm_concept_build scoped to a session_name, project, or search_all=True. There is no data until a build has run at least once. Builds are explicit and on-demand, not a live hook into the write path; re-run after logging significant new memories.
• Bounded by design: each build is row-capped (CONCEPT_BUILD_ROW_CAP, default 500) so a huge store can’t turn one tool call into a runaway job.
• Code cross-linking: when the code graph has indexed the same project, concept entities that match code symbols get linked, connecting “what we decided” to “where it lives in the code.”
• Optional dependency: real extraction needs the [concepts] extra (pip install marm-mcp-server[concepts] plus python -m spacy download en_core_web_sm). Without it, both concept tools stay registered and return entities_extracted: 0 instead of erroring. Base installs carry no spaCy dependency.
• Isolated storage: the concept graph lives in its own SQLite database (~/.marm/index/marm_index.db) with its own connection pool, so concept-graph writes can never block or corrupt the production memory database.

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.

MARM Dashboard

A local web UI for browsing and managing your MARM memory. It is bundled with marm-mcp-server and mounts at /dashboard when the HTTP server starts.

Start MARM HTTP, then open the dashboard:

python -m marm_mcp_server
# browser: http://localhost:8001/dashboard

Docker uses the same unified image and key:

docker run -d --name marm-mcp-server \
  -p 127.0.0.1:8001:8001 \
  -e MARM_API_KEY=your-key \
  -v ~/.marm:/home/marm/.marm \
  lyellr88/marm-mcp-server:latest
# browser: http://localhost:8001/dashboard

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 a fastembed-backed all-MiniLM-L6-v2 encoder, lazily loaded on first semantic use and serialized behind a lock so concurrent encodes can’t corrupt each other. If the encoder is unavailable, writes still succeed; memories are simply 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.

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 4x median write cost (still ~42ms) in exchange for a store that stays clean, because reads dominate memory workloads.
• Compaction (opt-in, COMPACTION_ENABLED=1) is Layer 3: after enough writes in a session, a background pass detects clusters of related memories using cosine similarity plus union-find connected components, 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 stdin pipe; async callers go through asyncio.to_thread so the event loop never blocks on subprocess IO.
• Crash recovery: stderr is drained on a background thread, child EOF/crash is detected, and the process is transparently respawned on the next call. Timeouts are deliberately not treated as crashes; a long index run may still be working, and killing it would destroy in-flight work.
• Supervision: a lazy singleton supervisor owns the client for the process lifetime. Startup is triggered by the first graph-tool call, never raises into the MCP layer, and verifies the pinned binary’s tool schema so upstream drift is caught at startup instead of mid-call.

Security & rate limiting

• Two-mode auth gate: keyless on loopback (127.0.0.1), MARM_API_KEY (Bearer) mandatory the moment the server is network-exposed (SERVER_HOST=0.0.0.0, Docker). --generate-key produces one. Safe by default, zero setup friction locally.
• IP-based rate limiting with sliding windows and temporary blocks, tuned through CLI presets rather than a config maze (table below).
• Local-first: everything lives under ~/.marm/; no cloud sync, no telemetry, no external storage.
• Graceful shutdown: SIGTERM/SIGINT handlers drain and close the connection pool cleanly, and an internal event system runs automation callbacks with per-callback error isolation and timeouts so one bad hook can’t wedge the server.

Swarm & multi-agent presets

The write queue serializes memory writes regardless of preset; swarm flags tune the HTTP rate limit on top of that. The queue controls write ordering; consolidation and compaction are separate memory-maintenance layers. This stack (WAL + pooling + one serialized writer + RPM presets) is intentionally scoped to “SQLite, many agents, one machine”; distributed multi-node memory is out of scope for the current design.

Self-maintaining documentation

Packaged docs are indexed into the marm_system memory namespace on startup and refreshed every 50 tool calls, with source-file hash tracking so unchanged docs are skipped and changed or deleted rows are re-indexed. Connected agents can answer MARM usage questions with marm_smart_recall instead of you pasting docs at them.

Configuration reference

Troubleshooting

For memory behavior, transports, supported clients, compaction, and backup questions, see the FAQ.

⭐ Star the Project

If MARM helps with your AI memory needs, please star the repository to support development!

Contributing

MARM welcomes contributors at every level. Code helps, but so do docs, setup notes, client testing, bug reports, benchmarks, and real workflow feedback from people using AI tools every day.

Good places to help:

• Test MARM with more MCP clients, IDE agents, and operating systems
• Improve docs, screenshots, examples, and platform-specific setup notes
• Report bugs or confusing install steps with clear reproduction details
• Share memory workflows, agent habits, and tool ideas from real use
• Check out open issues

💡 Want to get your name on this list? Check out our CONTRIBUTING.md guide to get started!

Join the MARM Community

Help build the future of AI memory - no coding required!

Connect: MARM Discord | GitHub Discussions

License & Usage Notice

Copyright © 2026 Ryan A. Lyell. MARM is released under the Apache 2.0 License (see NOTICE for the copyright statement), and forks, experiments, and integrations are welcome. MARM also wraps third-party open-source components such as codebase-memory-mcp under MIT; see THIRD_PARTY_NOTICES.md for attribution. If you build on it, please make unofficial versions easy to distinguish from releases published by the official MARM repository so users know what they are installing.

Project Documentation

Usage Guides

• README.md - This file: complete usage guide, tool reference, workflows, and architecture
• PROTOCOL.md - MCP operating protocol
• FAQ.md - Answers to common questions about using MARM

MCP Server Installation

• INSTALL-DOCKER.md - Docker deployment (recommended)
• INSTALL-WINDOWS.md - Windows installation guide
• INSTALL-LINUX.md - Linux installation guide
• INSTALL-PLATFORMS.md - Platform installation guide

Project Information

• CONTRIBUTING.md - How to contribute to MARM
• CHANGELOG.md - Version history and updates
• ACKNOWLEDGMENTS.md - Contributors and acknowledgments
• ROADMAP.md - Planned features and development roadmap
• LICENSE - Apache 2.0 license terms