🧠 M3 Memory — Local-First Agentic Memory for MCP Agents

The privacy-first, MCP-native memory layer for desktop coding agents — automatic contradiction detection, hybrid search, and built-in GDPR compliance. 100% local. Zero cloud.

Try it in 60 seconds

pip install m3-memory

Add one line to your agent's MCP config:

{ "mcpServers": { "memory": { "command": "mcp-memory" } } }

That's it. Claude Code, Gemini CLI, and Aider now have persistent, private memory.

Table of Contents

• Why M3 Memory?
• How It Compares · Full comparison →
• Architecture
• Quick Start
• Features
• 25 MCP Tools
• Documentation
• Community
• Roadmap
• Contributing

Why M3 Memory?

Most agent memory tools make you choose: local speed or cloud persistence or MCP compatibility. M3 Memory gives you all three — running entirely on your hardware with no external API calls.

You're debugging a deployment issue at a coffee shop. Claude Code recalls the architecture decisions from last week, the server configs from yesterday, and the troubleshooting steps that worked before — all from local SQLite, no internet required. Later, at your desktop at home, Gemini CLI picks up exactly where you left off. Same memories. Same knowledge graph. Synced the moment you hit the local network.

Your AI's memory belongs to you, lives on your hardware, and follows you across every device and every agent.

Why choose M3-Memory specifically?

See It in Action

Demo 1 — Automatic contradiction resolution Agent writes "server is on port 8080", then later "server is on port 9000" — M3 detects the conflict, supersedes the old memory, preserves full bitemporal history. No manual cleanup.

Demo 2 — Hybrid search across 1,000 memories FTS5 keyword match + vector similarity + MMR diversity re-ranking in a single pipeline. memory_suggest returns full score breakdown per result.

Demo 3 — Cross-device sync Write on your laptop. Pick it up on your desktop. Bi-directional delta sync via PostgreSQL — crash-resistant, watermark-tracked.

GIFs coming soon — contribute a recording or watch the Discord for updates.

⭐ Star if you want local agents that remember — feedback & issues very welcome!

How It Compares

M3-Memory vs Mem0 vs Letta vs LangChain Memory

Choose M3-Memory if you want the simplest, most private, MCP-native memory backend with automatic consistency and compliance — no framework lock-in.

Choose Mem0 for LangChain / LangGraph / CrewAI and managed cloud memory at scale.

Choose Letta for long-lived autonomous agents that self-edit memory within a full stateful runtime.

Choose LangChain Memory if you're already in the LangGraph ecosystem and want framework-native memory.

→ Full feature-by-feature breakdown: COMPARISON.md

Architecture

graph TD
    subgraph "🤖 AI Agents"
        C[Claude Code]
        G[Gemini CLI]
        A[Aider / OpenClaw]
    end

    subgraph "🌉 MCP Bridge"
        MB[memory_bridge.py — 25 MCP tools]
    end

    subgraph "💾 Storage Layers"
        SQ[(SQLite — Local L1)]
        PG[(PostgreSQL — Sync L2)]
        CH[(ChromaDB — Federated L3)]
    end

    C & G & A <--> MB
    MB <--> SQ
    SQ <-->|Bi-directional Delta Sync| PG
    SQ <-->|Push/Pull| CH

The Memory Write Pipeline

sequenceDiagram
    participant A as Agent
    participant M as M3 Memory
    participant L as Local LLM
    participant S as SQLite

    A->>M: memory_write(content)
    M->>M: Safety Check (XSS / injection / poisoning)
    M->>L: Generate Embedding
    L-->>M: Vector [0.12, -0.05, ...]
    M->>M: Contradiction Detection
    M->>M: Auto-Link Related Memories
    M->>M: SHA-256 Content Hash
    M->>S: Store Memory + Vector
    S-->>M: Success
    M-->>A: Created: <uuid>

Quick Start

Prerequisites

• Python 3.11+
• Any OpenAI-compatible local LLM server: LM Studio, Ollama, vLLM, LocalAI, llama.cpp
• (Optional) PostgreSQL + ChromaDB for full cross-device federation

Install

Option A — pip (recommended):

pip install m3-memory
mcp-memory --version   # confirm the CLI is installed

Add to your agent's MCP config — no path needed:

{
  "mcpServers": {
    "memory": {
      "command": "mcp-memory"
    }
  }
}

Option B — clone (for development):

git clone https://github.com/skynetcmd/m3-memory.git
cd m3-memory
python -m venv .venv
source .venv/bin/activate        # macOS/Linux
# .\.venv\Scripts\Activate.ps1  # Windows PowerShell
pip install -r requirements.txt

Validate

python validate_env.py    # check all dependencies and LLM connectivity
python run_tests.py       # run the end-to-end test suite

Agent Config Locations

For OS-specific setup: macOS · Linux · Windows

M3 Memory auto-discovers in Claude Code and other MCP clients via the MCP Registry. See mcp-server.json for the manifest.

Features

🔍 Hybrid Search That Actually Works

Three-stage pipeline — FTS5 keyword → semantic vector → MMR re-ranking — consistently outperforms pure vector search on technical queries. No more five near-identical results. Every result returns a full score breakdown (vector + BM25 + MMR penalty) via memory_suggest.

🚫 Automatic Contradiction Detection

Write a fact that conflicts with an existing one — M3 detects it automatically. The old memory is soft-deleted, a supersedes relationship is recorded, and the full history is preserved. No stale data. No manual cleanup. No agent-side logic required.

⏳ Bitemporal History

Track not just when a fact was stored, but when it was actually true. Query as_of="2026-01-15" to see what your agent believed on any past date — essential for compliance audits and debugging.

🕸️ Knowledge Graph

Memories auto-link on write (cosine > 0.7). Seven relationship types: related, supports, contradicts, extends, supersedes, references, consolidates. Traverse up to 3 hops with a single memory_graph call.

🧹 Self-Maintaining

Importance decay (0.5%/day after 7 days) · auto-archival (< 0.05 importance after 30 days) · per-agent retention (TTL + max count) · LLM consolidation (merges old groups into summaries) · deduplication (configurable cosine threshold)

🤖 Local LLM Intelligence

Works with any OpenAI-compatible server (LM Studio, Ollama, vLLM, LocalAI): auto-classification into 18 types · conversation summarization · multi-layered consolidation. Zero API costs. Zero data exfiltration.

🛡️ Security & Compliance

GDPR built-in: gdpr_forget (Article 17 — hard delete) · gdpr_export (Article 20 — portable JSON)

🔄 Cross-Device Sync

Bi-directional delta sync: SQLite ↔ PostgreSQL (UUID-based UPSERT, watermark-tracked, crash-resistant) + ChromaDB federation for distributed vector search across LAN. Hourly automated; manual via chroma_sync tool.

25 MCP Tools

Documentation

Community

M3_Bot is live — mention @M3_Bot or use !ask <question> in any channel to query the documentation directly.

Roadmap

Vote on features and propose new ones → ROADMAP.md

Contributing

See CONTRIBUTING.md for how to get started, run the test suite, and submit changes. Good first issues: GOOD_FIRST_ISSUES.md.

Project Structure

bin/          Core MCP bridges, SDK, and automation scripts
memory/       SQLite database and migration logic
config/       Configuration templates for agents and shell
docs/         Architecture diagrams, API reference, and OS install guides
examples/     Demo notebooks, mcp.json snippets, benchmark scripts
scripts/      Maintenance and utility scripts
tests/        End-to-end test suite (41 tests)

Production Release — v2026.4.8 · MIT License · Changelog

M3 Memory: the industrial-strength foundation for agents that remember.