M3 Memory MCP Server

![M3 Memory]

M3 Memory

Persistent, local memory for MCP agents.

"Wait, you remember that?" — Stop re-explaining your project to your AI. Give it a long-term brain that stays 100% on your machine.

🚀 New to M3? Start here with our 5-minute "Human-First" guide.

Works with Claude Code, Gemini CLI, Aider, OpenCode, and any MCP-compatible agent. Quick one-line command to have your agent install chat log sub-system which saves verbatim chat log info, before compaction, with zero lag/latency and 100% retrieval recall. Just tell your AI agent "install m3-memory chat log sub-system" and your agent will automatically install it with all the proper hooks with some minimal customization questions from you (you can accept the default answers).

---

📦 Install

pip install m3-memory

That's it. On first mcp-memory run, the CLI auto-fetches the system payload into ~/.m3-memory/repo/ (pinned to the wheel version) — with an interactive confirmation prompt if you run it in a terminal, silently if an MCP client is launching the server. Set M3_AUTO_INSTALL=0 to skip the auto-fetch and run mcp-memory install-m3 explicitly, or mcp-memory doctor to verify paths.

Add to your MCP config:

{
  "mcpServers": {
    "memory": { "command": "mcp-memory" }
  }
}

Requires a local embedding model. Ollama maybe the easiest:

ollama pull qwen3-embedding:0.6b && ollama serve

I personally use LM Studio for it's support for Apple's MLX. But, it's your preference.

Qwen3-Embedding-0.6B (1024-dim, Q8 quantized, ~639 MB) is the model M3 Memory is tuned for. But you can set and use other embedders as you wish. For example, you could use nomic-embed-text (768-dim) which also works (with minimal fidelity loss) — set EMBED_MODEL=nomic-embed-text in your environment.

As mentioned, you can use Ollama or LM Studio — load an embedding model and start its server.

Want auto-classification, summarization, and consolidation? Load a small chat model alongside the embedder (e.g. qwen2.5:0.5b via Ollama, or any 0.5–1B instruct GGUF in LM Studio / llama.cpp). M3 auto-selects it; embedding-only features work without it. See docs/QUICKSTART.md → Optional: load a small chat model.

Restart your agent. Done!

---

🔮 What happens next (benefits of use)

You're at a coffee shop on your MacBook, asking Claude to debug a deployment issue. It remembers the architecture decisions you made last week, the server configs you stored yesterday, and the troubleshooting steps that worked last time — all from local SQLite, no internet required.

Later, you're at your Windows desktop at home with Gemini CLI, and it picks up exactly where you left off. Same memories, same context, same knowledge graph. You didn't copy files, didn't export anything, didn't push to someone else's cloud. Your PostgreSQL sync handled everything in the background the moment your laptop hit the local network.

---

💡 Why this exists

Most AI agents don't persist state between sessions. You re-paste context, re-explain architecture, re-correct mistakes. When facts change, the agent has no mechanism to update what it "knows."

M3 Memory gives agents a structured, persistent memory layer that handles this.

---

⚡ What it does

Persistent memory — facts, decisions, preferences survive across sessions. Stored in local SQLite.

Hybrid retrieval — FTS5 keyword matching + semantic vector similarity + MMR diversity re-ranking. Automatic, no tuning required.

Contradiction handling — conflicting facts are automatically superseded. Bitemporal versioning preserves the full history.

Knowledge graph — related memories linked automatically on write. Nine relationship types, 3-hop traversal.

Zero-config local install — pip install m3-memory, one line in your MCP config, done. SQLite stores everything locally — no external databases, no cloud calls, no API costs. Works offline.

Cross-device sync — optional, easy-to-add bi-directional delta sync via PostgreSQL or ChromaDB. Set one environment variable and your memories follow you across machines.

---

📚 Learn more

---

🎯 Who this is for

---

🛡️ Why trust this

---

📊 Benchmarks

89.0% on LongMemEval-S (445/500 correct) — a 500-question evaluation of long-horizon conversational memory. Without oracle metadata: 74.8% (smart retrieval) to 68.0% (fixed-k baseline).

Full methodology, ablations, and honest caveats: benchmarks/longmemeval/README.md.

---

🧰 Core tools

Most sessions use three tools. The rest is there when you need it.

All 66 tools are documented in docs/AGENT_INSTRUCTIONS.md.

---

🤖 For AI agents

M3 Memory exposes 66 MCP tools for storing, searching, updating, and linking knowledge — including conversation grouping, a refresh lifecycle for aging memories, agent registry, handoffs, notifications, tasks, and chat-log capture for multi-agent orchestration. Any MCP-compatible agent can use them automatically.

To teach your agent best practices (search before answering, write aggressively, update instead of duplicating), drop the compact rules file into your project:

examples/AGENT_RULES.md

Full tool reference with all parameters and behaviors: docs/AGENT_INSTRUCTIONS.md

---

🪄 Let your agent install it

Already inside Claude Code or Gemini CLI? Paste one of these prompts:

Claude Code:

Install m3-memory for persistent memory. Run: pip install m3-memory
Then add {"mcpServers":{"memory":{"command":"mcp-memory"}}} to my
~/.claude/settings.json under "mcpServers". Make sure Ollama is running
with qwen3-embedding:0.6b. Then use /mcp to verify the memory server loaded.

Gemini CLI:

Install m3-memory for persistent memory. Run: pip install m3-memory
Then add {"mcpServers":{"memory":{"command":"mcp-memory"}}} to my
~/.gemini/settings.json under "mcpServers". Make sure Ollama is running
with qwen3-embedding:0.6b.

After install, test it:

Write a memory: "M3 Memory installed successfully on [today's date]"
Then search for: "M3 install"

Add the chat log subsystem

Want auto-capture of every Claude Code / Gemini CLI / OpenCode / Aider conversation into a searchable, promotable chat log store? Once m3-memory is wired up, just say:

Install the m3-memory chat log subsystem.

The agent runs bin/chatlog_init.py, wires the host-agent hook, and installs the embed sweeper schedule. See docs/CHATLOG.md for the architecture and ops guide.

---

🎬 See it in action

Contradiction detection

Hybrid search with scores

Cross-device, cross-platform sync

---

💬 Community

    Contributing · Good first issues

---