{"id":49499640,"url":"https://github.com/skynetcmd/m3-memory","last_synced_at":"2026-07-19T02:08:57.705Z","repository":{"id":349444072,"uuid":"1167246588","full_name":"skynetcmd/m3-memory","owner":"skynetcmd","description":"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 ready · 100% local (fully offline) or cloud capable","archived":false,"fork":false,"pushed_at":"2026-06-22T03:44:27.000Z","size":12384,"stargazers_count":14,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-22T05:14:52.739Z","etag":null,"topics":["agentic-memory","ai-agents","ai-memory","aider","claude-code","fips-140-3","gdpr","gemini","gemini-cli","homelab","local-llm","long-term-memory-llm","longmemeval","mcp","mcp-server","openclaw","privacy","rag","rag-memory","vector-search"],"latest_commit_sha":null,"homepage":"https://github.com/skynetcmd/m3-memory","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skynetcmd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["skynetcmd"]}},"created_at":"2026-02-26T04:56:40.000Z","updated_at":"2026-06-22T03:42:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/skynetcmd/m3-memory","commit_stats":null,"previous_names":["skynetcmd/m3-memory"],"tags_count":51,"template":false,"template_full_name":null,"purl":"pkg:github/skynetcmd/m3-memory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skynetcmd%2Fm3-memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skynetcmd%2Fm3-memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skynetcmd%2Fm3-memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skynetcmd%2Fm3-memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skynetcmd","download_url":"https://codeload.github.com/skynetcmd/m3-memory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skynetcmd%2Fm3-memory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34885802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-memory","ai-agents","ai-memory","aider","claude-code","fips-140-3","gdpr","gemini","gemini-cli","homelab","local-llm","long-term-memory-llm","longmemeval","mcp","mcp-server","openclaw","privacy","rag","rag-memory","vector-search"],"created_at":"2026-05-01T12:01:55.165Z","updated_at":"2026-07-19T02:08:57.691Z","avatar_url":"https://github.com/skynetcmd.png","language":"Python","funding_links":["https://github.com/sponsors/skynetcmd"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/skynetcmd/m3-memory\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/M3-banner.jpg\" alt=\"M3 Memory Banner\" width=\"100%\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# 🧠 M3 Memory\n\nM3 treats agent memory as a **distributed-systems infrastructure problem**, not a simple retrieval feature.\n\nInstead 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?*\n\n\u003e 🦜 **Core Release Feature: Drop-in LangChain \u0026 LangGraph Support**\n\u003e 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](docs/integrations/LANGCHAIN.md)).\n\n---\n\n## 🚀 Quick Links \u0026 Badges\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"macOS\" src=\"https://img.shields.io/badge/macOS-000000?style=flat-square\u0026logo=apple\u0026logoColor=white\"\u003e\n  \u003cimg alt=\"Windows\" src=\"https://img.shields.io/badge/Windows-0078D4?style=flat-square\u0026logo=windows\u0026logoColor=white\"\u003e\n  \u003cimg alt=\"Linux\" src=\"https://img.shields.io/badge/Linux-FCC624?style=flat-square\u0026logo=linux\u0026logoColor=black\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/m3-memory/\"\u003e\u003cimg alt=\"PyPI downloads (estimated total)\" src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/pypi-downloads.json\u0026style=flat-square\u0026logo=pypi\u0026logoColor=white\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/skynetcmd/m3-memory\"\u003e\u003cimg alt=\"GitHub unique clones (estimated total)\" src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/github-clones.json\u0026style=flat-square\u0026logo=github\u0026logoColor=white\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://star-history.com/#skynetcmd/m3-memory\u0026Date\"\u003e\u003cimg alt=\"Star history — click to view\" src=\"https://img.shields.io/badge/%E2%AD%90%20star%20history-181717?style=flat-square\u0026logo=github\u0026logoColor=white\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/m3-memory/\"\u003e\u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/m3-memory?style=flat-square\u0026color=blue\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org\"\u003e\u003cimg alt=\"Python 3.11+\" src=\"https://img.shields.io/badge/python-3.11+-blue?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/skynetcmd/m3-memory/blob/main/LICENSE\"\u003e\u003cimg alt=\"Apache 2.0\" src=\"https://img.shields.io/badge/license-Apache%202.0-green?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://modelcontextprotocol.io\"\u003e\u003cimg alt=\"MCP\" src=\"https://img.shields.io/badge/MCP-100+_tools-orange?style=flat-square\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"docs/integrations/LANGCHAIN.md\"\u003e\u003cimg alt=\"LangChain\" src=\"https://img.shields.io/badge/LangChain-1C3C3A?style=flat-square\u0026logo=langchain\u0026logoColor=white\"\u003e\u003c/a\u003e\n  \u003ca href=\"docs/claude_code_plugin.md\"\u003e\u003cimg alt=\"Claude\" src=\"https://img.shields.io/badge/Claude-D97753?style=flat-square\u0026logo=claude\u0026logoColor=white\"\u003e\u003c/a\u003e\n  \u003ca href=\"docs/antigravity_plugin.md\"\u003e\u003cimg alt=\"Antigravity\" src=\"https://img.shields.io/badge/Antigravity-4285F4?style=flat-square\u0026logo=google\u0026logoColor=white\"\u003e\u003c/a\u003e\n  \u003ca href=\"docs/HERMES.md\"\u003e\u003cimg alt=\"Hermes\" src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/hermes.svg\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"OpenClaw\" src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/openclaw.svg\"\u003e\n  \u003cimg alt=\"OpenCode\" src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/badges/opencode.svg\"\u003e\n\u003c/p\u003e\n\n\u003e 💡 **Get Started Quickly:**\n\u003e * 🚀 **[5-Minute \"Human-First\" Guide](docs/GETTING_STARTED.md)**\n\u003e * 🖥️ **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- [Overview \u0026 At a Glance](#-m3-at-a-glance)\n- [Memory Model](#-memory-model-at-a-glance)\n- [Installation \u0026 Onboarding](#-installation)\n- [Domain Gating (Token Optimization)](#-domain-gating-the-full-catalog-without-the-context-cost)\n- [Sovereign \u0026 Air-Gapped Deployments](#-sovereign--air-gapped-deployments)\n- [Interactive Features \u0026 Capabilities](#-what-m3-does)\n- [Documentation Index](#-documentation-index)\n- [Target Audience \u0026 Fit](#-who-this-is-for)\n- [Quality Assurance \u0026 Compliance](#-why-trust-this)\n- [Benchmarks \u0026 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 · Gemini CLI · Aider · Google Antigravity · OpenCode · 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| **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 the correct session as the **#1 result for ~92% of questions**. 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,179 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.\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 \u0026 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 the correct session as the **#1 result for ~92% 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 One-Liner (macOS \u0026 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 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.\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#### 🪐 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 \u0026 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\u003e=1.10,\u003c2 · 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\u003e=2,\u003c3\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`) | 109 | ~24,918 | 12.5% |\n\n\u003e 🛠️ *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 \u0026 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 \u0026 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) \u0026 [FIPS Boundary Reference](docs/FIPS_MODULE_BOUNDARY.md)).\n*   **Storage Location:** All config and data files reside under `~/.m3-memory` (configurable via `M3_MEMORY_ROOT`).\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 \u0026 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| Quick \u0026 Core | Advanced \u0026 Architecture | Integrations \u0026 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 \u0026 Rules](docs/AGENT_INSTRUCTIONS.md)** | 🔍 **[Myths \u0026 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 use multiple desktop coding agents:** Interoperate Claude Code, Gemini, and Aider on a shared local history.\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 only want transient in-session chat context that resets when you exit the terminal (rely on your agent's defaults).\n*   **Your need is only contextual retrieval + a little user state:** if plain conversation history, RAG over a knowledge base, and a small structured user profile cover you, that's simpler to build and operate — persistent evolving memory earns its keep when users interact repeatedly *over time* and benefit from accumulated context.\n*   **You want a hosted/managed database as the system of record:** M3 is local-first. It *can* use PostgreSQL as its primary store (`M3_DB_BACKEND=postgres`) for scale or multi-user deployments, but it's designed to run on your own infrastructure (a local SQLite file by default, or a Postgres you operate) — not against a managed cloud DB you don't control.\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:** Verified with **2,179 tests across 180 test files** spanning 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### Retrieval Recall (Session Hit-Rate @ k)\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| 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### End-to-End QA Accuracy\n**92.0% accuracy** (460/500 correct responses) with zero oracle metadata routing:\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 add {\"mcpServers\":{\"memory\":{\"command\":\"m3\"}}} to my\n~/.claude/settings.json under \"mcpServers\". For best retrieval, ensure\nOllama is running with qwen3-embedding:0.6b (optional, falls back\nto keyword search without it). Then use /mcp to verify the memory server loaded.\n```\n\n#### Gemini CLI Prompt\n```text\nInstall m3-memory for persistent memory. Run: pip install m3-memory\nThen add {\"mcpServers\":{\"memory\":{\"command\":\"m3\"}}} to my\n~/.gemini/settings.json under \"mcpServers\". For best retrieval, ensure\nOllama is running with qwen3-embedding:0.6b (optional, falls back\nto keyword search without it).\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 \u0026 Automatic Resolution\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/demo_contradiction.svg\" alt=\"Contradiction Demo\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### Hybrid Search Scoring Details\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/demo_search.svg\" alt=\"Hybrid Search Demo\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### Multi-Device Database Sync\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/demo_sync.svg\" alt=\"Sync Demo\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n---\n\n## 💬 Community\n\n[![Discord Badge](https://img.shields.io/badge/Discord-M3_Memory-5865F2?logo=discord\u0026logoColor=white\u0026style=flat-square)](https://discord.gg/ZcJ3EGC99B)\n\u0026nbsp;\n[![GitHub Issues Badge](https://img.shields.io/badge/GitHub-Issues-181717?logo=github\u0026style=flat-square)](https://github.com/skynetcmd/m3-memory/issues)\n\n[How to Contribute](docs/CONTRIBUTING.md) · [Good First Issues](docs/GOOD_FIRST_ISSUES.md)\n\n---\n\n## 📜 License \u0026 Attributions\n\nThis project is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.\n\n### Asset \u0026 Icon Credits\nThe provider badges under [`docs/badges/`](docs/badges/) embed small logo glyphs:\n* **OpenClaw \u0026 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\u003cbr\u003e\n\u003cp align=\"center\"\u003e\u003csub\u003eDownload counts are estimates — PyPI total excludes mirror bots; GitHub is unique clones. Auto-refreshed by \u003ca href=\"https://github.com/skynetcmd/m3-memory/blob/main/.github/workflows/star-history.yml\"\u003estar-history.yml\u003c/a\u003e.\u003c/sub\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003cb\u003ePython:\u003c/b\u003e m3 core runs on 3.11+ (including 3.14). The optional framework extras follow their own caps — \u003cb\u003ePydanticAI\u003c/b\u003e is 3.14-native (plain \u003ccode\u003epip install\u003c/code\u003e); \u003cb\u003eCrewAI\u003c/b\u003e requires 3.10–3.13 (a 3.14 escape hatch is \u003ca href=\"https://github.com/skynetcmd/m3-memory/blob/main/m3_memory/integrations/crewai/README.md\"\u003edocumented\u003c/a\u003e).\u003c/sub\u003e\u003c/p\u003e\n\u003c/br\u003e\u003cp\u003e\u003c/p\u003e\n---\n\n### ⭐ Star History\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e⭐ View star history →\u003c/b\u003e (click to expand the chart)\u003c/summary\u003e\n\n\u003cbr\u003e\n\n\u003ca href=\"https://star-history.com/#skynetcmd/m3-memory\u0026Date\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/star-history.svg\" alt=\"Star history for skynetcmd/m3-memory\" width=\"100%\"\u003e\n\u003c/a\u003e\n\n\u003csup\u003eChart 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.\u003c/sup\u003e\n\n\u003c/details\u003e\n\n\u003c!-- mcp-name: io.github.skynetcmd/m3-memory --\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskynetcmd%2Fm3-memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskynetcmd%2Fm3-memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskynetcmd%2Fm3-memory/lists"}