# https://github.com/purmemo-ai/purmemo-mcp 项目说明书

生成时间：2026-07-18 21:16:53 UTC

## 目录

- [项目概览与安装部署](#page-1)
- [认证体系与跨平台 Hook 适配](#page-2)
- [MCP 工具、Slash 命令与 Living Document 语义](#page-3)
- [架构决策（ADR）、打包分发与可观测性](#page-4)

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

## 项目概览与安装部署

### 相关页面

相关主题：[认证体系与跨平台 Hook 适配](#page-2)

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

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

- [README.md](https://github.com/purmemo-ai/purmemo-mcp/blob/main/README.md)
- [scripts/install.sh](https://github.com/purmemo-ai/purmemo-mcp/blob/main/scripts/install.sh)
- [scripts/install.ps1](https://github.com/purmemo-ai/purmemo-mcp/blob/main/scripts/install.ps1)
- [src/setup.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/setup.ts)
- [src/manifest.json](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/manifest.json)
- [package.json](https://github.com/purmemo-ai/purmemo-mcp/blob/main/package.json)
</details>

# 项目概览与安装部署

## 项目定位与核心能力

pūrmemo-mcp 是一个面向 AI 编程助手的记忆层（memory layer）中间件，以 Model Context Protocol（MCP）服务器的形式向 Claude Code、OpenAI Codex、Gemini CLI 等客户端暴露工具集。其核心目标是把开发者长期会话中的偏好、调试结论、调查记录与工件沉淀为可被未来的会话按"会话开场简报（session-start brief）"方式召回的持久记忆，从而减少重复上下文重建成本。

项目的版本号采用 `v15.7.x` 形式发布，从已记录的版本历史可见其迭代聚焦在四类变更：
- **诊断与召回质量**：例如 `get_investigations` 与 `get_test_results` 解除 200 字符裁剪以呈现完整根因文本 资料来源：[package.json:1-1]();
- **写入遥测的可读化**：v15.7.21 新增 `get_test_results`、`get_artifacts`、`get_investigations` 三个读工具以闭合只写缺口 资料来源：[README.md:1-1]();
- **认证韧性**：v15.7.18 引入持久化加密密钥以规避 macOS 上 `os.hostname()` 漂移导致的 token 静默损坏，v15.7.19 进一步对不可恢复的解密失败自动拉起浏览器重新登录 资料来源：[README.md:1-1]();
- **多端钩子（hooks）覆盖**：自 v15.7.15 起把 Codex 提升为一类 hook 表面，v15.7.16 修复其 feature flag 默认关闭导致 `hooks.json` 被静默忽略的问题 资料来源：[src/setup.ts:1-1]()。

## 安装方式与平台支持

仓库同时提供 POSIX 与 Windows 两套安装脚本，均负责把 MCP 服务器注册到主流编辑器的配置中并写入相应 hook 入口：

- **macOS / Linux**：执行 `scripts/install.sh`，脚本会探测 Node 与包管理器、运行 `npm install`、生成可执行入口并把它登记到 `claude.json`、`codex/config.toml` 及其 `hooks.json` 资料来源：[scripts/install.sh:1-1]()。
- **Windows**：对应 PowerShell 等价的 `scripts/install.ps1`，处理路径分隔符与 `codex` 的 PowerShell 钩子兼容性 资料来源：[scripts/install.ps1:1-1]()。

`src/manifest.json` 在声明式层面枚举了服务器对外暴露的工具名称、提示词与资源，配合 `package.json` 中的 `bin` 入口声明让 `npx purmemo-mcp`、`purmemo` 等命令在三种宿主（Claude Code / Codex / Gemini CLI）中都可被识别 资料来源：[src/manifest.json:1-1]() 资料来源：[package.json:1-1]()。

## 初始化流程与认证漂移恢复

CLI 在 `src/setup.ts` 中实现首次运行（`purmemo init`）以及隐式恢复流程。下表概括了从"零摩擦安装"目标出发的状态迁移：

| 触发场景 | 旧版本行为 | v15.7.20 之后的行为 |
| --- | --- | --- |
| 新用户首次安装 | 失败回退到需手动运行 `purmemo init` | 安装脚本自动完成设置，README 不再做强制引导 |
| 持久化密钥可解密 | 正常启动 | 正常启动，无变化 |
| 持久化密钥失败但 legacy 密钥可恢复 | 静默回退 | 静默回退（沿用 ADR-039 策略） |
| 两路解密均失败（hostname 漂移超窗） | 抛出 OpenSSL 错误致 CLI 砖化 | 自动拉起浏览器登录并写回新 token，无需用户手动介入 |

资料来源：[README.md:1-1]()。

这一链路依赖持久化密钥替代 `SHA-256(os.hostname() + os.userInfo().username)` 的旧派生方式，从而避免 macOS 在切换 Wi-Fi、启用 VPN 或休眠唤醒后 `os.hostname()` 翻转造成的 token 静默损坏 资料来源：[src/setup.ts:1-1]()。

## 钩子系统与会话开场简报

`src/setup.ts` 中包含 `installClaudeHooks`、`installCodexHooks`、`installGeminiHooks` 三组入口，分别写入 `~/.claude/hooks.json`、`~/.codex/hooks.json` 与 Gemini 的等价位置。Codex 的实现需要先调用 `enableCodexHooksFeatureFlag()` 把 `[features] codex_hooks = true` 写入 `config.toml`，否则其 `hooks.json` 在加载阶段会被静默丢弃 资料来源：[src/setup.ts:1-1]()。

钩子在 `SessionStart` 阶段注入一行简报 `pūrmemo vX.Y.Z · email · tier · memories · cycle usage`，并按"对话优先"排序召回最相关的历史；v15.7.24 修复了 Claude Code 转录文件按整段 JSON 解析失败导致用户消息计数恒为 0 的问题，并保证工具结果回合不被计入用户提示 资料来源：[README.md:1-1]() 资料来源：[src/setup.ts:1-1]()。

---

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

## 认证体系与跨平台 Hook 适配

### 相关页面

相关主题：[项目概览与安装部署](#page-1), [架构决策（ADR）、打包分发与可观测性](#page-4)

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

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

- [src/auth/oauth-manager.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/auth/oauth-manager.ts)
- [src/auth/token-store.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/auth/token-store.ts)
- [src/auth/universal-auth.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/auth/universal-auth.ts)
- [src/auth/setup-decisions.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/auth/setup-decisions.ts)
- [src/auth/profile-resolver.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/auth/profile-resolver.ts)
- [src/auth/profile-migrator.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/auth/profile-migrator.ts)
- [src/hooks/session-start.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/hooks/session-start.ts)
- [src/hooks/install-claude.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/hooks/install-claude.ts)
- [src/hooks/install-codex.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/hooks/install-codex.ts)
- [src/hooks/install-gemini.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/hooks/install-gemini.ts)
- [docs/adr/ADR-036-replace-append-semantics.md](https://github.com/purmemo-ai/purmemo-mcp/blob/main/docs/adr/ADR-036-replace-append-semantics.md)
- [docs/adr/ADR-039-token-key-fallback.md](https://github.com/purmemo-ai/purmemo-mcp/blob/main/docs/adr/ADR-039-token-key-fallback.md)
</details>

# 认证体系与跨平台 Hook 适配

## 概述与设计目标

purmemo-mcp 的认证体系负责在用户机器上安全地持有 OAuth 令牌、解析用户身份与订阅档位，并在不同 AI 客户端（Claude Code、OpenAI Codex、Gemini CLI）首次启动会话时提供一致的记忆上下文回显。该模块与 Hook 安装逻辑紧密耦合：Hook 既负责触发 CLI 的浏览器登录流程，也负责在 `SessionStart` 等事件上读取已保存的令牌并格式化头部摘要。`src/auth/oauth-manager.ts` 是顶层入口，统辖登录、设备激活、令牌轮换和重试策略。

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

## OAuth 令牌存储与加密密钥演进

令牌持久化逻辑位于 `src/auth/token-store.ts`。早期版本（v15.7.18 之前）以 `SHA-256(os.hostname() + os.userInfo().username)` 作为本地 OpenSSL 加密密钥的派生因子。这一实现暴露了 macOS 下的脆弱性：`os.hostname()` 在切换 Wi-Fi、启停 VPN（NordVPN 等）或睡眠唤醒后会变化，DHCP 重派名会导致派生密钥漂移，从而触发 `error:1C80006x` 系列的 OpenSSL 解密失败。v15.7.18 引入了持久化密钥（ADR-039），将派生源切换为稳定写入的本地文件，避免依赖运行时主机名。`src/auth/token-store.ts` 还提供双密钥回退窗口：当新密钥可解密失败时回退到旧密钥一次，记录可观测的迁移事件供 `profile-migrator.ts` 后续清扫。

资料来源：[src/auth/token-store.ts:42-138](), [src/auth/profile-migrator.ts:1-64]()

## 通用认证解析与 Profile 决策

`src/auth/universal-auth.ts` 把"令牌存在性 + 解密成功 + 订阅档位"三态统一为 `AuthState` 枚举，供上层工具（`save_conversation`、`get_test_results` 等）一次性消费。`src/auth/profile-resolver.ts` 进一步把多个 OAuth profile（用户在多邮箱/多档位之间切换）映射为当前活动 profile，写入频率随 `save_conversation` 调用按需触发。`src/auth/setup-decisions.ts` 是首次安装向导的策略表：它根据运行环境（是否已存在 `~/.purmemoo/token`、Hook 是否已注入）决定 CLI 应当静默登录、提示 `purmemo init`，还是主动拉起浏览器。v15.7.20 引入了"sign-in drift auto-recover"：当 CLI 检测到令牌解密失败但仍在 ADR-039 回退窗口内时，自动调用 `oauth-manager.launchBrowserSignIn()`，用户不再需要手动 `purmemo init`。

资料来源：[src/auth/universal-auth.ts:1-96](), [src/auth/profile-resolver.ts:1-72](), [src/auth/setup-decisions.ts:1-58]()

## 跨平台 Hook 适配

Hook 子系统针对三套客户端分别实现安装与回放路径，下表给出事件面与配置差异：

| 客户端 | 安装入口 | 配置位 | Hook 文件 | 必需特性开关 |
| --- | --- | --- | --- | --- |
| Claude Code | `install-claude.ts` | `~/.claude/settings.json` | `hooks/SessionStart.json` | 无 |
| OpenAI Codex | `install-codex.ts` | `~/.codex/config.toml` | `hooks/hooks.json` | `[features] codex_hooks = true` |
| Gemini CLI | `install-gemini.ts` | `~/.gemini/settings.json` | `hooks/SessionStart.toml` | 无 |

Codex 是 v15.7.15 才补齐的一等公民：它需要 `enableCodexHooksFeatureFlag()` 在 `config.toml` 中显式打开 `[features] codex_hooks = true`，否则 `hooks.json` 会被静默忽略（v15.7.16 修复）。三个客户端共用的回放逻辑封装在 `src/hooks/session-start.ts`，其职责是：读取本地 OAuth 令牌、解析当前 profile、统计会话级指标（memories 数、cycle usage）并打印 `pūrmemo vX.Y.Z · email · tier · memories · cycle usage` 形式的单行头部。v15.7.24 修复了 Claude Code 端的 JSONL 嗅探 bug：旧的整文件 `JSON.parse` 会在第二行抛错并吞掉 JSONL 回退，导致所有 transcript 被计为 0 条用户消息；现在按行解析且排除 `tool_result` 类回放轮次。

```mermaid
flowchart LR
  A[用户启动客户端] --> B{Hook 已安装?}
  B -- 否 --> C[install-claude/codex/gemini]
  B -- 是 --> D[SessionStart 触发]
  D --> E[session-start.ts 读取 token]
  E --> F{token 可解密?}
  F -- 否, 在回退窗口内 --> G[oauth-manager 启动浏览器登录]
  F -- 否, 超出窗口 --> H[提示 purmemo init]
  F -- 是 --> I[universal-auth 解析 AuthState]
  I --> J[打印 pūrmemo 头部摘要]
```

资料来源：[src/hooks/install-claude.ts:1-44](), [src/hooks/install-codex.ts:1-52](), [src/hooks/install-gemini.ts:1-38](), [src/hooks/session-start.ts:1-120]()

## 已知边界与社区反馈

社区追踪显示，认证模块的高频故障集中在三类：(1) macOS 主机名漂移导致的令牌解密失败（v15.7.18、v15.7.19 修复链）；(2) Codex Hook 因特性开关缺失而"安装成功但不触发"（v15.7.16）；(3) `get_test_results`、`get_investigations` 在早期版本将列表字段截断到 200 字符，遮蔽真实失败体（v15.7.22、v15.7.23）。后续改进方向包括进一步收紧 ADR-039 的回退窗口、以及在 `universal-auth` 中显式暴露 `mode='append'`（ADR-036）以避免误覆盖长期记忆。

资料来源：[docs/adr/ADR-036-replace-append-semantics.md:1-40](), [docs/adr/ADR-039-token-key-fallback.md:1-32]()

---

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

## MCP 工具、Slash 命令与 Living Document 语义

### 相关页面

相关主题：[认证体系与跨平台 Hook 适配](#page-2), [架构决策（ADR）、打包分发与可观测性](#page-4)

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

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

- [src/server.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/server.ts)
- [src/tools/handlers.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/tools/handlers.ts)
- [src/tools/handoff.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/tools/handoff.ts)
- [src/workflows/engine.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/workflows/engine.ts)
- [src/intelligent-memory.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/intelligent-memory.ts)
- [src/lib/api-client.ts](https://github.com/purmemo-ai/purmemo-mcp/blob/main/src/lib/api-client.ts)
</details>

# MCP 工具、Slash 命令与 Living Document 语义

## 一、MCP 工具面：注册、派发与外部回写

`src/server.ts` 是 MCP 服务的协议入口，在进程启动时构建 `McpServer` 实例，并把一组按职责命名的工具（`save_conversation`、`search_memory`、`get_investigations`、`get_test_results`、`get_artifacts` 等）统一注册到 `server.tool(name, schema, handler)` 上。每个工具的 schema 同时承担两件事：声明输入契约、向客户端 IDE/Agent 暴露可调用的名称与描述 资料来源：[src/server.ts:120-210]()。

注册完成后，运行时请求统一进入 `src/tools/handlers.ts` 中的派发表。该文件把"工具名 → 处理器函数"做静态映射，handler 只关心业务语义，不感知协议细节；所有外部副作用（鉴权刷新、HTTP 调用、加密回写）都通过 `src/lib/api-client.ts` 完成。api-client 封装了 OAuth token 的读取、续期与重试逻辑，对上层只暴露类似 `client.searchMemories(q)`、`client.saveMemory(payload)` 的方法 资料来源：[src/tools/handlers.ts:40-95]() 资料来源：[src/lib/api-client.ts:30-140]()。

写入类工具与读取类工具在 handler 内的分支位置并不相同：写入路径会先经过 `src/intelligent-memory.ts` 中的"分类与摘要"管道，再交给 api-client；读取路径则直接转发查询并做字段裁剪。这条分叉决定了后续 Living Document 的写入语义需要在哪里被显式声明。

## 二、Slash 命令与工作流引擎

Slash 命令是面向人类用户的命令式入口，由 `src/tools/handoff.ts` 中导出的工具集直接对应。例如 `/purmemo-save`、`/purmemo-recall`、`/purmemo-handoff` 在 MCP 工具面背后各自映射到一个 handler——slash 命令只是 MCP 工具在 CLI 形态上的别名，而不是另一套并行系统 资料来源：[src/tools/handoff.ts:1-80]()。

复杂的跨步骤行为（保存 + 摘要 + 测试 + 工件归档 + 调查记录）通过 `src/workflows/engine.ts` 的工作流引擎编排。引擎以"阶段（stage）"为单位持有上下文，每完成一个阶段就把中间产物写到 engine 的内存状态，最终一次性落盘。这种阶段性写法使 Living Document 的"追加"语义得以实现：引擎不必每一步都直接写入后端，而是按阶段聚合后调用 `save_conversation` 的 `mode='append'` 分支 资料来源：[src/workflows/engine.ts:60-180]()。

| 触发面 | 入口 | 落点 |
|---|---|---|
| MCP 工具调用 | `handlers.ts` 派发表 | `api-client.ts` |
| Slash 命令 | `handoff.ts` 别名 | `handlers.ts` 同名 handler |
| 多阶段任务 | `workflows/engine.ts` | 阶段化聚合后调用 MCP 工具 |

## 三、Living Document 与 `save_conversation` 的两种写入模式

ADR-036 明确了 `save_conversation` 的两种模式：默认 `mode='replace'`（一次性快照，覆盖同名记忆的现有正文）与显式 `mode='append'`（在既有正文下方追加带时间戳的分隔块）。这两种模式由 `intelligent-memory.ts` 在生成最终 payload 时分支选择：替换模式直接返回完整正文，追加模式则把当前内容拼到既有内容之后，并在中间插入"更新时间 + 来源阶段"的分隔行 资料来源：[src/intelligent-memory.ts:200-260]()。

工作流引擎是追加模式的主要消费者：跨多个阶段的会话、Handoff、code-review 等场景希望保留"事件流"的可追溯性，因此引擎在聚合阶段产物时显式把 `mode='append'` 一路透传到 save handler。一次性快照（CLI 用户手动 `/purmemo-save` 一段对话）则保留 `replace` 默认值，避免历史正文被无意义地拼接 资料来源：[src/workflows/engine.ts:140-210]()。

## 四、一致性与失败语义

由于写入最终都要经过 `api-client.ts`，所有模式都共享同一份鉴权与重试逻辑：token 失效时由 ADR-039 的"持久化 key + 主机名漂移回退"路径自动恢复，handler 不需要为不同 mode 重复实现错误处理 资料来源：[src/lib/api-client.ts:140-260]()。这意味着 Living Document 的"追加"语义在网络抖动或 OAuth 续期场景下与"替换"具有相同的鲁棒性——追加失败时整体阶段回滚，而不是只回滚最后一段。

资料来源：社区发布说明（v15.7.17 ADR-036、v15.7.21 读工具集、v15.7.18 持久化 key）佐证了上述两条写入分支与读工具的引入背景，与源码中 handler/引擎分支一致。

---

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

## 架构决策（ADR）、打包分发与可观测性

### 相关页面

相关主题：[认证体系与跨平台 Hook 适配](#page-2), [MCP 工具、Slash 命令与 Living Document 语义](#page-3)

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

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

- [ARCHITECTURE.md](https://github.com/purmemo-ai/purmemo-mcp/blob/main/ARCHITECTURE.md)
- [CLAUDE.md](https://github.com/purmemo-ai/purmemo-mcp/blob/main/CLAUDE.md)
- [CONTRIBUTING.md](https://github.com/purmemo-ai/purmemo-mcp/blob/main/CONTRIBUTING.md)
- [docs/ENVIRONMENT_SETUP.md](https://github.com/purmemo-ai/purmemo-mcp/blob/main/docs/ENVIRONMENT_SETUP.md)
- [docs/adr/ADR-009-part-intelligence-propagation.md](https://github.com/purmemo-ai/purmemo-mcp/blob/main/docs/adr/ADR-009-part-intelligence-propagation.md)
- [docs/adr/ADR-011-desktop-macos-distribution.md](https://github.com/purmemo-ai/purmemo-mcp/blob/main/docs/adr/ADR-011-desktop-macos-distribution.md)
- [docs/adr/ADR-036-save-conversation-modes.md](https://github.com/purmemo-ai/purmemo-mcp/blob/main/docs/adr/ADR-036-save-conversation-modes.md)
- [docs/adr/ADR-039-auth-persisted-encryption-key.md](https://github.com/purmemo-ai/purmemo-mcp/blob/main/docs/adr/ADR-039-auth-persisted-encryption-key.md)

</details>

# 架构决策（ADR）、打包分发与可观测性

本页说明 purmemo-mcp 项目在架构治理、CLI/桌面端分发，以及面向开发者与运维的可观测性三方面的设计。

## ADR 体系与治理

项目把每一项重要架构决策以增量编号的方式沉淀在 `docs/adr/`，形成 ADR（Architecture Decision Record）库：

- **ADR-009** 锁定 part intelligence 在子任务间的传播策略。资料来源：[docs/adr/ADR-009-part-intelligence-propagation.md:1-30]().
- **ADR-011** 确定 macOS 桌面端的分发形态。资料来源：[docs/adr/ADR-011-desktop-macos-distribution.md:1-40]().
- **ADR-036** 为 `save_conversation` 引入显式的 `mode` 参数，区分 `replace`（默认，一次性快照）与 `append`（带时间分隔符的活文档）。资料来源：[docs/adr/ADR-036-save-conversation-modes.md:1-25]().
- **ADR-039** 把 OAuth 令牌加密从基于 `os.hostname()` 的派生密钥切换为持久化密钥，解决 macOS 在切换 Wi-Fi、启停 VPN 或休眠唤醒时 `os.hostname()` 漂移导致的静默令牌损坏。资料来源：[docs/adr/ADR-039-auth-persisted-encryption-key.md:1-40]().

`ARCHITECTURE.md`、`CLAUDE.md` 与 `CONTRIBUTING.md` 共同构成新贡献者阅读项目的入口。资料来源：[ARCHITECTURE.md:1-40]()；资料来源：[CLAUDE.md:1-40]()。

## 打包与分发模型

分发采用 **双轨 + 多 hook 接入**：

- **CLI 主入口**：`purmemo init` 一键完成安装与登录；v15.7.20 之后，当持久化/旧密钥都解不出令牌时，CLI 自动拉起浏览器重新登录，并以一行说明替代原先的 `error:1C80006B` 类 OpenSSL 错误（v15.7.19）。
- **桌面端**：macOS 单独走 ADR-011 锁定的形态，不与 CLI 走同一分发通道。
- **多端钩子**：Claude Code、OpenAI Codex、Gemini CLI 都是一等 hook 面。Codex 需调用 `enableCodexHooksFeatureFlag()` 把 `codex_hooks = true` 写入 `config.toml` 的 `[features]`，否则 `hooks.json` 会被静默忽略（v15.7.15/16 修复）。

SessionStart 钩子在所有端统一输出一行头部：`pūrmemo v15.7.x · email · tier · memories · cycle usage`。构建/环境变量细节见 `docs/ENVIRONMENT_SETUP.md`。资料来源：[docs/ENVIRONMENT_SETUP.md:1-50]()。

## 可观测性

可观测性分三层，**写多读少**的局面在 v15.7.21 之后被弥补：

| 层面 | 实现 | 关键里程碑 |
|---|---|---|
| **写入遥测** | test/artifact/investigation 记录 | 长期有 write-only gap |
| **读取遥测** | `get_test_results` / `get_artifacts` / `get_investigations` | v15.7.21 新增 |
| **会话钩子** | JSONL 解析 + 消息计数 | v15.7.24 修 JSONL sniffing bug |

v15.7.22 修复 `get_test_results` 把 `failure_details` 截断到 200 字符的问题；v15.7.23 同样修复 `get_investigations` 把 `root_cause_analysis` 截断到 200 字符的问题——两者均改为回显完整正文并按折行缩进。SessionStart 钩子也修正了"whole-file JSON parse"吞掉 JSONL fallback 的缺陷，工具结果轮次不再被误算为用户消息（v15.7.24）。资料来源：[CONTRIBUTING.md:1-40]()。

## 贡献者路径

```mermaid
flowchart LR
    A[贡献者] --> B[阅读 ARCHITECTURE / CLAUDE]
    B --> C{触及契约/密钥/分发?}
    C -- 是 --> D[新增 ADR-0xx]
    C -- 否 --> E[直接 PR]
    D --> E
    E --> F[CI & 发布 v15.7.x]
    F --> G[CLI / 桌面 / Hooks 分发]
    G --> H[SessionStart 遥测 + 读工具]
```

当变更触及数据契约、密钥管理、分发面或对外 API 语义（如同 ADR-036 的 `mode` 参数、ADR-039 的密钥策略），应在 `docs/adr/` 追加新编号条目并在 PR 中引用；否则按 `CONTRIBUTING.md` 流程直接提交。CI 通过后由维护者整理到 v15.7.x 系列发布说明。资料来源：[CONTRIBUTING.md:1-40]()。

---

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

---

## Doramagic 踩坑日志

项目：purmemo-ai/purmemo-mcp

摘要：发现 17 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: v15.7.15 — Codex hook parity。

## 1. 安装坑 · 失败模式：installation: v15.7.15 — Codex hook parity

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v15.7.15 — Codex hook parity
- 对用户的影响：Upgrade or migration may change expected behavior: v15.7.15 — Codex hook parity
- 证据：failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.15 | v15.7.15 — Codex hook parity

## 2. 安装坑 · 失败模式：installation: v15.7.16 — enable Codex hooks feature flag

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v15.7.16 — enable Codex hooks feature flag
- 对用户的影响：Upgrade or migration may change expected behavior: v15.7.16 — enable Codex hooks feature flag
- 证据：failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.16 | v15.7.16 — enable Codex hooks feature flag

## 3. 安装坑 · 失败模式：installation: v15.7.19 — Auto-recover from unrecoverable token decrypt

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v15.7.19 — Auto-recover from unrecoverable token decrypt
- 对用户的影响：Upgrade or migration may change expected behavior: v15.7.19 — Auto-recover from unrecoverable token decrypt
- 证据：failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.19 | v15.7.19 — Auto-recover from unrecoverable token decrypt

## 4. 安装坑 · 失败模式：installation: v15.7.20 — Zero-friction install + auto-recover from sign-in drift

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v15.7.20 — Zero-friction install + auto-recover from sign-in drift
- 对用户的影响：Upgrade or migration may change expected behavior: v15.7.20 — Zero-friction install + auto-recover from sign-in drift
- 证据：failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.20 | v15.7.20 — Zero-friction install + auto-recover from sign-in drift

## 5. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/purmemo-ai/purmemo-mcp | host_targets=mcp_host, claude, cursor, chatgpt, claude_code

## 6. 配置坑 · 失败模式：configuration: v15.7.18 — auth: persisted encryption key

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v15.7.18 — auth: persisted encryption key
- 对用户的影响：Upgrade or migration may change expected behavior: v15.7.18 — auth: persisted encryption key
- 证据：failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.18 | v15.7.18 — auth: persisted encryption key

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

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

## 8. 运行坑 · 失败模式：runtime: v15.7.22 — get_test_results no longer truncates failure body

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: v15.7.22 — get_test_results no longer truncates failure body
- 对用户的影响：Upgrade or migration may change expected behavior: v15.7.22 — get_test_results no longer truncates failure body
- 证据：failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.22 | v15.7.22 — get_test_results no longer truncates failure body

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

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

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

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

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

## 12. 运行坑 · 失败模式：performance: v15.7.17 — ADR-036: explicit replace/append semantics for save_conversation

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v15.7.17 — ADR-036: explicit replace/append semantics for save_conversation
- 对用户的影响：Upgrade or migration may change expected behavior: v15.7.17 — ADR-036: explicit replace/append semantics for save_conversation
- 证据：failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.17 | v15.7.17 — ADR-036: explicit replace/append semantics for save_conversation

## 13. 运行坑 · 失败模式：performance: v15.7.24

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

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

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

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

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

## 16. 维护坑 · 失败模式：maintenance: v15.7.21 — close write-only telemetry gap

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v15.7.21 — close write-only telemetry gap
- 对用户的影响：Upgrade or migration may change expected behavior: v15.7.21 — close write-only telemetry gap
- 证据：failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.21 | v15.7.21 — close write-only telemetry gap

## 17. 维护坑 · 失败模式：maintenance: v15.7.23 — get_investigations no longer truncates root cause

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v15.7.23 — get_investigations no longer truncates root cause
- 对用户的影响：Upgrade or migration may change expected behavior: v15.7.23 — get_investigations no longer truncates root cause
- 证据：failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.23 | v15.7.23 — get_investigations no longer truncates root cause

<!-- canonical_name: purmemo-ai/purmemo-mcp; human_manual_source: deepwiki_human_wiki -->