m3-memory

<p align="center">
  <a href="https://github.com/skynetcmd/m3-memory">
    <img src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/M3-banner.jpg" alt="M3 Memory Banner" width="100%">
  </a>
</p>

# 🧠 M3 Memory

**A memory layer that outlives your agents.** You switch from Claude Code to Cursor, upgrade your model, start fresh next week — and everything your tools learned about your project is gone. You re-explain the same decisions, the same preferences, the same hard-won context, over and over.

**M3 fixes that.** It's a private, local-first memory your agents share and build on — so your project's knowledge accumulates instead of resetting every time the agent does. One memory store, on your machine, that your tools and agents read from and write to — whether that's Claude Code, Cursor, Gemini CLI, or any MCP-compatible agent.

Under the hood, M3 treats agent memory as a **distributed-systems infrastructure problem**, not a simple retrieval feature — a **shared, evolving, bitemporal, contradiction-aware knowledge base** that multiple heterogeneous agents and machines read and write, built to stay consistent over months and years.

**It runs where your data has to stay.** A single `pip install` with no account, no
API key, and no outbound calls — at home in a **homelab**, on a **corporate or
government network**, or **fully air-gapped**. The embedder runs in-process and
local, the store is a file you own, and installation works with no internet at all.
On the metric that isolates the memory layer — **retrieval accuracy, no answer model
or judge involved** — M3 reaches **99.2% session-hit-rate @ k=10 and 100% @ k=20** on
LongMemEval-S.

---

## 🎬 Quick video overview

One decision saved from a conversation, then recalled by a *different* agent in a *new* session, on a different machine. Captioned throughout, so it reads fine muted.

https://github.com/user-attachments/assets/09ab194a-d2a0-4fe5-a7db-69ae8225e39b

<sub>Player not loading? <a href="https://github.com/skynetcmd/m3-memory/releases/download/v2026.7.30.1/m3-promo.mp4"><b>Download the video</b></a> to play locally.</sub>

---

## ⚡ Quickstart

```bash
pip install m3-memory   # or: pipx install m3-memory — pick ONE and stay with it
m3 setup            # detects your agents, wires the MCP server, provisions the local embedder
m3 doctor           # verify: health, memory count, embedder, and which agents got wired
```

That's the whole install. No cloud account, no API key, no external embedding service.

### What it does, in four lines

Save a decision — your AI agent, or you from the shell:

```console
$ m3 memory memory_write --type decision --title "auth-jwt-algorithm" \
    --content "The auth service uses RS256 JWTs. HS256 was rejected because we need asymmetric verification at the edge."
"Created: 84a944fb-ef3e-403b-9240-f53ab3c015f7"
```

Next week, in a different agent, on a different model — ask in your own words:

```console
$ m3 memory memory_search --query "which signing algorithm did we pick for tokens?" --k 3
Top 1 results:
----------------------------------------
1. [84a944fb-ef3e-403b-9240-f53ab3c015f7] score=0.7501  type: decision  title: auth-jwt-algorithm
Content:
The auth service uses RS256 JWTs. HS256 was rejected because we need asymmetric verification at the edge.
----------------------------------------
```

The query shares no keywords with the stored text — no "RS256", no "JWT" — and still finds it. That's the hybrid engine: BM25 for exact terms, local BGE-M3 vectors for meaning, MMR for diversity. Your agent calls the same tools over MCP, so it recalls this automatically instead of asking you again.

