知识代理
知识代理让你将 claude-mem 观察历史的一部分汇编成一个可查询的“脑”，能够以对话方式回答问题。你得到的不是原始的搜索结果，而是从你实际的项目历史中提炼、基于事实的答案——包括决策、发现、错误修复和功能内容。
快速开始
使用知识代理的三种方式，从最简单到最强大。
1. 创建知识代理
使用 /knowledge-agent 技能或直接使用 MCP 工具：
build_corpus name="hooks-expertise" query="hooks architecture" project="claude-mem" limit=200这会搜索你的观察记录，收集匹配的记录，并将它们保存为语料文件。然后进行预处理——这会将语料加载到Claude会话的上下文窗口中：
prime_corpus name="hooks-expertise"您的知识代理已准备好。返回的 session_id 就是代理——一个已包含您历史记录的 Claude 会话。
2. 提出一个问题
一旦准备好，提出任何问题并获得有根据的答案：
query_corpus name="hooks-expertise" question="What are the 5 lifecycle hooks and when does each fire?"该代理基于其语料库进行回答——回应来源于您实际的项目历史，从而减少虚构和猜测。每个后续问题都建立在之前的对话基础上：
query_corpus name="hooks-expertise" question="Which hook handles context injection?"3. 开始新的对话
如果对话偏离了，或者你想针对相同语料提出一个无关的问题，请重新开始以清理状态：
reprime_corpus name="hooks-expertise"这会创建一个新会话，并重新加载完整语料库——就像用相同的“脑”开启一个全新的聊天。之前的问答上下文会被清除，但语料库知识仍然保留。在以下情况下使用：
- 谈话偏离了主题，你想重新开始
- 你正在同一语料库中切换话题
- 你想提出一个问题，而不让已有的答案影响回应
保持最新
当向您的项目中添加新观察时，请重建语料库以获取最新内容，然后重新初始化：
rebuild_corpus name="hooks-expertise"
reprime_corpus name="hooks-expertise"重建会重新运行原来的搜索过滤器。重新准备会将刷新后的数据加载到一个新会话中。
工作流程：构建、准备、查询
BUILD ──> PRIME ──> QUERY1. 建立语料库
语料库是一个经过筛选的观察集合，以 JSON 文件保存。使用搜索筛选器来选择你想要的历史片段。
curl -X POST http://localhost:37777/api/corpus \
-H "Content-Type: application/json" \
-d '{
"name": "hooks-expertise",
"query": "hooks architecture",
"project": "claude-mem",
"types": ["decision", "discovery"],
"limit": 200
}'在底层，CorpusBuilder 会搜索你的观察数据，填充完整记录，解析结构化字段（事实、概念、文件），计算统计数据，并将所有内容写入 ~/.claude-mem/corpora/hooks-expertise.corpus.json。
2. 初始化知识代理
prime将整个语料库加载到Claude会话的上下文窗口中。
curl -X POST http://localhost:37777/api/corpus/hooks-expertise/prime该代理将所有观察结果转化为全文本细节，并将其输入 Claude Agent SDK。Claude 阅读语料并确认主题。返回的 session_id 是 知识代理——一个包含您历史记录的 Claude 会话。
3. 查询
恢复已准备的会话并提问。
curl -X POST http://localhost:37777/api/corpus/hooks-expertise/query \
-H "Content-Type: application/json" \
-d '{ "question": "What are the 5 lifecycle hooks?" }'每个后续问题都会自然地增加对话内容。如果会话过期，代理会从语料库文件自动重新准备并重试。
筛选选项
在构建语料库时使用这些参数来控制包含哪些观察数据：
| 参数 | 类型 | 描述 |
|---|---|---|
name | 字符串 | 语料库名称（用于所有后续的 API 调用） |
project | 字符串 | 按项目名称过滤 |
types | string[] | 按观察类型过滤（bug修复、功能、决策、发现、重构、变更） |
concepts | 字符串数组 | 按标记概念过滤 |
files | string[] | 按读取或修改的文件进行筛选 |
query | 字符串 | 全文搜索查询 |
dateStart | 字符串 | 开始日期过滤器 (YYYY-MM-DD) |
dateEnd | 字符串 | 结束日期过滤器（YYYY-MM-DD） |
limit | 数字 | 要包含的最大观察值 |
架构
MCP Tools HTTP API
(mcp-server.ts) (worker on :37777)
| |
build_corpus ──┤ |
list_corpora ──┤ |
prime_corpus ──┤── callWorkerAPIPost() ──>|
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，并在将来的每个问题中恢复它。语料库会永久保留在上下文中，无需重新上传，也无需提示缓存技巧。1M token 的上下文窗口使这成为可能：大约 300 token 的 2,000 条观察数据可以轻松容纳。
何时使用 /knowledge-agent 与 /mem-search
/mem-search | /knowledge-agent | |
|---|---|---|
| 返回值 | 原始观察记录 | 综合对话答案 |
| 最适合 | 查找具体的观察、ID、时间线 | 询问有关模式、决策、架构的问题 |
| token模型 | 按查询付费（3层逐步披露） | 黄金时段一次性付费，随后跟进费用低 |
| 互动 | 搜索、筛选、获取 | 用自然语言提问 |
| 数据时效性 | 始终最新（实时查询数据库） | 构建时快照（重建以刷新） |
| 设置 | 无 -- 可立即使用 | 构建 prime 在第一次查询前必需 |
**经验法则：**当你需要找到某个具体的东西时，使用 /mem-search。当你想广泛了解某件事时，使用 /knowledge-agent。
API参考
| 方法 | 路径 | 描述 |
|---|---|---|
| POST | /api/corpus | 从过滤器构建新的语料库 |
| GET | /api/corpus | 列出所有语料库及其统计信息 |
| 获取 | /api/corpus/:name | 获取语料库元数据 |
| 删除 | /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失败，代理会自动从语料库文件重新初始化并重试 - SDK 进程退出：如果 Claude 进程在生成所有消息后退出，当会话 ID 或答案已被捕获时，代理将其视为成功
- 空语料库：一个包含0个观测值的语料库是有效的（只是空的）
- 来自设置的模型：从用户设置中读取
CLAUDE_MEM_MODEL——没有硬编码的模型ID
下一步
- Memory Search - 用于查找特定观察的三层搜索工作流程
- Progressive Disclosure - token 高效检索背后的哲学
- Architecture Overview - 系统组件