目录 展开 收起
MCP 能让 Claude Code 访问 ChatCrystal，但“能调用工具”不等于每个新对话都会自动回忆，也不等于写回内容已经被当前项目验证。可靠的工作流应把回忆、事实核对、质量预检和写回拆开，并留下来源。
本文接续 ChatCrystal MCP 配置 的连接步骤，依据固定提交 7642768 的 memory schema 与 回忆服务。
在任务开始时明确回忆输入
recall_for_task 接收目标、任务类型、项目标识、目录、分支、涉及文件和错误特征。mode 可用 task 或 debug；默认项目记忆上限为 5，全局补充上限为 3。include_relations 默认开启，控制语义结果的一跳关系扩展；关闭后仍会返回命中笔记的 related_note_ids。项目身份缺失时，服务会警告并只返回全局匹配；语义检索不可用时也会返回警告，而不是编造答案。
服务先在全库做有数量上限的语义检索，再按项目身份和 global 作用域筛选，并不是先限定项目再搜索；项目记忆可能因此未进入候选。遇到空结果要同时检查警告和原文，不能认定库中没有历史。
以下超时问题是构造示例；实际输入应来自当前任务：
{
"mode": "debug",
"task": {
"goal": "定位 API 请求偶发超时的原因",
"task_kind": "debug",
"project_key": "example-service",
"files_touched": ["src/server.ts"],
"error_signatures": ["ETIMEDOUT", "upstream reset"]
},
"options": { "project_limit": 5, "global_limit": 3, "include_relations": true }
}把返回的标题、摘要和关联笔记 ID 当作候选证据。回忆响应不包含独立的 error_signatures 字段；先打开笔记详情，再用输入中的错误特征核对原始会话、依赖版本和当前代码。回忆结果不是自动批准的修复方案。
在写回前做无副作用预检
validate_task_memory 与写回使用同一套请求形状，但只返回是否接受、原因、警告和物化后的笔记字段。可复用的内容通常需要具体标题、实质摘要、根因或解决方案，以及 pitfall、fix、pattern 或 decision 等结果类型。自动模式会跳过一次性环境状态、版本报告、进度日志和“代码更健壮”这类空泛结论；手动模式仍检查结构，但标题、摘要和结论可读时可能带质量警告接受。具体例外见 质量判定实现。
完成任务 → 组织根因、改动和验证证据
→ validate_task_memory
→ 通过后再 write_task_memory预检通过仍不表示事实正确；它只说明内容具备写入质量。把测试命令、影响范围和未验证条件写进摘要或结论，方便下一次回忆时重新判断。
控制写回作用域和去重
write_task_memory 的 mode 是 auto 或 manual。自动写回必须提供 source_run_key，用于同一来源运行的幂等收据；自动模式不能指定全局作用域。手动模式可明确选择 project 或 global，全局经验应确实跨项目复用。
下面的自动写回候选继续使用同一构造场景，不代表已发生的故障或实测修复。它演示质量拒绝路径：在固定提交的无副作用预检中，返回 accepted: false、reason: "low-note-quality" 和 durable_reusable_lesson 警告，因此不要把它直接交给 write_task_memory。补充真实可复用证据后重新预检；不要为了通过检查编造修复结果或改成手动模式绕过警告。实际调用时将 source_run_key 替换为当前逻辑运行的唯一标识；同一次失败重试保留原值，不同任务使用不同值。收据按 source_agent 与这个标识共同去重。
{
"mode": "auto",
"source_run_key": "run-2026-10-03-timeout",
"task": {
"goal": "定位 API 超时",
"task_kind": "debug",
"project_key": "example-service",
"source_agent": "claude"
},
"memory": {
"title": "异常路径泄漏连接导致代理超时",
"summary": "构造场景中，src/server.ts 的异常路径遗漏连接归还，连接池耗尽后出现 ETIMEDOUT。将数据库调用包在 try/finally 中，防止异常跳过连接释放；用正常返回和抛错两条路径检查连接归还。这里只验证记忆预检，不代表真实服务修复。",
"outcome_type": "fix",
"root_cause": "src/server.ts 在抛错后跳过连接归还，后续请求等待耗尽的连接池",
"resolution": "用 try/finally 包住数据库调用，防止异常跳过连接释放，并分别测试正常返回和抛错路径",
"error_signatures": ["ETIMEDOUT"],
"key_conclusions": [
"用 try/finally 包住数据库调用，防止异常跳过连接释放；先验证连接归还，再调整超时数值"
]
}
}服务会创建或合并 memory note，保存笔记和自动模式收据，再同步等待向量生成；它不是只提交一个后台索引任务。向量调用失败时，笔记可能已经落盘，自动收据的索引状态仍为 pending；同一 source_agent 和 source_run_key 重试会继续索引已有目标。正常返回不包含单独的 index 状态字段，应按返回的 note_id 或 merged_into_note_id 读取笔记详情并验收检索结果。具体顺序见 写回实现。
把自动化变成可审计步骤
在项目规则里明确四件事：开始任务先调用回忆并展示来源；应用历史方案前核对当前条件；结束任务只提交有复用价值的结论；工具失败时报告警告而不是假装没有历史。对无答案查询、错误匹配和拒绝写回都保留记录。
这样得到的是可复查的记忆流程，而不是“每次对话必然记住”。关系扩展和检索分数的边界见 语义搜索加关系上下文，MCP 连接层见 MCP 配置文章。