matebenyovszkyAgentPlaybooks Memory for Hermes
A native Hermes memory provider backed by AgentPlaybooks.
Remember durable facts across sessions, inspect and correct them in AgentPlaybooks,
and share selected knowledge with other agents through explicitly configured playbooks.
For playbook skills, MCP and OpenAPI tools, and authentication in Hermes, see
the AgentPlaybooks Tools plugin.
Install
On the gateway host/container, as the user running Hermes:
npm install -g @agentplaybooks/cli@0.8.1
apb memory setup PRIVATE_PLAYBOOK_GUID --target=hermes
apb memory setup PRIVATE_PLAYBOOK_GUID --target=hermes --apply
hermes memory setup
hermes memory status
Select agentplaybooks-memory in the Hermes setup wizard. Create a private playbook
and a playbook-scoped key with memory:read and memory:write in its Integrations
tab. Supply the key through Hermes's secret setup or the profile-scoped
AGENTPLAYBOOKS_MEMORY_API_KEY environment variable. The AgentPlaybooks CLI never
copies a credential. An account-management key is not a substitute for this key.
The CLI command is apb memory setup <guid> --target=hermes in a CLI release that
includes this provider. --profile=work selects a named profile; --profile=default
returns to the installation root even from another active profile. It honors HERMES_HOME; --hermes-home=<directory> selects
an explicit profile. Existing settings and different plugin files are reported as
conflicts. No existing memory is imported or overwritten.
Alternatively, install the Python package into Hermes's own Python environment:
python -m pip install ./packages/hermes-memory
hermes memory setup
The plugin is listed in the Hermes catalog and can be installed with
hermes plugins install agentplaybooks-memory. The catalog pins a reviewed source
commit. Direct repository installation also works with
hermes plugins install matebenyovszky/agentplaybooks/packages/hermes-memory/agentplaybooks.
Use --ref <full-commit-sha> to pin a direct installation, then run hermes memory setup.
Hermes discovers its hermes_agent.memory_providers entry point. The
catalog entry was
merged and is present in the live plugin catalog.
Requires Hermes 0.22.4 or later, with agent.memory_provider.MemoryProvider, profile-scoped
agent.secret_scope.get_secret, and authoritative memory-write provenance (previous_content). Tested
against the upstream revision recorded in this repository's compatibility workflow.
Hermes Desktop also presents native configuration fields for this provider. CLI
and Desktop share $HERMES_HOME/agentplaybooks/config.json and the profile's secret store.
What it does
- Recalls with up to four keywords across personal and team sources in parallel.
Four workers, a four-second deadline and an 8,000-character/eight-record limit
bound latency and context. Up to eight sources are searched; explicit tools
remain available for every configured source. Matching is lexical, not semantic. - Mirrored replacement/removal uses exact Hermes
previous_content. Missing or
ambiguous identity requires reconciliation and never mutates another entry. - Exposes
apb_memory_search,apb_memory_read,apb_memory_write,
apb_memory_archive,apb_memory_delete, andapb_memory_history. - Mirrors explicit built-in Hermes memory additions, replacements and removals.
The original entry key survives a replacement, preserving remote history. - Records agent, session, author, platform and source on writes.
- Keeps Hermes's built-in MEMORY.md and USER.md active. Correcting remote memory
does not rewrite those files: also correct a mirrored local entry with Hermes's
memory tool. Permanent forgetting must remove both copies; remote deletion also
deletes remote history. Archive retains content and is not forgetting.
The provider does not upload conversation transcripts, run automatic fact
extraction, import existing local memory, add embeddings, or implement a
persistent content cache, offline queue or automatic retries. A failed API operation is
reported, not queued for later delivery. The HTTP transport has a finite timeout;
Hermes itself supplies its normal external-provider execution deadline.
Only primary-agent contexts write. Session switches update provenance, and
per-turn author metadata follows gateway participants. One private playbook is the
memory boundary for a profile: everyone allowed to use that profile shares its
memory. Use separate profiles and private playbooks for users needing isolation.
Shared knowledge
Set shared_playbooks to comma-separated GUIDs in hermes memory setup, or pass
--shared=<guid>,<guid> to the AgentPlaybooks setup command. These are read-only
sources selectable with the memory tools' source argument; automatic recall
uses personal and configured team playbooks; read-only sources are queried explicitly.
For a private shared playbook, supply a read-only key using
AGENTPLAYBOOKS_SHARED_<GUID_WITHOUT_HYPHENS_UPPERCASE>_API_KEY in the profile's
secret environment. Public sources need no key. Personal credentials are never
sent to shared sources. Tags and metadata organize data; they are not access controls.
Personal writes are refused if the playbook is public or unlisted. Version 0.4.0
checks current private visibility and authenticated memory access in one small
request (GET /api/playbooks/:guid/memory?private_check=1&limit=1) before each
write and on first explicit read. Initialization is offline. Older servers that return an ordinary memory list retain
the anonymous metadata check: its expected 404 conceals a private playbook and is
not a failed memory read. The client identifies its requests with
AgentPlaybooks-Hermes-Memory/0.4.0 rather than Python's generic user agent.
Keep this playbook private: changing its visibility later
publishes existing contents according to the service's access model. Visibility
checks and writes are separate requests, not a transaction locking visibility.
Verify
Recall traffic and reconnection (0.4.0)
The default recall_mode is explicit: the provider searches only when an
apb_memory_* tool is called. Registration, initialization, session switching,
and unused prefetch callbacks make no network requests. Explicit Hermes memory
writes are still mirrored. Set recall_mode to automatic in the provider's
settings to opt into per-turn recall. It uses at most eight search requests,
four workers and a four-second budget, and suppresses the same query for 30
seconds. Query/result contents are not cached. A successful write invalidates
the query digest so the next recall can see the correction.
On HTTP 401/403 the client pauses authenticated requests for 60 seconds instead
of repeatedly calling with a rejected key. Update the profile's key/playbook in
Hermes memory setup, then restart that profile to bind fresh clients. Switching
profiles/users never reuses another provider's clients or recall state.
- Ask Hermes to save a new fact with
apb_memory_write. - Start a new session and read/search that key.
- Correct it in the AgentPlaybooks editor, then read it again from Hermes.
- Inspect history, archive it, and confirm normal search no longer returns it.
- Permanently delete it when finished.
Development tests use an HTTP fake of the existing REST API and do not touch a
real account. From the repository root:
python -m unittest discover -s packages/hermes-memory/tests -v
npm --prefix packages/cli test
License
MIT. The plugin has no third-party Python runtime dependencies beyond Hermes.
Avoiding unnecessary traffic (0.3.2)
There is no polling timer. Short English/Hungarian acknowledgements (including
köszönöm, rendben, and oké) skip automatic recall. The same query in the same
session and source set is suppressed for 30 seconds; only a bounded in-memory
digest is kept, and no recalled content is cached or replayed. A successful
explicit memory mutation clears this suppression. Explicit search/read tools
always remain available.
Automatic recall serializes keywords within each source while searching different
sources in parallel. A failed source stops immediately and is skipped for 60
seconds, so a failure does not fan out into four requests. Other sources continue.
The next user-triggered recall after that interval can try again; no background
retry is scheduled. Private visibility is still checked afresh before every write.
README from the reviewed commit b0b9bcc; it updates when the author re-pins.
