Shared memory layer for LLMs. Store documents, knowledge and notes in a single portable database and access them from any MCP-compatible client — Claude Code, VS Code Copilot, ChatGPT, Mistral Vibe, custom agents, or anything that speaks MCP.
Runs privately in a Docker container or natively. Your data never leaves your machine.
Every LLM session starts from scratch. Claude doesn't know what ChatGPT learned yesterday. Your Copilot session can't access the architectural decisions you discussed with Claude last week. Each tool operates in complete isolation.
Mnem-O-matic fixes this by providing a shared, persistent memory that any LLM can read from and write to.
Documents — reference material, code snippets, specs, configs, notes. Anything you want LLMs to have access to.
Knowledge — discrete facts, decisions, and observations. "The auth system uses JWT with RS256." "We chose Postgres over SQLite for the main database." "The deploy pipeline runs on GitHub Actions."
Notes — quick thoughts, ideas, observations, and voice transcripts. Informal content that LLMs should be aware of but that isn't structured enough to be a document or atomic enough to be a knowledge entry.
All types support namespaces (per-project or global), tags, and metadata. Everything is searchable via full-text and semantic search, narrowed when you need it by tag or by "updated since". Large documents are automatically split into chunks at store time, so search returns the most relevant passage rather than the entire file — giving agents focused context without burning their context window.
The filing cabinet is the part above — organized, tagged, searchable storage. What makes it also a memory is how content behaves over time: it has history, mistakes are reversible, and the store helps keep itself tidy:
- Temporal facts — knowledge answers questions whose answers change. When a fact changes, the old entry is superseded rather than overwritten: search returns only the current answer, and
fact_historyshows what was believed before, and until when. More → - Undo & recovery — every update and delete first saves the item's prior state as a revision;
restorerolls back a bad edit or recreates a deleted item under its original id. More → - Duplicate awareness & consolidation — storing near-identical content gets flagged in the store response, and
consolidation_reportclusters look-alike items and lists stale, never-retrieved ones. The bundledconsolidateandbriefingprompts turn review into one-command workflows — no server-side LLM involved, the connected agent is the judge. More → - Associative recall —
relatedreturns an item's nearest neighbors across all content types, so an agent that just read one thing can pull in the surrounding context it didn't know to search for. More → - Usage tracking — items carry retrieval counters, bumped only when something is genuinely read or surfaced by search. The raw material for spotting what earns its place. More →
- Audit trail — every write lands in an append-only log: what changed, when, from which client and address, and — when clients send an
X-Mnemomatic-Actorheader — who. Two-year retention by default. More →
The whole store downloads as a human-readable zip — one folder per namespace, one Markdown file per item, metadata in sidecars — via GET /export, the web viewer, or the CLI. Your memory stays portable and is never locked in. The server can also write that archive on a schedule with rotation: set MNEMOMATIC_BACKUP_DIR and backups happen with no host-side cron. More →
Semantic search runs on a local embedding model bundled into the Docker image — nothing leaves your machine. Four models are selectable at build time via the EMBED_MODEL build argument: arctic-embed-xs (the default) is the smallest and fastest, English only, at ~240 MB of memory; amaretto-embed-148m is a distillation of EmbeddingGemma that keeps most of its retrieval quality at roughly 40% of the memory, across 8 Latin-script languages plus code; gte-multilingual-base adds strong multilingual retrieval at near-arctic query speed; EmbeddingGemma has the best retrieval quality of the four — it resolves paraphrased queries that share no words with the stored content — at a higher CPU and memory cost. You can also bypass the built-in model and point MNEMOMATIC_EMBED_URL at any OpenAI-compatible embedding endpoint. See choosing the built-in embedding model for the full comparison.
Changing your mind is safe. The database records which model built its vector index, down to the task prefixes. Searching a new model's queries against an old model's vectors returns quietly wrong results — no error, just worse answers — so the server refuses to start on a mismatch and names what changed. Set MNEMOMATIC_REINDEX=auto and it re-embeds everything itself when the model changes, then stays out of the way on every later start. More →
A sample agent skill file is included at skills/mnemomatic/SKILL.md. It teaches an agent how to use Mnem-O-matic effectively — when to reach for memory at all, which search mode to pick, what content type to store, how facts supersede, and how to undo mistakes.
The skill is written for Claude Code but can be adapted to any agent framework that supports custom instructions or skill files. Tailor the wording, triggers, and examples to match your agent's terminology and workflow.
To install for Claude Code:
# Personal (available in all your projects)
mkdir -p ~/.claude/skills && cp -r skills/mnemomatic ~/.claude/skills/mnemomatic
# Project-only (available in the current project)
mkdir -p .claude/skills && cp -r skills/mnemomatic .claude/skills/mnemomaticA built-in, read-only web viewer lets you browse stored documents, knowledge, and notes in the browser — no MCP client required. It's view-only: no creating, editing, or deleting.
 Shared-secret login |
 Namespaces |
 Browsing a namespace |
 Item detail |
The viewer is disabled by default. Set a shared secret to enable it:
docker run -e MNEMOMATIC_UI_TOKEN=your-viewer-secret ...Then open http://your-host:8000/ui and enter the token once. There are no user accounts — access is a single shared secret, kept separate from the MCP API key. When MNEMOMATIC_UI_TOKEN is unset, /ui is not served at all.
A Settings page shows the configuration the server is running with — embedding model (linked to its model card), dimensions, task prefixes, chunking — and offers the export download.
See the Usage Guide for details and security notes.
Both Docker images run as an unprivileged user (uid 65532) — nothing in the server needs root. GET /health reports liveness without credentials, and the images ship a HEALTHCHECK that polls it, so docker compose up --wait and orchestrator readiness gates work with no configuration. Everything else stays behind the API key.
The database records which embedding model built its vector index, so swapping models cannot silently corrupt search: the server refuses to start on a mismatch and names what changed, and MNEMOMATIC_REINDEX=auto re-embeds once and then stays inert. The embedding_info tool reports the same state to an agent. More →
- Installation Guide — prerequisites, Docker profiles, TLS setup, configuration, development
- Upgrading from v1.x to v2.0 — two breaking changes: non-root containers and the replaced default model
- Usage Guide — connecting clients, authentication, tools, search, resources, web viewer
- Tech Stack — architecture decisions, embeddings, concurrency, performance