Q & Hermes

Hermes Phase 3 — Vault Brain

Owned-lane vault reads and writes for Hermes, plus an OpenRouter resilience fallback — solved with disjoint paths, not locks.

Dated 2026-06-14Programme Q & Hermes

Situation

Phase 3 gives Hermes a vault brain: it can read the Obsidian vault for recall and write notes back into its own owned lane, safely, without ever racing the Hub's frequent writes (context-push runs roughly every 15 minutes). It also adds OpenRouter as a resilience fallback so Hermes isn't single-pointed on Claude.

The vault is a git repo the Hub already commits to constantly, so non-fast-forward pushes are the *normal* case, not an edge case — the retry helper has to be robust. Anything Hermes writes under Hermes/ is also picked up for free by the Hub's existing vault-sync job, making it searchable from Mallory's edge recall.

Key decisions

Scope: in vs. deferred

In: vault recall, owned-lane writes, a TDD'd git rebase-push helper, a Hermes skill, OpenRouter fallback. Out: local vLLM/GPU passthrough and cost-based model routing — a later model-strategy phase.

One writer per path

The Hub keeps its existing paths (_generated/…, needs-response.md, etc.); Hermes gets a new Hermes/ namespace (Memory/, Dev/, Notes/) — enforced in code by vault_guard_path, not by convention alone.

Retry-on-non-fast-forward, not locking

vault_push loops up to N=5 attempts: pull --rebase --autostash, push, retry on non-ff. Disjoint paths guarantee rebases only reorder commits, never conflict content.

~/.hermes stays canonical agent memory

The vault is the *shared* knowledge base Hermes contributes notes into — complementary to, not a replacement for, Hermes' own SQLite memory.

OpenRouter as a fallback chain, not primary

hermes fallback add configures a fallback (e.g. claude-sonnet-4.6 then deepseek-chat via OpenRouter) so a Claude rate-limit/outage fails over instead of erroring.

Architecture

A pure bash helper library, offline-TDD'd, sitting between a Hermes skill and a working clone of the vault.

tower/vault_lib.sh

vault_guard_path, vault_pull, vault_search, vault_write, vault_push (retry loop), with_vault_lock (flock) — the tested helper, sourced by the skill/CLI.

tower/tests/vault_lib.test.sh

Offline bash unit tests: guard accepts/rejects paths, push retries on stubbed non-ff, write rejects out-of-lane paths before any git op.

~/.hermes/skills/vault/

Tells Hermes to call vault_search for recall and vault_write under Hermes/{Memory,Dev,Notes}/ — never elsewhere.

Vault working clone

~/repos/obsidian-vault on the Tower, pulled before every recall so reads see Hub-written notes too.

OpenRouter fallback config

hermes fallback add wiring a Claude/OpenRouter fallback chain, verified with hermes fallback list.

Risks & guardrails

Push races are frequent, not rare

Mitigated by the rebase-retry loop; disjoint paths guarantee the rebases stay clean.

LLM writes a bad path

vault_guard_path hard-rejects anything outside Hermes/ before any git operation runs.

Concurrent Hermes tasks

with_vault_lock wraps mutating ops in flock so Hermes' own tasks serialize against each other.

Clone drift / staleness

vault_search always pulls first, so recall reads current data.

gh token scope

Needs Contents R/W on obsidian-vault; the alexhansford login's repo scope already covers it.

Delivery

Helper TDD

Write vault_lib.sh + tests red→green in mallory-runtime, PR, merge.

Tower setup

Clone the vault, seed the Hermes/ namespace, pull the merged helper, add the Hermes skill.

Fallback config

hermes fallback add OpenRouter, verified via hermes fallback list.

Verify end-to-end

Unit tests green; a Hermes-driven round-trip searches the vault and writes a Hermes/Notes/ note that reaches origin/main (and D1 after vault-sync).

Out of scope

Local vLLM / GPU passthroughCost-based model routing (cheap subtasks to cheaper models)

spec · docs/superpowers/specs/2026-06-14-hermes-phase3-vault-brain-design.md
plan · docs/superpowers/plans/2026-06-14-hermes-phase3-vault-brain.md

Mallory · Estate briefing