M3 Memory

🧠 m3 Memory

Give your AI a memory that lasts.

Your AI assistant is helpful until you start a new conversation and it has forgotten what you were working on. m3 fixes that.

Your assistants remember your projects, preferences, decisions and past work, even after you close the app, start a new session or switch to a different agent. By default everything stays on your own computer, and it works offline. m3 itself needs no cloud account or API key; your AI assistant may have its own requirements.

pipx install m3-memory  # or pip install m3-memory in a virtual environment; use one, not both

m3 setup # finds your agents and connects them to m3 m3 doctor # checks that everything is working

No pipx yet? sudo apt install pipx (Debian, Ubuntu), brew install pipx (macOS) or py -m pip install --user pipx (Windows). If m3 is not found right after installing, open a new terminal.

Setup finds your agents and connects m3 to them. m3 setup detects your AI agents and wires m3 into each; if you run a local LLM (Ollama, LM Studio), it offers to use it to summarize and link your memories. That part is optional; to use it, install the LLM before m3 setup: Windows · macOS · Linux. That's the whole install.

New here? The 5-minute Getting Started guide walks you through your first saved memory.

---

What m3 is

m3 is a memory layer for AI agents: the AI assistants that work for you, such as Claude Code, Codex, Cursor or Gemini CLI. It runs on your own computer and stores facts, decisions, preferences and conversation history so your assistants can recall them later, across sessions, across tools and across machines. Assistants reach it through MCP, the standard way AI assistants connect to tools, and you can use it from the command line too.

It is not an AI model or a chatbot. You keep using the assistants you already use; they call m3 when they need to remember or recall something.

---

📅 A week with m3

Monday: you tell your AI assistant you're building a website and decide on PostgreSQL.

Wednesday: you open a new session and ask, "Where did we leave off?" Your assistant

finds the decision and carries on, without you repeating it.

Friday: you switch agents, say from Claude Code to Codex. Codex sees the same project

memory.

See it for yourself in a short video of one agent saving a decision that another recalls. (Developers: the same thing from the command line.)

✨ What m3 does for you

Simple to understand, easy to start, powerful when you need it. Every row links to the doc that backs it; How memory works in m3 explains the mechanics, and the technical summary and benchmarks carry the measurements.

---

🎯 Better memory, fewer wasted tokens

AI assistants can only work with so much text at once, and they measure it in tokens: small pieces of words, which can also set what you pay. When your assistant searches its memory, finding the right thing first means it reads less of what it doesn't need.

An illustration, not a measurement:

less precise search m3: the right memory first

1. unrelated note 1. ✔ the decision you need
2. unrelated note (it may already have what it needs)
3. ✔ the decision you need
4. unrelated note
5. unrelated note

On the LongMemEval-S benchmark, the correct session was m3's first result for 91.8% of questions (459 of 500). That measures retrieval accuracy, not token savings: how much your assistant saves depends on how it uses the results. m3 returns as many as it is asked for, so precise ranking lets an assistant ask for fewer, or stop at the first good one, and keep more room for the work itself.

m3 saves context in a second, measured way: it registers only 6 of its 100+ tools when an assistant connects, so their descriptions take about 3,200 tokens instead of about 33,000 for the full catalog (Interfaces).

---

How memory works in m3

When an agent (or you, from the shell) wants to remember something, it calls memory_write. m3 stores the text exactly as given, with a type, title and metadata. Later, memory_search finds it with hybrid retrieval: keyword matching (BM25), semantic similarity (local BGE-M3 embeddings) and diversity re-ranking (MMR). Nine signals contribute to the score, and every result can explain it.

When a fact changes, m3 does not overwrite it. Three mechanisms, each different:

• Similarity-based supersession (on every write). A new memory very similar to an older one of the same type (cosine similarity above 0.92 by default) but with different text becomes the current version: the older one's valid_to is closed and both stay queryable with as_of. It does not judge whether the two actually contradict, so a refinement ("PostgreSQL with connection pooling") replaces the older wording too; nothing is lost from the history. It applies only to an agent's own memories, and only when the write names its user or agent.
• Explicit supersession. An agent calls memory_supersede to replace a memory it knows is wrong.
• Contradiction detection (model-assisted). With the cognitive loop on, its Reflector stage uses a model to find memories that genuinely disagree and records them for resolution.

With the cognitive loop enabled, m3 also embeds new memories, extracts entities and relationships, and decays memories that are not used. Rolling related notes up into higher-level beliefs is a separate opt-in.

The default store is a single SQLite file. PostgreSQL is a first-class alternative when you want one store shared across machines.

---

📍 Project status

The core is stable, and so are the web dashboard, the cognitive loop and the Observer & Reflector stages.

• Memory reads audited: each memory read and search hit is logged with who read it, whose data it was and when, kept 90 days, and included in GDPR export and erasure (GDPR). Chat-log reads are next.
• One config file: m3_config.toml holds every setting, and m3 config show prints each one with where it came from (Config reference). Old environment-variable names are no longer read; m3 doctor names any still set (Environment variables).
• Predictable upgrades: calendar versions (YYYY.M.D.N). A renamed setting, argument or tool keeps working, with a warning, before it is removed, and m3 doctor names anything you still use (Changelog).

---

⚡ m3 at a glance: technical capabilities

m3 is a persistent, local-first memory layer for AI agents: an MCP server and a JSON-in, JSON-out command-line tool over the same store. It is not an LLM, a chatbot, a plain vector database, a RAG framework or an agent runtime.

m3 is more than a searchable memory store. It combines hybrid keyword and semantic retrieval, bitemporal history, automatic supersession, model-assisted contradiction review, a knowledge graph and background memory maintenance (the cognitive loop). Several agents can share one store; several machines can share one PostgreSQL database, or keep local stores synced through a PostgreSQL warehouse. Your existing assistants reach all of it through MCP, the CLI or framework integrations, with no new agent runtime, and it can run entirely on your own hardware.

| Hybrid retrieval | Built in | BM25 ke