{"id":49499640,"url":"https://github.com/skynetcmd/m3-memory","last_synced_at":"2026-05-30T01:04:49.008Z","repository":{"id":349444072,"uuid":"1167246588","full_name":"skynetcmd/m3-memory","owner":"skynetcmd","description":"Local-first Agentic Memory Layer Framework for MCP Agents and Multiple Computers • Over 60 tools • Hybrid search (FTS5 + vector + MMR) • GDPR • 100% local","archived":false,"fork":false,"pushed_at":"2026-05-01T10:43:51.000Z","size":8495,"stargazers_count":11,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-01T11:30:06.337Z","etag":null,"topics":["agentic-memory","ai-agents","ai-memory","aider","claude-code","gdpr","gemini","gemini-cli","homelab","hybrid-search","local-llm","long-term-memory-llm","mcp","mcp-server","ollama","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":null,"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":"docs/AGENTS.md","dco":null,"cla":null},"funding":{"github":["skynetcmd"]}},"created_at":"2026-02-26T04:56:40.000Z","updated_at":"2026-05-01T10:34:50.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":22,"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":32495949,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"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","gdpr","gemini","gemini-cli","homelab","hybrid-search","local-llm","long-term-memory-llm","mcp","mcp-server","ollama","openclaw","privacy","rag","rag-memory","vector-search"],"created_at":"2026-05-01T12:01:55.165Z","updated_at":"2026-05-30T01:04:49.002Z","avatar_url":"https://github.com/skynetcmd.png","language":"Python","funding_links":["https://github.com/sponsors/skynetcmd"],"categories":[],"sub_categories":[],"readme":"![M3 Memory]\n\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\" width=\"100%\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# M3 Memory\n\nLocal-first Agentic Memory Layer Framework for MCP Agents • 96 tools • Hybrid search (FTS5 + vector + MMR) • Directory ingestion \u0026 file-memory • GDPR • FIPS 140-3 ready • 100% local\n\n\u003e **\"Wait, you remember that?\"** — Stop re-explaining your project to your AI. Give it a long-term brain that stays 100% on your machine.\n\u003e\n\u003e 🚀 **[New to M3? Start here with our 5-minute \"Human-First\" guide.](docs/GETTING_STARTED.md)**\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\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/m3-memory/\"\u003e\u003cimg alt=\"Downloads\" src=\"https://img.shields.io/pypi/dm/m3-memory?style=flat-square\"\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-74_tools-orange?style=flat-square\"\u003e\u003c/a\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\nWorks with Claude Code, Gemini CLI, Aider, OpenCode, 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).\n\n\u003e 👉 **I've read enough, I just want to install it on [Windows](docs/QUICKSTART_WINDOWS.md), [macOS](docs/QUICKSTART_MACOS.md), or [Linux](docs/QUICKSTART_LINUX.md).**\n\n---\n\n## 📦 Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/skynetcmd/m3-memory/main/install.sh | bash\n```\n\nInstalls on macOS or Linux with the single command above. Use this to [install on Windows](https://github.com/skynetcmd/m3-memory/blob/main/docs/install_windows.md). Use this link to [install manually](https://github.com/skynetcmd/m3-memory/blob/main/INSTALL.md#tldr--manual-path-per-os) and this to [examine the script](https://raw.githubusercontent.com/skynetcmd/m3-memory/main/install.sh) and what it does.\n\n**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:\n\n```\n/plugin marketplace add skynetcmd/m3-memory\n/plugin install m3@skynetcmd\n```\n\n[Plugin reference](https://github.com/skynetcmd/m3-memory/blob/main/docs/claude_code_plugin.md) · [Claude.ai (web/desktop) connector](https://github.com/skynetcmd/m3-memory/blob/main/docs/claude_ai_connector.md)\n\n---\n\nAdd to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"memory\": { \"command\": \"m3\" }\n  }\n}\n```\n\n### 🚀 One-command setup\n\n```bash\npip install m3-memory\nm3 setup\n```\n\n`m3 setup` is an interactive wizard. It detects every agent on PATH (Claude\nCode, Gemini CLI, OpenCode, OpenClaw), asks a handful of questions, then\ndrives the full install end-to-end: system payload, sovereign CPU embedder\n(BGE-M3 on port 8082), per-agent MCP wiring, chatlog hooks, and a `doctor`\nverification. Restart your agent — that's it.\n\n### 🛡️ Sovereign by default\n\nThe embedder ships **in the repo**. Our own BGE-M3 CPU embedder runs as a\nsmall always-on service on `127.0.0.1:8082` after `m3 setup`. **No LM\nStudio, no Ollama, no GPU, no internet** required for embedding to work.\n\n| Embedder path | When it's used | What you do |\n|---|---|---|\n| **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. |\n| **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). |\n| **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. |\n\nWant auto-classification, summarization, and consolidation? Load a small\nchat model for generation (e.g. `qwen2.5:0.5b` via Ollama, or any 0.5–1B\ninstruct GGUF). M3 auto-selects it; embedding-only features work without\nit. See [docs/QUICKSTART.md → Optional: load a small chat model](docs/QUICKSTART.md#optional-load-a-small-chat-model-for-enrichment).\n\n\u003e **Optional — Rust core (`m3-core-rs`).** A Rust compute core ([`m3-core-rs`](https://github.com/skynetcmd/m3-core-rs)) takes over hot-path work — hashing, cosine/MMR ranking, redaction, and the in-process llama.cpp embeddings (CPU + optional GPU). Until `m3-core-rs` ships wheels to PyPI, install it manually: `pip install \"m3-core-rs @ git+https://github.com/skynetcmd/m3-core-rs.git@v0.9.0#subdirectory=crates/m3-core-py\"` (needs a Rust toolchain ≥1.94 + maturin). Set `M3_CORE_RS_DISABLE=1` at runtime to force the Python path. See [docs/ENVIRONMENT_VARIABLES.md → Project Oxidation](docs/ENVIRONMENT_VARIABLES.md).\n\nRestart your agent. Done!\n\n---\n\n## 🎚️ 96 tools, but they don't all crowd your context — domain gating keeps the catalog small\n\nM3 exposes 87 MCP tools so power users can customize at fine granularity —\nsingle-id deletes, bulk variants, per-store searches, KG traversals, GDPR\nprimitives, agent handoffs, watch-mode admin, the lot. Most agents never\ntouch most of them in a typical session.\n\nTo avoid burning context space on tool schemas you won't use, m3 groups\nits catalog into **8 domains** (`memory`, `chatlog`, `files`, `entity`,\n`agent`, `tasks`, `conversations`, `admin`) and **loads them lazily**.\nAt MCP startup only 6 essentials register (memory + chatlog + files\nsearch/write); the rest expose on demand when the agent calls\n`tools_load_domain(domain=\"…\")`.\n\nMeasured on m3 main with the gpt-4o tokenizer:\n\n| Mode | Tools at startup | Tokens at startup | % of 200 K window |\n|---|---:|---:|---:|\n| **Lazy (default)** | **8** | **~2,400** | **1.2 %** |\n| Typical session (lazy + agent loads files + memory) | 48 | ~11,400 | 5.7 % |\n| Eager (`M3_TOOLS_LAZY=0` — legacy) | 87 | ~16,100 | 8.0 % |\n\nFor comparison, common alternatives: a 40-tool GitHub MCP server\n≈ 12,000 tokens; the full 93-tool GitHub MCP server ≈ 55,000 tokens\n([MCP Token Counter](https://mcpplaygroundonline.com/blog/mcp-token-counter-optimize-context-window)).\nm3's lazy default keeps the always-on surface ~6× smaller than a stock\nGitHub server while giving the agent the full 96 tools whenever it\nactually needs them.\n\nDisable with `M3_TOOLS_LAZY=0` if your client doesn't support\n[dynamic tool registration](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)\nor you want every tool at startup. Direct Python imports\n(`from memory_bridge import memory_write`) always expose every tool —\nthis only gates the MCP wire surface.\n\n---\n\n## 🛡️ Air-gapped deployment\n\nM3 is sovereign **by default** — the baseline install needs no external\nservices. For fully air-gapped environments, the only extra step is to\npre-stage the repo (with the LFS-tracked GGUF materialized) on a connected\nmachine and transfer it to the target.\n\n```bash\n# On a connected machine:\ngit lfs install                                              # one-time\ngit clone https://github.com/skynetcmd/m3-memory.git\ncd m3-memory \u0026\u0026 git lfs pull                                  # ~438MB\npip download m3-memory -d _assets/python_wheels               # pre-fetch wheels\n\n# On the air-gapped target (after sneakernet-copying the folder):\npip install --no-index --find-links=_assets/python_wheels m3-memory\nm3 setup --non-interactive --capture-mode both\n```\n\nThat's it. No `curl`, no LM Studio, no third-party model server.\n\n**See the [Sovereign \u0026 Air-Gapped Deployment Guide](docs/SOVEREIGN_DEPLOYMENT.md)\nfor full instructions, FIPS-mode hardening, and GPU-on-air-gap details.**\n\nBy default, m3 stores its configuration, payload, and backups under\n`~/.m3-memory`. Override with `M3_MEMORY_ROOT`.\n\n---\n\n## 🔮 What happens next (benefits of use)\n\nYou'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.\n\nLater, 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.\n\n---\n\n## 💡 Why this exists\n\nMost 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.\"\n\nM3 Memory gives agents a structured, persistent memory layer that handles this.\n\n---\n\n## ⚡ What it does\n\n**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.\n\n**Persistent memory** — facts, decisions, preferences survive across sessions. Stored in local SQLite.\n\n**Hybrid retrieval** — FTS5 keyword matching + semantic vector similarity + MMR diversity re-ranking. Automatic, no tuning required.\n\n**Contradiction handling** — conflicting facts are automatically superseded. Bitemporal versioning preserves the full history.\n\n**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.\n\n**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.\n\n**Context-frugal tool catalog** — 96 MCP tools grouped into 8 domains, loaded lazily. Startup surface is **~2,400 tokens** (~1.2% of a 200K window) vs ~16,100 if every tool registered eagerly. Agent expands a domain when it needs the rest. See [§ 96 tools, domain-gated](#-96-tools-but-they-dont-all-crowd-your-context--domain-gating-keeps-the-catalog-small).\n\n**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.\n\n---\n\n## 📚 Learn more\n\n| | |\n|---|---|\n| 🚀 **[Getting started](docs/GETTING_STARTED.md)** | 👥 **[Multi-agent orchestration](docs/MULTI_AGENT.md)** |\n| ✨ **[Core features](docs/CORE_FEATURES.md)** | 🧩 **[Multi-agent example](examples/multi-agent-team/README.md)** |\n| 🏗️ **[System design](docs/ARCHITECTURE.md)** | ⚖️ **[Compare M3 to alternatives](docs/COMPARISON.md)** ([sovereign substrates table](docs/M3_Comparison_Table.md)) |\n| 🔧 **[Implementation details](docs/TECHNICAL_DETAILS.md)** | ⚙️ **[Configuration](docs/ENVIRONMENT_VARIABLES.md)** |\n| 🤖 **[Agent rules + all 96 tools](docs/AGENT_INSTRUCTIONS.md)** | 🛡️ **[Compliance \u0026 assurance](docs/COMPLIANCE.md)** (FISMA, CMMC, GDPR) |\n| 🏠 **[Homelab patterns](docs/HOMELAB_PATTERNS.md)** | 🔍 **[Myths \u0026 facts](docs/MYTHS_AND_FACTS.md)** (verify claims about M3) |\n| 🗺️ **[Roadmap](docs/ROADMAP.md)** | |\n\n---\n\n## 🎯 Who this is for\n\n### M3 is a good fit if…\n\n| | |\n|---|---|\n| 🤖 **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. |\n| 👥 **You run multiple agents** | Coordinating Claude + Gemini + a background worker on a shared local store, with handoffs and per-agent scoping. |\n| 🛡️ **You need compliance primitives** | `gdpr_forget` / `gdpr_export` as MCP tools, bitemporal valid-time / transaction-time, audit trail, no telemetry. |\n| 💾 **You want pure local-first** | Single-file SQLite. Works offline. No external database, no cloud calls, no API costs by default. |\n| 🌐 **You want memory across devices** | Optional bi-directional delta sync via PostgreSQL or ChromaDB — your data, your hardware. |\n\n### M3 is **not** the right tool if…\n\n| | Try instead |\n|---|---|\n| You're building LangChain / LangGraph / CrewAI pipelines and want framework-native memory | [Mem0](https://mem0.ai), [LangChain Memory / LangMem](https://python.langchain.com/docs/modules/memory/) |\n| You want a hosted agent runtime with managed scaling, dashboards, and SLAs | [Letta](https://letta.ai), [Mem0 Pro](https://mem0.ai) |\n| Pure retrieval-accuracy is your only criterion (M3 is mid-pack at 89.0% LME-S) | [agentmemory](https://github.com/agentmemory) (96.2%), [Hindsight](https://github.com/vectorize-io/hindsight) |\n| You only need in-session chat context that's discarded after the conversation | Your agent's built-in conversation buffer; M3 is overkill |\n\n---\n\n## 🛡️ Why trust this\n\n| | |\n|---|---|\n| **96 MCP tools** | Memory, search, GDPR, refresh lifecycle — plus agent registry, handoffs, notifications, tasks, entity graph, fact enrichment, chat-log capture, and a 21-tool files-memory layer (directory ingestion, hierarchical chunking, ascension to core memory, watch-mode staleness review) |\n| **563 end-to-end tests** | Covering write, search, contradiction, sync, GDPR, maintenance, orchestration, and the files-memory pipeline |\n| **Explainable retrieval** | `memory_suggest` returns vector, BM25, and MMR scores per result |\n| **SQLite core** | No external database required. Single-file, portable, inspectable |\n| **GDPR compliance** | `gdpr_forget` (Article 17) and `gdpr_export` (Article 20) as built-in tools — see [compliance \u0026 assurance](docs/COMPLIANCE.md) for FISMA / CMMC alignment too |\n| **Self-maintaining** | Automatic decay, dedup, orphan pruning, retention enforcement |\n| **Audited security posture** | Periodic Bandit + pip-audit + secrets-scan reports published under [`docs/audits/`](docs/audits/); CI gates on core-dep CVEs |\n| **Apache 2.0 licensed** | Free. No SaaS tier, no usage limits, no lock-in |\n\n\u003e 🧭 **Maturity, honestly.** The core (storage, retrieval, GDPR, MCP tools, sync) is stable and covered by the test suite. The newer enrichment + reflector pipeline matured rapidly through 2026-Q2 and has live-fire experience behind it but is still iterating. **Production-ready for personal, homelab, and multi-agent developer workflows today.** For regulated workloads, do your own evaluation against your specific use case — and we recommend that against any memory tool, not just M3. See [docs/MYTHS_AND_FACTS.md](docs/MYTHS_AND_FACTS.md) for what we *don't* claim.\n\n---\n\n## 📊 Benchmarks\n\n**89.0%** on [LongMemEval-S](https://github.com/xiaowu0162/LongMemEval) (445/500 correct) — a 500-question evaluation of long-horizon conversational memory. Without oracle metadata: **74.8%** (smart retrieval) to **68.0%** (fixed-k baseline).\n\n| Question type | n | Accuracy |\n|---|---|---|\n| single-session-user | 70 | 91.4% |\n| single-session-assistant | 56 | 94.6% |\n| single-session-preference | 30 | 93.3% |\n| multi-session | 133 | 85.0% |\n| temporal-reasoning | 133 | 86.5% |\n| knowledge-update | 78 | 92.3% |\n| **Overall** | **500** | **89.0%** |\n\nFull methodology, ablations, and honest caveats: [`benchmarks/longmemeval/LME-S_Benchmarking_Report.md`](benchmarks/longmemeval/LME-S_Benchmarking_Report.md). \nLoCoMo audit pending — see [`benchmarks/locomo/README.md`](benchmarks/locomo/README.md).\n\n\u003e 🔍 **Verifying claims about M3.** If a third-party AI assistant has described M3 with features or scores that don't match what's documented here, it's almost certainly hallucinating. See [`docs/MYTHS_AND_FACTS.md`](docs/MYTHS_AND_FACTS.md) for the source-of-truth list of what M3 actually implements (and what it doesn't).\n\n---\n\n## 🧰 Core tools\n\nMost sessions use three tools. The rest is there when you need it.\n\n| Tool | Purpose |\n|------|---------|\n| `memory_write` | Store a fact, decision, preference, config, or observation |\n| `memory_search` | Retrieve relevant memories (hybrid search) |\n| `memory_update` | Refine existing knowledge |\n| `memory_suggest` | Search with full score breakdown |\n| `memory_get` | Fetch a specific memory by ID |\n\nAll 96 tools are documented in [docs/AGENT_INSTRUCTIONS.md](docs/AGENT_INSTRUCTIONS.md) and the full inventory lives in [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md).\n\n---\n\n## 🤖 For AI agents\n\nM3 Memory exposes 96 MCP tools for storing, searching, updating, and linking knowledge — including conversation grouping, a refresh lifecycle for aging memories, agent registry, handoffs, notifications, tasks, entity-graph extraction, fact enrichment, chat-log capture for multi-agent orchestration, and a files-memory layer that ingests entire directories (markdown, PDF, plain text) into a hierarchical store with hybrid search, fact extraction, ascension to core memory, and watch-mode staleness review. Any MCP-compatible agent can use them automatically.\n\nTo teach your agent best practices (search before answering, write aggressively, update instead of duplicating), drop the compact rules file into your project:\n\n```\nexamples/AGENT_RULES.md\n```\n\nFull tool reference with all parameters and behaviors: [docs/AGENT_INSTRUCTIONS.md](docs/AGENT_INSTRUCTIONS.md)\n\n---\n\n## 🪄 Let your agent install it\n\nAlready inside Claude Code or Gemini CLI? Paste one of these prompts:\n\n**Claude Code:**\n```\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:**\n```\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\nAfter install, test it:\n```\nWrite a memory: \"M3 Memory installed successfully on [today's date]\"\nThen search for: \"M3 install\"\n```\n\n### Add the chat log subsystem\n\nWant auto-capture of every Claude Code / Gemini CLI / OpenCode / Aider conversation into a searchable, promotable chat log store? Once m3-memory is wired up, just say:\n\n```\nInstall the m3-memory chat log subsystem.\n```\n\nThe agent runs `bin/chatlog_init.py`, wires the host-agent hook, and installs the embed sweeper schedule. See [docs/CHATLOG.md](docs/CHATLOG.md) for the architecture and ops guide.\n\n---\n\n## 🎬 See it in action\n\n### Contradiction detection\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/demo_contradiction.svg\" alt=\"Demo: contradiction detection and automatic resolution\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### Hybrid search with scores\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/demo_search.svg\" alt=\"Demo: hybrid search with score breakdown\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### Cross-device, cross-platform sync\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/demo_sync.svg\" alt=\"Demo: cross-device, cross-platform memory sync\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n---\n\n## 💬 Community\n\n[![Discord](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](https://img.shields.io/badge/GitHub-Issues-181717?logo=github\u0026style=flat-square)](https://github.com/skynetcmd/m3-memory/issues)\n\u0026nbsp;\n[Contributing](docs/CONTRIBUTING.md) · [Good first issues](docs/GOOD_FIRST_ISSUES.md)\n\n---\n\n[![Star History](https://api.star-history.com/svg?repos=skynetcmd/m3-memory\u0026type=Date)](https://star-history.com/#skynetcmd/m3-memory\u0026Date)\n\n\u003c!-- mcp-name: io.github.skynetcmd/m3-memory --\u003e\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"}