claude-mem Phase 10 功能 Backlog 分诊：save_memory 工具、项目名归一化与 CLAUDE.md 生成开关的落地解析

本文基于 claude-mem 仓库中 2026-03-12 Issues/PRs 分诊 playbooks 的 Phase 10（.maestro/playbooks/2026-03-12-CM-Issues-PRs/2026-03-12-Issues-PRs-Triage/TRIAGE-10-Feature-Backlog.md）撰写，解读这一"功能 Backlog 分诊"阶段的完整决策过程：哪些小特性被直接实现、哪些大特性被"推迟而非拒绝"、以及每项决定如何对应到仓库中的真实代码实现与测试。读完本篇，你可以掌握 claude-mem 处理功能请求的优先级方法论，并能对照 save_observation 工具、项目名解析逻辑 和 设置默认值管理 理解从 Issue 到落地的完整链路。

一、Phase 10 的定位：先修 Bug，再理功能

该 playbook 是 10 个分诊阶段的最后一个，文档开篇明确了三原则：

1. 这些是功能请求而非 Bug——没有一项是紧急的，但其中若干项有强烈的用户诉求；
2. 分诊动作分三类：关闭（out of scope）、打标签（值得做但另立专项）、直接实现（小而高价值的）；
3. 大特性必须拆成独立 playbook 规划，不在本阶段顺手做。

文档列出的处理对象是 7 个 Issue：#1322（手动保存记忆）、#1273（UUID 观察 ID）、#1272（CLAUDE.md 生成开关）、#943（LiteLLM 代理）、#1252（嵌入式模式）、#1284（claude-brain 集成）、#1256（项目识别碎片化）。前置条件是所有 Bug 类阶段（Phase 01–09）完成后才进入本阶段——这是该项目"稳定性优先于功能扩张"的工程纪律的体现，可对照 TRIAGE-01-PR-Review-And-Merge.md 等前序阶段文档查看各阶段的划分方式。

二、小而高价值：手动保存记忆的 MCP 工具（Issue #1322）

2.1 需求与参数设计

playbook 对 #1322 的原始诉求描述是：用户希望在自动观察（observation）捕获之外，显式控制哪些内容被保存。文档给出的实现规格非常具体：

• 在现有 MCP 工具注册处（playbook 当时指向 src/services/worker-service.ts 或 src/services/server/Server.ts，search、get_observations 等工具的定义位置）新增一个工具，接受三个参数：

参数	类型	必填	说明
title	string	是	记忆标题
content	string	是	记忆正文/叙述内容
tags	string[]	否	分类标签

• 处理器行为的四步约定：

  1. 直接通过 ObservationStore 的存储入口创建一条 observation，并打上 tool_name: 'save_memory' 标记；
  2. 使用当前会话的 contentSessionId 与 cwd 作为归属上下文；
  3. 跳过 SDK agent 压缩流水线——用户输入原样落库（title 存为 title，content 存为 narrative），不做 AI 二次改写；
  4. 返回 { saved: true, id: <observation_id> }。

• 文档还特别叮嘱"实现前先搜索已有的手动 observation 模式"，避免重复造轮子。

2.2 仓库中的落地现状

对照当前仓库源码，这条需求已完成实现，而且命名经过了一次规范化：CHANGELOG.md 中两处记录还原了演进过程——早期版本引入"Manual memory storage — New save_memory MCP tool and POST /api/memory/save endpoint for explicit memory capture (PR #662)"，随后 "MCP tool naming: Renamed save_memory to save_observation for consistency with the observation-based data model (#1210)"。也就是说，playbook 中的 save_memory 最终在代码中以 save_observation 之名存在，与 claude-mem 的 observation 数据模型保持一致。

MCP 工具的注册现状可以从 MCP server 入口 看到全貌：search、get_observations、observation_search、smart_search、timeline 等工具集中定义于此，其中 search 的描述中内置了渐进披露（progressive disclosure）的使用范式——先 search(query) 拿到 ID 索引，再 get_observations([IDs]) 批量取详情。playbook 中"跳过压缩流水线、原样落库"的设计意图，正是为了让手动保存的路径与自动捕获路径在数据入口上汇合（都成为一条 observation），但在写入来源上可区分（tool_name 标记），这为后续检索与审计保留了抓手。

