🧠 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

_{Player not loading? Download the video to play locally.}

⚡ Quickstart

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 — from any agent, or straight from the shell:

$ 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:

$ 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 walks the same path with more context, and 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.

_{Also a drop-in memory backend for LangChain / LangGraph, CrewAI, and PydanticAI — see the framework guides.}

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.

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 for the row-by-row detail.

🚀 Quick Links & Badges

💡 Get Started Quickly:

• 🚀 5-Minute "Human-First" Guide
• 🖥️ OS Installation: Windows Setup · macOS Setup · Linux Setup

📑 Table of Contents

• Quickstart
• Beyond the Core (optional surface)
• Overview & At a Glance
• Memory Model
• Installation & Onboarding
• Domain Gating (Token Optimization)
• Sovereign & Air-Gapped Deployments
• Interactive Features & Capabilities
• Documentation Index
• Target Audience & Fit
• Quality Assurance & Compliance
• Benchmarks & Performance
• Core Tools Reference
• Agent Integration Prompts
• Interactive Demos

⚡ M3 at a Glance

🧠 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):

• 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. 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.)
• 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 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.
• Write-Gating & Content Safety: Filters out low-signal noise via an enrichment queue and content safety guardrails before storage.
• 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).
• 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).

📦 Installation

The 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.

The One-Liner (macOS & Linux)

curl -fsSL https://raw.githubusercontent.com/skynetcmd/m3-memory/main/install.sh | bash

• For Windows, please follow the Windows Manual Installation Guide.
• To install manually on any platform, refer to the OS-Specific Install Instructions or examine the installer script.

Developer Setup Wizard

If you are developing inside python environments:

pip install m3-memory
m3 setup

The 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.

Integrating with AI Coding Tools

🤖 Claude Code

Install as a plugin to unlock /m3:* slash commands, curation subagents, and automatic hooks:

/plugin marketplace add skynetcmd/m3-memory
/plugin install m3@skynetcmd

See Claude Code Plugin Reference and Claude.ai Connector Guide.

▷ Cursor

Auto-detected and wired by the setup wizard — it writes the m3 memory MCP server into ~/.cursor/mcp.json:

m3 setup

Re-run after installing Cursor and it's picked up automatically; m3 doctor --fix repoints the entry if paths move. See MCP Client Install Guide.

◧ Cline (VS Code)

Auto-detected and wired by the setup wizard — it writes the m3 memory MCP server into Cline's cline_mcp_settings.json:

m3 setup

Also available from Cline's MCP marketplace (see llms-install.md). See MCP Client Install Guide.

🪐 Google Antigravity

Install the plugin directly:

agy plugin install https://github.com/skynetcmd/m3-memory

See Antigravity Plugin Reference.

🦊 Hermes Agent

Run the wizard to automatically wire up optimal memory providers:

m3 setup

See Hermes Plugin Integration Guide.

🐍 Python / LangChain & LangGraph

Use M3 as a drop-in Mem0 replacement or LangMem backend:

pip install m3-memory[langchain]

See LangChain Integration Guide.

👥 CrewAI (v1.x)

A drop-in StorageBackend for CrewAI's unified memory:

pip install m3-memory[crewai]   # crewai>=1.10,<2 · Python 3.10–3.13 (a 3.14 escape hatch is documented)

See CrewAI Integration Guide.

🧩 PydanticAI

m3 tools + auto-recall, or a formal M3MemoryToolset. Built on Pydantic v2 — runs natively on Python 3.14:

pip install m3-memory[pydantic-ai]   # pydantic-ai-slim>=2,<3

See PydanticAI Integration Guide.

Manual MCP Server Configuration

To expose M3 to any Model Context Protocol host, add it to your configuration file:

{
  "mcpServers": {
    "memory": {
      "command": "m3"
    }
  }
}

🎚️ Domain Gating: the Full Catalog Without the Context Cost

M3 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.

Only 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.

