hermes atlas
apr·2026 123·repos hermes·v0.10.0 ★ star this repo
map/memory & context/hermes-agentmemory

MukundaKatta/hermes-agentmemory

Pull-model episodic memory plugin for Hermes Agent. Real deletes, audit trace, BYO Claude. MIT.

★ 5 langPython licenseMIT updated2026-05-15
view on github →
overview

hermes-agentmemory is a standalone memory plugin for Hermes Agent that ensures episodic memory deletions are complete and immediate. It utilizes a pull-model approach with synchronous writes and on-demand summarization via Claude models, avoiding the persistent derived summaries found in background-consolidation backends. The plugin provides a transparent audit trail of all memory injections through a JSONL trace log. It is designed for users who require reversible growth and auditable memory operations.

  • Immediate, complete deletion of episodic memories without derived artifacts
  • Detailed audit logs of every prefetch in trace.jsonl
  • On-demand summarization using the Claude model family
full readme from github

hermes-agentmemory

test License: MIT Python

A drop-in Hermes Agent memory plugin built on agentmemory.

Pull-model episodic memory with real deletes and an audit trace. The point: Hermes Agent is good at remembering. This plugin gives it a memory layer that takes deletion seriously.

Why another memory plugin?

Hermes ships with several first-class memory backends (Mem0, Honcho, Hindsight, etc.). They consolidate in the background, which is the dominant pattern in agentic memory right now. That makes recall cheap and fast at the cost of two things:

  1. Deletes are not always real. Once an episode is baked into a derived summary, removing the original event leaves the summary intact.
  2. Memory injection is opaque. Background prefetch happens off the hot path; the user does not see exactly which past events were used until something goes wrong.

agentmemory flips both. It does no background work, every write is synchronous, deletes are immediate and complete, and every prefetch writes a trace record (event_ids + summary + prompt) to $HERMES_HOME/agentmemory/trace.jsonl so the user can audit what entered the prompt.

Install

This is a standalone memory plugin. Hermes Agent stopped accepting new built-in memory providers — see CONTRIBUTING.md. The official path is to drop the plugin into the user-plugins directory that Hermes discovers automatically.

# 1. Clone into the user-plugins dir Hermes scans on startup
git clone https://github.com/MukundaKatta/hermes-agentmemory \
  "${HERMES_HOME:-$HOME/.hermes}/plugins/agentmemory"

# 2. Install the one Python dep used by the summarizer
pip install anthropic

# 3. Activate
hermes config set memory.provider agentmemory

# 4. Set the Anthropic key the summarizer will use
export ANTHROPIC_API_KEY=...

Hermes's discover_memory_providers() scans $HERMES_HOME/plugins/<name>/__init__.py for any class subclassing MemoryProvider, so no extra registration step is needed.

Configuration

Environment variables:

Var Default Purpose
ANTHROPIC_API_KEY (required) key for the on-demand summarizer
AGENTMEMORY_MODEL claude-sonnet-4-5-20251022 Claude model id
AGENTMEMORY_TOP_K 5 events to retrieve per prefetch
AGENTMEMORY_MAX_TOKENS 300 summary token budget
AGENTMEMORY_TRACE_LOG $HERMES_HOME/agentmemory/trace.jsonl where to append audit records

Tools the agent can call

  • agentmemory_recall(query, top_k?) — surface the top matching past events plus the event ids used.
  • agentmemory_forget(session_id?, event_id?) — real delete. No tombstone, no derived artifact left behind.
  • agentmemory_drift() — rolling-window retrieval-quality state, useful when recall starts feeling stale.

Auditing what the model saw

tail -f ~/.hermes/agentmemory/trace.jsonl

Every prefetch produces one JSON line: intent, event_ids, summary, and the live drift snapshot.

Trade-off, honestly

The first turn of every new session pays a 200ms-2s tax for the on-demand summary because there is no background pre-warming. In exchange you get:

  • deletes that are real and immediate
  • no quality decay from a smaller summarizer model (the summarizer is the same Claude family the agent uses)
  • a trace file the user can audit without touching the agent
  • < 600 lines of Python you can read end-to-end

For a self-hosted agent that markets itself as "the agent that grows with you", auditable memory is the part that lets growth stay reversible.

License

MIT.

See also