智能搜索（默认）¶

默认使用智能搜索：原始 mem-search 技能采用一种节省 token 的三步工作流。代理在每一步都会先审视结果，再决定接下来读取什么。没有自动或引导模式。

概述¶

claude-mem 不会一开始就提取全部历史数据（成本高昂），而是采用渐进式披露的方法：

搜索 → 获取带 ID 的紧凑索引（约 50-100 token/结果）
时间线 → 获取有趣结果周围的上下文
获取观察 → 仅获取筛选后 ID 的完整详情

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

三层工作流¶

第 1 层：搜索（索引）¶

先进行搜索，获取轻量的结果索引：

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

返回： 包含 ID、标题、日期、类型的紧凑表格 成本： 每个结果约 50-100 tokens 目的： 在获取详情之前，先概览已有内容

第 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 tokens 目的： 深入查看经过筛选确认的具体条目

为什么这样有效¶

传统方法： - 一开始就获取所有内容：20,000 tokens - 相关性：约 10%（实际有用的只有 2,000 tokens） - 浪费：18,000 tokens 用于无关上下文

三层方法： - 搜索索引：1,000 tokens（10 条结果） - 时间线上下文：500 tokens（围绕 2 条关键结果） - 获取详情：1,500 tokens（3 条观察） - 总计：3,000 tokens，100% 相关

简单搜索（可选）¶

不会对结果进行推理。速度快，但较浅。需要可靠召回时请使用智能搜索。

dumb_search(query="authentication token expiry", project="my-project")

简单搜索是一次调用式查找，通过匹配标题中的单词来选择记录。它可能会漏掉相关记录，也不会协调相互矛盾的证据。如需完整的三步审查，请使用智能搜索。

可用工具¶

`important_workflow` - 工作流文档¶

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

用法： 自动显示，无需调用

`search` - 搜索记忆索引¶

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

参数： - query - 用平常话描述要找的内容：先按含义匹配，再按关键词匹配（参见查询如何匹配） - limit - 最大结果数（默认：20） - offset - 跳过前 N 条结果，用于分页 - type - 记录类别：observations、sessions 或 prompts（默认：全部）。其他任何值都将被视为一种观察类型，类似于 obs_type - obs_type - 按类型筛选观察（bugfix、feature、decision、discovery、refactor、change）；多个类型用逗号分隔 - project - 按项目名称筛选 - dateStart - 按开始日期筛选（YYYY-MM-DD） - dateEnd - 按结束日期筛选（YYYY-MM-DD） - orderBy - 排序方式（date_desc、date_asc、relevance）

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

示例：

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

`timeline` - 获取时间线上下文¶

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

参数： - anchor - 用于居中时间线的观察 ID（如果提供了 query 则可选） - query - 用于自动查找锚点的搜索查询（如果提供了 anchor 则可选） - depth_before - 锚点之前的观察数量（默认：3） - depth_after - 锚点之后的观察数量（默认：3） - project - 按项目名称筛选 - projects - 显式项目范围（数组或以逗号分隔的名称，worker runtime）

在 worker runtime 中，如果未提供项目范围，观察或会话摘要锚点会将周围的观察、摘要和提示限制在锚点所属项目内，包括其合并的别名。查询模式使用匹配到的观察所属项目。显式范围优先，包括由 MCP 服务器提供的 checkout 范围；传入 projects 可请求跨特定项目的上下文。仅含时间戳的锚点无法识别项目，因此在未提供项目范围时，它保持未限定范围状态。

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

示例：

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 - 排序方式（date_desc、date_asc） - 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: timeline(anchor=<relevant_id>, depth_before=3, depth_after=3)
  → Review what led to and followed the decision

Step 3: get_observations(ids=[<selected_ids>])
  → Read the selected decision rationale, trade-offs, and 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: timeline(anchor=<interesting_id>, depth_before=3, depth_after=3)
  → Review the surrounding changes before selecting records

Step 3: get_observations(ids=[<selected_ids>])
  → Study the selected patterns and approaches

上下文恢复¶

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

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

查询的匹配方式¶

当向量索引（Chroma）运行时，search 首先按语义匹配你的查询，因此请用日常语言描述你要查找的内容：query="why the worker failed to start after the upgrade"。关键词匹配会填补语义扫描留空的任何记录类别，并在向量索引关闭或不可用时独立给出答案。

对观察记录和会话摘要进行关键词匹配时，查询会被当作普通文本来读取。它没有操作符：

每个词都必须出现在记录的某个位置，顺序不限、字段不限。query="security deprecated" 会找到同时提到这两个词的记录。
AND、OR、NOT、引号、括号和 field: 前缀都是普通词。 query="security NOT deprecated" 同样要求包含 "not" 和 "deprecated"，而 query='"database migration"' 不是短语搜索：这两个词可以出现在任何位置。要缩小结果范围，请使用 obs_type、project、dateStart 和 dateEnd 参数。
大小写无关。单词内部的标点会将其拆分为必须按顺序相邻出现的部分，因此 query="worker-service.ts" 能匹配该文件名，但无法匹配只提到 "worker"、"service" 和 "ts"（彼此分离）的记录。
当没有完整单词匹配时，单词可以匹配更长单词的一部分。 如果没有任何记录包含每个完整单词，则每个单词仍必须出现，但它可以是某个更长单词的一部分，因此 query="migrat" 能查到 "migration"。对于不使用空格分隔单词的脚本文字（中文、日文、韩文、泰文等），始终采用这种匹配方式。

