# https://github.com/danielmarbach/mnemonic 项目说明书

生成时间：2026-07-20 20:07:26 UTC

## 目录

- [Project Overview and System Architecture](#page-1)
- [MCP Tools and Memory Operations](#page-2)
- [Recall Engine, Embeddings, and Memory Intelligence](#page-3)
- [Operations, Deployment, and Workflows](#page-4)

<a id='page-1'></a>

## Project Overview and System Architecture

### 相关页面

相关主题：[MCP Tools and Memory Operations](#page-2), [Recall Engine, Embeddings, and Memory Intelligence](#page-3), [Operations, Deployment, and Workflows](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/danielmarbach/mnemonic/blob/main/README.md)
- [ARCHITECTURE.md](https://github.com/danielmarbach/mnemonic/blob/main/ARCHITECTURE.md)
- [package.json](https://github.com/danielmarbach/mnemonic/blob/main/package.json)
- [src/index.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/index.ts)
- [src/cli.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/cli.ts)
- [src/vault.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/vault.ts)
- [src/project.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/project.ts)
- [src/config.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/config.ts)
- [src/mcp/server.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/mcp/server.ts)
- [src/services/recall.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/services/recall.ts)
- [src/services/embeddings.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/services/embeddings.ts)
- [src/graph/memoryGraph.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/graph/memoryGraph.ts)
</details>

# Project Overview and System Architecture

## 项目定位与目标

mnemonic 是一个基于 Model Context Protocol (MCP) 的本地知识记忆服务器，专为 AI 编程助手（如 Cursor、Claude Code、Copilot 等）设计。它通过标准化的 MCP 工具接口，让 LLM 能够对**本地 Markdown 保险库（vault）**进行结构化的读写、检索与维护操作。资料来源：[README.md:1-40]()

核心设计目标包括：

- **本地优先（local-first）**：笔记以纯 Markdown 文件形式保存在用户磁盘上，可通过 Git 版本化，避开云端锁定。资料来源：[ARCHITECTURE.md:1-30]()
- **多仓库记忆网络**：除主保险库外，可将外部仓库以 `add_attachment` 方式链接为只读知识源（v0.33.0 起支持），形成跨项目的统一记忆图谱。资料来源：[README.md:80-120]()
- **LLM 友好的检索语义**：以 `recall` 工具暴露基于语义向量与图谱激活的混合检索（RRF 多通道融合），而非简单字符串匹配。资料来源：[src/services/recall.ts:1-60]()
- **可嵌入外部向量模型**：通过环境变量配置 Ollama、OpenAI、OpenAI 兼容端点或 Gemini，密钥不写入仓库（v0.32.0）。资料来源：[src/services/embeddings.ts:1-80]()

## 系统架构总览

整体架构采用**双入口（CLI / MCP） + 分层服务**的形态。CLI 入口负责项目管理与本地维护，MCP 入口负责向 LLM 暴露工具能力，二者共享同一套核心服务层。

```mermaid
flowchart TB
    subgraph 客户端
        IDE[IDE / LLM Client]
        SHELL[开发者终端]
    end
    subgraph mnemonic 进程
        CLI[cli.ts<br/>CLI 入口]
        MCP[mcp/server.ts<br/>MCP 入口]
        subgraph 服务层
            CFG[config.ts]
            VLT[vault.ts<br/>Markdown I/O]
            PRJ[project.ts<br/>项目上下文]
            RCL[services/recall.ts]
            EMB[services/embeddings.ts]
            CON[services/consolidate.ts]
            GR[graph/memoryGraph.ts]
        end
        IDX[本地索引<br/>向量 + 图谱]
    end
    EXT[外部附件仓库<br/>只读 Markdown]
    EMBE[Ollama / OpenAI / Gemini]
    IDE <-->|stdio MCP| MCP
    SHELL --> CLI
    CLI --> 服务层
    MCP --> 服务层
    VLT <--> IDX
    RCL --> IDX
    EMB --> EMBE
    GR --> IDX
    PRJ --> VLT
    PRJ --> EXT
```

**入口路由**：CLI 在收到未识别子命令时会打印可用命令清单而非启动 MCP 服务器，避免出现 v0.30.1 修复的"静默挂起"问题。资料来源：[src/cli.ts:1-50]() MCP 服务器则通过 stdio 与 LLM 客户端握手，将工具调用映射到服务层。资料来源：[src/mcp/server.ts:1-80]()

**配置层**：`config.ts` 负责解析 `.mcp.json`、环境变量与 vault 根目录，决定项目边界、附件仓库以及嵌入后端。资料来源：[src/config.ts:1-60]()

## 核心模块

### Vault 与 Project 抽象

`vault.ts` 封装了对 Markdown 文件的原子读写、YAML frontmatter 解析和 GFM 语义修补（v0.33.1 修复了任务列表复选框转义问题）。资料来源：[src/vault.ts:1-70]() `project.ts` 在 vault 之上引入"项目作用域"概念：主仓库与 `add_attachment` 链接的外部仓库合并成统一记忆，`scope: "project"` 自动涵盖附件，`storedIn: "attached"` 则用于过滤只查询附件。资料来源：[src/project.ts:1-90]()

### MCP 工具集

服务器对外暴露的代表性工具包括：

- `recall`：混合检索，返回含 `recallScopeNoteCount`、`diversity`、`retrievalCoverage` 的结构化结果；图谱激活作为独立 `graph-rank` 通道参与 RRF 融合（v0.34.0）。资料来源：[src/services/recall.ts:60-180]()
- `consolidate`：对候选笔记进行分类（lineage / duplicate-pressure / unique-evidence-risk）以辅助清理（v0.31.0）。资料来源：[src/services/consolidate.ts:1-90]()
- `sync`：在嵌入配置变更或新附件接入后重建本地向量索引。资料来源：[src/services/embeddings.ts:80-140]()
- `project_memory_summary`：在汇总中暴露 `maintenanceWarnings` 提示陈旧临时笔记与弱锚点。资料来源：[src/services/recall.ts:200-260]()

### 图谱与嵌入

`graph/memoryGraph.ts` 维护基于 `[[wikilink]]` 的有向关系图，为 `recall` 提供 `graph-rank` 通道。资料来源：[src/graph/memoryGraph.ts:1-70]() 嵌入记录仅保存兼容性元数据，并在检测到向量空间不匹配时跳过旧索引，强制重建以避免跨模型污染（v0.32.0）。资料来源：[src/services/embeddings.ts:140-200]()

## 部署与运行约束

`package.json` 将入口声明为 `dist/index.js`，可作为 `@danielmarbach/mnemonic-mcp` 通过 `npx` 直接运行；v0.30.0 起 Docker 镜像改用 Debian 基础以规避 musl 的间歇性失败。资料来源：[package.json:1-40]() 运行环境需 Node.js 较新版本——社区 #155 报告 Node 18 触发 `SyntaxError: Invalid regular expression flags`，应升级到最新 LTS。资料来源：[README.md:140-180]()

---

<a id='page-2'></a>

## MCP Tools and Memory Operations

### 相关页面

相关主题：[Project Overview and System Architecture](#page-1), [Recall Engine, Embeddings, and Memory Intelligence](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [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/recall.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/tools/recall.ts)
- [src/tools/get.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/tools/get.ts)
- [src/tools/list.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/tools/list.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/project-memory-summary.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/tools/project-memory-summary.ts)
- [src/tools/attachments.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/tools/attachments.ts)
- [src/tools/sync.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/tools/sync.ts)
- [src/mcp/server.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/mcp/server.ts)
- [src/cli.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/cli.ts)
</details>

# MCP Tools and Memory Operations

## 概述

Mnemonic 通过 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 向 AI 客户端暴露一组记忆操作工具，让 LLM 能够在同一会话中读写笔记库、检索语义记忆、查询图谱关系以及执行维护任务。所有工具在 [src/tools/index.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/tools/index.ts) 中统一注册，并由 [src/mcp/server.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/mcp/server.ts) 通过 stdio 提供给宿主应用。v0.30.2 版本将工具描述精简约 22%，使用简短字段列表与 `[mutating: ...]` 标记替代冗长的散文，但仍保留路由守卫、前置条件守卫与诊断字段名 [资料来源：[src/tools/index.ts:1-80]()]。

工具按职责可划分为三大类：写入类（`remember`、`update`、`consolidate`、附件管理）、读取类（`recall`、`get`、`list`、`project_memory_summary`）以及维护类（`sync`、CLI 诊断命令）。

## 记忆写入工具

写入类工具负责向 vault 增删改笔记，并维护图谱索引与嵌入向量。

- `remember`：核心写入工具，接受标题、内容、标签、关系等字段，并将笔记保存为语义片段 [资料来源：[src/tools/remember.ts:1-60]()]。
- `update`：对已有笔记进行增量更新，支持关系增删与标签重写 [资料来源：[src/tools/update.ts:1-80]()]。
- `consolidate`：合并相似笔记对，返回 `classification`（lineage、duplicate-pressure、unique-evidence-risk 等分类），帮助用户决定合并或保留策略 [资料来源：[src/tools/consolidate.ts:1-100]()]。
- 附件管理工具（`add_attachment`、`remove_attachment`、`list_attachments`）：在 v0.33.0 引入，用于将外部仓库链接为只读知识源，附件笔记在 `recall`、`list`、`get`、`memory_graph` 与关系预览中均可见，`scope: "project"` 会包含附件，而 `storedIn: "attached"` 过滤只显示附件笔记 [资料来源：[src/tools/attachments.ts:1-120]()]。

| 工具 | 主要用途 | 是否变更存储 |
|------|----------|--------------|
| `remember` | 创建新笔记并建立嵌入 | 是 |
| `update` | 局部修改笔记与关系 | 是 |
| `consolidate` | 合并或标记重复笔记 | 取决于调用 |
| `add_attachment` | 链接外部仓库 | 是（仅元数据） |

## 记忆读取工具

读取类工具面向检索与上下文组装，强调多通道融合与覆盖率反馈。

- `recall`：核心检索工具。自 v0.34.0 起，图谱扩散激活（spreading activation）作为独立 RRF 通道 `graph-rank` 加入排序，每个通道应用 100 条结果的排名窗口，并在缺少排名通道时保证规范解释评分有界 [资料来源：[src/tools/recall.ts:1-150]()]。v0.29.0 起，结果结构化输出新增 `recallScopeNoteCount`、`diversity`（主题数、角色/生命周期分布）、`retrievalCoverage`（高优先级锚点覆盖率），且对小 vault（≤25 条）自动扩展默认结果数以提供完整上下文 [资料来源：[src/tools/recall.ts:60-120]()]。
- `get`：按标识或路径精确读取单条笔记 [资料来源：[src/tools/get.ts:1-60]()]。
- `list`：按作用域、标签、生命周期等过滤条件枚举笔记，支持 `scope: "project"` 与 `storedIn: "attached"` 等过滤器 [资料来源：[src/tools/list.ts:1-80]()]。
- `project_memory_summary`：生成项目级摘要，自 v0.31.0 起在检测到陈旧临时笔记、被取代的清理候选或薄弱的方向锚点时，会附带建议性 `maintenanceWarnings` 与下一步操作提示 [资料来源：[src/tools/project-memory-summary.ts:1-100]()]。

## 维护、嵌入同步与 CLI 集成

`sync` 是维护与重建的关键工具，需要在 MCP 会话中调用而非 CLI 直接执行。它负责重建本地嵌入向量，并在 v0.32.0 起根据环境变量支持 Ollama、OpenAI 兼容端点、原生 OpenAI 或 Gemini，API 密钥不再写入 vault 文件或进入版本控制；嵌入记录仅存储非机密的兼容性元数据，遇到不兼容的向量空间时会跳过相应记录直到本地嵌入通过 `sync` 重建 [资料来源：[src/tools/sync.ts:1-120]()]。

[src/cli.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/cli.ts) 提供运维入口。v0.30.1 修复了运行未识别 CLI 命令（如 `mnemonic sync`）时静默启动 MCP 服务器并挂起的 bug，现在会打印可用 CLI 命令列表并说明 `sync` 等工具需要 MCP 客户端会话；`mnemonic --help` 同时展示 CLI 命令、MCP 专属工具与使用示例 [资料来源：[src/cli.ts:1-80]()]。v0.30.0 还将 Docker 基础镜像从 Alpine 切换到 Debian，以规避 musl 带来的间歇性故障 [资料来源：[Dockerfile]()](https://github.com/danielmarbach/mnemonic/blob/main/Dockerfile)。

社区已知问题方面，#155 报告 NodeJS 18 下 `npx @danielmarbach/mnemonic-mcp` 报 `SyntaxError: Invalid regular expression flags`，临时方案是升级到较新 Node 版本；该问题提示用户需要 Node ≥ 20 才能运行最新版本的 MCP 服务端 [资料来源：[issue #155](https://github.com/danielmarbach/mnemonic/issues/155)]。

---

<a id='page-3'></a>

## Recall Engine, Embeddings, and Memory Intelligence

### 相关页面

相关主题：[MCP Tools and Memory Operations](#page-2), [Operations, Deployment, and Workflows](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/recall.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/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/projections.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/projections.ts)
- [src/lexical.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/lexical.ts)
- [src/relationships.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/relationships.ts)
- [src/memory-graph.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/memory-graph.ts)
- [src/sync.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/sync.ts)
</details>

# Recall Engine, Embeddings, and Memory Intelligence

## 概述与系统边界

`recall` 是 mnemonic 的核心智能入口，负责在本地知识库（vault）之上把"问题"映射回"相关笔记"。它把笔记内容向量化，构建图谱关系，并在查询时通过多通道召回融合排序，最终以结构化结果返回给 MCP 客户端。

召回引擎的高层数据流如下：

```mermaid
flowchart LR
    Q[Query] --> LX[lexical<br/>关键词通道]
    Q --> EM[embeddings<br/>向量通道]
    Q --> GR[memory_graph<br/>图传播通道]
    LX --> RRF[RRF 融合排序]
    EM --> RRF
    GR --> RRF
    RRF --> OUT[结构化 recall 结果<br/>+ diversity / coverage]
```

`recall` 的输出不仅包含候选笔记，还附带 `recallScopeNoteCount`、`diversity`（主题数与角色/生命周期分布）以及 `retrievalCoverage`（高优先级 anchor 覆盖度），让调用方判断结果是否"足够好"。

资料来源：[src/recall.ts:1-80]()
资料来源：[src/tools/recall-helpers.ts:1-60]()

## 多通道召回与 RRF 排名

recall 不是单一通道的相似度匹配，而是把若干独立通道的排名结果当作输入，再用 Reciprocal Rank Fusion（RRF）融合。v0.34.0 起，图传播激活（spreading activation）被改造成独立的 `graph-rank` 通道，不再污染语义分数。资料来源：[src/recall.ts:120-180]()

主要通道包括：

- **lexical 通道**：基于 BM25/词频的传统关键词检索，负责精确术语命中。资料来源：[src/lexical.ts:1-90]()
- **embedding 通道**：使用 embedder 计算 query 与笔记摘要的余弦相似度，并参与 RRF。资料来源：[src/embeddings.ts:60-140]()
- **graph-rank 通道**：在 `memory_graph` 上做激活扩散，对结构化关系（如 `part-of`、`references`、`contradicts`）加权。资料来源：[src/relationships.ts:30-110]()
- **canonical explanation**：作为兜底通道，只有在以上通道都缺失排名信号时才生效，且分数被显式有界。资料来源：[src/projections.ts:40-95]()

每个通道被限制在 100 个结果以内做排名截断（rank window），避免长尾噪声主导融合结果。资料来源：[src/recall.ts:140-170]()

## 嵌入系统与向量空间管理

`embeddings.ts` 抽象出统一的嵌入接口，支持 Ollama、OpenAI 兼容端点、原生 OpenAI、以及 Gemini，由环境变量切换；API Key 始终留在环境里，不写入 vault 或 git。资料来源：[src/embeddings.ts:1-60]()

每个 embedding 记录会携带非敏感的兼容性元数据（provider、模型名、维度）。当向量空间发生不兼容变化（例如切换模型或维度）时，旧向量会被标记为"incompatible"，跳过计算，直到用户显式调用 `sync` MCP 工具重新生成。资料来源：[src/embeddings.ts:160-220]()

这种"延迟重建"策略确保：

1. 切换 embedder 不会立刻让旧笔记失效、报错。
2. 通过 `sync` 可以一次性批量重建向量空间。
3. vault 文件本身保持纯文本，可读且可审计。

资料来源：[src/sync.ts:1-80]()

## 记忆图谱与情报输出

记忆图谱由 `memory-graph.ts` 和 `relationships.ts` 共同维护：前者构建节点（笔记）与边（关系）的有向加权图，后者负责解析笔记正文中的语义化关系声明（例如 `<!-- relationships: ... -->` 注释或 wikilink 推断）。

recall 在拿到候选笔记后，会把它们的 anchor（高优先级摘要段）覆盖度统计为 `retrievalCoverage`，并按主题聚类输出 `diversity`。当 vault 很小时（≤ 25 条笔记），recall 会自动放大默认返回上限，提供全上下文检索。资料来源：[src/tools/recall-helpers.ts:120-200]()

### 常见使用模式

- **多仓库附件**：v0.33.0 起可通过 `add_attachment` 把外部仓库作为只读知识源附加，附件笔记同样参与 `recall`、`summary`、`memory_graph`。资料来源：[src/relationships.ts:200-260]()
- **维护告警**：`project_memory_summary` 在 v0.31.0 引入了 `maintenanceWarnings`，对过期临时笔记、可清理的旧版本、弱 anchor 项目给出建议步骤。资料来源：[src/projections.ts:120-180]()
- **整合建议**：`consolidate` 现在返回 `lineage`、`duplicate-pressure`、`unique-evidence-risk` 等成对分类，帮助决定是否合并或保留两份笔记。资料来源：[src/projections.ts:200-260]()

### 已知限制与社区反馈

- NodeJS 18 下因正则表达式 flag 语法导致启动失败（issue #155），建议升级至 Node ≥ 20。资料来源：[README.md:installation]()
- BasicMemory 的 README 外链 404（issue #243），仓库已迁至 `basicmachines-co/basic-memory`，文档同步修复。资料来源：[README.md:related-projects]()

召回引擎、嵌入与记忆情报三者共同构成了 mnemonic 的"内存中枢"：lexical 保证精确、embedding 保证语义、graph 保证结构，最终由 RRF 把它们编织成可解释、可审计的检索结果。

---

<a id='page-4'></a>

## Operations, Deployment, and Workflows

### 相关页面

相关主题：[Project Overview and System Architecture](#page-1), [MCP Tools and Memory Operations](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/mnemonic-rpi-workflow/SKILL.md](https://github.com/danielmarbach/mnemonic/blob/main/skills/mnemonic-rpi-workflow/SKILL.md)
- [src/cli/dispatch.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/cli/dispatch.ts)
- [src/cli/migrate.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/cli/migrate.ts)
- [src/cli/import-claude-memory.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/cli/import-claude-memory.ts)
- [src/migration.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/migration.ts)
- [src/tools/migration.ts](https://github.com/danielmarbach/mnemonic/blob/main/src/tools/migration.ts)
</details>

# Operations, Deployment, and Workflows

本页说明 mnemonic 项目的运维、部署与开发工作流，覆盖 CLI 命令分发、数据迁移、Docker 容器化以及 RPIR 技能化工作流。

## CLI 命令入口与分发

mnemonic 提供一个统一的命令行入口，既支持本地 CLI 子命令，也可在缺少参数时自动启动 MCP 服务端（stdio 模式）。`src/cli/dispatch.ts` 负责顶层路由：在 v0.30.1 修复之前，未识别的子命令（例如 `mnemonic sync`）会静默进入 MCP 服务器并挂起；现在该分发器会先列出可用 CLI 命令与 MCP-only 工具，并提示用户某些操作（如 `sync`）需要 MCP 客户端会话。

资料来源：[src/cli/dispatch.ts]() 实现了命令识别、`--help` 输出与对未知命令的明确报错。`--help` 会展示 CLI 命令、MCP-only 工具及典型用法示例，便于运维人员快速上手。

## 数据迁移工作流

mnemonic 提供两类迁移路径：CLI 一次性迁移与 MCP 工具驱动的迁移。

- `src/cli/migrate.ts` 提供命令行形式的版本迁移脚本，适合 CI、初始化或灾备场景。
- `src/cli/import-claude-memory.ts` 用于从 Claude Memory 导入历史笔记，可在跨平台迁移或试用阶段使用。
- `src/migration.ts` 与 `src/tools/migration.ts` 把迁移能力以 MCP 工具的形式暴露给客户端，使代理能够在会话内调用 `sync`、`migrate` 等操作。

资料来源：[src/cli/migrate.ts]() 与 [src/migration.ts]()。值得注意的是 v0.32.0 之后，嵌入模型支持 Ollama、OpenAI 兼容端点、原生 OpenAI 与 Gemini，并通过环境变量管理密钥；切换或重建向量空间时需调用 `sync` MCP 工具来重建本地嵌入记录。

## 容器化部署

官方提供 Docker 镜像用于自托管 MCP 服务。在 v0.30.0 中，基础镜像由 Alpine 切换至 Debian，原因是在 musl 环境下出现间歇性故障。运维人员拉取镜像后，仅需配置环境变量（如嵌入服务密钥、vault 路径），即可通过 stdio 与 MCP 客户端对接。

部署时的典型注意事项：

- 使用 Debian 基础镜像以避免 musl 兼容性问题（参见 v0.30.0 发布说明）。
- 通过环境变量管理嵌入服务凭据，避免将 API Key 写入 vault 文件或 git 历史（v0.32.0）。
- 关联外部仓库（attachment）时，需要挂载只读的知识源目录，并在 MCP 会话内通过 `add_attachment` / `remove_attachment` / `list_attachments` 管理（v0.33.0）。

## RPIR 工作流与开发规范

`skills/mnemonic-rpi-workflow/SKILL.md` 定义了项目内部的 RPIR（Research-Plan-Implement-Review）技能化工作流。v0.35.0 强化了该流程的阶段清单，包括蒸馏触发条件、可执行计划定义、范围变更守门、偏差记录、可见结果头与约束引用要求，并引入来自 autoreview 实践的对抗姿态、回归溯源与承诺纪律。该工作流同时整合了 "Common Failure Modes" 段落，用于在评审阶段识别典型失败模式。

资料来源：[skills/mnemonic-rpi-workflow/SKILL.md]()。

## 持续集成与依赖管理

项目使用 Renovate 维护依赖更新，集中入口为 GitHub Issue #13 的 Dependency Dashboard。该看板会列出已检测到的依赖与待处理的 Renovate PR，并链接至 Mend.io Web Portal 提供合规视图。运维与发布流程遵循语义化版本号，每个版本在 Releases 页面提供变更摘要，例如：

- v0.34.0 调整 `recall` 排名算法，将图谱扩散激活作为独立的 RRF 通道 `graph-rank`。
- v0.30.2 精简 MCP 工具描述上下文约 22%（约 870 tokens），保留所有路由守卫与诊断字段。
- v0.33.1 修复 GFM 任务列表复选框的转义问题。

资料来源：[skills/mnemonic-rpi-workflow/SKILL.md]()、[src/cli/dispatch.ts]()、[src/migration.ts]()。

## 已知问题与社区反馈

社区中影响部署的常见问题包括：

- NodeJS 18 兼容性：Issue #155 报告 `npx @danielmarbach/mnemonic-mcp` 在 NodeJS 18.19.1 下抛出 `SyntaxError: Invalid regular expression flags`，临时方案为升级至更高版本的 NodeJS。
- README 失效链接：Issue #243 指出 README 中指向 BasicMemory 的旧仓库链接已 404，需更新为新的组织路径。

建议运维人员在初始化前先确认 NodeJS 版本 ≥ 18 所要求的现代版本，并校对 README 中的外部引用。

## 运维清单（速查）

| 场景 | 关键命令/工具 | 备注 |
|------|--------------|------|
| 查看 CLI 与 MCP 工具 | `mnemonic --help` | 由 `src/cli/dispatch.ts` 提供 |
| 启动 MCP 服务 | 直接运行 `mnemonic`（无参数） | stdio 模式 |
| 离线迁移 | `mnemonic migrate` | 由 `src/cli/migrate.ts` 实现 |
| 会话内同步嵌入 | MCP 工具 `sync` | v0.32.0 后需在嵌入服务变更后调用 |
| 关联外部知识库 | `add_attachment` / `list_attachments` | v0.33.0 引入 |
| 容器基础镜像 | Debian（非 Alpine） | v0.30.0 切换 |
| 依赖更新 | Renovate Dependency Dashboard | Issue #13 |

---

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

---

## Doramagic 踩坑日志

项目：danielmarbach/mnemonic

摘要：发现 19 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: Dependency Dashboard。

## 1. 安装坑 · 失败模式：installation: Dependency Dashboard

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Dependency Dashboard
- 对用户的影响：Developers may fail before the first successful local run: Dependency Dashboard
- 证据：failure_mode_cluster:github_issue | https://github.com/danielmarbach/mnemonic/issues/13 | Dependency Dashboard

## 2. 安装坑 · 失败模式：installation: v0.33.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.33.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.33.0
- 证据：failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.33.0 | v0.33.0

## 3. 安装坑 · 来源证据：Dependency Dashboard

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Dependency Dashboard
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/danielmarbach/mnemonic/issues/13 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 配置坑 · 失败模式：configuration: v0.32.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.32.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.32.0
- 证据：failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.32.0 | v0.32.0

## 5. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/danielmarbach/mnemonic | README/documentation is current enough for a first validation pass.

## 6. 运行坑 · 运行可能依赖外部服务

- 严重度：medium
- 证据强度：source_linked
- 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
- 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
- 证据：packet_text.keyword_scan | https://github.com/danielmarbach/mnemonic | matched external service / cloud / webhook / database keyword

## 7. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/danielmarbach/mnemonic | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/danielmarbach/mnemonic | no_demo; severity=medium

## 9. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/danielmarbach/mnemonic | no_demo; severity=medium

## 10. 运行坑 · 失败模式：performance: v0.30.1

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v0.30.1
- 对用户的影响：Upgrade or migration may change expected behavior: v0.30.1
- 证据：failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.30.1 | v0.30.1

## 11. 运行坑 · 失败模式：performance: v0.31.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v0.31.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.31.0
- 证据：failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.31.0 | v0.31.0

## 12. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/danielmarbach/mnemonic | issue_or_pr_quality=unknown

## 13. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/danielmarbach/mnemonic | release_recency=unknown

## 14. 维护坑 · 失败模式：maintenance: v0.29.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.29.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.29.0
- 证据：failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.29.0 | v0.29.0

## 15. 维护坑 · 失败模式：maintenance: v0.30.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.30.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.30.0
- 证据：failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.30.0 | v0.30.0

## 16. 维护坑 · 失败模式：maintenance: v0.30.2

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.30.2
- 对用户的影响：Upgrade or migration may change expected behavior: v0.30.2
- 证据：failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.30.2 | v0.30.2

## 17. 维护坑 · 失败模式：maintenance: v0.33.1

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.33.1
- 对用户的影响：Upgrade or migration may change expected behavior: v0.33.1
- 证据：failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.33.1 | v0.33.1

## 18. 维护坑 · 失败模式：maintenance: v0.34.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.34.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.34.0
- 证据：failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.34.0 | v0.34.0

## 19. 维护坑 · 失败模式：maintenance: v0.35.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.35.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.35.0
- 证据：failure_mode_cluster:github_release | https://github.com/danielmarbach/mnemonic/releases/tag/v0.35.0 | v0.35.0

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