cd /news/ai-agents/the-same-platform-gives-its-tool-cat… · home topics ai-agents article
[ARTICLE · art-126324] src=dev.to ↗ pub= topic=ai-agents verified=true sentiment=· neutral

The Same Platform Gives Its Tool Catalog BM25 and Its Memory Store ls

An analysis of Anthropic's Claude Developer Platform found that its tool catalog and memory store handle retrieval differently: the tool search API offers regex- and BM25-based ranked search that returns up to five matching tools as tool_reference blocks, while the List memories endpoint exposes only depth, limit, page, path_prefix, and view parameters with no search or query option. Because memory items are returned in a stable, server-defined order rather than a relevance order, the writeup concludes that deciding what is relevant falls to the model reading the listing, and that path naming on the memory surface functions as retrieval design.

by read5 min views1 publishedSep 10, 2026

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.

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.

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.

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).

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. 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.

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.

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.

A longer version of this note lives at https://mnemoverse.com/docs/library/anthropic-memory-api-no-ranked-retrieval Disclosure: I work on Mnemoverse, a memory engine for AI agents connected over MCP, so weigh the argument accordingly.

── more in #ai-agents 4 stories · sorted by recency
── more on @anthropic 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
Live at https://your-agent.zahid.host
Get free account → Pricing
from €0/mo · no card required
LIVE [news/the-same-platform-gi…] indexed:0 read:5min 2026-09-10 ·