MCP工具

Prerequisites

By default, mnemonic uses Ollama locally. Start Ollama and pull an embedding model:

ollama pull nomic-embed-text-v2-moe

qwen3-embedding:0.6b is an alternative with a larger context window for longer notes:

ollama pull qwen3-embedding:0.6b

No code changes required — set EMBED_MODEL=qwen3-embedding:0.6b in your environment or MCP config.

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.

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-dir` destinations
- `--target-dir <path>` -> add any custom client skill directory

Update flow after upgrading `@danielmarbach/mnemonic-mcp`:

If you prefer automatic propagation without copy refreshes, use symlink mode:

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.

Setup

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:

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

Install bundled skills (Claude/OpenCode)

The npm package now includes skills/** plus a helper binary to install them into local skill directories.

```bash

If mnemonic is installed in this project:

npx mnemonic-install-skills --target all --mode copy

Docker Hub

Pre-built images for linux/amd64 and linux/arm64:

```bash docker pull danielmarbach/mnemonic-mcp:latest

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 -d and it will stay up between calls.

MCP client config

Configuration

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.

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:

projectMemoryPolicies and projectIdentityOverrides are written automatically by set_project_memory_policy and set_project_identity — no 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).

Example — raise concurrency on a fast machine and disable auto-push everywhere:

{
  "reindexEmbedConcurrency": 8,
  "mutationPushMode": "none"
}

CLI commands

mnemonic ships CLI commands in addition to the MCP server.

RPIR workflow conventions

For structured workflows, use the RPIR stages: research -> plan -> implement -> review (iterate only when needed).

• Create one request root note per workflow: role: context, lifecycle: temporary, tags: ["workflow", "request"].
• Keep one current plan note per request (role: plan) and update or supersede as the plan evolves.
• For apply/task notes, do not add a new role: use role: plan for executable steps and role: context for execution observations; tag both with apply.
• Keep relationships sparse and immediate-upstream only: research -> request, plan -> request/research, apply -> plan, review -> apply/plan, outcome -> plan (optionally request).
• Consolidate at workflow end: keep the durable outcome, preserve details that still matter, and explicitly remove temporary scaffolding when safe.

Multi-machine workflow

Main vault:

```bash

FAQ

Is the advantage over plain markdown files and grep just easier search?

Easier search is part of it, but three things work together:

• Semantic search over vector embeddings. Each note is indexed through your configured embedding provider so recall finds the right note even when you don't remember the exact words — searching "JWT expiry bug" can surface a note titled "RS256 migration rationale". grep only matches strings you already know.
• A connected knowledge graph. Notes link to each other with typed relationships (explains, supersedes, example-of). Related context surfaces together automatically; memory_graph shows the full web. A folder of markdown files has no edges between them.
• Decision history travels with the code. Every remember, update, and consolidate creates a descriptive git commit, so your decision log and implementation plans evolve alongside the code they describe — attributed and timestamped in git log.

mnemonic is designed to be removable — so give it a try with confidence. We think once you do, you'll stay. But if you ever leave, all the knowledge you've gathered is independent: plain markdown with standard YAML frontmatter, readable in any editor, searchable with grep, committable to git. No rescue operation required.

Are mnemonic's embeddings the same as what Claude uses?

No. The embeddings here are retrieval vectors generated by the provider you configure. With the default Ollama provider, projection text stays on your machine. With OpenAI-compatible cloud proxies, native OpenAI, or Gemini, projection text is sent to that external endpoint. The resulting vectors are stored as local gitignored JSON files. This is the same idea as retrieval-augmented generation (RAG): each note is converted to a dense numeric vector so recall can find semantically related notes even when you don't remember the exact words you used. It has nothing to do with how Claude processes tokens internally.

Why do project memories appear first in recall results even when global memories are more similar?

When you call recall with cwd, mnemonic adds a small fixed project tiebreaker (currently +0.03) to notes belonging to the detected project. This is a soft boost, not a hard filter — global memories are still included when relevant. The tiebreaker helps project context float to the top without overwhelming stronger global matches.

I want to brainstorm with no repo yet. Should I create a temp folder first?

Usually, no. If you're talking to an LLM with mnemonic MCP configured, treat it like a normal brainstorming chat and ask it to store key points in the main vault (global memory).

Example conversation style:

You: I have an idea for a meal-planning app. Let's brainstorm v1 scope.
LLM: Great. I can capture key decisions and open questions in global memory while we explore.

You: Please remember that the app should build weekly meals from pantry items, and avoid recipes with too many missing ingredients.
You: Also remember that I'm undecided on mobile-first vs web-first.

When the idea becomes a real repo, switch to that project context and ask the LLM to migrate only the notes that became project-specific.

You: We're creating the repo now at /path/to/meal-planner.
You: Recall my earlier meal-planner brainstorm notes and move the implementation-relevant ones into this project's vault.

This keeps early ideation reusable as personal/global knowledge while moving concrete project context into .mnemonic/ once collaboration and implementation begin.

How does mnemonic differ from Beads?

mnemonic and Beads address complementary concerns. mnemonic is a knowledge graph: it stores notes, relationships between them, and lets agents retrieve relevant context through semantic search. Beads is a task and dependency tracker: it models work items and their dependencies so agents can determine what is ready to execute next. Both tools can coexist in the same workflow — mnemonic stores knowledge and reasoning while Beads manages execution.

How does mnemonic differ from Memory Bank MCP?

mnemonic and Memory Bank MCP both provide persistent memory for agents, but differ in hosting and scope. Memory Bank MCP is a centralized service — your memory lives in a remote MCP service and is accessed across projects through that single endpoint. mnemonic is local-first — your memories live as plain markdown files on your machine: project-scoped notes in .mnemonic/ within each repo, and personal notes in a global vault under your home directory. There is no always-on server to configure or depend on; the MCP server spawns on demand per session.

How does mnemonic differ from Basic Memory?

Both tools are local-first and use markdown, but with different scoping models. Basic Memory maintains a knowledge base per project that agents can search and update, with optional cloud sync. mnemonic splits memory into two distinct vaults: a global personal vault (~/mnemonic-vault/) for cross-project knowledge, and a project-scoped vault (.mnemonic/) that travels with the repo and is shared via git. This lets you capture early ideas globally before a repo exists, then migrate only project-relevant notes into the shared vault once collaboration begins.

What are temporary notes?

mnemonic distinguishes between two lifecycle states. temporary notes capture evolving working-state: hypotheses, in-progress plans, experiment results, draft reasoning. permanent notes capture durable knowledge: decisions, root cause explanations, architectural guidance, lessons learned. As an investigation progresses, a cluster of temporary notes is typically consolidated into one or more permanent notes, and the scaffolding is discarded. Consolidation should keep the useful outcome without flattening away details future work may need. This two-phase lifecycle keeps exploratory thinking from polluting long-term memory while still giving agents a place to reason incrementally before committing to a conclusion.

Roles, when present, are separate from lifecycle: they help prioritization and retrieval, not retention policy. mnemonic still works without roles, and any inferred role metadata remains an internal hint rather than part of the user-facing note contract.