# hermes-plugin-perseus-vault

Perseus Computing LLC **memory provider plugin** for [[hermes-agent]]: connects Hermes to a Perseus Vault MCP endpoint so durable memory can be shared across Hermes instances. Not the Vault binary itself — see [[perseus-vault]].

Tags: hermes-agent, plugin, mcp, agent-memory, perseus-vault

## Summary

Install: `hermes plugins install Perseus-Computing-LLC/hermes-plugin-perseus-vault` then `hermes memory setup` (pick `perseus-vault`). `plugin.yaml` version **1.1.0**; MIT; Copyright (c) 2026 Perseus Computing LLC. Python. GitHub: 1 star, 1 fork, **no releases**. Created 2026-07-19; last push 2026-08-10 22:46 ET.

Requires env `PERSEUS_VAULT_MCP_TOKEN`. Default URL `https://vault.perseus.observer/message` (hosted). Self-hosted Vault is supported; override `PERSEUS_VAULT_URL`. Token is never read from `mcp_servers`.

## What it adds vs plain MCP

Vault can already be registered in Hermes as a local stdio MCP server (`perseus-vault serve`). This plugin is the **memory provider** path:

- Prefetch recall before each turn (`recall_when` + keyword), with lifecycle-safe invalidation
- Session-end distillation into Vault entities (**primary sessions only**; cron/subagent excluded)
- Mirror writes to Hermes `MEMORY.md` / `USER.md`
- Explicit tools: `perseus_remember`, `perseus_recall`, `perseus_forget`
- Persistent streamable-HTTP MCP session; reconnects on errors
- Optional Authorized Action Receipts: `PERSEUS_VAULT_AUTHORITY_MODE` = `off` | `shadow` | `enforce`
- Optional resource-bound constraints (repo/env/destination/payment fields)
- Optional hash-only ledger provenance (`LEDGER_PROVENANCE_URL` + `LEDGER_API_KEY`); fail-open

`kind: standalone`; `provides_hooks: tool_execution`; pip dep `mcp`.

## Security notes (from README)

- Never hardcode the bearer token in `config.yaml` or the plugin directory.
- Never store secrets in the Vault.
- AAR evidence is hash-only (no raw commands/args/credentials).
- Start AAR in `shadow`; `enforce` fail-closes on missing/mismatched authority.
- Forget cannot retract tokens already delivered to the model.

Hosted-endpoint data handling: **unknown** (not on this README). Local Vault privacy policy does not automatically cover `vault.perseus.observer`.

## Open tracker (as of 2026-08-13)

- PR #21: memory-bank scoping via `.hermes.md` (open)
- #17 recall-first / store-last agent behavior
- #16 distinguish recall outage vs timeout vs partial vs stale vs empty

## Related

- [[perseus-vault]] (binary, perseus-ctx, how the family connects)
- [[hermes-agent]]
- [[youtube-hermes-desktop-plugins]] (Desktop *UI* plugins — different surface)
- [[youtube-hermes-kanban-multi-agent]] (Kanban coordination — different surface)
- raw/`perseus-vault-2026-08-13/`

## Sources

- https://github.com/Perseus-Computing-LLC/hermes-plugin-perseus-vault
- https://raw.githubusercontent.com/Perseus-Computing-LLC/hermes-plugin-perseus-vault/main/README.md
- plugin.yaml, after-install.md, docs/clients.md, LICENSE via GitHub Contents API (2026-08-13)