{
  "markdown": "<p align=\"center\">\n  <a href=\"https://github.com/skynetcmd/m3-memory\">\n    <img src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/M3-banner.jpg\" alt=\"M3 Memory Banner\" width=\"100%\">\n  </a>\n</p>\n\n# 🧠 M3 Memory\n\n**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.\n\n**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.\n\nUnder 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.\n\n**It runs where your data has to stay.** A single `pip install` with no account, no\nAPI key, and no outbound calls — at home in a **homelab**, on a **corporate or\ngovernment network**, or **fully air-gapped**. The embedder runs in-process and\nlocal, the store is a file you own, and installation works with no internet at all.\nOn the metric that isolates the memory layer — **retrieval accuracy, no answer model\nor judge involved** — M3 reaches **99.2% session-hit-rate @ k=10 and 100% @ k=20** on\nLongMemEval-S.\n\n---\n\n## 🎬 Quick video overview\n\nOne 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.\n\nhttps://github.com/user-attachments/assets/09ab194a-d2a0-4fe5-a7db-69ae8225e39b\n\n<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>\n\n---\n\n## ⚡ Quickstart\n\n```bash\npip install m3-memory\nm3 setup            # detects your agents, wires the MCP server, provisions the local embedder\nm3 doctor           # verify: health, memory count, embedder, and which agents got wired\n```\n\nThat's the whole install. No cloud account, no API key, no external embedding service.\n\n### What it does, in four lines\n\nSave a decision — from any agent, or straight from the shell:\n\n```console\n$ m3 memory memory_write --type decision --title \"auth-jwt-algorithm\" \\\n    --content \"The auth service uses RS256 JWTs. HS256 was rejected because we need asymmetric verification at the edge.\"\n\"Created: 84a944fb-ef3e-403b-9240-f53ab3c015f7\"\n```\n\nNext week, in a different agent, on a different model — ask in your own words:\n\n```console\n$ m3 memory memory_search --query \"which signing algorithm did we pick for tokens?\" --k 3\nTop 1 results:\n----------------------------------------\n1. [84a944fb-ef3e-403b-9240-f53ab3c015f7] score=0.7501  type: decision  title: auth-jwt-algorithm\nContent:\nThe auth service uses RS256 JWTs. HS256 was rejected because we need asymmetric verification at the edge.\n----------------------------------------\n```\n\nThe 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.\n\n> 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.\n\n---\n\n## 🧩 Beyond the core\n\nThe 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.\n\n<table border=\"0\">\n<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>\n<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>\n<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>\n<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>\n<tr><td valign=\"top\">🐘</td><td><b>PostgreSQL</b> · <sub>needs <code>m3-memory[postgres]</code>; SQLite is the default and needs nothing</sub><br>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>\n</table>\n\n<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>\n\n> Every path gains automatic contradiction supersession, bitemporal historical queries, local sovereign embedding, and the full 100+ MCP tool set.\n\n---\n\n## ⚖️ How M3 Compares\n\nA 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)**.\n\nShort 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.\n\n---\n\n## 🚀 Quick Links & Badges\n\n<p align=\"center\">\n  <img alt=\"macOS\" src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/os-macos.svg\">\n  <img alt=\"Windows\" src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/os-windows.svg\">\n  <img alt=\"Linux\" src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/os-linux.svg\">\n</p>\n\n<p align=\"center\">\n  <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>\n  <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>\n  <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>\n</p>\n\n<p align=\"center\">\n  <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>\n  <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>\n  <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>\n  <a href=\"https://modelcontextprotocol.io\"><img alt=\"MCP\" src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/mcp.svg\"></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"docs/integrations/LANGCHAIN.md\"><img alt=\"LangChain\" src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/langchain.svg\"></a>\n  <a href=\"docs/claude_code_plugin.md\"><img alt=\"Claude\" src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/claude.svg\"></a>\n  <a href=\"docs/antigravity_plugin.md\"><img alt=\"Antigravity\" src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/antigravity.svg\"></a>\n  <a href=\"docs/HERMES.md\"><img alt=\"Hermes\" src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/hermes.svg\"></a>\n  <img alt=\"OpenClaw\" src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/openclaw.svg\">\n  <img alt=\"OpenCode\" src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/opencode.svg\">\n</p>\n\n> 💡 **Get Started Quickly:**\n> * 🚀 **[5-Minute \"Human-First\" Guide](docs/GETTING_STARTED.md)**\n> * 🖥️ **OS Installation:** [Windows Setup](docs/QUICKSTART_WINDOWS.md) · [macOS Setup](docs/QUICKSTART_MACOS.md) · [Linux Setup](docs/QUICKSTART_LINUX.md)\n\n---\n\n## 📑 Table of Contents\n\n- [Quickstart](#-quickstart)\n- [Beyond the Core (optional surface)](#-beyond-the-core)\n- [Overview & At a Glance](#-m3-at-a-glance)\n- [Memory Model](#-memory-model-at-a-glance)\n- [Installation & Onboarding](#-installation)\n- [Domain Gating (Token Optimization)](#-domain-gating-the-full-catalog-without-the-context-cost)\n- [Sovereign & Air-Gapped Deployments](#-sovereign--air-gapped-deployments)\n- [Interactive Features & Capabilities](#-what-m3-does)\n- [Documentation Index](#-documentation-index)\n- [Target Audience & Fit](#-who-this-is-for)\n- [Quality Assurance & Compliance](#-why-trust-this)\n- [Benchmarks & Performance](#-benchmarks)\n- [Core Tools Reference](#-core-tools)\n- [Agent Integration Prompts](#-for-ai-agents)\n- [Interactive Demos](#-see-it-in-action)\n\n---\n\n## ⚡ M3 at a Glance\n\n| Feature | Details |\n| :--- | :--- |\n| **Works With** | Claude Code · Cursor · Cline · Gemini CLI · Aider · Google Antigravity · OpenCode · OpenClaw · Hermes · LangChain/LangGraph · CrewAI · PydanticAI · Any MCP Agent |\n| **M3 Is** | A persistent memory layer · An MCP server · A hybrid retrieval engine · A bitemporal knowledge base |\n| **M3 Is Not** | An LLM · A chatbot · A plain vector database · A RAG framework · An IDE |\n| **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. |\n| **Deploys In** | Homelabs and self-hosted stacks · corporate and government networks · **air-gapped and classified environments** · regulated industries (FIPS 140-3-ready, GDPR tooling, audit logs). No account, no API key, no outbound calls. See [Sovereign & Air-Gapped Deployments](#-sovereign--air-gapped-deployments). |\n| **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 a gold session as the **#1 result for 91.8% of questions**. SHR measures the memory layer alone — no answer model, no judge — which is why it, not end-to-end QA, is the like-for-like comparison between memory systems. See [Benchmarks](#-benchmarks). |\n| **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. |\n| **Maturity** | Stable, battle-tested core engine (2,400+ 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)) |\n\n---\n\n## 🧠 Memory Model at a Glance\n\nM3 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)):\n\n*   **Structured Metadata:** Every memory contains a `type`, `source`, `confidence`, `scope`, provenance (`change_agent`), and salience (`importance`, `decay_rate`).\n*   **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.\n*   **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.\n*   **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. Supersession fires above a deliberately conservative cosine bar (`CONTRADICTION_THRESHOLD`, default 0.92), so near-restatements of a claim close the old fact while genuinely different-but-related facts are both kept — use `memory_supersede` to close one explicitly. (See [Technical Details](docs/TECHNICAL_DETAILS.md#contradiction-detection).)\n*   **Self-Maintaining Lifecycle:** Implements memory decay, deduplication, automatic consolidation into higher-order beliefs, TTL expiry, and GDPR erasure.\n*   **Procedural Memory:** A first-class `procedure` type (skill / runbook / how-to / checklist) that is **auto-distilled from successful task runs** — the background loop rolls up a completed task and its step/result memories into a reusable, step-by-step procedure, preserved with `distills_from` provenance back to its sources. A \"how do I…\" query surfaces it via a procedural retrieval boost.\n*   **Write-Gating & Content Safety:** Filters out low-signal noise via an enrichment queue and content safety guardrails before storage.\n*   **Explainable Retrieval:** Hybrid engine combining vector similarity, BM25 (FTS5), MMR diversity, and reranking. `memory_suggest` returns the exact score breakdown per result. (See [Confidence and Trust Guide](docs/CONFIDENCE_AND_TRUST.md)).\n*   **Proven Accuracy:** On LongMemEval-S, M3 delivers **state-of-the-art retrieval for a local-first substrate — 99.2% session-hit-rate @ k=10 and 100% @ k=20** (no oracle routing), with a gold session as the **#1 result for 91.8% of questions**. End-to-end QA accuracy is **92.0%** with no oracle metadata (see [Benchmarking Report](benchmarks/longmemeval/LME-S_Benchmarking_Report.md)).\n\n---\n\n## 📦 Installation\n\n*The [Quickstart](#-quickstart) above covers the common path (`pip install m3-memory` → `m3 setup`). This section adds the alternatives: the shell installer, per-agent wiring, and manual MCP configuration.*\n\n### The One-Liner (macOS & Linux)\n```bash\ncurl -fsSL https://raw.githubusercontent.com/skynetcmd/m3-memory/main/install.sh | bash\n```\n*   *For Windows, please follow the [Windows Manual Installation Guide](docs/install_windows.md).*\n*   *To install manually on any platform, refer to the [OS-Specific Install Instructions](INSTALL.md#tldr--manual-path-per-os) or examine the [installer script](https://raw.githubusercontent.com/skynetcmd/m3-memory/main/install.sh).*\n\n### Developer Setup Wizard\nIf you are developing inside python environments:\n```bash\npip install m3-memory\nm3 setup\n```\nThe `m3 setup` wizard automatically **detects your installed agents** — Claude Code, Cursor, Cline, Gemini CLI, OpenCode, Antigravity, OpenClaw, Hermes — and wires the m3 `memory` MCP server into each, installs settings files/hooks, provisions the sovereign CPU embedder, and performs a system diagnostic. Detection and wiring re-run on every `m3 update`/`m3 setup`, and `m3 doctor --fix` repoints any config whose paths have moved — so an agent you install *later* gets picked up automatically the next time you run setup or update.\n\n### Integrating with AI Coding Tools\n\n#### 🤖 Claude Code\nInstall as a plugin to unlock `/m3:*` slash commands, curation subagents, and automatic hooks:\n```\n/plugin marketplace add skynetcmd/m3-memory\n/plugin install m3@skynetcmd\n```\n*See [Claude Code Plugin Reference](docs/claude_code_plugin.md) and [Claude.ai Connector Guide](docs/claude_ai_connector.md).*\n\n#### ▷ Cursor\nAuto-detected and wired by the setup wizard — it writes the m3 `memory` MCP server into `~/.cursor/mcp.json`:\n```bash\nm3 setup\n```\nRe-run after installing Cursor and it's picked up automatically; `m3 doctor --fix` repoints the entry if paths move. *See [MCP Client Install Guide](docs/MCP_CLIENT_INSTALL.md).*\n\n#### ◧ Cline (VS Code)\nAuto-detected and wired by the setup wizard — it writes the m3 `memory` MCP server into Cline's `cline_mcp_settings.json`:\n```bash\nm3 setup\n```\nAlso available from [Cline's MCP marketplace](https://github.com/cline/mcp-marketplace) (see [`llms-install.md`](llms-install.md)). *See [MCP Client Install Guide](docs/MCP_CLIENT_INSTALL.md).*\n\n#### 🪐 Google Antigravity\nInstall the plugin directly:\n```bash\nagy plugin install https://github.com/skynetcmd/m3-memory\n```\n*See [Antigravity Plugin Reference](docs/antigravity_plugin.md).*\n\n#### 🦊 Hermes Agent\nRun the wizard to automatically wire up optimal memory providers:\n```bash\nm3 setup\n```\n*See [Hermes Plugin Integration Guide](docs/HERMES.md).*\n\n#### 🐍 Python / LangChain & LangGraph\nUse M3 as a drop-in Mem0 replacement or LangMem backend:\n```bash\npip install m3-memory[langchain]\n```\n*See [LangChain Integration Guide](docs/integrations/LANGCHAIN.md).*\n\n#### 👥 CrewAI (v1.x)\nA drop-in `StorageBackend` for CrewAI's unified memory:\n```bash\npip install m3-memory[crewai]   # crewai>=1.10,<2 · Python 3.10–3.13 (a 3.14 escape hatch is documented)\n```\n*See [CrewAI Integration Guide](m3_memory/integrations/crewai/README.md).*\n\n#### 🧩 PydanticAI\nm3 tools + auto-recall, or a formal `M3MemoryToolset`. Built on Pydantic v2 — runs natively on Python 3.14:\n```bash\npip install m3-memory[pydantic-ai]   # pydantic-ai-slim>=2,<3\n```\n*See [PydanticAI Integration Guide](m3_memory/integrations/pydantic_ai/README.md).*\n\n---\n\n### Manual MCP Server Configuration\nTo expose M3 to any Model Context Protocol host, add it to your configuration file:\n\n```json\n{\n  \"mcpServers\": {\n    \"memory\": {\n      \"command\": \"m3\"\n    }\n  }\n}\n```\n\n---\n\n## 🎚️ Domain Gating: the Full Catalog Without the Context Cost\n\nM3 gives you the full 100+ tool surface while occupying just **1.8% of a 200K context window** at startup — most MCP servers make you pay for every tool in every prompt. Tools are grouped into **9 domains** (`memory`, `chatlog`, `files`, `entity`, `agent`, `tasks`, `conversations`, `diagnostics`, `admin`) and loaded lazily.\n\nOnly the essential core set (~18, ~3,540 tokens) registers at startup. When your agent needs advanced functionality, it calls `tools_load_domain(domain=\"...\")` to fetch the rest on demand — so a large catalog costs near-zero context until you actually use a domain.\n\n| Gating Mode | Registered Tools | Tokens in Schema | % of 200K Window |\n| :--- | :---: | :---: | :---: |\n| **Lazy (Default)** | **~18** | **~3,540** | **1.8%** |\n| Typical Active Session | 64 | ~17,975 | 9.0% |\n| Eager Mode (`M3_TOOLS_LAZY=0`) | 110 | ~24,918 | 12.5% |\n\n> 🛠️ *Note: If your client does not support dynamic tool registration, set the environment variable `M3_TOOLS_LAZY=0` to register all tools eagerly.*\n\n---\n\n## 🛡️ Sovereign & Air-Gapped Deployments\n\nM3 operates completely offline by default.\n\n### Sovereign Local Embedder\nA high-performance BGE-M3 embedder runs locally after installation.\n*   **Default:** **in-process** via the `m3-core-rs` native module (llama.cpp linked in-process, zero IPC — *not* a separate service you have to run or monitor). CPU execution using GGUF format (`_assets/models/bge-m3-Q4_K_M.gguf`). A local HTTP embed server on `127.0.0.1:8082` exists only as an automatic fallback if the in-process path can't load.\n*   **Hardware Acceleration (GPU):** Execute `m3 embedder install-gpu` to compile with CUDA, Vulkan, or Metal.\n*   **External Provider Fallback:** Set `EMBED_BASE_URL` to route requests to Ollama, LM Studio, or vLLM.\n\n### Rust-Oxidized Performance Core\nM3 includes an optional Rust performance module (`m3_core_rs`) that speeds up MMR re-ranking, batch cosine distance calculations, and FTS compilations by **90× to 800×**. If absent, M3 falls back to pure Python execution automatically. Disable with `M3_CORE_RS_DISABLE=1`. (See [Oxidation Benchmarks](docs/OXIDATION_BENCHMARKS.md)).\n\n### Enterprise Security & Compliance\n*   **FIPS 140-3 Ready:** Standardized encryption pathways allow routing through validated cryptographic modules (e.g., wolfSSL via `M3_FIPS_MODE=1`).\n*   **Air-Gapped Install:** Supports installation without internet access via pre-compiled python wheels. (See [Sovereign Deployment Guide](docs/SOVEREIGN_DEPLOYMENT.md) & [FIPS Boundary Reference](docs/FIPS_MODULE_BOUNDARY.md)).\n*   **Storage Location:** State lives under three roots, so databases and configuration can be relocated and secured independently:\n\n    | Root | Default | Holds |\n    | :--- | :--- | :--- |\n    | `M3_ENGINE_ROOT` | `~/.m3/engine` | Databases + runtime state (`agent_memory.db`, `agent_chatlog.db`, `files_database.db`) |\n    | `M3_CONFIG_ROOT` | `~/.m3/config` | Configuration (chatlog config, salt) |\n    | `M3_MEMORY_ROOT` | `~/.m3-memory` | Payload / repo clone |\n\n    **All three are overridable.** Set any of them to relocate that root. `M3_MEMORY_ROOT` also acts as a master override — if set and the other two are unset, engine and config derive from it as `<root>/engine` and `<root>/config`. Precedence is `M3_ENGINE_ROOT` / `M3_CONFIG_ROOT` → `M3_MEMORY_ROOT/…` → the `~/.m3/…` default, so a specific root always wins over the master. (See [Architecture](docs/ARCHITECTURE.md).)\n\n---\n\n## 🔮 What M3 Does\n\n*   **Memory Persistence:** Saves system architecture, project decisions, and preferences across tool boundaries using a local SQLite database.\n*   **Autonomous Cognitive Loop:** Background worker (`m3_cognitive_loop.py`) that periodically sweeps chat logs to extract facts, reconcile contradictions, and construct an entity relationship graph.\n*   **Hybrid Vector & Keyword Search:** Seamlessly merges vector space, Full-Text Search (FTS5 BM25), and MMR diversity.\n*   **Hierarchical File Ingestion:** A dedicated 26-tool files domain reads directories, chunks files, extracts facts, and reviews staleness — with ~4× faster incremental re-ingest (unchanged sections reuse cached embeddings).\n*   **Verbatim Chatlog Capture:** A dedicated 10-tool chatlog domain records conversation turns *before compaction*, so prior Claude/Gemini sessions stay searchable and nothing is lost to context-window truncation.\n*   **Pluggable Storage Backend:** SQLite by default; select **PostgreSQL as a first-class primary store** with `M3_DB_BACKEND=postgres`. Same semantics on either backend — the choice doesn't change behavior.\n*   **Cross-Device Sync:** Optionally sync/federate to a PostgreSQL warehouse tier. Access the same memories on your laptop, desktop, or cloud environments.\n\n---\n\n## 📚 Documentation Index\n\n**Start here, in this order:** [Getting Started](docs/GETTING_STARTED.md) → [Memory Model](docs/MEMORY_MODEL.md) (what a memory *is*, and how supersession works) → [Agent Instructions](docs/AGENT_INSTRUCTIONS.md) (how to make your agent use it well). Everything else below is reference — reach for it when you hit the specific thing it covers.\n\n| Quick & Core | Advanced & Architecture | Integrations & Compliance |\n| :--- | :--- | :--- |\n| 🚀 **[Getting Started Guide](docs/GETTING_STARTED.md)** | 🏗️ **[System Architecture](docs/ARCHITECTURE.md)** | 🧩 **[LangChain/LangGraph](docs/integrations/LANGCHAIN.md)** |\n| ✨ **[Core Features](docs/CORE_FEATURES.md)** | 🔧 **[Technical Implementation](docs/TECHNICAL_DETAILS.md)** | 🧩 **[Hermes Agent](docs/HERMES.md)** |\n| ⚙️ **[Environment Variables](docs/ENVIRONMENT_VARIABLES.md)** | 🧠 **[Memory Model Guide](docs/MEMORY_MODEL.md)** | 🛡️ **[Compliance Guide](docs/COMPLIANCE.md)** (GDPR, FISMA) |\n| 🛠️ **[Operations Playbook](docs/OPERATIONS.md)** | ⚡ **[Rust Oxidation benchmarks](docs/OXIDATION_BENCHMARKS.md)** | 🛡️ **[FIPS Cryptographic Boundary](docs/FIPS_MODULE_BOUNDARY.md)** |\n| 🤖 **[Agent Instructions & Rules](docs/AGENT_INSTRUCTIONS.md)** | 🔍 **[Myths & Facts Guide](docs/MYTHS_AND_FACTS.md)** | 🏠 **[Homelab Patterns](docs/HOMELAB_PATTERNS.md)** |\n| 🧩 **[Tool Capability Matrix](docs/CAPABILITY_MATRIX.md)** | 🤖 **[AI Context Injection Profile](docs/llm-context.md)** | 🔢 **[Machine-Readable Features](docs/features.json)** |\n\n### More Documentation\n\n| Guide | Guide | Guide |\n| :--- | :--- | :--- |\n| 🗺️ [Roadmap](docs/ROADMAP.md) | 🔄 [Cross-Device Sync](docs/SYNC.md) | 👥 [Multi-Agent Orchestration](docs/MULTI_AGENT.md) |\n| ⚖️ [Comparison vs Alternatives](docs/COMPARISON.md) | ❓ [FAQ](docs/FAQ.md) | 🔐 [Security Policy](docs/SECURITY.md) |\n| 🩹 [Troubleshooting](docs/TROUBLESHOOTING.md) | ⌨️ [CLI Reference](docs/CLI_REFERENCE.md) | 📖 [API Reference](docs/API_REFERENCE.md) |\n| 📁 [Files Memory](docs/FILES_MEMORY.md) | 💬 [Chat Log Subsystem](docs/CHATLOG.md) | ✨ [Enrichment Guide](docs/M3_ENRICH_GUIDE.md) |\n| ⬆️ [Upgrade Guide](docs/HOW-TO-UPGRADE.md) | 🩺 [Health FAQ](docs/M3_HEALTH_FAQ.md) | 🧬 [Dual Embedding](docs/DUAL_EMBED.md) |\n| 📜 [Changelog](CHANGELOG.md) | 🤝 [Code of Conduct](docs/CODE_OF_CONDUCT.md) | 🏗️ [Build Wheels](docs/BUILD_WHEELS.md) |\n\n---\n\n## 🎯 Who This Is For\n\n### M3 is a great fit if...\n*   **You run a homelab or self-hosted stack:** M3 is a single `pip install` with no\n    account, no API key, and no outbound calls — it runs on the hardware you already\n    own, alongside your other self-hosted services. SQLite by default (zero\n    infrastructure); PostgreSQL when you want a shared store across machines.\n*   **You operate under sovereignty or data-residency requirements** — corporate,\n    government, defence, healthcare, or any regulated environment: memory and\n    embeddings never leave your boundary. The embedder is in-process and local, the\n    store is a file you control, and installation works **fully air-gapped** from\n    pre-compiled wheels. FIPS 140-3-ready crypto (`M3_FIPS_MODE=1`), GDPR\n    `gdpr_forget` / `gdpr_export`, audit logs, and relocatable storage roots so\n    databases and configuration can be secured independently.\n*   **You want the freedom to switch or add agents without losing what they know:** change tools on the fly or down the road — Claude Code, Gemini, OpenClaw, Hermes, whatever comes next — and your project's knowledge carries over instead of disappearing with the switch.\n*   **You build with LangChain/LangGraph:** An advanced replacement for standard memory models, adding bitemporal queries, contradiction management, and local embeddings.\n*   **You build with CrewAI (v1.10–1.x):** A drop-in `StorageBackend` (`Memory(storage=M3StorageBackend(user_id=\"crew-alpha\"))`) that gives CrewAI bitemporal recall, contradiction-aware supersession, and local embeddings — plus the thing single-vector stores can't do: a CrewAI-written memory can **also be searchable by every other m3 agent** (Claude Code, Gemini, LangChain) if you want. `pip install m3-memory[crewai]`. See the [CrewAI integration guide](m3_memory/integrations/crewai/README.md).\n*   **You build with PydanticAI:** m3-backed memory as either drop-in tools + auto-recall (`register_m3_tools`, `m3_recall_processor`) **or** a formal `M3MemoryToolset` (a real PydanticAI `AbstractToolset`). Built on Pydantic v2, so it runs on Python 3.14 with a plain `pip install m3-memory[pydantic-ai]`. See the [PydanticAI integration guide](m3_memory/integrations/pydantic_ai/README.md).\n*   **You need security and compliance:** Built-in `gdpr_forget` and `gdpr_export` tools, air-gapped support, and audit logs.\n*   **You value privacy:** Zero external cloud requests or subscriptions required.\n\n### M3 is NOT a fit if...\n*   You need a hosted SaaS dashboard with managed infrastructure (use [Letta](https://letta.ai)).\n*   **You don't want persistent memory:** you want each session to start fresh, with no ability to retrieve prior sessions' knowledge — M3 exists to do the opposite, so your agent's built-in defaults are the simpler fit.\n\n---\n\n## 🛡️ Why Trust This\n\n*   **Benchmarked Retrieval:** State-of-the-art for a local-first substrate — 99.2% session-hit-rate @ k=10, 100% @ k=20 on LongMemEval-S — with a published, reproducible methodology and no oracle routing. See [Benchmarks](#-benchmarks).\n*   **Robust Coverage:** Over **2,400 tests** guarding correct behavior across search, sync, GDPR lifecycle, and files ingestion — run with warnings-as-errors, so a new warning fails the suite.\n*   **Audit Reports:** Regular vulnerability reports (Bandit, secrets scans, pip-audit) published directly under [`docs/audits/`](docs/audits/).\n*   **Explainable Retrieval:** No black-box queries; retrieval math is open, readable, and scoring parameters are outputted directly.\n*   **Open Source:** Apache 2.0 licensed, free, with no SaaS walls or usage limits.\n\n---\n\n## 📊 Benchmarks\n\n> **Read retrieval accuracy first — it is the only number that measures the memory layer.**\n>\n> **Session Hit-Rate (SHR)** asks one question: *did the system surface the\n> evidence that answers the query?* No answer model is involved, so the score\n> reflects the memory layer and nothing else. It is the like-for-like metric\n> across memory systems.\n>\n> **End-to-end QA accuracy** runs that retrieved context through an LLM and has\n> a judge model grade the answer. Both choices move the score independently of\n> retrieval: a stronger answerer lifts a weaker memory layer, a lenient judge\n> lifts everyone, and neither is held constant across published comparisons. Two\n> systems quoting QA numbers are usually not measuring the same thing.\n>\n> Both are reported below. **SHR is the headline; QA is context.**\n\n### Retrieval Accuracy — Session Hit-Rate @ k *(the memory-layer metric)*\nEvaluated on the 500-question [LongMemEval-S](https://github.com/xiaowu0162/LongMemEval) dataset under default server configurations:\n\n| Retrieve Depth (k) | Session Hit-Rate (SHR) ⁂ | Success Count | vs. Prior Version |\n| :---: | :---: | :---: | :---: |\n| 1 | **91.8%** | 459 / 500 | First Report † |\n| 5 | **98.2%** | 491 / 500 | +2.0pp |\n| 10 (Default) | **99.2%** | 496 / 500 | +2.4pp |\n| 20 | **100.0%** | 500 / 500 | First Report ‡ |\n\n> † **SHR@1** is the strictest cut — a gold session as the single top-ranked result. M3 operates at **k=10** (its default), where a gold session is present for 99.2% of questions; k=1 is reported here for completeness, not as the headline. Cross-system SHR/recall figures are usually quoted at k=5, k=10, k=20, or k=50, so comparing another system's k=10+ number against this k=1 figure is not a like-for-like comparison.\n\n> ⁂ **Which aggregation.** These are binary per-question `recall_any@k` values — the convention adjacent LongMemEval submissions report. The benchmarking report's per-question-type table aggregates slightly differently and reads marginally higher at shallow depth (98.8% at k=5, 99.4% at k=10); k=20 is 100.0% either way. The table above quotes the more conservative figures.\n\n> ‡ **v3 improvement** — the v3 engine reaches **100% SHR at k=20**, exceeding the prior version's **97.8% measured at the deeper k=30** ([LongMemEval issue #43](https://github.com/xiaowu0162/LongMemEval/issues/43)) — higher recall at shallower depth. Both figures are retrieval-only SHR (no answerer). The \"vs. Prior Version\" deltas at k=5/k=10 compare v3 against the prior version's 96.2% / 96.8% at the same k.\n\n### End-to-End QA Accuracy *(answer-model and judge dependent — not a memory-layer comparison)*\n**92.0% accuracy** (460/500 correct responses) with zero oracle metadata routing.\nReported for completeness; see the note above on why this number is not\ncomparable across systems the way SHR is:\n\n| Question Domain | Count (n) | Accuracy |\n| :--- | :---: | :---: |\n| single-session-user | 70 | 94.3% |\n| single-session-assistant | 56 | 96.4% |\n| single-session-preference | 30 | 80.0% |\n| multi-session | 133 | 87.2% |\n| temporal-reasoning | 133 | 95.5% |\n| knowledge-update | 78 | 93.6% |\n| **Overall Summary** | **500** | **92.0%** |\n\n*Methodology and reproducibility details are located in the [LongMemEval-S Benchmarking Report](benchmarks/longmemeval/LME-S_Benchmarking_Report.md).*\n\n---\n\n## 🧰 Core Tools\n\nWhile M3 features 100+ tools, these five serve as your primary interface:\n\n| Tool Name | Operation Description |\n| :--- | :--- |\n| `memory_write` | Save a specific fact, project preference, or technical configuration. |\n| `memory_search` | Run hybrid keyword (BM25) and semantic vector search. |\n| `memory_update` | Edit existing facts to keep memory accurate. |\n| `memory_suggest` | Query memories alongside a mathematically explicit score breakdown. |\n| `memory_get` | Fetch details of a single memory using its unique ID. |\n\n*Refer to the [Agent Instructions Guide](docs/AGENT_INSTRUCTIONS.md) and [Full MCP Tool Catalog](docs/MCP_TOOLS.md) for complete parameter definitions.*\n\n---\n\n## 🤖 For AI Agents\n\nYou can drop the agent ruleset file [`examples/AGENT_RULES.md`](examples/AGENT_RULES.md) into your workspace to teach your agent best practices (e.g., query before writing, update existing records instead of duplicating).\n\n### Command Installation Prompts\nCopy and paste these prompts into your terminal client to let your agent set up M3 for you:\n\n#### Claude Code Prompt\n```text\nInstall m3-memory for persistent memory. Run: pip install m3-memory\nThen run: m3 setup\nThat wires the m3 \"memory\" MCP server into my agents and provisions the\nlocal BGE-M3 embedder — no external embedding service is needed. If it\ndoesn't detect Claude Code, add {\"mcpServers\":{\"memory\":{\"command\":\"m3\"}}}\nto my ~/.claude/settings.json under \"mcpServers\". Then use /mcp to verify\nthe memory server loaded.\n```\n\n#### Gemini CLI Prompt\n```text\nInstall m3-memory for persistent memory. Run: pip install m3-memory\nThen run: m3 setup\nThat wires the m3 \"memory\" MCP server into my agents and provisions the\nlocal BGE-M3 embedder — no external embedding service is needed. If it\ndoesn't detect Gemini CLI, add {\"mcpServers\":{\"memory\":{\"command\":\"m3\"}}}\nto my ~/.gemini/settings.json under \"mcpServers\".\n```\n\n#### Active Chatlog Capture Plugin\nTo configure instant conversation logging and backup, tell your active coding agent:\n```text\nInstall the m3-memory chat log subsystem.\n```\nThe agent executes `bin/chatlog_init.py` and configures execution triggers (see [Chat Log Architecture Guide](docs/CHATLOG.md)).\n\n---\n\n## 🎬 See it in action\n\n### Contradiction Detection & Automatic Resolution\n<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/demo_contradiction.svg\" alt=\"Contradiction Demo\" width=\"100%\">\n</p>\n\n### Hybrid Search Scoring Details\n<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/demo_search.svg\" alt=\"Hybrid Search Demo\" width=\"100%\">\n</p>\n\n### Multi-Device Database Sync\n<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/demo_sync.svg\" alt=\"Sync Demo\" width=\"100%\">\n</p>\n\n---\n\n## 💬 Community\n\n[![Discord Badge](https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/discord.svg)](https://discord.gg/ZcJ3EGC99B)\n&nbsp;\n[![GitHub Issues Badge](https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/github-issues.svg)](https://github.com/skynetcmd/m3-memory/issues)\n\n[How to Contribute](docs/CONTRIBUTING.md) · [FAQ for Developers](docs/FAQ_FOR_DEVELOPERS.md) · [Good First Issues](docs/GOOD_FIRST_ISSUES.md)\n\n---\n\n## 📜 License & Attributions\n\nThis project is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.\n\n### Built with\n\nM3 Memory is authored and maintained by **skynetCMD**. It was built with the help of\nAI coding assistants — **Gemini CLI**, **Claude Code**, and **Google Antigravity** —\nwhich contributed code under the author's direction. (They are tools that assisted;\nthey are not maintainers, sponsors, or co-owners of the project.)\n\n### Asset & Icon Credits\nThe provider badges under [`docs/badges/`](docs/badges/) embed small logo glyphs:\n* **OpenClaw & OpenCode icons** are from the MIT-licensed [LobeHub icon set](https://github.com/lobehub/lobe-icons) (`lobe-icons`).\n* **The Hermes badge** uses a generic caduceus glyph.\n\nSee [NOTICE](NOTICE) for the full third-party attribution list.\n\n<br>\n<p align=\"center\"><sub>PyPI downloads are the pepy.tech total. Badges are regenerated on a schedule by <a href=\"https://github.com/skynetcmd/m3-memory/blob/main/.github/workflows/star-history.yml\">star-history.yml</a>.</sub></p>\n<p align=\"center\"><sub><b>Python:</b> m3 core runs on 3.11+ (including 3.14). The optional framework extras follow their own caps — <b>PydanticAI</b> is 3.14-native (plain <code>pip install</code>); <b>CrewAI</b> requires 3.10–3.13 (a 3.14 escape hatch is <a href=\"https://github.com/skynetcmd/m3-memory/blob/main/m3_memory/integrations/crewai/README.md\">documented</a>).</sub></p>\n</br><p></p>\n---\n\n### ⭐ Star History\n\n<details>\n<summary><b>⭐ View star history →</b> (click to expand the chart)</summary>\n\n<br>\n\n<a href=\"https://star-history.com/#skynetcmd/m3-memory&Date\">\n  <img src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/star-history.svg\" alt=\"Star history for skynetcmd/m3-memory\" width=\"100%\">\n</a>\n\n<sup>Chart regenerated on a schedule by [`.github/workflows/star-history.yml`](.github/workflows/star-history.yml) using the repo's own token — no third-party embed. Click through for the live interactive version.</sup>\n\n</details>\n\n<!-- mcp-name: io.github.skynetcmd/m3-memory -->\n\n",
  "bytes": 39470,
  "sha": "24a5b0a20d392c1bc3f70c0a513ffe0353850b73c6a84a464242048d2153333b",
  "repo_slug": "skynetcmd/m3-memory",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_skynetcmd_m3_memory_7d021ad1/readme"
}