Finding the Right Memory
Claude-mem’s retrieval problem begins after the database has accumulated more observations than any new prompt can carry. The system must find a useful slice, preserve enough surrounding meaning, and deliver it without overwhelming the host agent. This chapter explains the project’s progressive-disclosure workflow and the cooperation between Chroma, SQLite, FTS5, timelines, and context budgeting. The practical outcome is a way to decide not only what to search for, but how much detail to request and when a missing result says something about retrieval rather than storage.
Search first, detail later
A large memory corpus creates a deceptively bad temptation: ask for everything that might be relevant and let the model sort it out. Claude-mem takes the opposite route. Its worker-mode MCP interface begins with a compact search result containing identifiers, dates, types, and titles. The result is an index, not a full report. The reader can scan candidate memories without paying the cost of importing every narrative and tool payload into the active context.
The identifier is what makes the next step possible. After seeing a candidate about an authentication failure, the reader can use timeline around that observation. Timeline retrieval adds chronological neighbors—other observations, session summaries, and prompts around an anchor or query—so an isolated title is not mistaken for the whole story. A decision often makes sense only beside the failed attempt that preceded it or the test result that followed it. Timeline context supplies that neighborhood without requiring the entire project history.
Only then does get_observations fetch full details for selected IDs. A full observation can include the narrative, facts, concepts, file lists, session linkage, and other stored fields that were intentionally omitted from the compact index. When that summary still leaves an exact command output or literal tool response unresolved, get_tool_uses is the deeper disclosure layer. It returns the original raw tool input and response for already identified calls, but those bodies are large and unsummarized. The workflow therefore treats raw I/O as an exception, not as a more honest default for every query.
This sequence is a form of risk control as much as a token optimization. At the index stage, a wrong candidate costs little and can be discarded. At the timeline stage, the reader tests whether the candidate belongs to the right episode. At the full-observation stage, the reader commits context space only to records that survived that test. At the raw stage, the reader is asking for source-like evidence because the generated account is insufficient. Each transition increases detail and decreases the number of records being carried forward.
Consider a query such as “inherited environment variable authentication failure.” A compact search may surface several observations: one about a failing test, another about an environment cleanup, and a session summary. The titles and dates show which items are worth examining. A timeline around the cleanup observation can reveal whether it followed the failing test. Fetching both observations then exposes the narratives and facts. If the exact value printed by the diagnostic command matters, the reader can request the associated raw tool use. The system has moved from broad recall to narrow evidence instead of forcing the model to read a complete history.
The same staged logic applies to different kinds of records. Search can cover observations, session summaries, and user prompts.