m3-memory 2026.7.14.1

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

🧠 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?

🦜 Core Release Feature: Drop-in LangChain & LangGraph Support M3 now functions as a drop-in Mem0 replacement (one-line import swap) and is fully LangMem-compatible (store=M3Store()). Gain automatic contradiction supersession, bitemporal historical queries, local sovereign embedding, and the full 100+ MCP tool set inside your LangChain apps via pip install m3-memory[langchain]. (See LangChain Integration Guide).

---

🚀 Quick Links & Badges

💡 Get Started Quickly:

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

---

📑 Table of Contents

• 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

Feature	Details
Works With	Claude Code · Gemini CLI · Aider · Google Antigravity · OpenCode · Hermes · LangChain/LangGraph · 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.
Maturity	Production-grade. Uses SQLite by default for lightweight operation; scales out to PostgreSQL for enterprise sync. (See 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):

• Structured Metadata: Every memory contains a type, source, confidence, scope, provenance (change_agent), and salience (importance, decay_rate).
• Bitemporal History: Distinguishes valid-time from transaction-time. Superseded facts are closed rather than deleted, allowing you to 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.
• 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: Evaluated via LongMemEval-S, yielding 92.0% end-to-end QA accuracy and 99.2% recall @ k=10 (see Benchmarking Report).

---

📦 Installation

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 scans your PATH for active agents (Claude Code, Gemini CLI, OpenCode, OpenClaw), installs settings files/hooks, provisions the sovereign CPU embedder, and performs a system diagnostic.

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.

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

---

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 Keeps the Catalog Small

Exposing 100+ tools can overwhelm an LLM's context window. To avoid this, M3 groups its tools into 9 domains (memory, chatlog, files, entity, agent, tasks, conversations, diagnostics, admin) and loads them lazily.

Only the essential core set (~18) registers at startup. When your agent needs advanced functionalities, it calls tools_load_domain(domain="...") to fetch the rest dynamically.

Gating Mode	Registered Tools	Tokens in Schema	% of 200K Window
Lazy (Default)	~18	~3,540	1.8%
Typical Active Session	64	~17,975	9.0%
Eager Mode (M3_TOOLS_LAZY=0)	109	~24,918	12.5%

🛠️ 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 on 127.0.0.1:8082 after installation.

• Default: CPU execution using GGUF format (_assets/models/bge-m3-Q4_K_M.gguf).
• 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: All config and data files reside under ~/.m3-memory (configurable via M3_MEMORY_ROOT).

---

🔮 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.
• Cross-Device Sync: Optional PostgreSQL or ChromaDB synchronization backend. Access the same memories on your laptop, desktop, or cloud environments.

---

📚 Documentation Index

Quick & Core	Advanced & Architecture	Integrations & Compliance
🚀 Getting Started Guide	🏗️ System Architecture	🧩 LangChain/LangGraph
✨ Core Features	🔧 Technical Implementation	🧩 Hermes Agent
⚙️ Environment Variables	🧠 Memory Model Guide	🛡️ Compliance Guide (GDPR, FISMA)
🛠️ Operations Playbook	⚡ Rust Oxidation benchmarks	🛡️ FIPS Cryptographic Boundary
🤖 Agent Instructions & Rules	🔍 Myths & Facts Guide	🏠 Homelab Patterns
🧩 Tool Capability Matrix	🤖 AI Context Injection Profile	🔢 Machine-Readable Features

More Documentation

Guide	Guide	Guide
🗺️ Roadmap	🔄 Cross-Device Sync	👥 Multi-Agent Orchestration
⚖️ Comparison vs Alternatives	❓ FAQ	🔐 Security Policy
🩹 Troubleshooting	⌨️ CLI Reference	📖 API Reference
📁 Files Memory	💬 Chat Log Subsystem	✨ Enrichment Guide
⬆️ Upgrade Guide	🩺 Health FAQ	🧬 Dual Embedding
📜 Changelog	🤝 Code of Conduct	🏗️ Build Wheels

---

🎯 Who This Is For

M3 is a great fit if...

• You use multiple desktop coding agents: Interoperate Claude Code, Gemini, and Aider on a shared local history.
• You build with LangChain/LangGraph: An advanced replacement for standard memory models, adding bitemporal queries, contradiction management, and local embeddings.
• 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 use CrewAI and want standard, framework-native memory models (use Mem0).
• You need a hosted SaaS dashboard with managed infrastructure (use Letta).
• You only want transient in-session chat context that resets when you exit the terminal (rely on your agent's defaults).

---

🛡️ Why Trust This

• Robust Coverage: Verified with 1,283 tests across 154 test files (~2,070 cases with parametrization) spanning search, sync, GDPR lifecycle, and files ingestion.
• 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

Retrieval Recall (Session Hit-Rate @ k)

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

Retrieve Depth (k)	Session Hit-Rate (SHR)	Success Count	vs. Prior Version
5	98.2%	491 / 500	+2.0pp
10 (Default)	99.2%	496 / 500	+2.4pp
20	100.0%	500 / 500	First Report

End-to-End QA Accuracy

92.0% accuracy (460/500 correct responses) with zero oracle metadata routing:

Question Domain	Count (n)	Accuracy
single-session-user	70	94.3%
single-session-assistant	56	96.4%
single-session-preference	30	80.0%
multi-session	133	87.2%
temporal-reasoning	133	95.5%
knowledge-update	78	93.6%
Overall Summary	500	92.0%

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:

Tool Name	Operation Description
memory_write	Save a specific fact, project preference, or technical configuration.
memory_search	Run hybrid keyword (BM25) and semantic vector search.
memory_update	Edit existing facts to keep memory accurate.
memory_suggest	Query memories alongside a mathematically explicit score breakdown.
memory_get	Fetch details of a single memory using its unique ID.

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 add {"mcpServers":{"memory":{"command":"m3"}}} to my
~/.claude/settings.json under "mcpServers". For best retrieval, ensure
Ollama is running with qwen3-embedding:0.6b (optional, falls back
to keyword search without it). Then use /mcp to verify the memory server loaded.

Gemini CLI Prompt

Install m3-memory for persistent memory. Run: pip install m3-memory
Then add {"mcpServers":{"memory":{"command":"m3"}}} to my
~/.gemini/settings.json under "mcpServers". For best retrieval, ensure
Ollama is running with qwen3-embedding:0.6b (optional, falls back
to keyword search without it).

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 · Good First Issues

---

📜 License & Attributions

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

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.

---

⭐ Star History

^{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.}