M3 Memory

![M3 Memory]

M3 Memory

M3 treats agent memory as a distributed-systems problem, not a retrieval feature. Instead of every tool (Claude, Gemini, OpenCode, …) keeping its own throwaway memory, M3 is a shared, evolving, bitemporal knowledge base that multiple heterogeneous agents and machines read and write — built to answer "how do agents maintain a consistent, evolving, temporal knowledge base over months and years?" rather than just "how do we retrieve a chunk?"

That framing is what makes the rest different: memory as persistent infrastructure, bitemporal history ("what did we believe last Tuesday, and when was it corrected?"), automatic contradiction management (not just append-and-hope), a memory-first MCP operational API (not a bare store/fetch), and local-first without giving up cross-agent interoperability.

Local-first Memory Framework for AI Agents · 99.2% LongMemEval-S retrieval @ k=10 · Supports Claude · Gemini · Antigravity · OpenCode · OpenClaw · Hermes · MCP-native and plugins · Hybrid search (FTS5 + vector + MMR) · GDPR · FIPS 140-3 deployment-ready · 100% local (fully offline) or cloud capable

> "Wait, you remember that?" — Stop re-explaining your project to your AI. Give it a long-term brain that stays 100% on your machine. > > 🚀 [New to M3? Start here with our 5-minute "Human-First" guide.](docs/GETTING_STARTED.md)

Works with Claude Code, Gemini CLI, Aider, Google Antigravity, OpenCode, Hermes Agent, and any MCP-compatible agent. Quick one-line command to have your agent install chat log sub-system which saves verbatim chat log info, before compaction, with zero lag/latency and 100% retrieval recall. Just tell your AI agent "install m3-memory chat log sub-system" and your agent will automatically install it with all the proper hooks with some minimal customization questions from you (you can accept the default answers).

> 👉 I've read enough, I just want to install it on [Windows](docs/QUICKSTARTWINDOWS.md), [macOS](docs/QUICKSTARTMACOS.md), or [Linux](docs/QUICKSTART_LINUX.md).

---

📦 Install

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

Installs on macOS or Linux with the single command above. Use this to install on Windows. Use this link to install manually and this to examine the script and what it does.

Claude Code users can also install as a plugin instead — gets you 15 /m3:* slash commands, two curator subagents (m3:curate-memory, m3:curate-chatlog), and auto-wired hooks:

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

Plugin reference · Claude.ai (web/desktop) connector

Google Antigravity users can install the plugin directly:

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

Plugin reference

Hermes Agent users can install the memory-provider plugin directly (supports optimal replacement of default memory or parallel coexistence for rich SOTA retrieval):

# Handled automatically via our setup wizard:
m3 setup

[Plugin integration guide](docs/HERMES.md)

---

Add to your MCP config:

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

🚀 One-command setup

pip install m3-memory
m3 setup

m3 setup is an interactive wizard. It detects every agent on PATH (Claude Code, Gemini CLI, OpenCode, OpenClaw), asks a handful of questions, then drives the full install end-to-end: system payload, sovereign CPU embedder (BGE-M3 on port 8082), per-agent MCP wiring, chatlog hooks, and a doctor verification. Restart your agent — that's it.

🛡️ Sovereign by default

The embedder ships in the repo. Our own BGE-M3 CPU embedder runs as a small always-on service on 127.0.0.1:8082 after m3 setup. No LM Studio, no Ollama, no GPU, no internet required for embedding to work.

| Embedder path | When it's used | What you do | |---|---|---| | Sovereign CPU (port 8082) | Always installed by m3 setup. Concurrency=2 BGE-M3, GGUF bundled via Git LFS at _assets/models/bge-m3-Q4_K_M.gguf. | Nothing — it's the default. | | GPU in-process | Optional opt-in for ~10-50× faster embedding. CUDA / Vulkan / Metal auto-detected. | m3 embedder install-gpu (needs the matching GPU toolchain). | | External (Ollama, LM Studio, vLLM, …) | Power users who want a different model or shared host service. | Set EMBED_BASE_URL to your endpoint; m3 falls back to it if the sovereign service is down. |

