Table of Contents
- Why MARM MCP
- Demo Video
- Quick Start
- Connect Your Client Fast
- Complete MCP Tool Suite
- MARM Dashboard
- Architecture Overview
- Contributing
- Project Documentation
Why MARM MCP: The Problem & Solution
Your AI forgets everything. MARM MCP doesn't.
Modern LLMs lose context over time, repeat prior ideas, and drift off requirements. MARM MCP solves this with a unified, persistent, MCP‑native memory layer that sits beneath any AI client you use. It blends semantic search, structured session logs, reusable notebooks, and smart summaries so your agents can remember, reference, and build on prior work—consistently, across sessions, and across tools.
Before vs After
- Without MARM: lost context, repeated suggestions, drifting scope, "start from scratch."
- With MARM: session memory, cross-session continuity, concrete recall of decisions, and faster, more accurate delivery.
What MARM MCP Delivers
| Memory | Multi-AI | Architecture | |------------|--------------|------------------| | Semantic Search - Find by meaning using AI embeddings | Unified Memory Layer - Works with Claude, Qwen, Gemini, MCP clients | Lean MCP Tool Surface - Focused tools with lifecycle automation | | Auto-Classification - Content categorized (code, project, book, general) | Cross-Platform Intelligence - Different AIs learn from shared knowledge | Database Optimization - SQLite with WAL mode and connection pooling | | Persistent Cross-Session Memory - Memories survive across agent conversations | User-Controlled Memory - "Bring Your Own History," granular control | Rate Limiting - IP-based tiers for stability | | Smart Recall - Vector similarity search with context-aware fallbacks | | MCP Compliance - Response size management for predictable performance | | | | Docker Ready - Containerized deployment with health/readiness checks |
MARM Demo Video: Docker Install + Persistent AI Memory in Action
https://github.com/user-attachments/assets/c7c6a162-5408-4eda-a461-610b7e713dfe
Watch MARM install through Docker, connect to Claude, and share persistent memory across Claude, Gemini, and Qwen.
What Users Are Saying
“MARM successfully handles our industrial automation workflows in production. We've validated session management, persistent logging, and smart recall across container restarts in our Windows 11 + Docker environment. The system reliably tracks complex technical decisions and maintains data integrity through deployment cycles.”
@Ophy21, GitHub user (Industrial Automation Engineer)
“MARM proved exceptionally valuable for DevOps and complex Docker projects. It maintained 100% memory accuracy, preserved context on 46 services and network configurations, and enabled standards-compliant Python/Terraform work. Semantic search and automated session logs made solving async and infrastructure issues far easier. Value Rating: 9.5/10 - indispensable for enterprise-grade memory, technical standards, and long-session code management.” @joe_nyc, Discord user (DevOps/Infrastructure Engineer)
🚀 Quick Start for MCP (HTTP & STDIO)
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).
Local pip HTTP (zero config)
pip install marm-mcp-server
python -m marm_mcp_server
# 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
# xAI / Grok Remote MCP
# Use a hosted HTTPS MARM endpoint, not localhost. See Docker / hosted setup below.
Local pip STDIO
pip install marm-mcp-server
# 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
# xAI / Grok Remote MCP
# Use a hosted HTTPS MARM endpoint, not localhost. See Docker / hosted setup below.
python -m marm_mcp_server.server_stdio
Docker HTTP (key required)
# Step 1: generate key (do not add < > around the key)
docker run --rm lyellr88/marm-mcp-server:latest python -m marm_mcp_server --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"
codex mcp add marm-memory --url http://localhost:8001/mcp --bearer-token-env-var MARM_API_KEY
Docker STDIO (no HTTP key)
docker run --rm -i \
-v ~/.marm:/home/marm/.marm \
lyellr88/marm-mcp-server:latest \
python -m marm_mcp_server.server_stdio
Most useful support info:
- 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 Fast
Claude Code remains the recommended first setup path, but MARM also works with other MCP clients and IDE agents.
CLI clients - Claude Code · Codex · Gemini CLI · Qwen CLI · Linux variants · Docker/key
IDE agents - VS Code / Copilot Agent · Cursor · Docker/key IDE setup
Remote/API platforms - xAI / Grok Remote MCP · Platform integration
Complete MCP Tool Suite (8 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.
MARM now handles lifecycle work internally. Documentation loads on the first real tool call, session state initializes automatically, and documentation refreshes every 50 tool calls. Packaged docs are indexed into searchable memory with hash-based caching, so unchanged docs are skipped across restarts.
Architecture note: MARM uses parameterized dispatching tooling to keep MCP discovery lean without hiding behavior. Domain-specific tools such as marm_notebook(action=...) and marm_delete(type=...) group closely related operations behind explicit parameters, while recall, logging, and summaries stay separate so agents still choose the right capability clearly. This design ensures the total MCP schema footprint remains under 10KB while preserving full functionality.
| Category | Tool | Description | |--------------|----------|-----------------| | **Memory I