The Same Platform Gives Its Tool Catalog BM25 and Its Memory Store ls
The Same Platform Gives Its Tool Catalog BM25 and Its Memory Store ls
同一平台为工具目录提供 BM25 检索，却为记忆存储提供 ls 命令
Overflow is a single problem, more candidates than fit and a need to hand back the ones that matter, and the Claude Developer Platform answers it one way for tools and a different way for memory. “溢出”是一个共同的问题：候选内容多于可容纳空间，因此需要筛选出最重要的部分。Claude 开发者平台针对工具和记忆分别给出了不同的解决方案。
One problem, two surfaces. A tool catalog overflows when the definitions cost more context than the task is worth. A memory store overflows for the same reason, and the platform documents the scale. A store can hold up to ten thousand memories, and one call to List memories returns between 1 and 100 items per page, capped at 20 when it carries content (memory stores guide, List memories, both probed 2026-09-07). Ten thousand candidates, twenty full items per call. Something has to choose.
一个问题，两个界面。当工具定义的上下文成本超过任务本身的价值时，工具目录就会溢出。记忆存储溢出的原因也如出一辙，平台文档中记录了其规模：一个存储库最多可容纳一万条记忆，单次调用 List memories 每页返回 1 到 100 个项目，若包含内容则上限为 20 个（参考 2026-09-07 查询的记忆存储指南及 List memories 文档）。一万个候选对象，每次调用仅返回二十个完整项目，必须有某种机制进行筛选。
The tool side gets ranked search. The engineering post on advanced tool use states it directly: “The Claude Developer Platform provides regex-based and BM25-based search tools out of the box, but you can also implement custom search tools using embeddings or other strategies” (Anthropic, advanced tool use, probed 2026-09-07). The API reference names two variants, tool_search_tool_regex_20251119 and tool_search_tool_bm25_20251119, and describes the second as the one where “Claude uses natural language queries to search for tools”. It also says what comes back: “The API runs the search and returns the matching tools as tool_reference blocks (up to 5 by default; Claude can set a limit in its search input)” (tool search tool, probed 2026-09-07). On that path the model never holds the full catalog: the reference says that initially the context contains only the tool search tool and any non-deferred tools, and everything else arrives as the shortlist the API hands back.
工具端采用了排名搜索。关于高级工具使用的工程文章直接指出：“Claude 开发者平台开箱即用地提供了基于正则表达式和 BM25 的搜索工具，但你也可以使用嵌入（embeddings）或其他策略实现自定义搜索工具”（Anthropic，高级工具使用，2026-09-07 查询）。API 参考文档列出了两个变体：tool_search_tool_regex_20251119 和 tool_search_tool_bm25_20251119，并描述后者为“Claude 使用自然语言查询来搜索工具”。文档还说明了返回结果：“API 执行搜索并以 tool_reference 块的形式返回匹配的工具（默认最多 5 个；Claude 可以在搜索输入中设置限制）”（工具搜索工具，2026-09-07 查询）。在这种路径下，模型从不持有完整目录：参考文档称，初始上下文中仅包含工具搜索工具和任何非延迟加载的工具，其余内容均作为 API 返回的精选列表呈现。
The memory side gets a directory listing. The block titled Query parameters on the List memories reference lists exactly five: depth, limit, page, path_prefix, view. Neither query nor search appears among them (probed 2026-09-07). The vendor supplies the metaphor without being asked: “depth=1 behaves like ls; omitting depth behaves like find”. It also states the ordering, and the wording is worth reading twice: “Items are returned in a stable, server-defined order.” A stable order is not a relevance order. The separate client-side memory tool, which stores files in infrastructure the developer controls rather than in a managed store, lands in the same place: six documented commands, view, create, str_replace, insert, delete, rename, and no search among them (memory tool, probed 2026-09-07).
记忆端则采用了目录列表。List memories 参考文档中名为“查询参数”的区块仅列出了五个参数：depth、limit、page、path_prefix 和 view。其中并未出现 query 或 search（2026-09-07 查询）。供应商主动提供了类比：“depth=1 的行为类似于 ls；省略 depth 的行为类似于 find”。文档还说明了排序方式，其措辞值得深思：“项目以稳定的、服务器定义的顺序返回。”稳定的顺序并不等同于相关性顺序。独立的客户端记忆工具（将文件存储在开发者控制的基础设施而非托管存储中）也面临同样的情况：六个已记录的命令 view、create、str_replace、insert、delete、rename 中同样没有搜索功能（记忆工具，2026-09-07 查询）。
Which makes the path tree the retrieval design. The distinction in one sentence: the tool catalog has ranked selection, the memory store has selection by place and depth, so deciding what is relevant falls to the model reading the listing. The practical consequence is stated on the tool side and nowhere on the memory side. The engineering post tells tool authors that “Tool search matches against names and descriptions, so clear, descriptive definitions improve discovery accuracy” (Anthropic, advanced tool use, probed 2026-09-07), and the tool search reference makes the same point in its optimization tips, telling authors to “Use consistent namespacing in tool names: prefix by service or resource” so that one search matches the whole group (tool search tool, probed 2026-09-07). Both are plain statements that on that surface, naming is retrieval design. 这使得路径树成为了检索设计的核心。一句话总结区别：工具目录拥有排名选择机制，而记忆存储则是通过位置和深度进行选择，因此判断哪些内容相关，取决于读取列表的模型。其实际后果在工具端有明确说明，但在记忆端却只字未提。工程文章告诉工具作者：“工具搜索会匹配名称和描述，因此清晰、描述性的定义能提高发现准确度”（Anthropic，高级工具使用，2026-09-07 查询），工具搜索参考文档在优化建议中也表达了同样的观点，建议作者“在工具名称中使用一致的命名空间：按服务或资源添加前缀”，以便一次搜索能匹配整个组（工具搜索工具，2026-09-07 查询）。这两者都明确表明，在该界面上，命名即检索设计。
The memory surface has the same property and no equivalent sentence: the published best practices for memory management cover store count and volume, not what to call a path. Since path_prefix and depth are the only two selectors the endpoint offers, path segments are not folders that a human finds tidy. They are the selection keys, and inventing them is the retrieval work. The published guidance partitions one level higher, at the store: “Rather than one large general-purpose store, use smaller purpose-built stores: one per user, one for shared domain knowledge, and one for project-specific context.” Inside a single store, the tree is left to whoever writes the paths. That part of the design outlives the endpoint, because the full projection is documented as the way to “use this as the bulk-read path for export and sync”, so bulk reads run over the same listing regardless of what else the API grows.
记忆界面具有相同的属性，却缺乏相应的指导：已发布的记忆管理最佳实践涵盖了存储数量和容量，却未提及如何命名路径。由于 path_prefix 和 depth 是该端点仅有的两个选择器，路径片段并非人类眼中整洁的文件夹，它们是选择键，而设计这些键就是检索工作的核心。已发布的指南在更高一层（即存储库层面）进行了划分：“与其使用一个大型通用存储库，不如使用较小的专用存储库：每个用户一个，共享领域知识一个，项目特定上下文一个。”在单个存储库内部，树状结构留给路径编写者自行决定。这部分设计比端点本身更持久，因为完整投影被记录为“用作导出和同步的批量读取路径”，因此无论 API 如何扩展，批量读取都将基于相同的列表运行。
One narrowing, stated plainly: all of the above is about the list endpoint in the HTTP API. A store attached to a session is mounted in the sandbox as a directory under /mnt/memory/, and the guide says “The agent reads and writes the store with the standard agent toolset”, so an agent working inside that sandbox reaches those files with ordinary file tools. The absence described here is an absence in one documented endpoint, not an absence in the product.
明确一点：以上所有内容均针对 HTTP API 中的列表端点。附加到会话的存储库会被挂载到沙盒中的 /mnt/memory/ 目录下，指南称“代理使用标准代理工具集读取和写入存储库”，因此在沙盒内工作的代理可以使用普通文件工具访问这些文件。此处描述的缺失仅限于某个已记录的端点，而非产品本身的缺失。
What this does not prove: The endpoint is marked Beta and rides a dated header, anthropic-beta: agent-memory-2026-07-22. Every quote and parameter above was probed on 2026-09-07 and every page address is printed in full, so none of this needs to be taken on trust. It does not show that the platform has no way to search memory. It supports one narrower statement: on 2026-09-07, the documented List memories endpoint exposed five query parameters and none of them was a search parameter. It says nothing about why. Two pages that answer the same question differently are an observation, not a diagnosis of intent, and there is no basis here for assigning one. It also says nothing about which shape works better. Whether a ranked shortlist beats a prefix walk for agent memory is an empirical question, and this is a distinction rather than a result. That test has not been run here.
这并不能证明什么：该端点被标记为 Beta 版，并带有日期头 anthropic-beta: agent-memory-2026-07-22。上述每一条引用和参数均于 2026-09-07 查询，且每个页面地址均完整列出，因此无需盲目信任。这并不代表平台无法搜索记忆。它仅支持一个更窄的结论：在 2026-09-07，已记录的 List memories 端点提供了五个查询参数，其中没有一个是搜索参数。这并未说明原因。两个页面以不同方式回答同一个问题是一种观察，而非对意图的诊断，此处没有依据进行推断。它也未说明哪种形式更好。对于代理记忆而言，排名精选列表是否优于前缀遍历是一个经验性问题，本文仅指出区别，而非得出结论。相关测试尚未在此进行。