Hermes Agent integration

August 17, 2026 ยท View on GitHub

Perseus Vault is distributed as a standalone Hermes memory-provider plugin. The standalone repository is the source of truth; Hermes core does not need a Perseus-specific patch to discover or configure it.

Installation and setup

hermes plugins install Perseus-Computing-LLC/hermes-plugin-perseus-vault
hermes memory setup
hermes memory status

The provider is selected as memory.provider: perseus-vault. The bearer token belongs in the active profile's .env; endpoint, workspace, and behavioral settings belong in config.yaml or the provider's setup surface.

Hermes contract exercised

The provider implements the Hermes MemoryProvider lifecycle and uses the following integration points:

  • get_config_schema() / save_config() for profile-safe setup;
  • initialize() / shutdown() for the MCP transport lifecycle;
  • prefetch() and queue_prefetch() for relevant context before a turn;
  • sync_turn() using a non-blocking background buffer;
  • on_turn_start() for session and memory-bank resolution;
  • on_session_end() for scoped primary-session capture;
  • on_memory_write() to mirror built-in MEMORY.md / USER.md writes;
  • a static, curated tool schema rather than the full Vault administration surface.

No Hermes core files are modified by this repository.

Isolation and data handling

  • Every provider storage/configuration decision uses the active HERMES_HOME.
  • A .hermes.md or HERMES.md file can select a deterministic memory_bank workspace, keeping projects or clients isolated without duplicating Hermes profiles.
  • Automatic prefetch and session capture send data to the configured Vault MCP endpoint. Operators choose the endpoint and can run Vault themselves.
  • The token is read from the environment or profile .env, never from Vault memory or checked-in configuration.
  • Authorized Action Receipt enforcement is opt-in. The default is off; shadow mode is available for observation, and enforce mode fails closed when the authority manifest, scope, lease, or approval is missing.
  • Optional Ledger serve-provenance records only a hash-only, non-blocking digest of served memory. It never sends raw recalled text as evidence.

Verification

The repository's provider suite runs against both the system Python toolchain and Hermes' managed runtime. The current suite contains 115 tests covering standalone discovery, configuration precedence, profile/bank isolation, context freshness, lifecycle invalidation, tool gating, AAR behavior, and hash-only provenance. CI runs the suite on Python 3.11 and 3.13 against a fresh Hermes checkout.

PYTHONPATH=/path/to/hermes-agent:$PYTHONPATH \
  python -m unittest discover -s tests -p 'test_*.py'

Maintenance commitment

Perseus Computing LLC maintains this adapter independently of Hermes core. A provider update is released as a new immutable commit/version; integration changes are tested against the current Hermes source before publication. The adapter remains within the public MemoryProvider contract and avoids Hermes-specific changes outside that contract.

Upstream tracking: