memory-rewind

memory-rewind

Automatic version history for a Hermes agent's own knowledge — memories/MEMORY.md,
memories/USER.md, SOUL.md and the skills/ tree (including curator-archived
skills) — with commands to browse, diff and restore any past version.

Hermes rewrites these files while it works: the memory tool edits the memory store,
skill_manage creates and edits skills, the curator archives and consolidates them.
None of those writes keeps a history, so a truncated MEMORY.md, a skill edited into
a broken state, or an archived skill that will not come back has nothing to roll back
to. memory-rewind records every change as it happens and lets you put any file or
skill back exactly as it was.

Install

hermes plugins install AhmetArif0/hermes-memory-rewind#memory-rewind --enable

Requires Hermes 0.21.5 or newer and git on PATH. Restart a running gateway
(hermes gateway restart) so it loads the plugin. History starts with the next session.

Use

hermes memory-rewind log                        # recent versions of everything
hermes memory-rewind log memory                 # versions of memories/MEMORY.md
hermes memory-rewind log skills/research/arxiv  # versions of one skill
hermes memory-rewind show <version> user        # memories/USER.md at a version
hermes memory-rewind diff <version> memory      # what changed since a version
hermes memory-rewind restore <version> memory   # put MEMORY.md back (asks first)
hermes memory-rewind restore <version> skills/research/arxiv --yes
hermes memory-rewind snapshot -m "before cleanup"
hermes memory-rewind status
hermes memory-rewind forget --yes               # delete the whole history

memory, user and soul are shortcuts for memories/MEMORY.md,
memories/USER.md and SOUL.md. Versions are the ids printed by log
(HEAD, HEAD~1, … also work). Commands act on the active profile
(hermes -p <profile> memory-rewind …).

log shows what produced each version:

$ hermes memory-rewind log user
3f2a9c1b7e  2026-09-27 14:05  after memory  (1 file)
    via   memory: remove, add (user)
    from  telegram, session 20260927_140012_ab12cd
    M  memories/USER.md

via names the tool call: the tool, its actions, and the memory target or skill
names, with [error] (or [blocked], [timeout], …) when the call did not succeed.
from names the session and, when Hermes reported it, the platform.

From a chat

/memory-history shows the same history from any chat: Telegram, Discord and other
gateway platforms, the Desktop app, the TUI and the CLI chat. It is read-only.

/memory-history                          the last 10 versions
/memory-history user                     versions of USER.md (also memory, soul, skills/<path>)
/memory-history <version> [target]       what that version changed

Viewing never records a version. Restoring stays a host command; the version view prints
the exact hermes memory-rewind restore … line to run. Replies are plain text and at most
3,000 characters, and a reply never includes host paths or raw git errors.

Every restore records the current state first and prints the command that undoes it.
Built-in memory is loaded when a session starts, so a restored MEMORY.md/USER.md
takes effect in the next session (/new).

What is recorded

| Recorded | Never recorded |
|---|---|
| memories/MEMORY.md, memories/USER.md | .env, auth.json, keys and certificates, database files |
| SOUL.md | skills/.hub/ (hub lock, audit log, cache, quarantined skills) |
| skills/**, including skills/.archive/ | skills/.usage.json, curator ledger, state and backups, bundled-skill manifest |
| | Hermes lock files (skills/.locks/, skills/.usage.json.lock) |
| | symlinks, embedded git repositories, caches, files larger than max_file_kb |

A version is recorded when a session starts and when each turn starts (baselines
before anything can change), after each memory or skill_manage call (and file edits
that target these paths), and at the end of each turn to catch changes the turn made
outside tools (terminal edits). Unchanged state records nothing. Each version notes the
tool calls and sessions behind it; the file list shows what actually changed. Changes
made between turns, such as a staged write approved with /memory approve, a curator
run or an edit in the Desktop app, land in the next session start or turn start
version, which names no call or session.

History is a bare git repository at
~/.hermes/plugin-data/memory-rewind/history.git (per profile). It is isolated from
your own git setup: your global config, hooks and signing are never used.

Settings

Set in the Desktop Plugins tab, or in config.yaml:

plugins:
  entries:
    memory-rewind:
      settings:
        enabled: true        # record new versions automatically
        track_skills: true   # version skills/ (including .archive)
        track_soul: true     # version SOUL.md
        max_file_kb: 1024    # skip larger files

Security and footprint

• No network access, no downloads, no self-update, and no Python dependencies
  (standard library only). The only external program is the local git binary.
• What it registers: the hooks on_session_start, pre_llm_call, post_tool_call
  and on_session_end, the hermes memory-rewind command, and one read-only slash
  command, /memory-history. It gives the model no tools. register() only
  registers; it does no I/O. The pre_llm_call callback declares only the session id
  and platform, so Hermes never passes it the user message or the conversation, and it
  returns nothing, so nothing is added to the prompt.
• What it reads: memories/MEMORY.md, memories/USER.md, SOUL.md and skills/
  (minus the exclusions above), plus its own settings. It never opens .env,
  auth.json, databases or skills/.hub/. From hook payloads it keeps only the tool
  name, action names, memory target, skill names, call outcome, session id and platform,
  never message or file content.
• What it writes: only $HERMES_HOME/plugin-data/memory-rewind/ (the history
  repository and an index cache). Tracked files are written only when you run
  restore, and forget deletes only the history.
• How git runs: against its own bare repository, with your global and system git
  config, hooks, signing and pager ignored, literal pathspecs, a 60-second timeout,
  and background gc detaching disabled.
• When it runs: a synchronous baseline when a session starts and when each turn
  starts (about 40 ms once history exists; the very first one records the whole skills
  tree and took 0.7 s on a 1,100-file tree), and background snapshots after
  memory/skill_manage calls and at the end of each turn. On exit, a queued
  snapshot gets up to 5 seconds to finish.

Privacy

History keeps what the files contained. If you ask the agent to forget something,
the removal is recorded, but older versions still contain it. Versions also note session
ids, platforms and skill names. A /memory-history reply in a group chat is visible to
everyone in it, including what a version changed in memory. Run
hermes memory-rewind forget --yes to delete the history for the active profile.

Limits

• External memory providers (Honcho, Mem0, …) store data outside these files and are
  not covered.
• Restore is a command you run on the host; the agent has no tool to rewrite history or
  restore, and /memory-history cannot restore.
• Snapshots after a call and at turn end run in the background and usually land within a
  fraction of a second. A change something else makes in that window, or while a turn is
  running, is recorded with that call or turn.

How it works

See docs/DESIGN.md.

Development

python -m pytest tests/                                   # unit tests (no Hermes needed)
PYTHONPATH=/path/to/hermes-agent python -m pytest tests/  # plus end-to-end tests against Hermes

The end-to-end tests load the plugin through Hermes' real plugin manager, drive the real
memory tool and hook dispatch, run the hermes CLI, and check that separate profiles
keep separate histories.

Changes

• 1.3.2: Fix: restore could replace what a running agent had just written. It
  now applies only the plan it showed: it holds the memory tool's own lock on MEMORY.md
  or USER.md while it checks and writes, and it refuses when a file changed after the
  plan was made (for example, a gateway session stored a memory while you read the plan;
  run the command again to see the new plan). For a memory file the plan also lists the
  entries the restore brings back and the entries it removes: restoring the file to bring
  back one deleted entry also removes the entries added after that version.
• 1.3.1: Fix: importing a Hermes backup (hermes import, also what the dashboard's
  import runs) put the backup's copy of the history back over the live one. Every version
  recorded after the backup, including the state right before the import, dropped out of
  log, and git later deleted it for good. Each version now leaves a small marker, so
  those versions stay in the history and the import itself is recorded as a change that
  restore can undo. This protects any import made after 1.3.1 has run once (a session
  start is enough), whichever version made the backup.
  The design-notes link on the plugin page works again.
• 1.3.0: Fix: changes made outside the agent's turns were credited to whatever
  came next. With memory.write_approval on, a write approved with /memory approve
  appeared as the agent's next memory call (for example via memory: remove on a
  version that added an entry), and a skill the curator archived appeared as the next
  session's work. Each turn now starts with a baseline, and the session-start baseline
  names no session, so these changes land in a turn start or session start version
  that names no call or session.
• 1.2.0: /memory-history shows the history from any chat surface (gateway platforms,
  Desktop, TUI, CLI chat): recent versions, the versions of one file or skill, and what a
  version changed. It is read-only and follows the profile of the chat it runs in.
  Fix: some edits were missed. If an edit kept a file's size and landed in the same
  second as the previous snapshot, it could go unrecorded, and the newest version then
  kept the old content.
• 1.1.0: log shows what produced each version: the tool call (tool, actions,
  memory target or skill names, and the outcome when it did not succeed) and the
  session and platform. Hermes' skill lock files and curator/Termux state files are no
  longer recorded. Before, every skill_manage call added a version holding only a
  lock file. Older versions that contain them never restore them. After upgrading,
  the first new version lists them as removed from the history; the files on disk
  are not touched.
• 1.0.0: first release.

License

MIT

README from the reviewed commit 3549271; it updates when the author re-pins.