知识代理¶
知识代理允许你将 claude-mem 观察历史中的一段切片编译成一个可查询的“大脑”，以对话方式回答问题。你得到的不是原始搜索结果，而是从真实项目历史（决策、发现、缺陷修复和功能）中提炼出的、有依据的综合答案。
快速开始¶
三种使用知识代理的方式，从最简单到最强大。
1. 创建知识代理¶
使用 /knowledge-agent 技能或直接使用 MCP 工具：
这会搜索你的观察历史，收集匹配的记录，并将其保存为语料库文件。然后预热它——将语料库加载到 Claude 会话的上下文窗口中：
你的知识代理已就绪。返回的 session_id 就是代理——一个内置了你的历史记录的 Claude 会话。
2. 提出单个问题¶
预热之后，提出任何问题都能得到有依据的答案：
query_corpus name="hooks-expertise" question="What are the 5 lifecycle hooks and when does each fire?"
代理会基于其语料库作答——回答源自你的真实项目历史，减少幻觉和臆测。每个后续问题都会延续之前的对话：
3. 开启全新对话¶
如果对话跑偏，或者你想针对同一语料库提出不相关的问题，重新预热以全新开始：
这会创建一个新会话，重新加载完整语料库——就像与同一个“大脑”开启一段全新聊天。所有之前的问答上下文都会被清空，但语料库知识仍然保留。在以下情况下使用此操作：
- 对话偏离正轨，你想要一个干净的状态
- 你要在同一语料库内切换主题
- 你想提问时避免之前的答案影响后续响应
保持最新¶
当项目新增观察记录时，重建语料库以纳入最新内容，然后重新预热：
重建会重新执行原始搜索筛选条件。重新预热会将刷新后的数据加载到一个新会话中。
工作流：构建、预热、查询¶
1. 构建语料库¶
语料库是经过筛选的观察记录集合，保存为 JSON 文件。使用搜索筛选条件精确选择你想要的历史片段。
WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
curl -X POST http://127.0.0.1:$WORKER_PORT/api/corpus \
-H "Content-Type: application/json" \
-d '{
"name": "hooks-expertise",
"query": "hooks architecture",
"project": "claude-mem",
"types": ["decision", "discovery"],
"limit": 200
}'
在底层，CorpusBuilder 会搜索你的观察记录，补全完整记录，解析结构化字段（facts、concepts、files），计算统计信息，并将所有内容写入 ~/.claude-mem/corpora/hooks-expertise.corpus.json。
2. 预热知识代理¶
预热会将整个语料库加载到 Claude 会话的上下文窗口中。
代理会将所有观察记录渲染成完整详细的文本，并送入 Claude Agent SDK。Claude 会读取语料库并确认其中的主题。返回的 session_id 就是知识代理——一个内置了你的历史记录的 Claude 会话。
3. 查询¶
恢复已预热的会话并提出问题。
curl -X POST http://127.0.0.1:$WORKER_PORT/api/corpus/hooks-expertise/query \
-H "Content-Type: application/json" \
-d '{ "question": "What are the 5 lifecycle hooks?" }'
每个后续问题都会自然地延续这段对话。如果会话过期，代理会自动从语料库文件重新预热并重试。
筛选选项¶
构建语料库时，可使用以下参数控制包含哪些观察记录：
| 参数 | 类型 | 说明 |
|---|---|---|
name |
string | 语料库名称（用于之后所有 API 调用） |
project |
string | 按项目名称筛选 |
types |
string[] | 按观察记录类型筛选（bugfix, feature, decision, discovery, refactor, change） |
concepts |
string[] | 按已标记的概念筛选 |
files |
string[] | 按读取或修改的文件筛选 |
query |
string | 全文搜索查询 |
dateStart |
string | 开始日期筛选（YYYY-MM-DD） |
dateEnd |
string | 结束日期筛选（YYYY-MM-DD） |
limit |
number | 要包含的最大观察记录数 |
架构¶
MCP Tools HTTP API
(mcp-server.ts) (worker on :$WORKER_PORT)
| |
build_corpus ──┤ |
list_corpora ──┤ |
prime_corpus ──┤──── callWorker() ───────>|
query_corpus ──┤ |
rebuild_corpus ──┤ |
reprime_corpus ──┘ |
v
CorpusRoutes
(8 endpoints)
/ | \
CorpusBuilder | KnowledgeAgent
| | |
SearchOrchestrator | Agent SDK V1
SessionStore | query() + resume
|
CorpusStore
(~/.claude-mem/corpora/)
关键要点： Agent SDK 的 resume 选项允许你只预热一次会话（上传语料库），保存 session_id，然后在之后的每个问题中恢复它。语料库会一直留在上下文中——无需重新上传，也无需 Prompt 缓存技巧。1M token 的上下文窗口让这成为可能：2000 条观察记录，每条约 300 tokens，可以轻松容纳。
何时使用 /knowledge-agent 与 /mem-search¶
/mem-search |
/knowledge-agent |
|
|---|---|---|
| 返回内容 | 原始观测记录 | 综合对话式回答 |
| 适用场景 | 查找特定观测、ID、时间线 | 询问关于模式、决策、架构的问题 |
| Token 计费模式 | 按查询付费（3 层渐进式披露） | 预热的 prime 阶段一次性付费，之后跟进查询更便宜 |
| 交互方式 | 搜索、筛选、获取 | 用自然语言提问 |
| 数据新鲜度 | 始终最新（实时查询数据库） | 构建时的快照（重新构建以刷新） |
| 设置 | 无需设置——立即可用 | 首次查询前需要构建 + 预热（prime） |
经验法则： 需要查找特定内容时使用 /mem-search。想从宏观层面理解某个主题时使用 /knowledge-agent。
API 参考¶
| 方法 | 路径 | 描述 |
|---|---|---|
| POST | /api/corpus |
根据过滤器构建新语料库 |
| GET | /api/corpus |
列出所有语料库及其统计信息 |
| GET | /api/corpus/:name |
获取语料库元数据 |
| DELETE | /api/corpus/:name |
删除语料库 |
| POST | /api/corpus/:name/rebuild |
根据存储的过滤器重新构建 |
| POST | /api/corpus/:name/prime |
创建加载了语料库的 AI 会话 |
| POST | /api/corpus/:name/query |
向知识代理提问 |
| POST | /api/corpus/:name/reprime |
开启新会话（清除之前的问答） |
边界情况¶
- 会话过期：如果
resume失败，代理会自动从语料库文件重新预热（reprime）并重试 - SDK 进程退出：如果 Claude 进程在生成所有消息后退出，当 session_id 或答案已被捕获时，代理会将其视为成功
- 空语料库：包含 0 条观测记录的语料库是有效的（只是为空而已）
- 从设置中读取模型：从用户设置中读取
CLAUDE_MEM_MODEL——没有硬编码的模型 ID
后续步骤¶
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/claude-mem