> New here? The **[5-Minute Getting Started Guide](docs/GETTING_STARTED.md)** walks the same path with more context, and [Core Tools](#-core-tools) lists the five you'll use most.

---

## 🧩 Beyond the core

The Quickstart above is the whole product for most people: shared memory, wired into your agents, working offline. Everything below is **optional surface** you can ignore until you want it — each row says what it costs to turn on.

<table border="0">
<tr><td valign="top">🤖</td><td><b>Coding agents</b> · <sub><b>included in the base install</b></sub><br><code>m3 setup</code> auto-detects and wires m3 into <b>Claude Code, Cursor, Cline, Gemini CLI, Google Antigravity, Aider, OpenCode, OpenClaw, Hermes</b> — one shared memory across every agent, and any agent you add later is picked up automatically. (See <a href="docs/MCP_CLIENT_INSTALL.md">MCP Client Install</a>)</td></tr>
<tr><td valign="top">👥</td><td><b>Multi-agent synchronization</b> · <sub><b>included in the base install</b></sub><br>agents coordinate through one store: memory scoped per <code>agent</code> / <code>org</code> / <code>user</code>, direct handoffs into another agent's inbox, shared tasks with a recursive task tree, and opt-in SQL-layer isolation so an agent's private notes stay private. Concurrent readers and writers are safe by design (WAL + retry), so a planner, an implementer and a reviewer can work at the same time. (See <a href="docs/MULTI_AGENT.md">Multi-Agent Orchestration</a>)</td></tr>
<tr><td valign="top">🖥️</td><td><b>Web dashboard, open to all users — not just developers</b> · <sub><b>included in the base install</b></sub><br>a built-in, backend-agnostic control panel (default <code>http://127.0.0.1:8088</code>): browse memory, read your auto-generated Memory Wiki, explore the interactive knowledge graph, and watch system health / load. Just run <code>m3 dashboard</code>. (See <a href="docs/DASHBOARD.md">Dashboard Guide</a>)</td></tr>
<tr><td valign="top">📖</td><td><b>Auto-generated wiki + Obsidian export</b> · <sub>core feature — in the base install, nothing extra to enable</sub><br><code>m3 wiki generate</code> compiles your canonical memories (pinned, high-confidence, beliefs, procedures) and indexed files into a browsable, interlinked Markdown vault — one page per topic, real hyperlinks for every relationship, and provenance links down to the source document each fact came from. Renders on GitHub, in a self-contained offline HTML viewer, or as an <b>Obsidian vault</b> (<code>--obsidian</code> for graph view + backlinks). (See <a href="docs/WIKI.md">Wiki Guide</a>)</td></tr>
<tr><td valign="top">🐘</td><td><b>PostgreSQL</b> · <sub>optional — you do not need a database</sub><br><b>Most people should ignore this row.</b> m3 stores everything in a local SQLite file by default: nothing to install, nothing to run. Point m3 at a PostgreSQL server instead when you want <b>one shared store for several machines</b> — set <code>pip install "m3-memory[postgres]"</code> and <code>M3_DB_BACKEND=postgres</code>. It is a manual step today; <code>m3 setup</code> does not configure it for you. (See <a href="docs/ARCHITECTURE.md">Architecture</a> · <a href="docs/SYNC.md">Sync</a>)</td></tr>
</table>

<sub>Also a drop-in memory backend for <b><a href="docs/integrations/LANGCHAIN.md">LangChain / LangGraph</a></b>, <b><a href="m3_memory/integrations/crewai/README.md">CrewAI</a></b>, and <b><a href="m3_memory/integrations/pydantic_ai/README.md">PydanticAI</a></b> — see the framework guides.</sub>

> Every path gains automatic contradiction supersession, bitemporal historical queries, local sovereign embedding, and the full 100+ MCP tool set.

---

## ⚖️ How M3 Compares

A full, feature-by-feature **comparison table** — M3 vs **Mem0, Letta, Zep, Graphiti, LangChain Memory / LangMem, agentmemory, Chronos, Hindsight, Mastra OM, Memento**, and more — with sourced benchmarks and honest "when to choose the other tool" guidance, lives in **[COMPARISON.md](docs/COMPARISON.md)**.

Short version: M3 is the **local-first, MCP-native** option that stays *yours* and works across every agent — where cloud services (Mem0), full agent runtimes (Letta), and graph-database systems (Zep, Graphiti) each ask you to adopt their infrastructure. See the [comparison guide](docs/COMPARISON.md) for the row-by-row detail.

---

## 🚀 Quick Links & Badges

<p align="center">
  <img alt="macOS" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/os-macos.svg">
  <img alt="Windows" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/os-windows.svg">
  <img alt="Linux" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/os-linux.svg">
</p>

<p align="center">
  <a href="https://pypi.org/project/m3-memory/"><img alt="PyPI downloads" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/pypi-downloads.svg"></a>
  <a href="https://github.com/skynetcmd/m3-memory"><img alt="GitHub clones" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/github-clones.svg"></a>
  <a href="https://star-history.com/#skynetcmd/m3-memory&Date"><img alt="Star history" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/star-history.svg"></a>
</p>

<p align="center">
  <a href="https://pypi.org/project/m3-memory/"><img alt="PyPI" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/pypi-version.svg"></a>
  <a href="https://www.python.org"><img alt="Python 3.11+" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/python.svg"></a>
  <a href="https://github.com/skynetcmd/m3-memory/blob/main/LICENSE"><img alt="Apache 2.0" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/license.svg"></a>
  <a href="https://modelcontextprotocol.io"><img alt="MCP" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/mcp.svg"></a>
</p>

<p align="center">
  <a href="docs/integrations/LANGCHAIN.md"><img alt="LangChain" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/langchain.svg"></a>
  <a href="docs/claude_code_plugin.md"><img alt="Claude" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/claude.svg"></a>
  <a href="docs/antigravit