Tools
M3 Memory
By 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
Install
pip install m3-memoryConfiguration Example
{
"mcpServers": {
"memory": { "command": "m3" }
}
}README
![M3 Memory]
<p align="center">
<a href="https://github.com/skynetcmd/m3-memory">
<img src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/M3-banner.jpg" alt="M3 Memory" width="100%">
</a>
</p>
# M3 Memory
Local-first Agentic Memory Layer Framework for MCP Agents • 105 tools • Hybrid search (FTS5 + vector + MMR) • Directory ingestion & file-memory • GDPR • FIPS 140-3 ready • 100% local
> **"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)**
<p align="center">
<a href="https://pypi.org/project/m3-memory/"><img alt="PyPI" src="https://img.shields.io/pypi/v/m3-memory?style=flat-square"></a>
<a href="https://pypi.org/project/m3-memory/"><img alt="Downloads" src="https://img.shields.io/pypi/dm/m3-memory?style=flat-square"></a>
<a href="https://www.python.org"><img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11+-blue?style=flat-square"></a>
<a href="https://github.com/skynetcmd/m3-memory/blob/main/LICENSE"><img alt="Apache 2.0" src="https://img.shields.io/badge/license-Apache%202.0-green?style=flat-square"></a>
<a href="https://modelcontextprotocol.io"><img alt="MCP" src="https://img.shields.io/badge/MCP-101_tools-orange?style=flat-square"></a>
<img alt="macOS" src="https://img.shields.io/badge/macOS-000000?style=flat-square&logo=apple&logoColor=white">
<img alt="Windows" src="https://img.shields.io/badge/Windows-0078D4?style=flat-square&logo=windows&logoColor=white">
<img alt="Linux" src="https://img.shields.io/badge/Linux-FCC624?style=flat-square&logo=linux&logoColor=black">
</p>
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/QUICKSTART_WINDOWS.md), [macOS](docs/QUICKSTART_MACOS.md), or [Linux](docs/QUICKSTART_LINUX.md).**
---
## 📦 Install
```bash
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](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.
**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](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)
**Google Antigravity users** can install the plugin directly:
```bash
agy plugin install https://github.com/skynetcmd/m3-memory
```
[Plugin reference](https://github.com/skynetcmd/m3-memory/blob/main/docs/antigravity_plugin.md)
**Hermes Agent users** can install the memory-provider plugin directly (supports optimal replacement of default memory or parallel coexistence for rich SOTA retrieval):
```bash
# Handled automatically via our setup wizard:
m3 setup
```
[Plugin integration guide](docs/HERMES.md)
---
Add to your MCP config:
```json
{
"mcpServers": {
"memory": { "command": "m3" }
}
}
```
### 🚀 One-command setup
```bash
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.** Auto-oxidation is enabled by default to deliver enhanced performance across hot-path operations. Users can easily opt out if desired: simply set `M3_CORE_RS_DISABLE=1` in your environment to run the pure-Python fallback path. See [docs/ENVIRONMENT_VARIABLES.md](docs/ENVIRONMENT_VARIABLES.md) for configuration details.
Restart your agent. Done!
---
## 🎚️ 105 tools, but they don't all crowd your context — domain gating keeps the catalog small
M3 exposes 105 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) | 104 | ~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](https://mcpplaygroundonline.com/blog/mcp-token-counter-optimize-context-window)).
m3's lazy default keeps the always-on surface ~7× smaller than the full
eager catalog while giving the agent the full 105 tools whenever it
actually needs them.
Disable with `M3_TOOLS_LAZY=0` if your client doesn't support
[dynamic tool registration](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)
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.
```bash
# 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`.
---
## 🔮 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
... (truncated)
tools
Comments
Sign in to leave a comment