Experimental integration · merged, dispatch-layer tested

Mneme HQ + Hermes Agent

A thin plugin adapter carries Mneme’s decision corpus into Nous Research’s Hermes Agent: retrieved decisions are injected each turn through pre_llm_call, and supported mutations are checked before execution through a blocking pre_tool_call gate. Experimental against Hermes Agent 0.19.0; shell/process bypasses remain and no blocking Stop-equivalent is available.

Set up Mneme Evidence Running it across a team? Request a pilot →

Status: experimental, merged, bounded

The integration merged on August 25, 2026 (PR #329) and lives at mneme/integrations/hermes/ plus the standalone plugin directory integrations/hermes-plugin/. It is labeled experimental: all verification ran at the Hermes plugin dispatch layer (invoke_hook / resolve_pre_tool_block) against hermes-agent 0.19.0. Credential-backed live model sessions were not available in the probe environment and have not been replayed.

The claim, precisely: context injection and pre-tool enforcement for supported mutations. The adapter implements no governance semantics of its own — retrieval is the unchanged DecisionRetriever path shared with the Claude Agent SDK adapter, enforcement is the unchanged mneme check contract shared with the Claude Code hook, V4A patch parsing is the frozen Codex CLI transport parser, and shell preflight is ADR-021 class-A reconstruction reused as-is.

Architecture: two hooks, one corpus

pre_llm_call  (per turn)
   ↓
MemoryStore → DecisionRetriever → format_decisions
   ↓
{"context": ...} appended to the turn's user message

pre_tool_call  (blocking)
   ↓
ToolEvent translation → introduced-delta materialization
   ↓
mneme check --json
   ↓
trusted strict WARN/FAIL → {"action": "block",
"message": reason}; everything else passes untouched

Blocking requires a verdict the gate could parse and trust. Hermes swallows hook exceptions and ignores invalid directives, so the gate can only prevent what it deterministically evaluated — failures can never silently become blocks. Enforcement mode follows the shared resolution (MNEME_HOOK_MODE, then strict).

Coverage matrix

This integration is precise about what it prevents and what it does not:

Mutation surface	Pre-execution outcome
`write_file`	Blocked on violation. Full proposed content is present in the payload; introduced-delta checking applies unchanged (ADR-018).
`patch`, mode `replace`	Blocked on violation. Maps one-to-one onto the canonical Edit event.
`patch`, mode `patch` (Add / Update ops)	Blocked on violation. Parsed by the frozen Codex CLI V4A parser with current-file snapshots supplied per Update operation.
`patch`, mode `patch` (Delete op)	Skip by design (ADR-018): a pure deletion introduces no content. No delete-protection is claimed or provided.
`terminal`: single quoted-delimiter heredoc write	Blocked on violation. ADR-021 class-A reconstruction reused; no new shell interpretation.
`terminal`: redirects, `tee`, `sed -i`, `mv`, `rm`, compound commands	Bypassed pre-execution — classified only, never guessed. Classification does not block.
`execute_code`	Bypassed. Arbitrary Python file I/O; an unevaluated surface, characterized rather than governed.
`process` tool	Bypassed. Spawns arbitrary commands; discovered during the H0 registry sweep.
Sub-agents (`delegate_task`)	Unverified live. The hook fires again per child dispatch under the dispatch contract; confirmed only by contract reading until a credential-backed replay.
Completion time (session delta)	Not covered. Hermes has no blocking Stop-equivalent: `on_session_end` is observer-only, so nothing backstops this gate.

What this integration is not

No enforcement parity with Claude Code or Codex CLI. Those integrations implement ADR-021’s full prevent → catch → verify arc. Hermes currently supports only the prevent tier, plus guidance injection.
No session-delta backstop. Until Hermes exposes a blocking Stop-boundary primitive, anything that escapes pre-execution interception is caught by CI alone.
No live-session evidence yet. Dispatch-level findings are deterministic and reproducible; model-driven end-to-end sessions remain unproven until run with provider credentials.
No core changes. Adapter, tests, and docs only — no fork of Hermes core, no HTTP/MCP surface, no changes to retrieval, conflict detection, typed-rule matching, path applicability, or benchmark fixtures. The governance benchmark remains 7/7.

Install

Install the runtime: pipx install "mneme-hq>=0.5.1".
Copy integrations/hermes-plugin/ to <project>/.hermes/plugins/mneme/.
Make the mneme package importable from Hermes’ Python environment.
Enable project plugins and opt in — project plugins are opt-in even when the environment variable is set (verified against 0.19.0):
```
HERMES_ENABLE_PROJECT_PLUGINS=true
# plus plugins.enabled: [mneme] in Hermes config
```

Evidence

PR #329 — implementation, tests, and H0–H4 closeout record
docs/integrations/hermes.md — capability probe findings and bypass matrix
tests/integrations/hermes/ — context, gate, wiring, identity, and one end-to-end test through the real mneme check subprocess

FAQ

Which Hermes mutations are blocked before execution?

write_file, patch mode replace, patch mode patch Add/Update operations, and a single simple quoted-delimiter heredoc write through terminal. Everything else passes through unblocked — some surfaces are explicitly characterized as bypasses rather than guessed at.

Is there a Stop audit like Claude Code or Codex CLI have?

No. Hermes exposes no blocking Stop-equivalent — on_session_end is observer-only and its return value is ignored. There is no catch boundary behind this gate today; CI remains the only post-mutation verification.

What was actually tested?

Everything ran through Hermes’ real plugin-manager dispatch layer (invoke_hook / resolve_pre_tool_block) against hermes-agent 0.19.0: payload shapes, blocking directives for forbidden file content and forbidden heredocs, context-injection returns, and fail-open behavior. Live model-driven sessions were not available in the probe environment and are explicitly not claimed.

What happens if the checker itself fails?

The gate fails open — and by construction it can only fail open. Hermes swallows hook exceptions and ignores invalid directives, so a broken check degrades to an unblocked call; it can never be reported as governed-and-passing.

Deterministic guardrails inside Hermes Agent

Open-source. Repo-native. Context injection and pre-tool prevention over the same decision corpus — with every limitation on this page stated rather than implied.

GitHub All integrations