What is tool-based memory retrieval?

Query-time retrieval, covered in the previous chapter, fires automatically before every single message, regardless of what an agent actually needs in that specific moment. Some tasks genuinely call for something more flexible than a single, fixed search happening once per turn, an agent that can search memory as many times as an evolving task actually requires, at whatever point during its own reasoning that need actually arises. This chapter looks at exposing memory search as a tool the agent itself decides when to call.

What Does It Actually Mean to Expose Memory Search as a Tool Rather Than Running It Automatically?

Tool-based retrieval hands an agent the same underlying search capability, but as something it explicitly chooses to invoke, with its own name, its own description, and its own expected inputs, rather than something that fires on its own before the agent ever starts reasoning. The agent decides, in the middle of working through a task, whether the situation actually calls for a memory lookup right now, and if so, what specifically to search for, rather than being handed one fixed search result whether it’s actually useful for the current step or not.

Why Would a Multi-Step Task Genuinely Benefit from an Agent Searching Several Separate Times Rather Than Just Once?

A complex task often unfolds in stages, and what’s actually relevant to search for can change meaningfully from one stage to the next, information relevant to an early planning step might be completely different from what’s relevant once the agent has moved on to evaluating a specific option in detail. A single, fixed search run once at the very start of a task, using only the original request as its query, has no way to adapt to what the agent actually discovers or decides partway through. Letting the agent search again, with a new, more specific query shaped by what it’s learned so far, is exactly what a single upfront search structurally can’t provide.

Why Does Simply Handing an Agent a Search Tool Not Automatically Guarantee It Will Actually Use It Well, or at All?

An agent weighing whether to invoke an available tool is making a genuine cost-benefit judgment, and if that tool’s purpose and value aren’t communicated clearly, the agent has no strong reason to reach for it over whatever’s already conveniently available. This isn’t a hypothetical risk, it’s exactly the kind of gap that shows up when a memory search tool is handed to an agent with a vague or generic description, only for the agent to simply never invoke it, defaulting instead to whatever’s already sitting in its immediate context, even when that memory tool holds genuinely useful information the agent never actually retrieves.

What Actually Makes a Tool Description Effective Enough to Reliably Prompt an Agent to Use a Memory Search Tool When It Genuinely Should?

An effective description states specifically what kind of information the tool can surface and, just as importantly, describes the concrete situations where searching it would actually be worthwhile, rather than leaving the agent to guess at when reaching for it might pay off. A vague description like “searches memory” gives an agent little concrete reason to prefer it over simply continuing with what it already has, while a specific description naming exactly what kinds of past information live behind that tool gives the agent an actual, legible reason to reach for it at precisely the moments that reason applies.

Does Tool-Based Retrieval Mean Every Search an Agent Runs Has to Wait for the Agent to Explicitly Decide to Search?

Not necessarily, and the two approaches this Part has covered aren’t mutually exclusive. A system can combine proactive, query-time retrieval to guarantee a baseline of relevant context always shows up automatically, with a tool-based option available on top for the genuinely unpredictable, mid-task searches that a fixed, upfront pattern could never have anticipated. This combination gets the reliability of a guaranteed baseline alongside the flexibility of letting the agent reach further whenever its own evolving reasoning actually calls for it.

How Does Weaviate Engram Support Exposing Memory Search as a Genuine Tool an Agent Can Invoke Repeatedly?

Weaviate Engram’s search method can be wrapped as a callable function with a clear, specific description, letting an agent invoke it as many times as a task actually requires, each time with whatever query its current reasoning step calls for. Consider a real-estate research assistant helping a buyer compare several properties in sequence, where the buyer’s stated preferences need to be checked against each individual property as the agent works through the comparison:

from engram import EngramClient

client = EngramClient(api_key=os.environ["ENGRAM_API_KEY"])

def search_buyer_preferences(query: str, buyer_id: str) -> str:
    """
    Searches this buyer's previously stated home-buying preferences and
    dealbreakers. Use this whenever evaluating a specific property against
    what the buyer has said matters to them, such as school district
    requirements, commute limits, or must-have features.
    """
    results = client.memories.search(
        query=query,
        user_id=buyer_id,
        retrieval_config="hybrid",
    )
    return "\n".join(f"- {m.content}" for m in results)

Because the tool’s description names exactly the situations where the agent should reach for it, evaluating a specific property against stated preferences, the agent invokes it separately for each property under comparison, searching for school-district requirements when evaluating one listing and searching for commute tolerance when evaluating another, rather than relying on a single, generic search run once at the very start of the task. This is exactly the value tool-based retrieval delivers for a use case like multi-property comparison, where what’s actually relevant to check genuinely shifts from one property to the next, and where a single fixed search could never have anticipated every comparison the agent would eventually need to make.

Tool-based retrieval gives an agent the flexibility to search memory exactly when its own evolving reasoning calls for it. A related pattern deserves its own separate treatment: retrieving a specific, already-known memory directly, without any relevance ranking at all, exactly the fetch retrieval type introduced earlier in this Part. Our next chapter, What is fetch-based retrieval for bounded memories?, takes up exactly that pattern in depth.