🛠️ Note: If your client does not support dynamic tool registration, set the environment variable M3_TOOLS_LAZY=0 to register all tools eagerly.

🛡️ Sovereign & Air-Gapped Deployments

M3 operates completely offline by default.

Sovereign Local Embedder

A high-performance BGE-M3 embedder runs locally after installation.

• 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.
• Hardware Acceleration (GPU): Execute m3 embedder install-gpu to compile with CUDA, Vulkan, or Metal.
• External Provider Fallback: Set EMBED_BASE_URL to route requests to Ollama, LM Studio, or vLLM.

Rust-Oxidized Performance Core

M3 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).

Enterprise Security & Compliance

• FIPS 140-3 Ready: Standardized encryption pathways allow routing through validated cryptographic modules (e.g., wolfSSL via M3_FIPS_MODE=1).

• Air-Gapped Install: Supports installation without internet access via pre-compiled python wheels. (See Sovereign Deployment Guide & FIPS Boundary Reference).

• Storage Location: State lives under three roots, so databases and configuration can be relocated and secured independently:

  Root	Default	Holds
  M3_ENGINE_ROOT	~/.m3/engine	Databases + runtime state (agent_memory.db, agent_chatlog.db, files_database.db)
  M3_CONFIG_ROOT	~/.m3/config	Configuration (chatlog config, salt)
  M3_MEMORY_ROOT	~/.m3-memory	Payload / repo clone

  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.)

🔮 What M3 Does

• Memory Persistence: Saves system architecture, project decisions, and preferences across tool boundaries using a local SQLite database.
• 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.
• Hybrid Vector & Keyword Search: Seamlessly merges vector space, Full-Text Search (FTS5 BM25), and MMR diversity.
• 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).
• 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.
• 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.
• Cross-Device Sync: Optionally sync/federate to a PostgreSQL warehouse tier. Access the same memories on your laptop, desktop, or cloud environments.

📚 Documentation Index

Start here, in this order: Getting Started → Memory Model (what a memory is, and how supersession works) → Agent Instructions (how to make your agent use it well). Everything else below is reference — reach for it when you hit the specific thing it covers.

More Documentation

🎯 Who This Is For

M3 is a great fit if...

• You run a homelab or self-hosted stack: M3 is a single pip install with no account, no API key, and no outbound calls — it runs on the hardware you already own, alongside your other self-hosted services. SQLite by default (zero infrastructure); PostgreSQL when you want a shared store across machines.
• You operate under sovereignty or data-residency requirements — corporate, government, defence, healthcare, or any regulated environment: memory and embeddings never leave your boundary. The embedder is in-process and local, the store is a file you control, and installation works fully air-gapped from pre-compiled wheels. FIPS 140-3-ready crypto (M3_FIPS_MODE=1), GDPR gdpr_forget / gdpr_export, audit logs, and relocatable storage roots so databases and configuration can be secured independently.
• 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.
• You build with LangChain/LangGraph: An advanced replacement for standard memory models, adding bitemporal queries, contradiction management, and local embeddings.
• 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.
• 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.
• You need security and compliance: Built-in gdpr_forget and gdpr_export tools, air-gapped support, and audit logs.
• You value privacy: Zero external cloud requests or subscriptions required.

M3 is NOT a fit if...

• You need a hosted SaaS dashboard with managed infrastructure (use Letta).
• 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.

🛡️ Why Trust This

• 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.
• 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.
• Audit Reports: Regular vulnerability reports (Bandit, secrets scans, pip-audit) published directly under docs/audits/.
• Explainable Retrieval: No black-box queries; retrieval math is open, readable, and scoring parameters are outputted directly.
• Open Source: Apache 2.0 licensed, free, with no SaaS walls or usage limits.

📊 Benchmarks

Read retrieval accuracy first — it is the only number that measures the memory layer.

Session Hit-Rate (SHR) asks one question: did the system surface the evidence that answers the query? No answer model is involved, so the score reflects the memory layer and nothing else. It is the like-for-like metric across memory systems.