query="database migration"       # records mentioning both words, anywhere
query="worker-service.ts"         # a file name
query="security NOT deprecated"  # all three words, "not" included: there are no operators

你的提示词则会被作为一整段文本进行匹配：整个查询必须按原样出现在提示词中，因此 query="database migration" 会漏掉 "migration of the database" 这样的提示词。请保持提示词搜索简短。

托管服务器运行时使用 PostgreSQL 全文搜索检索观察记录，这有其自身的规则：单词按英语词干匹配，OR 组合多个备选词，引号要求短语精确匹配，前导 - 排除某个单词，并且不支持在更长单词内部进行匹配。

Token 管理¶

Token 效率最佳实践¶

始终从 search 开始 - 先获取索引（每个结果约 50-100 Token）
使用较小的 limit - 从 3-5 个结果开始，必要时再增加
在获取前先过滤 - 使用 type、date、project 过滤器
批量调用 get_observations - 始终在单次调用中组合多个 ID
在查看详情前先检查 timeline - 在选择完整记录之前，先查看相关结果周围的上下文

Token 成本估算¶

操作	每个结果的 Token 数
search（索引）	50-100
timeline（每条观察记录）	100-200
get_observations（完整详情）	500-1,000

示例对比：

低效方式：

# Fetching 20 full observations upfront: 10,000-20,000 tokens
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

# Inspect nearby context: ~300-600 tokens
timeline(anchor=12, depth_before=1, depth_after=1)
# Review the timeline and keep only the relevant IDs

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

# Total: ~2,800-4,600 tokens (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")

检查数据库中是否有数据：

WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
curl "http://127.0.0.1:$WORKER_PORT/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 已被删除 - ID 编号输入错误

解决方案：

# Verify IDs exist in the intended project
search(query="<related-search>", project="correct-project-name")

# Inspect context around an ID returned by that search
timeline(anchor=<returned_id>, project="correct-project-name")

# Read only the verified, relevant IDs
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 tokens!

# Do this:
search(query="<your-query>", limit=50)  # ~2,500-5,000 tokens
# Review the index and inspect context around a relevant result
timeline(anchor=<relevant_id>, depth_before=2, depth_after=2)
# Review context, then select the 5 observations needed
get_observations(ids=[<5-most-relevant>])  # ~2,500-5,000 tokens
# Add only the timeline context needed to select those details

搜索性能¶

如果搜索看起来较慢： 1. 在查询中使用更具体的关键词（有助于 FTS5 索引） 2. 使用日期范围筛选器缩小范围 3. 尽可能指定项目筛选器 4. 使用较小的 limit 值

最佳实践¶

先索引，后细节 - 始终从搜索开始，以概览选项
先筛选，再获取 - 使用搜索参数缩小结果范围
批量获取 ID - 在单个 get_observations 调用中分组多个 ID
先看时间线，再看细节 - 在选择完整记录之前，检查周围事件和后续更正
具体查询 - 越具体 = 相关性越高
初始限制要小 - 从 3-5 个结果开始，需要时再扩展
深入之前先复查 - 在获取完整细节之前先查看索引

技术细节¶

架构： MCP 工具是本地 Worker HTTP API 的轻量封装。MCP 服务器将工具调用转换为发送到 Worker Service 的 HTTP 请求，由后者处理所有业务逻辑、数据库查询和 Chroma 向量搜索。

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

Worker Service： Express API，运行在配置的 Worker 端口上，由 Bun 管理

数据库： 基于 ~/.claude-mem/claude-mem.db 的 SQLite FTS5 全文搜索

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

后续步骤¶

渐进式披露 - 三层工作流背后的理念
架构概述 - 系统组件
数据库模式 - 理解数据结构
Claude Desktop 设置 - 安装与配置 ```

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/claude-mem

智能搜索（默认）¶

概述¶

三层工作流¶

第 1 层：搜索（索引）¶

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

第 3 层：获取观察（详情）¶

为什么这样有效¶

简单搜索（可选）¶

可用工具¶

important_workflow - 工作流文档¶

search - 搜索记忆索引¶

timeline - 获取时间线上下文¶

get_observations - 获取完整详情¶

常见使用场景¶

调试问题¶

理解决策¶

代码考古¶

功能历史¶

从过去的工作中学习¶

上下文恢复¶

查询的匹配方式¶

Token 管理¶

Token 效率最佳实践¶

Token 成本估算¶

高级过滤¶

日期范围¶

多种类型¶

项目特定¶

分页¶

结果元数据¶

故障排除¶

未找到结果¶

在 get_observations 中未找到 ID¶

Token 限制错误¶

搜索性能¶

最佳实践¶

技术细节¶

后续步骤¶

`important_workflow` - 工作流文档¶

`search` - 搜索记忆索引¶

`timeline` - 获取时间线上下文¶

`get_observations` - 获取完整详情¶