HHermes Explained

Memory

Memory Tools

Tool surfaces that let the agent inspect, add, or retrieve memory.

Importance 4/50 backlinks1 source refs

Memory Tools

What it is

Tool surfaces that let the agent inspect, add, or retrieve memory.

In plain terms

An intercom panel wired with separate buttons for adding a note, correcting one, or erasing one only does what its installer wired up. That is the memory tool: a single model-facing control surface with add, replace, and remove actions, gated the same way any other tool can be switched on or off for a given deployment.

Why it matters

Inspecting what’s already stored, adding a new fact, or retrieving something from earlier — memory tools are the concrete, model-facing tool calls that make memory something the agent actively manages mid-turn rather than a passive background process. Because these tools are gated the same way any other toolset is, an operator can disable write access to memory while leaving read access intact, or the reverse. That granularity matters more once memory starts holding anything sensitive.

How it works

One tool named memory (tools/memory_tool.py) exposes an action of add, replace, or remove against a target of memory (the agent’s own notes) or user (facts about the person), plus a batch operations array for making several changes atomically in one call checked against the final character budget. Replace and remove work by old_text - a short unique substring identifying the entry, since entries have no ID. Every mutating call passes through a write-approval gate (tools/write_approval.py) that can allow it, block it outright, or stage it for later sign-off. A separate MemoryManager (agent/memory_manager.py) mirrors every successful add, replace, or remove out to one registered external provider - Honcho, Hindsight, and similar plugins - so that provider stays in sync with the built-in tool, and it keeps a provider’s own tool names from colliding with a reserved core tool.

A concrete example

Mid-conversation, the model calls memory with action add, target user, content “Prefers dark mode in every UI.” The tool checks that entry does not already exist, appends it, and confirms the save. When the user later changes their mind, the model calls memory again with action replace and old_text “dark mode” to swap in the new preference by matching the substring. If an operator has turned off the memory toolset for that deployment, the same call returns an error instead, and nothing is saved.

How it connects

This note belongs to the Memory family. Its closest neighboring concepts are: Privacy, Memory, Agent Runtime, Personal OS.

Source evidence

  • vendor/hermes-agent/tools/memory_tool.py:1022-1032#memory_tool — Verified Source Map evidence for memory_tool. The memory tool routes a single operation by action to add, replace, or remove; this flow continues through the add branch.

Workflows

  • No first-pass workflow mapping yet; this concept still appears in the vault graph through articles and source evidence.
  • No article currently mentions this concept by name/alias often enough to qualify (see mention-mining policy).