What is tool-use memory?

Everything covered so far in this Part has largely been about what an agent knows, facts about a person, a preference, a running summary of a situation. There’s a different, quieter category of memory that isn’t about the world or the user at all, it’s about the agent’s own competence at operating its tools correctly. Getting this kind of memory right is what lets an agent stop repeating the same mechanical mistake indefinitely, even when nothing about the user or the task has changed.

What Exactly Is Tool-Use Memory, and How Is It Different From Ordinary Procedural Memory?

Tool-use memory is a specific case of the procedural memory covered earlier in this Part, narrowed down to one particular kind of skill: correctly invoking a specific tool, function, or API. Where general procedural memory might capture a broad approach to solving a class of problem, tool-use memory is much more mechanical and specific, which argument to pass, which parameter to set, which filter to apply instead of a plain text search, given a particular kind of request.

This narrowness is actually the point. A tool has a fixed, well-defined interface, so a lesson about using it correctly can be stated precisely, in a way that’s immediately actionable the next time that exact tool gets called again. That’s different from a broader procedural lesson, which might need to be adapted and reinterpreted for each new situation it applies to.

Why Do Agents Keep Making the Same Tool-Calling Mistake Without Memory to Correct It?

Without memory, every tool call an agent makes is decided fresh, based only on the current context window and whatever general instructions were baked into its system prompt. If a user corrects a mistaken tool call, that correction only exists within the current conversation. The moment the conversation ends and a new one starts, the correction is gone, and the agent is right back to making its default, uncorrected choice the next time a similar situation comes up.

This is a genuinely wasteful pattern, since the same correction ends up being given over and over, by the same user or by different users hitting the identical mechanical issue, with no mechanism carrying that lesson forward. The fix isn’t a smarter model, it’s giving the correction somewhere durable to live once it’s been made the first time.

What Makes a Tool-Use Lesson Tricky to Capture Compared to an Ordinary Fact?

A tool-use correction rarely arrives as a single, self-contained statement the way a plain fact usually does. It typically has to be reconstructed from several separate pieces: what the agent was asked to do, what tool call it actually made, and the follow-up feedback explaining why that call was wrong. These three pieces might come from entirely different points in an interaction, sometimes even from different components in a multi-agent system where one agent handles the conversation and a separate agent or subagent actually executes the tool call.

Only once all three pieces are available does a genuinely useful lesson emerge. Storing any one piece on its own, the original request, the mistaken call, or the raw feedback, wouldn’t be nearly as valuable as the synthesized lesson: given this kind of request, use this argument, not that one.

Should the Raw Pieces of a Correction Be Stored Alongside the Final Lesson?

Generally not, once the lesson has actually been synthesized from them. The raw request, the mistaken call, and the literal feedback text are only useful as intermediate inputs to producing the actual, reusable lesson. Keeping all of that raw material around permanently adds clutter without adding value, since nothing about a future tool call benefits from re-reading the exact wording of an old correction rather than just applying the distilled rule it produced.

This connects to something already covered in earlier chapters on the memory pipeline: intermediate values used to build a memory don’t have to be the thing that ends up persisted. What matters for tool-use memory specifically is that the pipeline has a way to combine several separate, related pieces of raw input into one clean, retrievable rule before anything gets written to permanent storage.

How Does Weaviate Engram Combine Scattered Signals Into a Single Tool-Use Lesson?

Weaviate Engram’s pipeline supports exactly this pattern using a buffer step that collects related pieces of information from separate inputs, then a transform step that combines everything in the buffer into one consolidated memory once enough has accumulated. Consider a data-analysis assistant that translates natural-language requests into calls against a spreadsheet API, where the agent initially picks the wrong parameter and gets corrected:

from engram import EngramClient

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

client.memories.add(
    [
        {"topic": "task_goal", "content": "User asked to find all rows where the region column equals 'West'."},
        {"topic": "actions_taken", "content": "Assistant called the query tool with a raw text search for 'West' instead of an equality filter on the region field."},
    ],
    group="spreadsheet-assistant",
)

Moments later, the user’s follow-up feedback arrives as its own separate input, and the pipeline’s buffer holds all three pieces together until it’s ready to combine them:

client.memories.add(
    [
        {"topic": "feedback", "content": "Region is a categorical column, so use an exact-match filter, not a text search, or you'll miss rows where the value doesn't exactly contain that word."},
    ],
    group="spreadsheet-assistant",
)

lesson = client.memories.search(
    query="How should categorical column values be filtered when querying spreadsheet data?",
    group="spreadsheet-assistant",
)

Once the buffer flushes, Engram’s transform step combines the task goal, the mistaken action, and the feedback into a single, distilled memory: when filtering a categorical column like region, use an exact-match filter rather than a text search. The next time this assistant handles a similar request, searching for that lesson surfaces exactly the corrected rule, not the raw history of how it was learned, letting it apply the fix immediately rather than repeating the same mechanical mistake it already got corrected on once before.

Tool-use memory captures how an agent should operate its own tools correctly. Zooming out from any single tool or task, there’s a broader structural question worth addressing next: whether a lesson learned in one particular conversation should be available in a completely different conversation, and whether that’s the same thing as making it available across separate sessions with a gap of time between them. Our next chapter, What is the difference between cross-session and cross-conversation memory?, takes up exactly that distinction.