本文面向：已经在使用 Claude Code 的开发者，希望 AI 在每次新对话中自动获取历史上下文。
预计阅读时间：10 分钟
最终效果：Claude Code 新开对话时自动检索知识库，任务结束后自动沉淀有价值的经验。

---

痛点：每次新对话都从零开始

你用 Claude Code 已经修过三次同一个 CORS 报错。每次新开对话，它都不记得之前怎么解决的，你得重新描述问题、重新贴日志、重新等它排查。

这是所有 AI 编程工具的共同缺陷：对话之间没有记忆。上一轮的经验不会自动带入下一轮。你只好自己当人肉搜索引擎，在历史对话里翻来翻去。

ChatCrystal 通过 MCP（Model Context Protocol）解决了这个问题。配置一次，Claude Code 就能在新对话开始时自动查询你的知识库，在对话结束时把值得保留的经验写回去。

方案原理

MCP 是 Anthropic 定义的模型上下文协议，允许 AI 助手通过标准接口调用外部工具。ChatCrystal 实现了一个 MCP Server，暴露了 7 个工具：

工具	用途
search_knowledge	语义搜索知识库
recall_for_task	根据任务上下文自动回忆相关经验
write_task_memory	任务结束后写回经验
validate_task_memory	预检写回内容（不产生副作用）
get_note	查看笔记详情
list_notes / get_relations	浏览笔记和关联关系

其中 recall_for_task 和 write_task_memory 是核心——它们构成了"回忆-积累"闭环。

第一步：配置 MCP

编辑 Claude Code 的设置文件。如果你使用项目级配置，文件路径是：

~/.claude/settings.json

添加 mcpServers 字段：

{
  "mcpServers": {
    "chatcrystal": {
      "command": "crystal",
      "args": ["mcp"]
    }
  }
}

确保 ChatCrystal 服务正在运行，且 crystal 命令在 PATH 中可用：

crystal status

看到服务状态和数据库统计信息就说明配置正确。如果提示找不到命令，先 npm install -g chatcrystal 重新安装。

第二步：recall_for_task —— 开始任务时自动回忆

recall_for_task 是 ChatCrystal 专门为"新对话回忆历史"设计的工具。Claude Code 在接受一个新任务时，会调用它来检索相关的历史经验。

它的工作流程是：

1. 接收任务上下文（目标、类型、错误签名等）
2. 语义搜索知识库，找到相关的笔记
3. 优先返回当前项目的经验，再补充全局通用经验
4. 每条经验包含标题、摘要、坑点、可复用模式和关联笔记

你在 Claude Code 对话中不需要手动调用它。当你描述一个问题或任务时，Claude Code 会自动判断是否需要查询知识库。例如：

你：帮我修复 Next.js 项目里的 CORS 跨域报错

Claude Code 内部会调用 recall_for_task，传入类似这样的参数：

{
  "mode": "task",
  "task": {
    "goal": "修复 Next.js 项目的 CORS 跨域报错",
    "task_kind": "debug",
    "project_dir": "/home/user/my-next-app",
    "error_signatures": ["CORS policy blocked", "Access-Control-Allow-Origin"]
  }
}

其中 mode 有两种取值：

• task（默认）：常规任务回忆，返回项目优先 + 全局补充的记忆
• debug：调试模式，会更关注错误签名和历史修复方案

ChatCrystal 会返回该项目中之前处理 CORS 问题的经验，以及全局通用的跨域配置模式。Claude Code 拿到这些上下文后，就能直接参考历史方案，而不是从零开始排查。

第三步：write_task_memory —— 任务结束后写回知识

对话结束后，如果 Claude Code 发现这次任务产生了有价值的经验，会自动调用 write_task_memory 将其写入知识库。

写回时需要提供结构化的经验内容：

{
  "mode": "auto",
  "source_run_key": "session-2024-03-15-001",
  "task": {
    "goal": "修复 Next.js CORS 跨域报错",
    "task_kind": "debug",
    "project_key": "my-next-app",
    "error_signatures": ["CORS policy blocked"]
  },
  "memory": {
    "title": "Next.js App Router CORS 头在 middleware 中设置",
    "summary": "Next.js App Router 中 API Route 的 CORS 头需要在 middleware 里设置，而不是在 route handler 里",
    "outcome_type": "fix",
    "root_cause": "Next.js App Router 的 route handler 返回的 Response 对象会忽略手动设置的 CORS 头",
    "resolution": "在 middleware.ts 中统一处理 OPTIONS 预检请求和 CORS 头注入",
    "reusable_patterns": [
      "App Router 的 CORS 应在 middleware 层处理",
      "OPTIONS 请求必须返回 204 而非 200"
    ],
    "code_snippets": [{
      "language": "typescript",
      "code": "export function middleware(request: NextRequest) {\n  const response = NextResponse.next();\n  response.headers.set('Access-Control-Allow-Origin', '*');\n  return response;\n}",
      "description": "middleware 统一注入 CORS 头"
    }],
    "tags": ["nextjs", "cors", "app-router"]
  }
}