该工具的行为契约有专门测试覆盖，可参考 MCP 工具可见性测试 与 MCP 工具 schema 测试：前者校验工具在不同运行时下的可见性，后者校验工具参数 schema 与注册描述的一致性。

三、修复而非新功能：项目识别碎片化（Issue #1256）

3.1 问题本质

#1256 指出：以 basename(cwd) 作为项目名，在 monorepo 中多个同名单元目录（例如多个包目录都叫 common）下会导致数据碎片化——同一仓库不同子目录的 observations 被归到不同"项目"名下，检索时无法聚合。

playbook 给出的分诊动作是典型的"先查已有工作再动手"：先确认 Phase 01 中 PR #1298（git root 检测）是否已评审合并；若已合并，则用"同一 monorepo 不同子目录的 observations 应聚合到同一项目"作为验收标准来验证；若未合并，则明确写出修复方案：用 git rev-parse --show-toplevel 替代 basename(cwd) 做项目识别，并指明了阅读入口（当时的 getCurrentProjectName()）。

3.2 源码级实现印证

当前仓库中，该方案已经落地，且实现比 playbook 描述更完整。src/utils/project-name.ts 中的 findGitRepoRoot() 在任意目录内执行 git rev-parse --show-toplevel，解析出绝对仓库根路径；getProjectName() 的决策链是：

1. cwd 为空 → 返回 unknown-project 兜底；
2. 先 expandHome 展开 ~（用户配置路径在程序化调用时不会被 shell 展开，这一细节在 expand-home.ts 中有专门说明）；
3. 命中 git 仓库 → 以仓库根的 basename 作为项目名，从而在子目录、worktree 间保持稳定（代码注释直接标注了关联 Issue 编号 #2663）；
4. 非 git 目录 → 回退到 cwd basename；
5. Windows 盘符根目录（如 C:\）→ 返回 drive-C 这类形式；根目录等无 basename 场景 → unknown-project。

同一文件中的 getProjectContext() 还处理了 git worktree 场景：通过 detectWorktree()（src/utils/worktree.ts）识别后，生成 parent/子项目 的复合项目名并保留 parent 归属，让 worktree 会话既独立又与主仓库关联。对应的行为测试在 project-name.test.ts 与 project-name-isolation.test.ts 中，项目过滤逻辑 则消费这些名字做数据隔离。

这一节完整体现了 Phase 10 的分诊方法论："小修复"不是立刻写代码，而是先定位已有 PR、以验收测试定义完成标准，再决定复用还是新写。

四、简单开关：CLAUDE.md 生成可关闭（Issue #1272）

4.1 需求与实现约束

#1272 的诉求：允许用户关闭在子目录中自动生成 CLAUDE.md 的行为。playbook 给出的实现路径同样极简：

• 在 SettingsDefaultsManager.ts 中新增一个默认 'true' 的开关（文档建议命名 CLAUDE_MEM_GENERATE_CLAUDE_MD）；
• 在 CLAUDE.md 生成代码中写入前检查该设置，为 'false' 时完全跳过生成；
• 明确的架构约束："这是一个简单 gate——不要重构生成逻辑"。

这条任务的价值在于示范了 claude-mem 对"低风险功能"的标准做法：默认开启保持向后兼容、单点开关、零逻辑重构。

4.2 当前实现中的对应物

在当前 SettingsDefaultsManager.ts 的 SettingsDefaults 接口中，与该能力对应的目录级 CLAUDE.md 相关键已经存在：CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED（是否在子目录生成 CLAUDE.md）与 CLAUDE_MEM_FOLDER_USE_LOCAL_MD。该管理器的工作模式是"新建的 settings.json 会用全量默认值播种，持久化值优先于 DEFAULTS"，所以新增一个默认 'true' 的键即自动满足 playbook 的要求：老用户不受影响，新用户开箱即有该开关可改。文件读写与目录级 CLAUDE.md 的实际生成逻辑分别位于 claude-md-utils.ts 与 agents-md-utils.ts，其行为测试见 claude-md-utils.test.ts。