End-to-end QA accuracy runs that retrieved context through an LLM and has a judge model grade the answer. Both choices move the score independently of retrieval: a stronger answerer lifts a weaker memory layer, a lenient judge lifts everyone, and neither is held constant across published comparisons. Two systems quoting QA numbers are usually not measuring the same thing.

Both are reported below. SHR is the headline; QA is context.

Retrieval Accuracy — Session Hit-Rate @ k (the memory-layer metric)

Evaluated on the 500-question LongMemEval-S dataset under default server configurations:

† 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.

⁂ 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.

‡ 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) — 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.

End-to-End QA Accuracy (answer-model and judge dependent — not a memory-layer comparison)

92.0% accuracy (460/500 correct responses) with zero oracle metadata routing. Reported for completeness; see the note above on why this number is not comparable across systems the way SHR is:

Methodology and reproducibility details are located in the LongMemEval-S Benchmarking Report.

🧰 Core Tools

While M3 features 100+ tools, these five serve as your primary interface:

Refer to the Agent Instructions Guide and Full MCP Tool Catalog for complete parameter definitions.

🤖 For AI Agents

You can drop the agent ruleset file examples/AGENT_RULES.md into your workspace to teach your agent best practices (e.g., query before writing, update existing records instead of duplicating).

Command Installation Prompts

Copy and paste these prompts into your terminal client to let your agent set up M3 for you:

Claude Code Prompt

Install m3-memory for persistent memory. Run: pip install m3-memory
Then run: m3 setup
That wires the m3 "memory" MCP server into my agents and provisions the
local BGE-M3 embedder — no external embedding service is needed. If it
doesn't detect Claude Code, add {"mcpServers":{"memory":{"command":"m3"}}}
to my ~/.claude/settings.json under "mcpServers". Then use /mcp to verify
the memory server loaded.

Gemini CLI Prompt

Install m3-memory for persistent memory. Run: pip install m3-memory
Then run: m3 setup
That wires the m3 "memory" MCP server into my agents and provisions the
local BGE-M3 embedder — no external embedding service is needed. If it
doesn't detect Gemini CLI, add {"mcpServers":{"memory":{"command":"m3"}}}
to my ~/.gemini/settings.json under "mcpServers".

Active Chatlog Capture Plugin

To configure instant conversation logging and backup, tell your active coding agent:

Install the m3-memory chat log subsystem.

The agent executes bin/chatlog_init.py and configures execution triggers (see Chat Log Architecture Guide).

🎬 See it in action

Contradiction Detection & Automatic Resolution

Hybrid Search Scoring Details

Multi-Device Database Sync

💬 Community

How to Contribute · FAQ for Developers · Good First Issues

📜 License & Attributions

This project is licensed under the Apache License 2.0. See LICENSE for details.

Built with

M3 Memory is authored and maintained by skynetCMD. It was built with the help of AI coding assistants — Gemini CLI, Claude Code, and Google Antigravity — which contributed code under the author's direction. (They are tools that assisted; they are not maintainers, sponsors, or co-owners of the project.)

Asset & Icon Credits

The provider badges under docs/badges/ embed small logo glyphs:

• OpenClaw & OpenCode icons are from the MIT-licensed LobeHub icon set (lobe-icons).
• The Hermes badge uses a generic caduceus glyph.

See NOTICE for the full third-party attribution list.

_{PyPI downloads are the pepy.tech total. Badges are regenerated on a schedule by star-history.yml.}

_{Python: m3 core runs on 3.11+ (including 3.14). The optional framework extras follow their own caps — PydanticAI is 3.14-native (plain pip install); CrewAI requires 3.10–3.13 (a 3.14 escape hatch is documented).}

⭐ Star History

⭐ View star history → (click to expand the chart)

^{Chart regenerated on a schedule by .github/workflows/star-history.yml using the repo's own token — no third-party embed. Click through for the live interactive version.}