几个关键字段说明：

• source_run_key：当前会话的唯一标识，用于去重——防止同一次会话被重复写入。mode=auto 时必填。
• mode：auto 表示 AI 自动判断是否写回，manual 表示用户明确要求写回。manual 模式下还可以通过 scope: "global" 将经验写入全局知识库（跨项目共享）。
• root_cause / resolution / reusable_patterns：这些可选字段让经验更有复用价值，尽量填写。

第四步：质量门控 —— 什么知识值得写回

ChatCrystal 对写回内容有严格的质量要求。不是所有对话都值得沉淀为知识。

会通过门控的内容：

• 有具体标题和实质性摘要（内部质量门控会按中英文分别评估摘要长度和信息密度）
• 包含可复用的经验核心：坑点（pitfall）、修复方案（fix）、决策（decision）、模式（pattern）
• 有明确的根因分析或解决方案

会被拒绝的内容：

• 一次性环境检查（“Node 版本是 20.11.0”）
• 版本号或状态报告（“依赖安装成功”）
• 普通进度日志（“已完成第一步”）
• 模糊的泛化描述（“代码需要更健壮”）

门控系统从五个维度评分：问题清晰度、过程深度、决策价值、结果闭合度、复用潜力。综合分数达到阈值才会写入。这意味着你的知识库里只会积累真正有用的经验，不会被噪音淹没。

如果内容不够格，可以先调用 validate_task_memory 预检——它接受与 write_task_memory 完全相同的参数，但不产生任何副作用。返回是否接受、原因和警告信息，告诉你缺少哪些信号，避免产生无效写入。

实际使用场景

场景一：自动引用历史方案

你在一个 React Native 项目中遇到了 Hermes 引擎的性能问题。新开对话后，Claude Code 自动回忆到你三个月前在另一个 RN 项目中处理过类似问题，直接引用当时的 profiling 结果和优化方案，省去了重新调研的时间。

场景二：避免重复踩坑

你正准备升级某个依赖。Claude Code 回忆到你上次升级时踩过的坑——某个 peer dependency 版本冲突导致构建失败——提前给你预警，并附上当时的解决方案。

场景三：跨项目经验复用

你在项目 A 中总结了一套 API 错误处理模式，写回了知识库。之后在项目 B 中做类似功能时，Claude Code 通过全局记忆检索到了这套模式，即使两个项目完全不同。

与纯 CLI 搜索的区别

你可能会问：直接用 crystal search 命令不是也能搜索吗？区别在于：

	CLI 手动搜索	MCP 自动回忆
触发方式	你自己决定搜什么、什么时候搜	Claude Code 根据上下文自动判断
查询构造	你手动输入关键词	基于任务目标和错误签名自动构建
结果筛选	返回原始搜索结果	按项目优先级自动分层，附带关联笔记
写回	需要手动操作	对话结束后自动沉淀有价值的经验

CLI 搜索适合你明确知道要找什么的场景。MCP 自动回忆适合"我不确定之前有没有处理过类似问题"的场景——让 AI 来帮你回忆。

常见问题

MCP 配置后 Claude Code 没有调用知识库？

Claude Code 会根据对话内容自行判断是否需要查询。如果任务很简单或与历史经验无关，它可能不会调用。你可以在对话中主动提示："查一下之前有没有类似的问题"来触发检索。

写回的知识太多怎么办？

质量门控会自动过滤低价值内容。如果你发现某些不想要的笔记被写入了，可以通过 Web UI（crystal notes list）查看并删除。

多个项目的记忆会混淆吗？

不会。recall_for_task 会根据 project_dir 或 project_key 自动区分项目。当前项目的记忆优先返回，其他项目的记忆只作为补充。

下一步

• 如果你还没有搭建 ChatCrystal，先看 零基础搭建指南
• 配置 LLM 和 Embedding 模型：云端 LLM 配置 和 Embedding 选型
• 了解 CLI 搜索能力：用知识库找回 3 天前的调试方案
• 想深入了解质量门控机制，运行 crystal notes list 查看你知识库中已有的笔记，观察什么样的内容被保留了下来

---

项目地址：github.com/ZengLiangYi/ChatCrystal