get_observations
定义
get_observations 是 claude-mem 提供的 4 个 MCP 搜索工具之一，职责不是做全文检索，也不是先给你一个轻量结果列表，而是通过 observation IDs 获取完整 observation 详情。
它的定位可以概括为：fetch full details only for filtered IDs。
在 Claude-Mem 的搜索体系里，它属于一个强调 token 效率的三层工作流中的第三层，也是最“重”的一层：返回的信息最完整，但单条结果的 token 成本也最高。
在本文档中的语境
本文档把 Claude-Mem 的记忆检索描述为一个 token-efficient 的 3-layer workflow pattern，其中：
- search：先获取紧凑索引，每条结果大约
50–100 tokens。 timeline：查看某条 observation 或某个查询附近的时间顺序上下文。- get_observations：只对已经筛出来的 ID 拉取完整详情，每条结果大约
500–1,000 tokens。
也就是说，get_observations 不是第一步工具，而是最后一步的详情拉取工具。它存在的意义，是避免一开始就把大量完整 observation 全部展开，从而造成上下文和 token 浪费。
关键机制
1. 以 ID 为输入，而不是以查询为输入
get_observations 的调用方式不是直接输入自然语言搜索词，而是输入一组 observation ID。示例调用为：
get_observations(ids=[123, 456])
这说明它依赖前序工具先完成“发现候选项”的过程。通常流程是：
search(query="authentication bug", type="bugfix", limit=10)
然后人工或 Claude 根据返回索引检查结果，识别出真正相关的 ID，例如 #123、#456，再调用 get_observations。
2. 只为“已过滤结果”获取完整详情
文档对它的定位写得非常明确：Fetch full details ONLY for filtered IDs。
这里的重点不是“能拿详情”，而是“只能在已经过滤之后再拿详情”。
这意味着它不应该被当成大范围扫描工具使用，也不适合对一批未经筛选的结果直接全部展开。正确做法是先通过 search 得到低成本索引，再缩小范围，最后才进入详情阶段。
3. 单条结果 token 成本高
文档给出的量级是：每个结果约 500–1,000 tokens。
这比 search 阶段每条 50–100 tokens 的成本高出一个数量级，因此它天然要求“少而准”的调用策略。Claude-Mem 整个三层工作流的核心收益，也正来自这种分层展开方式。
4. 始终批量传入多个 IDs
文档明确要求：get_observations 是 Fetch full observation details by IDs (always batch multiple IDs)。
这不是一个可有可无的调用建议，而是推荐用法中的硬性倾向：应始终一次批量传入多个 ID，而不是逐条单独请求。
这样做有几个直接目的：
- 减少多次往返调用。
- 把详情获取集中在一次请求中完成。
- 更符合 Claude-Mem 设计的 token/上下文利用方式。
- 让 Claude 在同一批相关 observation 之间做并列比较，而不是碎片化读取。
典型工作流
标准三步
- 先用 search 搜索记忆索引。
- 从索引结果中挑出真正相关的 observation IDs。
- 用 get_observations 对这些 ID 批量获取完整详情。
文档中的示例就是：
// Step 1: Search for index
search(query="authentication bug", type="bugfix", limit=10)
// Step 2: Review index, identify relevant IDs (e.g., #123, #456)
// Step 3: Fetch full details
get_observations(ids=[123, 456])
为什么不是直接跳到 get_observations
因为它的返回体积大。若跳过 search 的索引层，直接尝试拿“很多条完整 observation”，会快速消耗上下文窗口。
文档明确把这套分层方式的收益总结为：~10x token savings by filtering before fetching details。
也就是先过滤、后展开，能带来大约 10 倍 的 token 节省。get_observations 正是这条节省链路中最需要克制使用的一环。
与其他工具的分工
与 search 的区别
search 负责的是“找”和“初筛”。它支持全文查询，以及按 type/date/project 等条件过滤，输出的是紧凑索引。
get_observations 不负责“找”。它负责的是：当你已经知道要看哪些 observation 时，把这些 observation 的完整内容取回来。
如果把两者类比：
- search 像目录或索引页。
- get_observations 像按目录编号去调正文全文。
与 timeline 的区别
timeline 负责的是“时间上下文”，帮助理解某条 observation 周边发生了什么。
get_observations 负责的是“对象本体详情”，即某些 observation 自身的完整内容。
所以这两者解决的问题不同：
timeline：看前后脉络。- get_observations：看条目全文。
细节与边界
它不是检索入口
如果用户还不知道哪些 observation 相关，就不应直接使用 get_observations。正确入口应当是 search。
它不是大规模展开工具
尽管它支持按多个 ID 批量获取，但“批量”不等于“无限制地把所有搜索结果都展开”。文档强调的是：只对 filtered IDs 获取 full details。
换言之，它适用于“少量、已确认、值得深读”的结果集，而不是“为了保险把所有候选都拉全”。
它返回的是完整 observation details
文档没有把返回内容描述为摘要、索引或上下文片段，而是明确称为 full observation details。因此在工作流中，它通常是最接近“原始详细记录”的读取层。
它的高成本决定了使用顺序
由于每条大约 500–1,000 tokens，所以它天然应该放在最后。若把它提前到第一步，会直接破坏 Claude-Mem 所强调的 token-efficient 设计。
在 Claude-Mem 架构中的意义
Claude-Mem 的核心组件包括本地 worker service、SQLite database、向量数据库 Chroma，以及面向自然语言查询的记忆搜索能力。get_observations 在这里承担的是“把已命中的记忆条目从轻量索引提升到完整内容”的职责。
它与 search 配合后，形成一种渐进披露（progressive disclosure）式读取方式：
- 先低成本浏览候选。
- 再看时间线辅助判断。
- 最后仅对高价值目标调取全文。
这也是 claude-mem 能在记忆检索中兼顾可用性与 token 成本控制的重要原因。
使用建议
- 先用 search，不要把 get_observations 当第一步。
- 只对真正相关的 observation IDs 调用它。
- 始终把多个相关 ID 一次性批量传入。
- 预期它的返回会比较重：每条约
500–1,000 tokens。 - 当你需要的是“前后发生了什么”，先考虑
timeline；当你需要的是“这条 observation 具体写了什么”，再用 get_observations。