mnemonic is a local MCP server that stores memories as plain markdown in git. Project-scoped semantic search with configurable embeddings. No database. No always-on service.
Your AI assistant forgets everything between sessions. mnemonic fixes that — without a database or a SaaS subscription.
Every memory is a markdown file with YAML frontmatter — designed for removability from day one. Give it a try; we think you'll like it enough to stay. And if you ever do leave, all the knowledge you've gathered is yours: plain markdown, independent of mnemonic, no strings attached.
Memories belong to projects. When you're in a repo, relevant notes surface first with a similarity boost. Global memories stay accessible but don't crowd out context.
No Postgres to babysit. Every remember, update, and consolidate creates a semantic git commit — your decision log and implementation plans travel with the code in the same history. Pushes are controlled so project-vault writes do not fail on unpublished branches by default. History is inspectable, conflicts are isolated to individual files, and sync works across machines.
Ollama is the local default, and advanced users can choose OpenAI-compatible endpoints, native OpenAI, or Gemini. recall finds the right note even when you don't remember the exact words; grep and file tools only match strings you already know. Embeddings are gitignored, recomputed on each machine, and never committed.
Project memories live in .mnemonic/ inside your repo. Commit them alongside code so the whole team benefits from captured decisions.
The MCP server starts on demand via stdio. Claude Code, Cursor, and other MCP clients invoke it per-session. Zero background processes when you're not using it.
Pending migrations are visible per vault, dry-runs are built in, and failed runs roll staged note writes back instead of leaving half-migrated memories behind.
Mark notes temporary for plans and WIP, permanent for decisions worth keeping. Capture what future work will need — decisions, outcomes, corrections, and constraints — and leave routine chatter out. Pin any note as a session anchor to always bring it to the top.
Opt-in temporal mode adds compact git-backed history to recall results. Each change is described in plain language — "Expanded the note with additional detail", "Connected this note to related work" — and the overall arc is summarised: "The core decision remained stable while rationale expanded." See how a decision formed without wading through raw diffs.
Every recall result carries structured quality signals: signalStrength rates each note on role, centrality, and recency; retrievalCoverage shows how many of your most important notes made it in; diversity reveals how many perspectives the result set spans. Agents don't just see ranked notes — they see why each note is worth paying attention to.
Link other repositories as read-only knowledge sources so relevant context from adjacent projects surfaces automatically in recall and summaries. Mark an attachment writable and mnemonic can remember, update, and relate notes across repository boundaries while keeping each project's decision log in its own git history.
mnemonic combines repo-scoped shared memory with a personal global vault. The main differences from similar tools are where memory lives, how it is shared, and whether it depends on a hosted service.
| Tool | Primary model | Storage model | Sharing model | Hosting model |
|---|---|---|---|---|
| mnemonic | Shared project memory + personal global memory for coding agents | Project memory in .mnemonic/ as plain markdown; personal memory in a global user vault |
Team-shared via git commits in the repo; personal memory across projects | Local MCP server, on demand |
| Memory Bank MCP | Structured memory bank service for agents | Memory bank files managed through a central MCP service | Centralized across projects | Remote / centralized service |
| Basic Memory | Local-first knowledge base for agents | Markdown knowledge base with semantic search | Shareable knowledge base, not primarily repo-scoped | Local-first, optional cloud |
For deeper comparison notes and FAQs, see the README FAQ.
mnemonic routes memories between a private main vault and a shareable project vault based on where you are and what you're storing.
Private global memories stored in ~/mnemonic-vault — its own git repo. Cross-project knowledge, user preferences, early brainstorming before a repo exists, and anything you don't want committed to a project repo.
Project memories committed into <git-root>/.mnemonic/ alongside your source code. Architecture decisions, bug fix context, and tribal knowledge travel with the repo.
No project yet? Capture ideas in the main vault first, then move only project-specific notes into your repo once it exists.
Semantic search finds the right note even when you don't remember exact words. When results are weak, keyword matching rescues relevant candidates. Notes that explain key decisions and concepts then get a boost so "why"-style questions surface the right answer.
All tools are text-first and optimized for LLM consumption — compact, semantically explicit, no unnecessary structure. On protected branches, write actions pause and ask before committing unless you choose a different policy.
mnemonic requires Node.js 18+. Ollama is the local default for embeddings; OpenAI-compatible, OpenAI, and Gemini providers are optional environment-configured alternatives.
ollama pull nomic-embed-text-v2-moe
qwen3-embedding:0.6b is also a viable alternative for longer-context notes:
ollama pull qwen3-embedding:0.6b
No code changes are required; set EMBED_MODEL=qwen3-embedding:0.6b. For cloud or proxy providers, set EMBED_PROVIDER and the matching environment variables in your MCP config.
Pick one:
npm install @danielmarbach/mnemonic-mcp
brew tap danielmarbach/mnemonic-mcp https://github.com/danielmarbach/mnemonic brew install mnemonic-mcp
docker pull danielmarbach/mnemonic-mcp:latest
Pre-built for linux/amd64 and linux/arm64. Tagged with the release version and latest.
npm install npm run build
{
"mcpServers": {
"mnemonic": {
"command": "npx",
"args": ["@danielmarbach/mnemonic-mcp"],
"env": {
"VAULT_PATH": "/Users/you/mnemonic-vault"
}
}
}
}
{
"mcpServers": {
"mnemonic": {
"command": "docker",
"args": [
"compose", "-f",
"/path/to/mnemonic/compose.yaml",
"run", "--rm", "mnemonic"
]
}
}
}
Add to ~/.config/opencode/opencode.json or project-local opencode.json.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mnemonic": {
"type": "local",
"command": ["npx", "@danielmarbach/mnemonic-mcp"],
"environment": {
"VAULT_PATH": "/Users/you/mnemonic-vault"
}
}
}
}
Add to ~/.codex/config.toml or project-local .codex/config.toml.
[mcp_servers.mnemonic] command = "npx" args = ["@danielmarbach/mnemonic-mcp"] [mcp_servers.mnemonic.env] VAULT_PATH = "/Users/you/mnemonic-vault"
Open the command palette and search for MCP: Open User Configuration, or edit mcp.json directly, then add the snippet below.
{
"servers": {
"mnemonic": {
"command": "npx",
"args": ["@danielmarbach/mnemonic-mcp"],
"env": {
"VAULT_PATH": "/Users/YOU/mnemonic-vault"
}
}
}
}
| Variable | Default | Description |
|---|---|---|
VAULT_PATH |
~/mnemonic-vault | Path to your markdown vault |
EMBED_PROVIDER |
ollama | ollama, openai-compatible, openai, or gemini |
OLLAMA_URL |
http://localhost:11434 | Ollama server URL, limited to localhost/private-network addresses |
EMBED_MODEL |
provider default | Embedding model; required for openai-compatible |
EMBED_DIMENSIONS |
unset | Optional provider-supported output dimensions |
EMBED_BASE_URL / EMBED_API_KEY |
unset | OpenAI-compatible endpoint and optional bearer token |
OPENAI_BASE_URL / OPENAI_API_KEY |
api.openai.com / unset | Native OpenAI endpoint and required API key |
GEMINI_BASE_URL / GEMINI_API_KEY |
generativelanguage.googleapis.com / unset | Native Gemini endpoint and required API key |
DISABLE_GIT |
false | Set true to skip all git operations |
Provider configuration is read from the process environment only. API keys are never stored in notes, embedding records, vault config, or git. Ollama keeps projection text local; OpenAI-compatible cloud proxies, native OpenAI, and Gemini send projection text to the configured external endpoint.
After changing EMBED_PROVIDER, EMBED_MODEL, EMBED_DIMENSIONS, or endpoint semantics behind the same model alias, call the sync MCP tool with force: true. Incompatible embeddings are skipped rather than compared across vector spaces.
The main vault's ~/mnemonic-vault/config.json holds machine-local settings you can edit by hand. Two fields are user-tunable:
| Field | Default | Description |
|---|---|---|
reindexEmbedConcurrency |
4 | Parallel embedding requests during sync (capped 1–16) |
mutationPushMode |
main-only | all, main-only, or none — controls when writes auto-push to git |
projectMemoryPolicies and projectIdentityOverrides are written automatically by MCP tools — no need to edit them by hand.
{
"reindexEmbedConcurrency": 8,
"mutationPushMode": "none"
}
Mnemonic's tools are self-describing — each includes "use when" / "do not use when" guidance, behavioral annotations, and typed schemas. Most models will use them correctly from tool metadata alone.
For memory-tool protocol guidance, use mnemonic-workflow-hint. For structured task execution guidance, use mnemonic-rpi-workflow.
# Install bundled skills into Claude + OpenCode skill directories mnemonic-install-skills --target all --mode copy # Refresh installed copies after upgrading mnemonic mnemonic-install-skills --target all --mode copy --update
Vault maintenance and onboarding without an MCP client. Run them directly from the shell.
Apply pending schema migrations to your vaults. Always preview with --dry-run first — failed runs roll staged writes back automatically.
# Preview what would change mnemonic migrate --dry-run # Apply and auto-commit mnemonic migrate # List available migrations mnemonic migrate --list # Limit to one project vault mnemonic migrate --cwd=/path/to/project
Import Claude Code auto-memory into your vault. Each ## heading in ~/.claude/projects/<project>/memory/*.md becomes a separate mnemonic note — independently searchable via recall. Duplicate titles are skipped, so it's safe to re-run.
# Preview what would be imported mnemonic import-claude-memory --dry-run # Import for the current project mnemonic import-claude-memory # Specific project path mnemonic import-claude-memory --cwd=/path/to/project # Then ask your MCP client to run the sync tool to embed and push
The project stores its design log in its own .mnemonic/ vault. Every architectural call and deliberate trade-off lives there as a real note, captured through the MCP tools while building the project.
Call project_memory_summary first for orientation, then recover working state. The mnemonic-workflow-hint prompt establishes this order explicitly so agents orient on project context before diving into temporary-note recovery.
Temporary notes are scaffolding, not permanent knowledge. When finished work stabilizes, keep the useful outcome, preserve details future work may need, and remove scaffolding when safe. The working-state section in project_memory_summary surfaces WIP notes so agents can resume without searching.
Do not implement the full runtime project-context loading/unloading architecture yet. Implement a lightweight recall heuristic instead: when scope is all, prefer current-project matches first and widen to global matches only if needed to fill the limit.
Rationale: this captures most of the practical benefit without introducing cache lifecycle, invalidation, active-project state, or long-lived runtime complexity. Keep the broader dynamic-loading plan as a future scaling option.
A module-level singleton in src/cache.ts caches notes, embeddings, and projections per vault for the duration of the MCP session. Notes and embeddings are co-loaded in a single Promise.all() pass on first access, so both are always warm after one I/O round trip.
The cache is keyed by project ID and invalidated on every write-path tool. All cache functions are fail-soft: errors return undefined and callers fall back to direct storage. Instrumented with [cache:hit/miss/build/invalidate/fallback] events and per-tool timing.
Four post-processing layers added on top of semantic recall, each additive and fail-soft: provenance and confidence metadata from git; opt-in temporal history enriched after semantic selection; projection-based embedding from structured note representations; bounded 1-hop relationship previews scored by project affinity, anchor status, and recency.
Core recall ranking is unaffected by any layer. Failures degrade gracefully to basic results.
Temporal mode now explains what kind of change happened, not just that one occurred. Each history entry is classified into one of eight semantic categories — create, refine, expand, clarify, connect, restructure, reverse, unknown — using structural signals: additions/deletions ratio, churn, relationship changes, and commit message prefixes.
Classification is language-independent. Conservative thresholds prefer unknown over misclassification. Raw diffs are intentionally excluded from default output.
Every architectural call, trade-off, and lesson — committed to the repo inside .mnemonic/notes/ as plain markdown. Human-readable. Open the folder and read them directly.