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

M3 treats agent memory as a **distributed-systems infrastructure problem**, not a simple retrieval feature.

Instead of every tool keeping its own throwaway context, M3 is a **shared, evolving, bitemporal knowledge base** that multiple heterogeneous agents and machines read and write. It is designed to solve a fundamental challenge: *How do agents maintain a consistent, evolving, and temporal knowledge base over months and years?*

**Plugs into your stack — coding agents, framework, and database.** M3 brings contradiction-aware, bitemporal, locally-embedded memory to the tools you already use, and scales from a zero-setup file to a shared server:

<table border="0">
<tr><td valign="top">🤖</td><td><b>Coding agents</b> — <code>m3 setup</code> auto-detects and wires m3 into <b>Claude Code, Cursor, Cline, Gemini CLI, Aider, Antigravity, OpenCode</b>, and any MCP client — one shared memory across every agent, re-wired on update. (See <a href="docs/MCP_CLIENT_INSTALL.md">MCP Client Install</a>)</td></tr>
<tr><td valign="top">🖥️</td><td><b>Web dashboard, open to all users — not just developers</b> — 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. <code>pip install m3-memory[dashboard]</code> then <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> — <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> — run M3 on a first-class PostgreSQL primary backend (<code>M3_DB_BACKEND=postgres</code>) for a shared, server-hosted store, with cross-device sync to a PostgreSQL warehouse. SQLite stays the zero-infrastructure default. (See <a href="docs/ARCHITECTURE.md">Architecture</a> · <a href="docs/SYNC.md">Sync</a>)</td></tr>
<tr><td valign="top">🦜</td><td><b>LangChain &amp; LangGraph</b> — drop-in <b>Mem0 replacement</b> (one-line import swap) and fully <b>LangMem-compatible</b> (<code>store=M3Store()</code>): <code>pip install m3-memory[langchain]</code>. (See <a href="docs/integrations/LANGCHAIN.md">LangChain Guide</a>)</td></tr>
<tr><td valign="top">👥</td><td><b>CrewAI</b> — a drop-in <code>StorageBackend</code> for CrewAI's unified memory: <code>pip install m3-memory[crewai]</code>. (See <a href="m3_memory/integrations/crewai/README.md">CrewAI Guide</a>)</td></tr>
<tr><td valign="top">🧩</td><td><b>PydanticAI</b> — wire M3 in as the agent's memory layer: <code>pip install m3-memory[pydantic-ai]</code>. (See <a href="m3_memory/integrations/pydantic_ai/README.md">PydanticAI Guide</a>)</td></tr>
</table>

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

---

## 🚀 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/antigravity_plugin.md"><img alt="Antigravity" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/antigravity.svg"></a>
  <a href="docs/HERMES.md"><img alt="Hermes" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/hermes.svg"></a>
  <img alt="OpenClaw" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/openclaw.svg">
  <img alt="OpenCode" src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/opencode.svg">
</p>

> 💡 **Get Started Quickly:**
> * 🚀 **[5-Minute "Human-First" Guide](docs/GETTING_STARTED.md)**
> * 🖥️ **OS Installation:** [Windows Setup](docs/QUICKSTART_WINDOWS.md) · [macOS Setup](docs/QUICKSTART_MACOS.md) · [Linux Setup](docs/QUICKSTART_LINUX.md)

---

## 📑 Table of Contents

- [Overview & At a Glance](#-m3-at-a-glance)
- [Memory Model](#-memory-model-at-a-glance)
- [Installation & Onboarding](#-installation)
- [Domain Gating (Token Optimization)](#-domain-gating-the-full-catalog-without-the-context-cost)
- [Sovereign & Air-Gapped Deployments](#-sovereign--air-gapped-deployments)
- [Interactive Features & Capabilities](#-what-m3-does)
- [Documentation Index](#-documentation-index)
- [Target Audience & Fit](#-who-this-is-for)
- [Quality Assurance & Compliance](#-why-trust-this)
- [Benchmarks & Performance](#-benchmarks)
- [Core Tools Reference](#-core-tools)
- [Agent Integration Prompts](#-for-ai-agents)
- [Interactive Demos](#-see-it-in-action)

---

## ⚡ M3 at a Glance

| Feature | Details |
| :--- | :--- |
| **Works With** | Claude Code · Cursor · Cline · Gemini CLI · Aider · Google Antigravity · OpenCode · Hermes · LangChain/LangGraph · CrewAI · PydanticAI · Any MCP Agent |
| **M3 Is** | A persistent memory layer · An MCP server · A hybrid retrieval engine · A bitemporal knowledge base |
| **M3 Is Not** | An LLM · A chatbot · A plain vector database · A RAG framework · An IDE |
| **Core Promise** | Private, offline-capable, locally owned memory shared securely across all your developer tools — with FIPS 140-3-ready crypto and atomic multi-agent writes for regulated and multi-agent environments. |
| **Retrieval Accuracy** | State-of-the-art for a local-first substrate — **99.2% session-hit-rate @ k=10, 100% @ k=20** on LongMemEval-S (no oracle routing), with the correct session as the **#1 result for ~92% of questions**. See [Benchmarks](#-benchmarks). |
| **Context Efficiency** | Exposes 100+ tools but occupies just **~1.8% of a 200K context window** at startup — lazy domain-gating loads the rest on demand. |
| **Maturity** | Stable, battle-tested core engine (2,501 tests) that's safe to build on today; new features and integrations are added actively. **SQLite by default; PostgreSQL as a first-class primary backend** (`M3_DB_BACKEND=postgres`) via a pluggable SQL storage seam. (See [features.json](docs/features.json)) |

---

## 🧠 Memory Model at a Glance

M3 is a **typed, bitemporal, confidence-scored, self-maintaining knowledge base**. Every feature listed below is implemented natively (see [Memory Model Details](docs/MEMORY_MODEL.md)):

*   **Structured Metadata:** Every memory contains a `type`, `source`, `confidence`, `scope`, provenance (`change_agent`), and salience (`importance`, `decay_rate`).
*   **Verbatim, Non-Destructive Storage:** Memory content is stored exactly as written and **never altered in place** — the raw text is always retrievable byte-for-byte. Corrections don't overwrite: a superseded fact is *closed* (its validity interval ends) and the new fact is linked to it, so both the original wording and its full edit history stay queryable. You get true verbatim recall *and* an audit trail, not one or the other.
*   **Bitemporal History:** Distinguishes valid-time from transaction-time. Because superseded facts are closed rather than deleted, you can query what the agent believed at any specific point in time.
*   **Contradiction Management:** Conflicting facts are resolved automatically on write. The stale fact is marked as superseded, and confidence values are updated dynamically via Bayesian confidence posteriors.
*   **Self-Maintaining Lifecycle:** Implements memory decay, deduplication, automatic consolidation into higher-order beliefs, TTL expiry, and GDPR erasure.
*   **Procedural Memory:** A first-class `procedure` type (skill / runbook / how-to / checklist) that is **auto-distilled from successful task