Want auto-classification, summarization, and consolidation? Load a small chat model for generation (e.g. qwen2.5:0.5b via Ollama, or any 0.5–1B instruct GGUF). M3 auto-selects it; embedding-only features work without it. See [docs/QUICKSTART.md → Optional: load a small chat model](docs/QUICKSTART.md#optional-load-a-small-chat-model-for-enrichment).

> ⚡ Auto-Oxidation is ON by Default. The performance-critical hot paths — FTS5 query sanitize/compile, batch cosine and hybrid ranking, MMR rerank, and redaction scrubbing — are oxidized to an optional in-process Rust core (m3_core_rs) that ships as a local wheel (no service, no daemon). It is enabled automatically whenever the wheel is importable, and every path falls back silently to the pure-Python implementation when it is absent. On a per-operation micro-benchmark (FFI-inclusive, output-verified, on real DB vectors) the wins are large where it matters — up to ~846× on packed MMR rerank and ~97–178× on packed batch-cosine (the raw-bytes path production actually takes), 11–15× on redaction, plus smaller but consistent wins on FTS query compilation and token-Jaccard (1.4–10×) — while trivially small C-backed ops (e.g. sha256) stay break-even or favor Python and are left on the Python path. Full table, methodology, and caveats: [docs/OXIDATIONBENCHMARKS.md](docs/OXIDATIONBENCHMARKS.md). Opt out at any time by setting M3_CORE_RS_DISABLE=1 to force the pure-Python path. See [docs/ENVIRONMENTVARIABLES.md](docs/ENVIRONMENTVARIABLES.md) for configuration details.

Restart your agent. Done!

---

🎚️ 100+ tools, but they don't all crowd your context — domain gating keeps the catalog small

M3 exposes 100+ MCP tools so power users can customize at fine granularity — single-id deletes, bulk variants, per-store searches, KG traversals, GDPR primitives, agent handoffs, watch-mode admin, the lot. Most agents never touch most of them in a typical session.

To avoid burning context space on tool schemas you won't use, m3 groups its catalog into 8 domains (memory, chatlog, files, entity, agent, tasks, conversations, admin) and loads them lazily. At MCP startup only the essentials register (6 data tools — memory + chatlog + files search/write — plus the 4 always-on dispatcher/meta tools); the rest expose on demand when the agent calls tools_load_domain(domain="…").

Measured on m3 main with the gpt-4o tokenizer over the serialized tool schemas ({name, description, parameters} per tool, as registered on the MCP wire):

| Mode | Tools at startup | Tokens at startup | % of 200 K window | % of 256 K window | |---|---:|---:|---:|---:| | Lazy (default) | 10 | ~3,540 | 1.8 % | 1.4 % | | Typical session (lazy + agent loads files + memory) | 64 | ~17,975 | 9.0 % | 7.0 % | | Eager (M3_TOOLS_LAZY=0 — legacy) | 107 | ~24,918 | 12.5 % | 9.7 % |

For comparison, common alternatives: a 40-tool GitHub MCP server ≈ 12,000 tokens; the full 93-tool GitHub MCP server ≈ 55,000 tokens (MCP Token Counter). m3's lazy default keeps the always-on surface ~7× smaller than the full eager catalog while giving the agent the full tool set whenever it actually needs them.

Disable with M3_TOOLS_LAZY=0 if your client doesn't support dynamic tool registration or you want every tool at startup. Direct Python imports (from memory_bridge import memory_write) always expose every tool — this only gates the MCP wire surface.

---

🛡️ Air-gapped deployment

M3 is sovereign by default — the baseline install needs no external services. For fully air-gapped environments, the only extra step is to pre-stage the repo (with the LFS-tracked GGUF materialized) on a connected machine and transfer it to the target.

# On a connected machine:
git lfs install                                              # one-time
git clone https://github.com/skynetcmd/m3-memory.git
cd m3-memory && git lfs pull                                  # ~438MB
pip download m3-memory -d _assets/python_wheels               # pre-fetch wheels

# On the air-gapped target (after sneakernet-copying the folder):
pip install --no-index --find-links=_assets/python_wheels m3-memory
m3 setup --non-interactive --capture-mode both

That's it. No curl, no LM Studio, no third-party model server.

See the [Sovereign & Air-Gapped Deployment Guide](docs/SOVEREIGN_DEPLOYMENT.md) for full instructions, FIPS-mode hardening, and GPU-on-air-gap details.

By default, m3 stores its configuration, payload, and backups under ~/.m3-memory. Override with M3_MEMORY_ROOT.

🔒 FIPS 140-3 deployment-ready (what that does and doesn't mean)

M3 implements no custom cryptography and uses only FIPS-approved algorithms (AES-256-GCM, SHA-256, PBKDF2-HMAC-SHA256, TLS 1.3). Every cryptographic operation — the encrypted secrets vault, key derivation, the tamper-evident audit hash chain — is routed through a single provider boundary (crypto_provider.py) so a validated module can serve it.

• M3_FIPS_MODE=1 routes all crypto through wolfCrypt (the wolfSSL

cryptographic module), runs power-up Known-Answer-Tests, and fails closed if wolfCrypt isn't available — never silently falling back to Python crypto. This works with the freely-buildable open-source wolfSSL.

• M3_FIPS_STRICT=1 additionally **requires the CMVP-validated wolfCrypt

FIPS module** (the commercial wolfSSL FIPS build) and refuses anything else.

> **M3 itself is not a FIPS-validated cryptographic module — no application > is. "Deployment-ready" means M3 avoids non-approved algorithms, implements no > crypto of its own, and uses a validated provider (wolfCrypt) when configured. > See [docs/FIPSMODULEBOUNDARY.md](docs/FIPSMODULEBOUNDARY.md)** for the > module boundary, the three tiers, and known limitations.

---

🔮 What happens next (benefits of use)

You're at a coffee shop on your MacBook, asking Claude to debug a deployment issue. It remembers the architecture decisions you made last week, the server configs you stored yesterday, and the troubleshooting steps that worked last time — all from local SQLite, no internet required.

Later, you're at your Windows desktop at home with Gemini CLI, and it picks up exactly where you left off. Same memories, same context, same knowledge graph. You didn't copy files, didn't export anything, didn't push to someone else's cloud. Your PostgreSQL sync handled everything in the background the moment your laptop hit the local network.

---

💡 Why this exists

Most AI agents don't persist state between sessions. You re-paste context, re-explain architecture, re-correct mistakes. When facts change, the agent has no mechanism to update what it "knows."

M3 Memory gives agents a structured, persistent memory layer that handles this.

---

⚡ What it does

Autonomous cognitive loop — optional background worker (m3_cognitive_loop.py) that extracts facts, resolves contradictions, and links entities while you sleep. Turns raw chat logs into a refined knowledge graph without human intervention.

Persistent memory — facts, decisions, preferences survive across sessions. Stored in local SQLite.

Hybrid retrieval — FTS5 keyword matching + semantic vector similarity + MMR diversity re-ranking. Automatic, no tuning required.

Contradiction handling — conflicting facts are automatically superseded. Bitemporal versioning preserves the full history.

Knowledge graph — related memories linked automatically on write. Nine relationship types, 3-hop traversal. Entity extraction (entity_search, entity_get) supplements the graph with first-class people / places / things resolution. The entity-graph layer ships a stock entity-type and predicate vocabulary, and it's user-configurable: point M3_ENTITY_VOCAB_YAML at your own profile to swap or extend the vocab for your domain — no code changes.

Zero-config local install — pip install m3-memory plus one line in your MCP config, or m3 setup for a one-command wizard that detects agents, wires settings.json + hooks, installs the sovereign CPU embedder, and verifies with doctor in one shot. SQLite stores everything locally — no external databases, no cloud calls, no API costs. Works offline.

Context-frugal tool catalog — 100+ MCP tools grouped into 8 domains, loaded lazily. Startup surface is ~3,540 tokens (~1.8% of a 200K window) vs ~24,918 if every tool registered eagerly. Agent expands a domain when it needs the rest. See [§ 100+ tools, domain-gated](#-100-tools-but-they-dont-all-crowd-your-context--domain-gating-keeps-the-catalog-small).

Cross-device sync — optional, easy-to-add bi-directional delta sync via PostgreSQL or ChromaDB, with manifest-driven multi-DB support for fleet deployments. Set one environment variable and your memories follow you across machines.

---

📚 Learn more

| | | |---|---| | 🚀 [Getting started](docs/GETTINGSTARTED.md) | 👥 [Multi-agent orchestration](docs/MULTIAGENT.md) | | ✨ [Core features](docs/COREFEATURES.md) | 🧩 [Multi-agent example](examples/multi-agent-team/README.md) | | 🏗️ [System design](docs/ARCHITECTURE.md) | ⚖️ [Compare M3 to alternatives](docs/COMPARISON.md) ([sovereign substrates table](docs/M3ComparisonTable.md)) | | 🔧 [Implementation details](docs/TECHNICALDETAILS.md) | ⚙️ [Configuration](docs/ENVIRONMENTVARIABLES.md) | | 🤖 [Agent rules + all tools](docs/AGENTINSTRUCTIONS.md) | 🛡️ [Compliance & assurance](docs/COMPLIANCE.md) (FISMA, CMMC, GDPR) | | 🏠 [Homelab patterns](docs/HOMELABPATTERNS.md) | 🔍 [Myths & facts](docs/MYTHSAND_FACTS.md) (verify claims about M3) | | 🗺️ [Roadmap](docs/ROADMAP.md) | 📜 [Changelog](CHANGELOG.md) |

---

🎯 Who this is for

M3 is a good fit if…

| | | |---|---| | 🤖 You use coding agents | Claude Code, Gemini CLI, Aider, OpenCode, or any MCP-compatible agent. Non-MCP clients work too via the built-in HTTP proxy. | | 👥 You run multiple agents | Coordinating Claude + Gemini + a background worker on a shared local store, with handoffs and per-agent scoping. | | 🛡️ You need compliance primitives | gdpr_forget / gdpr_export as MCP tools, bitemporal valid-time / transaction-time, audit trail, no telemetry. | | 💾 You want pure local-first | Single-file SQLite. Works offline. No external database, no cloud calls, no API costs by default. | | 🌐 You want memory across devices | Optional bi-directional delta sync via PostgreSQL or ChromaDB — your data, your hardware. |

M3 is not the right tool if…

| | Try instead | |---|---| | You're building LangChain / LangGraph / CrewAI pipelines and want framework-native memory | Mem0, [LangChain Memory /

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: skynetcmd
• Source: skynetcmd/m3-memory
• License: Apache-2.0
• Homepage: https://github.com/skynetcmd/m3-memory

Install and usage instructions live in the source repository linked above.