五、"推迟而非拒绝"：四个大功能的分诊决策

playbook 最有参考价值的一部分，是对四个"值得做但太大"的功能给出统一的关闭话术模板——每个 Issue 附一条解释性评论，并打上 enhancement + deferred 标签（若标签可用）。这四条原样保留如下，因为它们本身就是分诊文档的核心资产：

Issue	功能	推迟理由（原文评论）
#1273	UUID 观察 ID	Valuable for multi-machine sync. Requires schema migration and ID format change across all APIs. Deferring to a dedicated playbook. Current integer IDs remain stable for single-machine use.
#943	LiteLLM 代理支持	Good feature request. Requires adding proxy URL configuration to SDK agent spawn. Deferring — workaround: set ANTHROPIC_API_BASE env var if your proxy supports the Anthropic API format.
#1252	嵌入式/进程内模式	Architecture change to eliminate the external worker. This would be a major refactor of the hook→worker communication layer. Deferring to a dedicated design effort.
#1284	claude-brain 集成	Interesting integration idea. claude-brain and claude-mem solve overlapping problems with different approaches. Deferring — users can use both independently.

从这四条决策可以读出 claude-mem 的取舍标准：涉及 schema 迁移/ID 格式变更（#1273）、涉及 hook→worker 通信层重构（#1252）、涉及 SDK 启动链路配置（#943）的，一律要求独立设计文档；而存在可用环境变量绕过方案的（如 #943 的 ANTHROPIC_API_BASE），在评论中直接给出 workaround，降低用户等待成本。这套"给出理由 + 给出替代路径 + 打上可追踪标签"的做法，值得任何开源项目的 backlog 管理借鉴。

六、收尾交付物与验证门禁

playbook 的最后两项任务定义了本阶段的"完成"标准：

1. 最终综合分诊报告：要求以 YAML front matter（type: report、title: Final Issues & PRs Triage Report、created: 2026-03-12、tags: [triage, final-report, issues, prs]）汇总全部 10 个阶段的 Issue/PR 处理结果、分诊前后 Issue 与 PR 总量对比、未被任何阶段覆盖的 gap 清单，并列出"开放超过 3 个月无活动"的候选陈旧 PR（#474、#854、#996、#1064、#1072、#1078、#1083、#1085、#1088、#1092、#1101、#1102），基于"目标 Issue 是否仍存在"给出关闭/保留建议。仓库中可见该系列的中间产物，如 Phase 01 分诊报告，可对照了解各阶段报告的固定格式。
2. 全量验证门禁：
   • npm test —— 全部测试必须通过；
   • npm run build-and-sync —— 构建并同步产物；
   • 人工确认 worker 启动、viewer UI 可在 http://localhost:37777 加载。

当前仓库中，测试套件已扩展到数百个文件（见 tests/ 目录），package.json 中可查到这些脚本的最新定义；worker 默认端口等运行参数亦可在 SettingsDefaultsManager.ts 的默认值清单（如 CLAUDE_MEM_WORKER_PORT、CLAUDE_MEM_WORKER_HOST）中核对。

七、小结：一份功能 Backlog 分诊文档的方法论价值

Phase 10 文档虽然只有五行任务清单，却浓缩了一整套可复用的分诊纪律：

• 分级处置：小高价值（save_memory、CLAUDE.md 开关）直接实现并给参数级规格；中等的（#1256）先查已有 PR 再以验收测试定完成标准；大的（四个 deferred）统一"推迟+理由+workaround+标签"。
• 规格即契约：每项待实现功能都写明了参数表、处理步骤、返回结构与明确禁令（"不要重构生成逻辑"），执行者无需再猜测意图。
• 验证闭环：以 npm test + npm run build-and-sync + 手动 UI 检查作为阶段出口，并以最终报告固化 gap 与陈旧 PR 清单，避免分诊只改状态不留痕迹。

对照当前仓库可以看到，文档中的三项实现任务都已在后续版本中落地且部分演进（如 save_memory 更名 save_observation、项目名解析引入 git 根检测与 worktree 复合键），这正是"playbook 先行、源码印证、测试背书"这一工程范式在 claude-mem 仓库中的完整实例。