使用MCP工具进行内存搜索

Claude-mem 通过 4 个 MCP 工具 提供跨会话的持久记忆，这些工具遵循一个高 token 效率的 3 层工作流程模式。

概览

claude-mem 不会一次性获取所有历史数据（代价高），而是使用逐步披露的方法：

搜索 → 获取带有 ID 的紧凑索引（每个结果约 50-100 个标记）
时间轴 → 获取有关有趣结果的背景信息
获取观测 → 仅获取筛选后的ID的完整详情

与传统的 RAG 方法相比，这实现了约 10 倍的 token 节省。

三层工作流程

第1层：搜索（索引）

首先通过搜索来获取一个轻量级的结果索引：

search(query="authentication bug", type="bugfix", limit=10)

返回： 包含ID、标题、日期、类型的紧凑表格 成本: 每个结果约50-100 个 token 目的: 在获取详细信息之前调查现有的情况

第2层：时间线（上下文）

获取特定观察的时间顺序背景：

timeline(anchor=<observation_id>, depth_before=3, depth_after=3)

或者搜索并一步获取时间线：

timeline(query="authentication", depth_before=2, depth_after=2)

返回： 按时间顺序显示之前/之后发生的情况 成本: 可变，取决于深度 目的: 理解叙事弧线和背景

第3层：获取观察（详细信息）

仅获取相关观察的完整详细信息：

get_observations(ids=[123, 456, 789])

返回: 完整的观察细节（叙述、事实、文件、概念） 成本: 每次观测约 500-1000 token 目的: 深入研究特定的、经过验证的项目

为什么这有效

传统方法：

事先获取所有内容：20,000 个 token
相关性：约10%（实际上有用的部分为2,000个标记）
浪费：18,000 个token在无关的上下文上

三层方法：

搜索索引：1,000 token（10 个结果）
时间线上下文：500 个标记（大约 2 个关键结果）
获取详情：1,500 token（3 次观察）
总计：3,000 token，100% 相关

可用工具

`__IMPORTANT` - 工作流程文档

始终可见的三层工作流程模式提醒。有助于 Claude 理解如何高效使用搜索工具。

使用方式: 自动显示，无需调用

`search` - 搜索内存索引

搜索你的记忆并获取带有ID的紧凑索引。

参数：

query - 全文搜索查询（支持 AND、OR、NOT、短语搜索）
limit - 最大结果数（默认值：20）
offset - 分页时跳过前 N 个结果
type - 按观察类型筛选（错误修复、功能、决策、发现、重构、变更）
obs_type - 按记录类型筛选（观测、会话、提示）
project - 按项目名称筛选
dateStart - 按开始日期筛选 (YYYY-MM-DD)
dateEnd - 按结束日期筛选 (YYYY-MM-DD)
orderBy - 排序顺序（日期降序, 日期升序, 相关性）

返回值： 包含ID、标题、日期、类型的紧凑索引表

示例：

search(query="database migration", type="bugfix", limit=5, orderBy="date_desc")

`timeline` - 获取时间顺序的背景

获取围绕特定点或查询的观察的按时间顺序的视图。

参数：

anchor - 用于围绕时间轴中心的观察ID（如果提供查询则可选）
query - 用于自动查找锚点的搜索查询（如果提供了锚点，则可选）
depth_before - 锚点前的观察次数（默认值：3）
depth_after - 锚点后的观测数量（默认值：3）
project - 按项目名称筛选

返回值： 显示事件发生前/期间/之后的时间顺序列表

示例：

timeline(anchor=12345, depth_before=5, depth_after=5)

或基于搜索的：

timeline(query="implemented JWT auth", depth_before=3, depth_after=3)

`get_observations` - 获取完整详情

通过ID获取完整的观察详情。为了效率，请始终在一次调用中批量处理多个ID。

参数：

ids - 观测 ID 数组（必填）
orderBy - 排序顺序（日期降序，日期升序）
limit - 最大返回观测数
project - 按项目名称筛选

返回值： 完整的观察细节，包括叙述、事实、文件、概念

示例：

get_observations(ids=[123, 456, 789, 1011])

重要: 始终批量处理ID，而不是对每个观测单独调用。

常见用例

调试问题

场景: 找出数据库连接出了什么问题

Step 1: search(query="error database connection", type="bugfix", limit=10)
  → Review index, identify observations #245, #312, #489

