# https://github.com/danielmarbach/mnemonic Project Manual

Generated at: 2026-07-20 20:09:45 UTC

## Table of Contents

- [Overview and Installation](#page-overview-setup)
- [Vault Architecture and Data Model](#page-vault-architecture)
- [Recall, Embeddings, and AI Integration](#page-recall-embeddings)
- [RPIR Workflow, MCP Tools, CLI, and Failure Modes](#page-rpir-operations)

<a id='page-overview-setup'></a>

## Overview and Installation

### Related Pages

Related topics: [Vault Architecture and Data Model](#page-vault-architecture)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/danielmarbach/mnemonic/blob/main/README.md)
- [package.json](https://github.com/danielmarbach/mnemonic/blob/main/package.json)
- [Dockerfile](https://github.com/danielmarbach/mnemonic/blob/main/Dockerfile)
- [compose.yaml](https://github.com/danielmarbach/mnemonic/blob/main/compose.yaml)
- [Formula/mnemonic-mcp.rb](https://github.com/danielmarbach/mnemonic/blob/main/Formula/mnemonic-mcp.rb)
- [scripts/install-skills.mjs](https://github.com/danielmarbach/mnemonic/blob/main/scripts/install-skills.mjs)
- [src/index.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/index.ts)
- [.nvmrc](https://github.com/danielmarbach/mnemonic/blob/main/.nvmrc)
</details>

# 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:

```bash
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]()):

```bash
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:

```bash
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

| Layer | Responsibility | Key file |
|-------|---------------|----------|
| CLI entry | Parse argv, dispatch to MCP server or helpers | `src/index.ts` |
| MCP server | Stream JSON-RPC over stdio, register tools | `src/server.ts` |
| Vault store | Read/write Markdown notes, frontmatter, attachments | `src/vault/` |
| Recall engine | Spreading activation + semantic + RRF rank fusion | `src/recall/` |
| Embeddings | Provider abstraction, vector sync | `src/embeddings/` |

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`.

---

<a id='page-vault-architecture'></a>

## Vault Architecture and Data Model

### Related Pages

Related topics: [Overview and Installation](#page-overview-setup), [Recall, Embeddings, and AI Integration](#page-recall-embeddings)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [ARCHITECTURE.md](https://github.com/danielmarbach/mnemonic/blob/main/ARCHITECTURE.md)
- [src/vault.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/vault.ts)
- [src/storage.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/storage.ts)
- [src/attached-storage.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/attached-storage.ts)
- [src/project.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/project.ts)
- [src/project-introspection.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/project-introspection.ts)
</details>

# 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:

| Layer | File | Responsibility |
|---|---|---|
| Primary storage | `src/storage.ts` | Notes, embeddings, graph edges, vector space metadata |
| Attached storage | `src/attached-storage.ts` | Read-only external repository notes, filtered via `storedIn: "attached"` |
| Project registry | `src/project.ts` | Multi-project routing, project resolution, `project_memory_summary` |

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.

---

<a id='page-recall-embeddings'></a>

## Recall, Embeddings, and AI Integration

### Related Pages

Related topics: [Vault Architecture and Data Model](#page-vault-architecture), [RPIR Workflow, MCP Tools, CLI, and Failure Modes](#page-rpir-operations)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/recall.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/recall.ts)
- [src/tools/recall.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/tools/recall.ts)
- [src/tools/recall-helpers.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/tools/recall-helpers.ts)
- [src/embeddings.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/embeddings.ts)
- [src/helpers/embed.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/helpers/embed.ts)
- [src/projections.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/projections.ts)
- [src/config.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/config.ts)
</details>

# 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:

| Provider | Configuration | Notes |
|---|---|---|
| Ollama | `EMBEDDINGS_PROVIDER=ollama` with `EMBEDDINGS_OLLAMA_URL` | Local-first path |
| OpenAI-compatible | `EMBEDDINGS_PROVIDER=openai-compatible` with `EMBEDDINGS_BASE_URL` | Custom endpoints |
| OpenAI native | `EMBEDDINGS_PROVIDER=openai` with `EMBEDDINGS_API_KEY` | Direct API access |
| Gemini | `EMBEDDINGS_PROVIDER=gemini` with `EMBEDDINGS_API_KEY` | Google's embedding API |

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.

---

<a id='page-rpir-operations'></a>

## RPIR Workflow, MCP Tools, CLI, and Failure Modes

### Related Pages

Related topics: [Overview and Installation](#page-overview-setup), [Recall, Embeddings, and AI Integration](#page-recall-embeddings)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [skills/mnemonic-rpi-workflow/SKILL.md](https://github.com/danielmarbach/mnemonic/blob/main/skills/mnemonic-rpi-workflow/SKILL.md)
- [src/tools/index.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/tools/index.ts)
- [src/tools/remember.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/tools/remember.ts)
- [src/tools/update.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/tools/update.ts)
- [src/tools/consolidate.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/tools/consolidate.ts)
- [src/tools/forget.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/tools/forget.ts)
</details>

# 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:

| Tool | File | Role |
|---|---|---|
| `remember` | `src/tools/remember.ts` | Persist a new note into the vault |
| `recall` | `recall.ts` | Retrieve notes (RRF over semantic + graph-rank channels, v0.34.0) |
| `update` | `src/tools/update.ts` | Apply a semantic patch to an existing note |
| `consolidate` | `src/tools/consolidate.ts` | Merge or reconcile note pairs with per-pair `classification` (v0.31.0) |
| `forget` | `src/tools/forget.ts` | Remove a note |
| `sync` | (MCP-only) | Rebuild embeddings after a provider switch (v0.32.0) |
| `add_attachment` / `remove_attachment` / `list_attachments` | (v0.33.0) | Manage read-only multi-repository attachments |
| `project_memory_summary` | (v0.31.0) | Surface `maintenanceWarnings` and next-step suggestions |
| `memory_graph` / `list` / `get` | (v0.33.0) | Read-side views that include attached notes |

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.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: danielmarbach/mnemonic

Summary: 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
- Evidence strength: source_linked
- 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
- Evidence: failure_mode_cluster:github_issue | https://github.com/danielmarbach/mnemonic/issues/13

## 2. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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
- 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
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/danielmarbach/mnemonic/issues/13

## 4. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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
- 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
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/danielmarbach/mnemonic

## 6. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: packet_text.keyword_scan | https://github.com/danielmarbach/mnemonic

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/danielmarbach/mnemonic

## 8. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/danielmarbach/mnemonic

## 9. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/danielmarbach/mnemonic

## 10. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- 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
- 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
- Evidence strength: source_linked
- 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
- 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
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/danielmarbach/mnemonic

## 13. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/danielmarbach/mnemonic

## 14. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.29.0
- User impact: Upgrade or migration may change expected behavior: v0.29.0
- Evidence: failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.29.0

## 15. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.30.0
- User impact: Upgrade or migration may change expected behavior: v0.30.0
- Evidence: failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.30.0

## 16. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.30.2
- User impact: Upgrade or migration may change expected behavior: v0.30.2
- Evidence: failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.30.2

## 17. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.33.1
- User impact: Upgrade or migration may change expected behavior: v0.33.1
- Evidence: failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.33.1

## 18. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.34.0
- User impact: Upgrade or migration may change expected behavior: v0.34.0
- Evidence: failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.34.0

## 19. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.35.0
- User impact: Upgrade or migration may change expected behavior: v0.35.0
- Evidence: failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.35.0

<!-- canonical_name: danielmarbach/mnemonic; human_manual_source: deepwiki_human_wiki -->