Related Pages

Related topics: Vault Architecture and Data Model

Overview and Installation

Project Overview

Mnemonic is a Model Context Protocol (MCP) server that provides a structured memory layer for LLM clients. It manages a local vault of notes organized as projects, supports graph-based retrieval (recall, memory_graph), embeddings across multiple providers, and auxiliary workflows such as consolidation and project summaries. The current stable release is v0.35.0 (Source: package.json:3-3), and the project is published to npm as @danielmarbach/mnemonic-mcp, which can be launched directly via npx without a global install (Source: README.md:1-40).

The runtime exposes MCP tools plus a small CLI surface. Recent versions added add_attachment / remove_attachment / list_attachments for read-only repository attachments and switched the base Docker image from Alpine to Debian due to musl-related intermittent failures (Source: Dockerfile:1-15). CLI behavior was hardened in v0.30.1 so that unknown commands print a clear error rather than silently starting the MCP server (Source: src/index.ts:1-80).

System Requirements

The runtime requires a modern Node.js version. The community reports that npx @danielmarbach/mnemonic-mcp fails with SyntaxError: Invalid regular expression flags on Node 18.19.1; the recommended workaround is upgrading to the latest LTS (Source: issue #155). The repository pins its development Node version in .nvmrc, and CI validates against the same major (Source: .nvmrc:1-1).

For embedding-based features you need network access to at least one provider. Since v0.32.0, embeddings can target Ollama, OpenAI-compatible endpoints, native OpenAI, or Gemini through environment configuration, with API keys kept out of vault files and source control (Source: README.md:120-180). If you previously embedded with a different model, call the sync MCP tool after switching providers so the local vector store is rebuilt against the new compatibility metadata (Source: README.md:180-220).

Installation Methods

Mnemonic ships through three primary distribution channels: npm (the default MCP client path), a Debian-based container, and a Homebrew formula for macOS/Linux desktops. Pick one based on how you intend to invoke it.

npm (recommended for MCP clients)

The package is published as @danielmarbach/mnemonic-mcp and exposes a bin entry. Launch it on demand:

npx @danielmarbach/mnemonic-mcp

This is the same entry MCP clients (Claude Desktop, Cursor, etc.) call when you register the server (Source: package.json:40-60). Skills — optional workflow bundles used by the agent — are installed via a dedicated script that writes them into your skills directory (Source: scripts/install-skills.mjs:1-40):

node scripts/install-skills.mjs

Docker / Compose

The Dockerfile builds on node:20-bookworm-slim (Debian) and installs only the production dependencies required to run the MCP server (Source: Dockerfile:1-15). compose.yaml wires the image to a persistent volume for the vault and exposes the stdio contract expected by MCP hosts running in containers (Source: compose.yaml:1-30). After docker compose up, attach the container to your MCP client using the stdio transport.

Homebrew (macOS / Linux desktops)

A tap formula packages the npm release and is kept in sync with tagged versions, allowing brew install and brew upgrade flows for desktop users (Source: Formula/mnemonic-mcp.rb:1-25).

First-Run Verification

After installing, confirm the CLI recognizes the available command set:

mnemonic --help

The help output lists CLI commands, the MCP-only tools that require a client session (such as sync), and a few usage examples (Source: src/index.ts:20-80). Running an MCP-only command on the bare CLI now prints a clear error rather than hanging — this was a v0.30.1 fix (Source: README.md:60-100).

For embedding-dependent recall, confirm your chosen provider is reachable before invoking recall; otherwise recall silently degrades to keyword graph traversal (Source: README.md:180-220).

Architecture at a Glance

This layered split is consistent with the release history: v0.34.0 decoupled graph spreading into its own RRF channel (graph-rank) without mutating semantic scores, and v0.33.0 introduced attachments that surface across recall, summaries, list, get, and memory_graph (Source: README.md:40-120).

Common Pitfalls

• Outdated Node: Node 18 triggers regex flag errors on startup; upgrade first (Source: issue #155).
• Wrong README link: The README previously pointed to basicmachines/basicmemory, which 404s after the org rename — the canonical URL is now under basicmachines-co (Source: issue #243).
• Mismatched embeddings after provider switch: until you call sync, newer embeddings skip the vector store and recall behaves keyword-only (Source: README.md:180-220).
• CLI hangs: invoking an MCP-only command at the terminal instead of through a client now produces an explicit error list (Source: README.md:60-100).

Once mnemonic --help returns the expected command list and your MCP client connects, the system is ready for note ingestion and recall.

Related Pages

Related topics: Overview and Installation, Recall, Embeddings, and AI Integration

Vault Architecture and Data Model

The vault is the central abstraction in mnemonic: it is a file-system-backed, project-scoped container that owns notes, their embeddings, the memory graph, and metadata about attached repositories. Every MCP tool — recall, search, list, get, consolidate, project_memory_summary, memory_graph — operates against a vault instance resolved at request time from the project registry Source: src/vault.ts:1-40.

Core Concepts and Responsibilities

A vault is created, opened, or resolved through the Vault class, which encapsulates:

• Note I/O — markdown files on disk with frontmatter parsed into structured Note records Source: src/vault.ts:42-120.
• Embedding index — vectors persisted alongside notes, lazily rebuilt when local embedding compatibility metadata drifts Source: src/storage.ts:1-80.
• Memory graph — nodes (notes) and edges (relationships) used for graph-spreading activation recall Source: src/vault.ts:122-180.
• Maintenance state — temporary notes, superseded candidates, and orientation anchors surfaced as maintenanceWarnings Source: src/project-introspection.ts:60-140.

The vault is intentionally read-mostly: mutating operations (add, update, consolidate) flow through explicit, audited paths so that attached repositories stay read-only Source: ARCHITECTURE.md:1-60.

Storage Layers

Mnemonic separates three storage concerns, each in its own module:

Attached notes are first-class in retrieval — they appear in recall, list, get, memory_graph, and relationship previews — but are gated behind scope: "project" when callers want to include them, or filtered to exclusively by storedIn: "attached" Source: src/attached-storage.ts:1-90. This separation is why add_attachment / remove_attachment / list_attachments exist as discrete MCP tools rather than mutating the primary vault Source: ARCHITECTURE.md:60-120.

Embedding records carry non-secret compatibility metadata (model identifier, dimensions, provider) so that providers can be swapped (Ollama, OpenAI, OpenAI-compatible, Gemini) via environment configuration without re-embedding the entire vault immediately — incompatible vector spaces are skipped until sync is called Source: src/storage.ts:80-160.

Data Model

A Note record contains the canonical fields consumed across tools:

id, path, title, content, summary,
metadata (frontmatter), tags, lifecycle, role,
embeddingId, createdAt, updatedAt, storedIn

• storedIn discriminates "primary" from "attached" notes and drives scope filters Source: src/vault.ts:42-120.
• lifecycle and role power the diversity and retrievalCoverage diagnostics returned by recall (theme count, role/lifecycle mix, fraction of high-priority anchors covered) Source: src/vault.ts:180-240.
• Relationships live as edges keyed by note id pairs; the graph is used as an independent Reciprocal Rank Fusion channel called graph-rank in v0.34.0, with a 100-result rank window per channel and bounded canonical explanation scoring when channels are missing Source: src/vault.ts:240-300.

consolidate produces per-pair classification values (lineage, duplicate-pressure, unique-evidence-risk) so that consolidation suggestions are explainable rather than opaque Source: src/project-introspection.ts:140-220.

Projects, Routing, and Introspection

A vault always belongs to a project. The project registry maps incoming MCP requests to a vault instance, and project_memory_summary exposes three advisory surfaces Source: src/project.ts:1-90:

1. Stale temporary notes (lifecycle flags older than threshold).
2. Superseded cleanup candidates derived from consolidation lineage.
3. Weak orientation anchors — high-priority notes with low retrievalCoverage.

Each warning ships with an actionable next-step suggestion mirrored in both structured and text output Source: src/project-introspection.ts:60-140.

Small vaults (≤ 25 notes) automatically have the default recall limit expanded so retrieval returns full-context results without requiring callers to specify a higher limit Source: src/vault.ts:300-360.

Operational Notes

• API keys for embedding providers are intentionally not persisted in vault files or committed to git; configuration is environment-driven Source: ARCHITECTURE.md:120-180.
• Round-trip serialization preserves GFM task list checkboxes after v0.33.1; semantic patches must not escape - [ ] / - [x] as \[ ] / \[x] Source: src/vault.ts:360-420.
• Community issue #155 documents that older Node.js 18 runtimes fail with SyntaxError: Invalid regular expression flags; vault code uses regex features requiring a current Node LTS Source: issue #155.
• Community issue #243 notes a stale external link in README.md; the README is informational and does not affect the vault data model.

Together these layers form a vault that is portable on disk, extensible via attachments, and observable through structured diagnostics — the substrate on which every other mnemonic capability is built.

Related Pages

Related topics: Vault Architecture and Data Model, RPIR Workflow, MCP Tools, CLI, and Failure Modes

Recall, Embeddings, and AI Integration

Overview

The recall tool is the primary retrieval surface exposed by the mnemonic Model Context Protocol (MCP) server. It combines lexical matching, semantic vector similarity, and graph spreading activation into a single ranked result set using Reciprocal Rank Fusion (RRF). Source: src/tools/recall.ts:1-60. Embeddings back the semantic channel and are produced by configurable providers that keep secrets out of vault files and version control. Source: src/embeddings.ts:1-80. Together, these modules form the bridge between stored notes and the language models that consume them through an MCP client.

Recall Pipeline and Scoring

Recall orchestrates several independent rank channels before fusing them. Each channel produces at most a 100-result rank window, and the fusion step keeps canonical explanation scoring bounded when fewer channels are available. Source: src/recall.ts:120-220. The channels include:

• Semantic channel built from embedding similarity against the active vector space.
• Lexical channel that matches note titles, tags, and inline content.
• Graph-rank channel introduced in v0.34.0, which treats spreading activation as an independent RRF input instead of mutating semantic scores. Source: src/recall.ts:220-310.

Helper utilities normalize query expansion, scope resolution, and per-result metadata in src/tools/recall-helpers.ts. Source: src/tools/recall-helpers.ts:30-140. For small vaults of 25 notes or fewer, recall automatically expands its default result limit to provide full-context retrieval. Source: src/recall.ts:60-120.

Recall also honors the multi-repository attachment model: notes originating from add_attachment repositories appear in results when scope includes project, while storedIn: "attached" narrows to that subset. Source: src/tools/recall.ts:140-260.

Embedding Providers and Configuration

As of v0.32.0, mnemonic delegates embeddings to one of four providers selected through environment variables, never through vault configuration:

Source: src/embeddings.ts:80-220. API keys are read from the process environment and never serialized into embedding records. Each embedding record instead stores non-secret compatibility metadata (model name, dimensionality, provider identifier) so a vault can detect whether the local vector space is still compatible with the configured provider. Source: src/embeddings.ts:220-340.

When a stored vector space is incompatible with the active provider, records are skipped during retrieval until a sync call rebuilds the local embeddings against the new dimensions and model. Source: src/helpers/embed.ts:1-120. The projection layer (src/projections.ts) normalizes vectors to a common dimensionality before similarity computation, which lets mnemonic mix legacy and refreshed embeddings during a migration. Source: src/projections.ts:40-160.

The configuration loader validates that the selected provider is reachable and refuses to start recall with a misconfigured backend. Source: src/config.ts:120-220.

Output Structure and Diagnostics

Structured recall output includes three diagnostic aggregates that help downstream agents judge result quality:

• recallScopeNoteCount — the total notes considered within the active scope.
• diversity — the count of distinct themes plus the role/lifecycle mix.
• retrievalCoverage — the fraction of high-priority orientation anchors covered by the returned set.

Source: src/recall.ts:310-420. These fields were added in v0.29.0 so that AI clients can detect degenerate retrievals and request broader queries when coverage is low. Source: src/tools/recall-helpers.ts:140-260.

The MCP tool description that reaches the client keeps routing guards, prerequisite guards, and diagnostic field names stable even after the v0.30.2 reduction of prose verbosity, so clients can still branch on these signals. Source: src/tools/recall.ts:60-140. When invoked outside an MCP session — for example, when a user types mnemonic recall from a shell — the CLI refuses the call, lists available CLI commands, and explains that retrieval tools require an MCP client session (regression fixed in v0.30.1). Source: src/tools/recall.ts:260-340.

AI Integration Notes

Several operational caveats surface repeatedly in community discussions and reflect how the modules above behave together:

• Node runtime version. Issue #155 reports SyntaxError: Invalid regular expression flags on NodeJS 18 because the embedding HTTP layer relies on modern syntax features; upgrading to a current LTS release resolves the failure. Source: src/embeddings.ts:1-80.
• Vault portability. Because embedding records carry compatibility metadata rather than raw secrets, a vault can be cloned, opened on a different host, and re-synced without leaking provider credentials. Source: src/embeddings.ts:220-340.
• Recall determinism. With graph-rank elevated to its own RRF channel, deterministic ordering no longer depends on the magnitude of semantic scores, which improves reproducibility for AI workflows that re-rank on top of recall. Source: src/recall.ts:220-310.

Together, these modules let an MCP-connected language model retrieve, evaluate, and reason over a vault without ever persisting provider keys alongside the notes.

Related Pages

Related topics: Overview and Installation, Recall, Embeddings, and AI Integration

RPIR Workflow, MCP Tools, CLI, and Failure Modes

The mnemonic project exposes its memory operations through two complementary surfaces: a Model Context Protocol (MCP) server consumed by LLM clients, and a command-line interface for direct operator use. Overlaying both is the RPIR workflow skill — a procedural guide that drives an LLM through the Recall → Plan → Implement → Review cycle when working with the vault. This page documents how these three pieces fit together and where they are known to fail.

RPIR Workflow Skill (skills/mnemonic-rpi-workflow/SKILL.md)

The RPIR skill is the canonical procedure that an LLM agent must follow when the user asks it to act on mnemonic memory. Version v0.35.0 strengthened every stage of the checklist:

• Distill triggers — explicit conditions that must be met before recalling.
• Executable plan definition — plans must be testable, not aspirational.
• Scope-change gates — any change that expands beyond the user's request must be flagged.
• Deviation recording — when the agent diverges from the plan, the reason must be visible.
• Visible outcome headers — results are surfaced under named headings so the user can audit them.
• Constraint-citation requirements — every claim about vault behavior cites the source rule.

The skill integrates review principles from the autoreview practice, mandating an adversarial posture, regression provenance (each change traceable to a prior state), and commitment discipline (no silent scope expansion). Source: skills/mnemonic-rpi-workflow/SKILL.md:1-40.

MCP Tool Surface (src/tools/index.ts)

All mutation and retrieval flows are registered through a single tool registry. Each tool description follows the v0.30.2 terse format — field lists plus [mutating: ...] tags — which trimmed ~870 tokens (~22%) from the description footprint while preserving routing guards, prerequisite guards, and diagnostic field names. Source: src/tools/index.ts:1-60.

Core tools, with their routing concern:

Recall emits recallScopeNoteCount, diversity (theme count + role/lifecycle mix), and retrievalCoverage (fraction of high-priority anchors covered) since v0.29.0; small vaults (≤25 notes) automatically expand the default result limit. Source: src/tools/recall.ts:1-80.

CLI Routing and MCP-only Tools

The CLI and the MCP toolset overlap but are not identical. v0.30.1 introduced explicit CLI routing: invoking an unrecognized command (e.g. mnemonic sync) previously caused the process to silently enter MCP-server mode and hang. It now prints an error listing available CLI commands and explaining that mutating tools such as sync require an active MCP client session. mnemonic --help surfaces both the CLI commands and the MCP-only tools, with usage examples. Source: src/cli.ts:1-50.

This split is intentional: the CLI is a thin operator shell, while the full mutating surface (embedding rebuilds, attachment registration, semantic patching) is reserved for MCP clients that can pass through rich arguments.

Common Failure Modes

The v0.35.0 release of the RPIR skill formalized a Common Failure Modes section. The recurring categories observed across the release history are:

1. Recall ranking regressions — fixed in v0.34.0 by isolating graph spreading activation as an independent Reciprocal Rank Fusion channel (graph-rank) rather than mutating semantic scores, and by bounding canonical explanation scoring when rank channels are missing.
2. Round-trip serialization breaks — v0.33.1 stopped the semantic patch from escaping GFM task list checkboxes (- [ ] / - [x]) as \[ ] / \[x].
3. Provider compatibility gaps — v0.32.0 added embeddings via Ollama, OpenAI-compatible endpoints, native OpenAI, or Gemini; embedding records now skip incompatible vector spaces until sync is called locally.
4. CLI/MCP confusion — v0.30.1 closed the "silent MCP hang on unrecognized command" footgun.
5. Stale vault hygiene — v0.31.0 introduced maintenanceWarnings on project_memory_summary for stale temporary notes, superseded cleanup candidates, and weak orientation anchors.
6. Context bloat — v0.30.2 trimmed tool descriptions; further drift risks reintroducing the ~870-token overhead if descriptions revert to prose form.

The RPIR skill's stage checklists are designed so that an agent encountering any of the above must record the deviation, cite the relevant tool file, and emit a visible outcome header describing the mitigation taken. Source: skills/mnemonic-rpi-workflow/SKILL.md:40-120.

Cross-references

• Community issue #155 documents a Node.js 18 failure (SyntaxError: Invalid regular expression flags) when launching npx @danielmarbach/mnemonic-mcp; upgrading Node is the documented workaround.
• Issue #243 flags a broken README link to BasicMemory (now at basicmachines-co/basic-memory), relevant when reading the related-projects section of the skill.
• Renovate dependency tracking lives in issue #13; dependency drift can surface as new failure modes after provider upgrades.

Doramagic Pitfall Log

Found 19 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Dependency Dashboard
• User impact: Developers may fail before the first successful local run: Dependency Dashboard
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Dependency Dashboard. Context: Observed when using node, docker
• Evidence: failure_mode_cluster:github_issue | https://github.com/danielmarbach/mnemonic/issues/13

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v0.33.0
• User impact: Upgrade or migration may change expected behavior: v0.33.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.33.0. Context: Observed when using node, docker
• Evidence: failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.33.0

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/danielmarbach/mnemonic/issues/13

4. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v0.32.0
• User impact: Upgrade or migration may change expected behavior: v0.32.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.32.0. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.32.0

5. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/danielmarbach/mnemonic

6. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: packet_text.keyword_scan | https://github.com/danielmarbach/mnemonic

7. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/danielmarbach/mnemonic

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/danielmarbach/mnemonic

9. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/danielmarbach/mnemonic

10. Runtime risk: Runtime risk requires verification

• Severity: low
• Finding: Developers should check this performance risk before relying on the project: v0.30.1
• User impact: Upgrade or migration may change expected behavior: v0.30.1
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.30.1. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.30.1

11. Runtime risk: Runtime risk requires verification

• Severity: low
• Finding: Developers should check this performance risk before relying on the project: v0.31.0
• User impact: Upgrade or migration may change expected behavior: v0.31.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.31.0. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.31.0

12. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/danielmarbach/mnemonic

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using mnemonic with real data or production workflows.

• Dependency Dashboard - github / github_issue
• v0.35.0 - github / github_release
• v0.34.0 - github / github_release
• v0.33.1 - github / github_release
• v0.33.0 - github / github_release
• v0.32.0 - github / github_release
• v0.31.0 - github / github_release
• v0.30.2 - github / github_release
• v0.30.1 - github / github_release
• v0.30.0 - github / github_release
• v0.29.0 - github / github_release
• Capability evidence risk requires verification - GitHub / issue