Step 2: timeline(anchor=312, depth_before=3, depth_after=3)
  → See what was happening around the fix

Step 3: get_observations(ids=[312, 489])
  → Get full details on relevant fixes

理解决策

情境: 审查有关身份验证的架构选择

Step 1: search(query="authentication", type="decision", limit=5)
  → Find decision observations

Step 2: get_observations(ids=[<relevant_ids>])
  → Get full decision rationale, trade-offs, facts

代码考古

场景: 查找特定文件的修改时间

Step 1: search(query="worker-service.ts", limit=20)
  → Get all observations mentioning that file

Step 2: timeline(query="worker-service.ts refactor", depth_before=2, depth_after=2)
  → See what led to and followed from the refactor

Step 3: get_observations(ids=[<specific_observation_ids>])
  → Get implementation details

功能历史

情境: 跟踪功能的演变

Step 1: search(query="dark mode", type="feature", orderBy="date_asc")
  → Chronological view of feature work

Step 2: timeline(anchor=<first_observation_id>, depth_after=10)
  → See the full development timeline

Step 3: get_observations(ids=[<key_milestones>])
  → Deep dive on critical implementation points

从过去的工作中学习

场景: 审查重构模式

Step 1: search(type="refactor", limit=10, orderBy="date_desc")
  → Recent refactoring work

Step 2: get_observations(ids=[<interesting_ids>])
  → Study the patterns and approaches used

上下文恢复

场景： 在离开项目一段时间后恢复上下文

Step 1: search(query="project-name", limit=10, orderBy="date_desc")
  → See recent work

Step 2: timeline(anchor=<most_recent_id>, depth_before=10)
  → Understand what led to current state

Step 3: get_observations(ids=[<critical_observations>])
  → Refresh memory on key decisions

搜索查询语法

query 参数支持 SQLite FTS5 全文搜索语法：

布尔运算符

query="authentication AND JWT"           # Both terms must appear
query="OAuth OR JWT"                      # Either term can appear
query="security NOT deprecated"           # Exclude deprecated items

短语搜索

query='"database migration"'             # Exact phrase match

特定列搜索

query="title:authentication"             # Search in title only
query="content:database"                  # Search in content only
query="concepts:security"                 # Search in concepts only

组合操作符

query='"user auth" AND (JWT OR session) NOT deprecated'

token 管理

token 效率最佳实践

总是从搜索开始 - 先获取索引（每个结果约50-100个标记）
使用小的限制 - 从 3-5 个结果开始，如有需要再增加
在获取前筛选 - 使用类型、日期、项目筛选器
批量获取观测值 - 总是将多个 ID 聚合在一次调用中
战略性使用时间线 - 仅在叙事重要时获取上下文

token成本估算

操作	每个结果的token
搜索 (索引)	50-100
时间线（每次观察）	100-200
获取观测（完整详情）	500-1,000

示例比较：

低效：

# Fetching 20 full observations upfront: 10,000-20,000 个 token
get_observations(ids=[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20])

高效：

# Search index: ~1,000 tokens
search(query="bug fix", limit=20)

# Review IDs, identify 3 relevant observations

# Fetch only relevant: ~1,500-3,000 个 token
get_observations(ids=[5, 12, 18])

# Total: 2,500-4,000 个 token (vs 10,000-20,000)

高级筛选

日期范围

search(
  query="performance optimization",
  dateStart="2025-10-01",
  dateEnd="2025-10-31"
)

多种类型

对于多类型的观测，可进行多次搜索或使用更广泛的查询：

search(query="database", type="bugfix", limit=10)
search(query="database", type="feature", limit=10)

项目特定

search(query="API", project="my-app", limit=15)

分页

# First page
search(query="refactor", limit=10, offset=0)

# Second page
search(query="refactor", limit=10, offset=10)

# Third page
search(query="refactor", limit=10, offset=20)

结果元数据

所有观察都包括丰富的元数据：

ID - 唯一观测标识符
类型 - 错误修复，功能，决策，发现，重构，更改
日期 - 工作发生的时间
标题 - 简短描述
概念 - 标签主题（例如，安全性、性能、架构）
已读取文件 - 工作过程中检查的文件
已修改文件 - 工作过程中更改的文件
叙述 - 发生了什么以及原因的故事
事实 - 关键事实点（所作决策、使用的模式、指标）

故障排除

未找到结果

扩大你的搜索：

# Too specific
search(query="JWT authentication implementation with RS256")

