mnemonic MCP server
Commit Nov 15, 2026Provides project-scoped memory for AI clients using markdown files and git-synced semantic search.
Also known as danielmarbach/mnemonic
- Stars
- 32
- Tools
- 40
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- Apache-2.0
What is mnemonic MCP?
mnemonic provides project-scoped memory for AI clients using markdown files and git-synced semantic search. It exposes 40 tools, such as add_attachment, consolidate, detect_project.
Summary generated from the project's README
About mnemonic MCP server
Developers can maintain project-specific context and decision logs through mnemonic, which provides an AI client with a persistent memory layer using plain markdown files. By storing information in a local vault, your AI assistant can carry decisions, fixes, and technical context across different chat sessions without requiring you to repeat instructions. The system uses git to sync these notes, making your project knowledge diffable, mergeable, and part of your repository history.
This server operates locally using a Node process and relies on Ollama for local embeddings, though it also supports OpenAI, Gemini, and OpenAI-compatible providers. It utilizes hybrid recall to find conceptual matches alongside exact identifiers, error codes, or versions. Users can link external repositories as read-only knowledge sources through document-source attachments. Because the storage is based on markdown with YAML frontmatter, your data remains portable and independent of the tool itself.
What you can do with it
- 1Preserving project context across sessionsAn AI client can remember specific architectural decisions or bug fixes so you do not have to re-explain them in new chats.
- 2Syncing knowledge within a teamShare project-specific notes with teammates by including the mnemonic folder directly in your git repository.
- 3Searching external documentationIndex and search through the markdown documentation of external repositories as if they were part of your own memory.
- 4Hybrid information retrievalFind relevant information using both semantic meaning and exact technical terms like error codes or version numbers.
Written from the project's README. Every use case is checked against a quote from it.
mnemonic MCP tools 40
Detected from the READMEadd_attachmentconsolidatedetect_projectdiscover_tagsexecute_migrationforgetgetget_project_identityget_project_memory_policylistlist_attachmentslist_migrations
| add_attachment | — | |
| consolidate | — | |
| detect_project | — | |
| discover_tags | — | |
| execute_migration | — | |
| forget | — | |
| get | — | |
| get_project_identity | — | |
| get_project_memory_policy | — | |
| list | — | |
| list_attachments | — | |
| list_migrations | — |
Show all 40 toolsShow fewer tools
memory_graphmove_memoryproject_memory_summaryrecallrecent_memoriesrememberrelateremove_attachmentset_attachment_branchset_attachment_enabledset_project_identityset_project_memory_policysyncunrelateupdatewhere_is_memoryrelated-toexplainsexample-ofsupersedesderives-fromfollowskindrootincludeexcludebranchwritable
| memory_graph | — | |
| move_memory | — | |
| project_memory_summary | — | |
| recall | — | |
| recent_memories | — | |
| remember | — | |
| relate | — | |
| remove_attachment | — | |
| set_attachment_branch | — | |
| set_attachment_enabled | — | |
| set_project_identity | — | |
| set_project_memory_policy | — | |
| sync | — | |
| unrelate | — | |
| update | — | |
| where_is_memory | — | |
| related-to | — | |
| explains | — | |
| example-of | — | |
| supersedes | — | |
| derives-from | — | |
| follows | — | |
| kind | — | |
| root | — | |
| include | — | |
| exclude | — | |
| branch | — | |
| writable | — |
Configuration
VAULT_PATH
| Name | Description | |
|---|---|---|
| VAULT_PATH | — |
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubmnemonic
A local MCP memory server backed by plain markdown files, synced via git. No database. Project-scoped memory with hybrid semantic, exact-match, and relationship-aware recall.
For the high-level system map, see ARCHITECTURE.md. For release notes, see CHANGELOG.md.
Why mnemonic
- Your MCP client can carry decisions, fixes, and context across sessions, so you do not have to re-explain the same project.
- Memories are plain markdown with YAML frontmatter. They are readable, diffable, mergeable, and easy to back up.
- No database or always-on service is required. mnemonic uses files, git, and a local Node process.
- Project-scoped recall favors the right repo context while keeping stronger global matches accessible.
- Hybrid recall finds conceptual matches as well as exact names, identifiers, phrases, error codes, and versions.
- Shared
.mnemonic/notes travel with the repository, so project knowledge is not trapped in one person's chat history. - Document-source attachments let you link external repos as read-only knowledge sources. Their markdown docs are indexed and searchable through recall alongside your memories.
- Embeddings stay local and gitignored. You get semantic retrieval without committing generated vector data.
- Every
remember,update, andconsolidatecreates a semantic git commit. Your decision log and plans travel with the code in the same history. - If you stop using mnemonic, your notes remain plain markdown with YAML frontmatter. The knowledge you gather stays independent and remains yours.
Stability
The storage format is stable with migration support for any future changes. Since 1.0, mnemonic follows semantic versioning: breaking changes to the note format, vault layout, tool surface or CLI bump the major version. Keep an eye on the changelog; list_migrations shows pending work per vault after each update.
Scale: mnemonic favors simplicity and portability over large-scale knowledge bases.
- Hundreds to low thousands of notes: a good fit.
- Several thousand: often fine, depending on note size, machine speed, and embedding throughput.
- Within a session, notes and embeddings are cached after first access. Repeated
recall,get, andproject_memory_summarycalls skip storage reads regardless of vault size. - Very large collections: expect longer reindexing, higher recall latency, and more git churn.
- Many concurrent writers or massive scale: consider a dedicated database and indexing layer instead.
Prerequisites
By default, mnemonic uses Ollama locally. Start Ollama and pull an embedding model:
ollama pull nomic-embed-text-v2-moe
qwen3-embedding models (0.6B, 4B, 8B) work with the same endpoints — locally only EMBED_MODEL changes (e.g. EMBED_MODEL=qwen3-embedding:0.6b); for remote or vLLM/LM Studio-style serving use EMBED_PROVIDER=openai-compatible with EMBED_BASE_URL (remote Ollama cannot use OLLAMA_URL, which is validated to localhost/private networks). Note that note embeddings always use a bounded projection (title, summary, headings), so a larger model context window mainly benefits document-source attachments: their chunk ceiling defaults to 4000 characters and is configurable via EMBED_MAX_CHUNK_CHARS.
Advanced users can use OpenAI-compatible endpoints, native OpenAI, or Gemini instead. Provider settings are environment-only; mnemonic never writes API keys to notes, embedding files, vault config, or git.
Setup
Native (Node.js 20+)
npm install
npm run build
npm test
# release-confidence gate (build + full tests + isolated dogfooding)
npm run verify:release
The gate fails on required dogfood checks and reports advisory findings separately in the dogfood output.
npm run build already runs typecheck, but running it explicitly first gives a faster failure loop when iterating on the codebase.
For local dogfooding, start the built MCP server with:
npm run mcp:local
This rebuilds first, then launches build/index.js, so MCP clients always point at the latest source.
For reproducible dogfooding of recency and relationship-navigation behavior, prefer the isolated dogfood runner over the live project vault. The isolated runner copies the current .mnemonic notes into a temporary workspace, runs the chosen pack there, and deletes the workspace afterward.
Docker
docker compose build
docker compose up ollama-init # pulls nomic-embed-text-v2-moe into the ollama volume (one-time)
Ollama runs as a container with a named volume (ollama-data) so downloaded models persist across restarts. The vault directory (~/mnemonic-vault by default) is bind-mounted from the host. Git credentials (~/.gitconfig and ~/.ssh) are mounted read-only so push/pull work inside the container.
Override the vault location:
VAULT_PATH=/path/to/your-vault docker compose run --rm mnemonic
Installing
npm
Published to the public npm registry. No authentication required.
# Latest stable release
npm install @danielmarbach/mnemonic-mcp
# Specific release
npm install @danielmarbach/mnemonic-mcp@1.0.0
Install bundled skills (Claude/OpenCode)
The npm package now includes skills/** plus a helper binary to install them into local skill directories.
# If mnemonic is installed in this project:
npx mnemonic-install-skills --target all --mode copy
# One-off install without adding dependency:
npx -y -p @danielmarbach/mnemonic-mcp mnemonic-install-skills --target all --mode copy
Supported targets:
--target claude->~/.claude/skills--target opencode->~/.config/opencode/skills--target all-> both (default)--target custom-> only use--target-dirdestinations--target-dir <path>-> add any custom client skill directory
Update flow after upgrading @danielmarbach/mnemonic-mcp:
npx mnemonic-install-skills --target all --mode copy --update
If you prefer automatic propagation without copy refreshes, use symlink mode:
npx mnemonic-install-skills --target all --mode symlink --update
After install, load and use the skill by name:
- Skill name:
mnemonic-rpi-workflow - Prompt counterpart:
mnemonic-rpi-workflow
In clients that support explicit skill loading (for example Claude Code or OpenCode), load mnemonic-rpi-workflow before running multi-step RPIR workflows.
Homebrew
The formula lives in this repository. Tap it with an explicit URL so no separate repository is needed:
brew tap danielmarbach/mnemonic-mcp https://github.com/danielmarbach/mnemonic
brew install mnemonic-mcp
Or in a single step (direct formula URL):
brew install --formula https://raw.githubusercontent.com/danielmarbach/mnemonic/main/Formula/mnemonic-mcp.rb
To test a prerelease (release candidate or beta) before it becomes a stable release, install the mnemonic-mcp-prerelease formula instead. It points at the newest prerelease tag (after a stable release it stays on the last prerelease until the next one ships) and conflicts with the stable formula, so uninstall one before installing the other:
brew install mnemonic-mcp-prerelease
Docker Hub
Pre-built images for linux/amd64 and linux/arm64:
docker pull danielmarbach/mnemonic-mcp:latest
# Or a specific version
docker pull danielmarbach/mnemonic-mcp:1.0.0
MCP client config
Claude Desktop / Cursor (native)
{
"mcpServers": {
"mnemonic": {
"command": "npx",
"args": ["@danielmarbach/mnemonic-mcp"],
"env": {
"VAULT_PATH": "/Users/you/mnemonic-vault"
}
}
}
}
For a fixed installed version, point at the local binary instead:
{
"mcpServers": {
"mnemonic": {
"command": "/path/to/your/project/node_modules/.bin/mnemonic",
"env": {
"VAULT_PATH": "/Users/you/mnemonic-vault"
}
}
}
}
Claude Desktop / Cursor (Homebrew)
{
"mcpServers": {
"mnemonic": {
"command": "mnemonic",
"env": {
"VAULT_PATH": "/Users/you/mnemonic-vault"
}
}
}
}
Claude Desktop / Cursor (Docker)
{
"mcpServers": {
"mnemonic": {
"command": "docker",
"args": ["compose", "-f", "/path/to/mnemonic/compose.yaml", "run", "--rm", "mnemonic"],
"env": {
"VAULT_PATH": "/Users/you/mnemonic-vault"
}
}
}
}
Ollama must be running before the MCP client invokes mnemonic. Start it once with
docker compose up ollama -dand it will stay up between calls.
OpenCode
Add to ~/.config/opencode/opencode.json (global) or opencode.json in your project root:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mnemonic": {
"type": "local",
"command": ["npx", "@danielmarbach/mnemonic-mcp"],
"environment": {
"VAULT_PATH": "/Users/you/mnemonic-vault"
}
}
}
}
Codex
Add to ~/.codex/config.toml (global) or .codex/config.toml in a trusted project:
[mcp_servers.mnemonic]
command = "npx"
args = ["@danielmarbach/mnemonic-mcp"]
[mcp_servers.mnemonic.env]
VAULT_PATH = "/Users/you/mnemonic-vault"
For local development against this repository's source tree, use npm run mcp:local or point your MCP client at scripts/mcp-local.sh.
Configuration
| Variable | Default | Description |
|---|---|---|
VAULT_PATH |
~/mnemonic-vault |
Path to your markdown vault |
EMBED_PROVIDER |
ollama |
ollama, openai-compatible, openai, or gemini |
EMBED_MODEL |
provider default | Embedding model. Defaults to nomic-embed-text-v2-moe for Ollama, text-embedding-3-small for OpenAI, and gemini-embedding-2 for Gemini. Required for openai-compatible. |
EMBED_DIMENSIONS |
unset | Optional provider-supported output dimensions |
EMBED_MAX_CHUNK_CHARS |
unset | Max characters per document-source chunk (200–100000, default 4000). A non-default value re-chunks attachments on the next sync. |
OLLAMA_URL |
http://localhost:11434 |
Ollama server URL, validated to localhost/private-network addresses |
EMBED_BASE_URL |
unset | Base URL for openai-compatible endpoints such as LiteLLM, LM Studio, vLLM, or Ollama's OpenAI-compatible API |
EMBED_API_KEY |
unset | Optional bearer token for openai-compatible; never persisted by mnemonic |
OPENAI_BASE_URL |
https://api.openai.com |
Native OpenAI base URL; also used as fallback for openai-compatible when EMBED_BASE_URL is unset |
OPENAI_API_KEY |
unset | Required for EMBED_PROVIDER=openai; also used as fallback for openai-compatible when EMBED_API_KEY is unset |
GEMINI_BASE_URL |
https://generativelanguage.googleapis.com |
Native Gemini API base URL |
GEMINI_API_KEY |
unset | Required for EMBED_PROVIDER=gemini; never persisted by mnemonic |
DISABLE_GIT |
false |
Set true to skip all git ops |
MNEMONIC_TOOLSET |
full |
core registers only the nine everyday tools (recall, get, remember, update, relate, list, sync, project_memory_summary, consolidate). That halves the tool definitions every session loads, which helps smaller models pick the right tool. Unknown values fall back to full |
Empty values count as unset, so a client that templates OLLAMA_URL="" gets the default instead of a startup error.
The server also sends MCP instructions in its initialize response: a short usage protocol (always pass cwd, recall before remember, get for full content, relate after remember). Most clients add it to the model's context automatically, so agents follow the basic workflow without extra setup.
Provider configuration is read from the process environment at startup. Only non-secret compatibility metadata is stored in local gitignored embedding JSON files: provider, model, dimensions, metric, optional input mode, and compatibility key.
After changing EMBED_PROVIDER, EMBED_MODEL, EMBED_DIMENSIONS, or endpoint semantics behind the same model alias, call the sync MCP tool with { "force": true } to rebuild local embeddings. Until rebuilt, incompatible embeddings are skipped rather than compared across vector spaces, so semantic recall may return fewer results.
Privacy note: Ollama keeps projection text local. OpenAI-compatible cloud proxies, native OpenAI, and Gemini send the note projection text used for embeddings 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 — use a local provider or do not attach a repository whose content is restricted.
config.json
The main vault's ~/mnemonic-vault/config.json holds machine-local settings that survive across sessions. You can edit it by hand. Unknown fields are ignored, and invalid values fall back to defaults.
User-tunable fields:
| Field | Default | Description |
|---|---|---|
reindexEmbedConcurrency |
4 |
Parallel embedding and cache reads during sync (capped 1 to 16) |
mutationPushMode |
"main-only" |
When to auto-push after a write: "all", "main-only", or "none" |
projectMemoryPolicies and projectIdentityOverrides are written automatically by set_project_memory_policy and set_project_identity. You do not need to edit them by hand.
Project memory policies can include protected-branch settings (protectedBranchBehavior, protectedBranchPatterns) used by mutating tools when they commit to project vaults (remember, update, forget, move_memory, and mutating consolidate strategies).
For example, raise concurrency on a fast machine and disable auto-push everywhere:
{
"reindexEmbedConcurrency": 8,
"mutationPushMode": "none"
}
How it works
Vault layout
Two vault types store notes:
Main vault: private global memories at ~/mnemonic-vault (its own git repo):
~/mnemonic-vault/
.gitignore ← auto-created, gitignores embeddings/ and projections/
notes/
setup-notes-a1b2c3.md
embeddings/ ← local only, never committed
setup-notes-a1b2c3.json
projections/ ← local only, never committed
setup-notes-a1b2c3.json
Project vault: project-specific memories committed into the project repo:
<git-root>/
.mnemonic/
.gitignore ← auto-created, gitignores embeddings/ and projections/
notes/
auth-bug-fix-d4e5f6.md
embeddings/ ← local only, never committed
auth-bug-fix-d4e5f6.json
projections/ ← local only, never committed
auth-bug-fix-d4e5f6.json
Routing
cwd sets project context; scope picks storage:
cwd+scope: "project"(default whencwdis present and no policy is saved) → project vault (.mnemonic/)cwd+scope: "global"→ main vault, with project association in frontmatter- no
cwd→ main vault as a plain global memory
Use set_project_memory_policy to save per-project defaults:
- write scope (
project,global,ask) - consolidation mode (
supersedes,delete) - protected-branch behavior for project-vault writes (
ask,block,allow) - protected-branch patterns (glob strings; defaults are
main,master,release*)
When write scope policy is ask, remember returns a clear storage choice instead of guessing. On supported MCP clients, it asks you to choose project or global storage through the client UI. When protected-branch behavior is ask, mutating tools that would commit to the project vault ask for one-time confirmation through the client UI. Clients without that support return the allowProtectedBranch: true override option and instructions for persisting block or allow.
A saved write-scope policy is authoritative: when an explicitly passed scope contradicts it, nothing is written. On clients with elicitation support, remember asks the user to pick between the policy and the explicit value; other clients get an error explaining the conflict. Pass scopePolicyOverride: true only when the user explicitly requested the deviation. An ask policy conflicts with any explicit scope, since the user asked to choose every time. Successful writes record the governing policy as [policy=global] in the result text (or [policy=global→project, override]) and as policyScope in structured output.
move_memory takes target (main-vault or project-vault) and also accepts the scope alias with remember's vocabulary (global/project); target values from either vocabulary are normalized.
Project identity
Project identity derives from the git remote URL, normalized to a stable slug: git@github.com:acme/myapp.git and https://github.com/acme/myapp both become github-com-acme-myapp, so a repo cloned over SSH on one machine and over HTTPS on another is the same project, regardless of local clone paths. Vaults created before 1.0 stored HTTPS projects as https-github-com-acme-myapp; the normalize-project-ids migration rewrites only those https-/http- prefixes in notes and config.json, including in project vaults that have no config.json (list_migrations and the startup warning show it as pending for the project vaults loaded in the session; execute_migration runs it, and mnemonic migrate --cwd=<repo> runs it for a specific repository), and reads already understand the old ids before the migration runs. New main and project vaults record their schema version in config.json at creation. The default remote is origin; use set_project_identity to switch to upstream for fork workflows. If no remote exists, the git root folder name is used; if not in a git repo, the directory name.
mnemonic MCP questions
What tools does mnemonic MCP provide?
It exposes 40 tools, including add_attachment, consolidate, detect_project, discover_tags, execute_migration.
Does mnemonic require a database?
No, it uses plain markdown files and JSON files synced via git, requiring no database or always-on service.
How does mnemonic handle embeddings?
Embeddings stay local and are gitignored, allowing for semantic retrieval without committing vector data.
Can I use mnemonic with Docker?
Yes, you can use Docker Compose to run mnemonic with an Ollama container.