项目定位与核心能力

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）以及隐式恢复流程。下表概括了从"零摩擦安装"目标出发的状态迁移：

资料来源：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。

概述与设计目标

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 子系统针对三套客户端分别实现安装与回放路径，下表给出事件面与配置差异：

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 类回放轮次。

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

一、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。

三、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/引擎分支一致。

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 之后被弥补：

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。

贡献者路径

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。

Pitfall Log / 踩坑日志

项目：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