渐进式披露策略
渐进式披露策略：Claude-Mem 的具体实现
学习目标
本章聚焦 Claude-Mem 如何通过 MCP Tools 实现三层渐进式披露。建议先阅读前置知识，下文直接聚焦具体落地方案。
前置知识
本章涉及渐进式披露的通用原理，建议先阅读：
- 渐进式披露策略 — 三层工作流模式与 token 经济学
项目实践
MCP 工具定义
Claude-Mem 在 src/servers/mcp-server.ts 中定义了完整的 MCP 工具列表。核心三层工具：
__IMPORTANT — 工具使用指南（伪工具，仅返回指令）search — 第 1 层：搜索索引timeline — 第 2 层：时间线上下文get_observations — 第 3 层：完整详情__IMPORTANT 是一个特殊的伪工具，它不执行任何操作，仅返回三层工作流的使用说明。当 Agent 列出可用工具时，这条指令会出现在首位，引导 Agent 正确使用三层模式。
工具到 Worker API 的映射
MCP 工具通过 HTTP 调用转发到 Worker Service：
| MCP 工具 | Worker API 端点 | 方法 |
|---|---|---|
search | /api/search | GET |
timeline | /api/timeline | GET |
get_observations | /api/observations/batch | POST |
smart_search | tree-sitter AST 搜索 | 本地执行 |
这种映射表模式（TOOL_ENDPOINT_MAP）使得新增工具只需添加一行配置，无需重复编写 HTTP 调用逻辑。
Worker 端搜索管线
Worker Service 中的 SearchManager（src/services/worker/SearchManager.ts，约 60KB）实现了完整的搜索逻辑：
- FTS5 全文搜索：利用 SQLite 的 FTS5 扩展进行快速关键词匹配
- 结果分页：
PaginationHelper支持offset和limit参数 - 多格式格式化：
ResultFormatter支持表格、列表等不同输出格式 - 过滤器链：按项目、类型、日期范围等多维度过滤
智能文件搜索
除记忆搜索外，MCP 还提供了基于 tree-sitter 的代码搜索工具：
| 工具 | 功能 |
|---|---|
smart_search | 使用 tree-sitter AST 解析搜索符号、函数、类 |
smart_outline | 获取文件的结构大纲（符号列表，代码体折叠） |
smart_unfold | 展开特定符号的完整源代码 |
这些工具支持 15+ 种编程语言（通过 tree-sitter 语法树），在检索代码时比简单文本搜索更高效。
上下文注入的渐进式结构
ContextBuilder 生成的上下文输出本身就是渐进式披露的第一层：
<claude-mem-context># Project: my-project# Memory: 42 observations across 8 sessions# Token economics: 12,340 total, 294 avg per observation
## Timeline[2026-05-27] #42 修复认证中间件 session 泄漏 [bugfix][2026-05-27] #41 重构 JWT token 刷新逻辑 [refactor][2026-05-26] #40 添加用户角色权限模块 [feature]...
## Latest Summary- Request: 修复用户报告的认证 bug- Learned: 异步回调中的清理逻辑必须在 finally 块中执行...</claude-mem-context>这个轻量上下文（约 500-2000 token）提供了项目概况，Agent 可以通过 MCP 工具按需展开感兴趣的条目。
问题与规避
Worker 连接失败
问题：MCP Server 启动时 Worker 可能未就绪，导致搜索工具调用失败。
规避：ensureWorkerConnection() 先 health check，失败则尝试 auto-start。在 server-beta 运行时模式下，跳过 worker auto-start，因为 observation_* 工具直接调用远程 REST API。
父进程死亡孤儿进程
问题：Claude Code 退出后，MCP 子进程可能成为孤儿进程持续占用端口。
规避：startParentHeartbeat() 每 30 秒检查 process.ppid，若父进程 PID 变为 1（init）或变化，则主动退出。这是 Unix 守护进程的标准孤儿检测模式。
设计取舍
为什么使用 GET 参数而非 POST Body？
search 和 timeline 工具使用 URL query parameters 传递参数，而非 POST request body：
- 优势：简单、可缓存、符合 RESTful 查询语义
- 代价：URL 长度限制（通常 2KB），复杂查询可能超长
- 权衡：记忆搜索的查询通常较短，URL 限制不构成问题。批量操作（
get_observations）使用 POST，因为 IDs 数组可能很长。
为什么保留 memory_* 兼容别名？
MCP Server 同时提供 observation_* 和 memory_* 两套工具名：
observation_add/memory_addobservation_search/memory_searchobservation_context/memory_context
原因：向后兼容。早期版本的 Claude-Mem 使用 memory_* 命名，保留别名确保旧版 MCP 客户端无需修改即可工作。新版客户端应使用 observation_* 命名。