# Better
search(query="authentication")

检查数据库是否有数据：

bash

curl "http://localhost:37777/api/search?query=test"

尝试无过滤:

# Remove type/date filters to see if data exists
search(query="your-search-term")

在 get_observations 中未找到 ID

错误： 未找到观察ID：[123, 456]

原因：

来自不同项目的ID（使用 project 参数）
ID已被删除
身份证号码中的打字错误

解决方案：

# Verify IDs exist
search(query="<related-search>")

# Use correct project filter
get_observations(ids=[123, 456], project="correct-project-name")

token 限制错误

错误： 响应超出 token 限制

解决方案： 使用三层工作流程来降低前期成本：

# Instead of fetching 50 full observations:
# get_observations(ids=[1,2,3,...,50])  # 25,000-50,000 个 token!

# Do this:
search(query="<your-query>", limit=50)  # ~2,500-5,000 个 token
# Review index, identify 5 relevant observations
get_observations(ids=[<5-most-relevant>])  # ~2,500-5,000 个 token
# Total: 5,000-10,000 个 token (50-80% savings)

搜索性能

如果搜索看起来很慢：

在查询中更具体（有助于 FTS5 索引）
使用日期范围筛选来缩小范围
在可能的情况下指定项目过滤器
使用较小的限制值

最佳实践

先索引，后详述 - 永远先进行搜索以了解选项
获取前筛选 - 使用搜索参数缩小结果范围
批量 ID 获取 - 在一次 get_observations 调用中组合多个 ID
使用时间线来提供上下文 - 当叙事很重要时，时间线展示故事
具体查询 - 越具体 = 相关性越高
最初的限制较小 - 从3-5个结果开始，如有需要再扩展
深入前的复习 - 在获取完整详情前先检查索引

技术细节

架构: MCP 工具是 Worker HTTP API (localhost:37777) 上的一个轻量封装。MCP 服务器将工具调用转换为对 worker 服务的 HTTP 请求，worker 服务处理所有的业务逻辑、数据库查询和 Chroma 向量搜索。

MCP 服务器: 位于 ~/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs

Worker 服务： 由 Bun 管理的端口 37777 上的 Express API

数据库： SQLite FTS5 全文搜索在 ~/.claude-mem/claude-mem.db 上

向量搜索: 用于语义搜索的 Chroma 嵌入（底层实现）

下一步

Progressive Disclosure - 三层工作流程的哲学
Architecture Overview - 系统组件
Database Schema - 理解数据结构
Claude Desktop Setup - 安装与配置

使用MCP工具进行内存搜索 ​

概览 ​

三层工作流程 ​

第1层：搜索（索引） ​

第2层：时间线（上下文） ​

第3层：获取观察（详细信息） ​

为什么这有效 ​

可用工具 ​

__IMPORTANT - 工作流程文档 ​

search - 搜索内存索引 ​

timeline - 获取时间顺序的背景 ​

get_observations - 获取完整详情 ​

常见用例 ​

调试问题 ​

理解决策 ​

代码考古 ​

功能历史 ​

从过去的工作中学习 ​

上下文恢复 ​

搜索查询语法 ​

布尔运算符 ​

短语搜索 ​

特定列搜索 ​

组合操作符 ​

token 管理 ​

token 效率最佳实践 ​

token成本估算 ​

高级筛选 ​

日期范围 ​

多种类型 ​

项目特定 ​

分页 ​

结果元数据 ​

故障排除 ​

未找到结果 ​

在 get_observations 中未找到 ID ​

token 限制错误 ​

搜索性能 ​

最佳实践 ​

技术细节 ​

下一步 ​

使用MCP工具进行内存搜索

概览

三层工作流程

第1层：搜索（索引）

第2层：时间线（上下文）

第3层：获取观察（详细信息）

为什么这有效

可用工具

`__IMPORTANT` - 工作流程文档

`search` - 搜索内存索引

`timeline` - 获取时间顺序的背景

`get_observations` - 获取完整详情

常见用例

调试问题

理解决策

代码考古

功能历史

从过去的工作中学习

上下文恢复

搜索查询语法

布尔运算符

短语搜索

特定列搜索

组合操作符

token 管理

token 效率最佳实践

token成本估算

高级筛选

日期范围

多种类型

项目特定

分页

结果元数据

故障排除

未找到结果

在 get_observations 中未找到 ID

token 限制错误

搜索性能

最佳实践

技术细节

下一步