mnemonic is a local MCP server that stores memories as plain markdown in git. Project-scoped hybrid recall finds concepts, exact names, identifiers, and connected context. No database. No always-on service.
Your AI assistant forgets everything between sessions. mnemonic carries that context forward without a database or SaaS subscription.
Every memory is a markdown file with YAML frontmatter. If you stop using mnemonic, you can still read, search, and commit those notes because they remain independent of the tool.
Memories belong to projects. When you're in a repo, the default recall applies project-anchored precision: strongly matching global memories, anchored (alwaysLoad) notes, exact wording, and connected context still surface, while weakly-matching global noise stays out of the default set. Pass scope: "all" explicitly to include everything.
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 combines conceptual search with exact names, identifiers, phrases, error codes, versions, and connected notes. 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, and permanent for decisions worth keeping. Capture what future work will need: decisions, outcomes, corrections, and constraints. 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, such as "Expanded the note with additional detail" or "Connected this note to related work". The overall arc is summarised too: "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 see ranked notes and the signals behind each result.
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. Use document-source attachments to index external markdown documentation as searchable content alongside your memories.
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, and pulls read-only knowledge from external repositories you attach.
Private global memories stored in ~/mnemonic-vault, its own git repo. Use it for cross-project knowledge, user preferences, early brainstorming before a repo exists, and anything you do not 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.
Read-only knowledge from other repositories you point at, with no copying and nothing written back. Attach a repo and its markdown documentation becomes searchable alongside your memories, so context from adjacent projects, frameworks, or runbooks surfaces when it matters. sync pulls a pinned revision and indexes it; the index lives next to your project vault and is rebuilt on demand.
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 conceptual matches while lexical search catches exact names, identifiers, phrases, and versions on every query. Relationship context adds connected notes, and bounded rank fusion keeps the final result stable and fail-soft.
All tools are text-first and optimized for LLM consumption. They stay compact and semantically explicit without 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 (other sizes such as 4B/8B work the same way). For remote or cloud serving, use EMBED_PROVIDER=openai-compatible with EMBED_BASE_URL. Document-source chunks default to 4000 characters; set EMBED_MAX_CHUNK_CHARS to exploit larger model context windows.
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_MAX_CHUNK_CHARS |
4000 | Max characters per document-source chunk (200–100000); non-default values re-chunk attachments on the next sync |
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. Document-source attachments send each chunk's text (content plus heading ancestry and source path) to the configured embedding provider.
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 and cache reads during sync (capped 1 to 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. You do not need to edit them by hand.
{
"reindexEmbedConcurrency": 8,
"mutationPushMode": "none"
}
Attach an external repo and its markdown documentation becomes searchable alongside your memories. mnemonic reads the files, finds the right page for your question, and can return the exact section when you need the source text. It matches by meaning, not just by the words the docs use, so a question phrased differently from the documentation still lands on the right section. Nothing is written back to that repository.
Give mnemonic the local path to the repo, then narrow which files count as documentation when the defaults aren't right for you:
{
"cwd": "/path/to/your/project",
"localPath": "/path/to/external/repo",
"kind": "document-source",
"root": "docs",
"include": ["**/*.md"],
"exclude": ["**/CHANGELOG.md"]
}
| Option | Default | Meaning |
|---|---|---|
root |
the whole repo | Which folder inside the repo to index |
include |
all markdown | Which files count as documentation |
exclude |
generated & vendor files | Files to skip, such as node_modules, build output, and caches |
acceptedMediaTypes |
markdown | File types accepted as documentation |
After attaching, run a quick sync to index the current revision. The same attachment also works with another repository's mnemonic notes. Keep them read-only by default, or mark them writable so memories can flow both ways. The README covers every option for both kinds.
Mnemonic's tools are self-describing. Each includes "use when" and "do not use when" guidance, behavioral annotations, and typed schemas. Most models can 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 that you can search with recall. Duplicate titles are skipped, so it is 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.
Recall combines bounded semantic, lexical, and relationship signals while preserving provenance, confidence metadata, projection-based embeddings, and compact temporal history. Exact wording is always available as a rescue channel, while relationship expansion remains bounded and semantic-conditioned.
Rank fusion and priors stay bounded; failures degrade gracefully to useful 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, or unknown. It uses structural signals such as the 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 is committed to the repo inside .mnemonic/notes/ as plain markdown. Open the folder and read the notes directly.