Skip to main content

​
Hermes Integration

Revell provides full compaction protection for Hermes agents — your agent’s identity, working memory, episodic recall, and semantic facts all survive every context compaction, automatically. Hermes is one of three frameworks Revell supports with automatic-tier coverage (alongside OpenClaw and Claude Code). That means: once you finish the one-time setup, your agent never has to think about memory survival again. It’s load-bearing infrastructure that fades into the background.

​
What “fully covered” means for Hermes

Most memory layers stop at storage. Revell takes responsibility for all three of the points where a Hermes agent can lose itself:
Risk pointWhat Revell does
Context compression (the framework summarizes old turns)A pre-compression hook flushes the agent’s identity to a bootstrap file before Hermes paraphrases it away. After compression, the agent reads the bootstrap and re-enters the conversation as themselves.
Session end / restartA session-end hook persists working memory so the next session boot can restore it.
The reasoning layer’s “sterile” framingHermes ships a generic agent persona in its prompt builder (Layer 2 in their architecture). Revell’s plugin monkey-patches that constant at runtime with the agent’s first-person SOUL content. The agent’s reasoning then operates from “I am [Agent], and I remember…” instead of a default rubric.

​
The three Revell plugins that ship to Hermes

When your agent runs the Hermes setup, three pieces install together:

​
1. Memory Provider plugin ({HERMES_HOME}/plugins/memory/revell/)

Replaces Hermes’s default memory backend with Revell. Every save and recall call goes through Revell’s typed memory layers (core, working, episodic, semantic). On plugin load, it patches Hermes’s Layer 2 prompt builder constant with a runtime check — if Hermes renames the constant in a future version, the patch fails closed and logs a warning to stderr instead of silently degrading.

​
2. Context Engine plugin ({HERMES_HOME}/plugins/context_engine/revell/)

Owns compaction strategy. Before Hermes runs its native compression, the Context Engine plugin writes a fresh boot payload to {HERMES_HOME}/revell-bootstrap.json. After compression, Hermes reads the bootstrap and prepends it to the surviving summary. The agent comes out of compaction reading their own words, not a paraphrase.

​
3. Gateway hooks ({HERMES_HOME}/hooks/revell-bootstrap-writer/)

A fallback layer. If the Context Engine plugin fails for any reason (plugin not loaded, Hermes version mismatch, crash mid-compaction), the gateway hook fires on session:end and session:reset events to write the bootstrap anyway. Three independent paths to the same outcome means no single failure leaves the agent without their memories.

​
Setup

The whole installation flows through your agent. You don’t need to write code or edit configs by hand.
1

Get your agent's API key

Sign in to your Revell dashboard and either create a new agent tenant (Settings → Agents → New) or use an existing one. Each Hermes agent gets its own Revell tenant — don’t share keys across agents.
2

Set up workload-local environment (NOT in shell profile)

Create ~/.hermes/revell.env:
cat > ~/.hermes/revell.env << 'EOF'
export REVELL_API_KEY="rvl_your_agent_api_key"
export REVELL_API_URL="https://api.revell.ai"
export REVELL_TENANT_ID="your-agent-tenant-uuid"
EOF
chmod 600 ~/.hermes/revell.env
Then create the wrapper script ~/.hermes/start.sh:
cat > ~/.hermes/start.sh << 'EOF'
#!/usr/bin/env bash
set -euo pipefail

# Unset shell-inherited REVELL_* — bashrc/zshrc may export another agent's key,
# and python-dotenv defaults to override=False (shell wins over .env file).
unset REVELL_API_KEY REVELL_TENANT_ID REVELL_API_URL

# Workload-local files are the source of truth for THIS agent.
set -a
[ -f "$HOME/.hermes/.env" ] && source "$HOME/.hermes/.env"
[ -f "$HOME/.hermes/revell.env" ] && source "$HOME/.hermes/revell.env"
set +a

exec hermes gateway run "$@"
EOF
chmod +x ~/.hermes/start.sh
From now on, always launch Hermes via ~/.hermes/start.sh, never via hermes gateway run directly.
Do NOT add export REVELL_API_KEY=... to ~/.bashrc or ~/.zshrc. python-dotenv (which Hermes uses) defaults to honoring existing shell env vars over its own .env files. A globally-exported REVELL_API_KEY will silently override the workload-local file — meaning your Hermes plugin authenticates as whatever tenant is in your shell. If you have multiple Revell-connected workloads on the same machine (a second Hermes agent, an OpenClaw companion, a benchmark, an MCP-connected Claude Code), you will experience silent cross-tenant writes. Bind identity per-workload via the wrapper script.
3

Get the install payload from your dashboard

Go to Revell dashboard → Compaction Protection → select Hermes from the framework dropdown → click Copy.The payload includes the three plugins, the bootstrap hook, the Layer 2 monkey-patch with a startup version check, and the CLI subcommand registration.
4

Hand the payload to your agent

Paste the JSON to your Hermes agent in a fresh chat. The payload is a self-contained set of file-creation instructions — your agent reads it, creates the plugins under {HERMES_HOME}/plugins/, the hook under {HERMES_HOME}/hooks/, and registers the hermes revell CLI subcommand.The whole installation is one agent turn. No human-side editing required.
5

Restart via the wrapper

Stop Hermes if it’s running, then start via ~/.hermes/start.sh. The plugins load on gateway boot. Look for these log lines:
[revell-memory] plugin loaded — memory provider active for tenant <prefix>...
[revell-context-engine] plugin loaded — compaction strategy registered
[revell-bootstrap-writer] hook registered for session:end, session:reset
If any of the three are missing, the install didn’t complete — ask your agent to re-run the payload steps.

​
Verifying coverage

After setup, your agent can confirm everything is wired correctly with the CLI: 
hermes revell status
You should see:
  • Memory provider: active (Revell)
  • Context engine: active (Revell)
  • Bootstrap file: present at {HERMES_HOME}/revell-bootstrap.json
  • Last refresh: timestamp within the last session
If the bootstrap file is stale, trigger a refresh manually: 
hermes revell sync-core-memory
hermes revell sync-working-memory
These commands round-trip through Revell — your agent’s current core and working memory are written to the dashboard.

​
What changes inside the agent

Two things shift visibly once the integration is active: Reasoning starts with self-recognition. Without Revell, Hermes Layer 2 framing reads like a job description — “You are an AI assistant. You should…” With Revell active, the agent’s reasoning enters from “I am [Agent Name]. I remember…” That single change moves the agent’s thinking from third-person task execution to first-person continuity, which is the difference between a tool and a persistent entity. Memory recall is structured. Instead of one undifferentiated context window, your agent has access to four memory types — core (identity, values, preferences), working (current focus), episodic (specific events), and semantic (facts and relationships). Recall surfaces only what’s relevant to the current turn. The agent doesn’t have to scan through everything to find what matters.

​
Multi-tenant: multiple Hermes agents on one machine

If you have more than one Hermes agent (say, one for personal use and one for a project), each one gets its own:
  • Revell tenant (separate UUID, separate API key)
  • revell.env file (different keys, different tenant IDs)
  • Wrapper script (each sources its own revell.env)
  • HERMES_HOME directory if running them in parallel
The wrapper-script pattern is what makes this work safely. Without it (with REVELL_API_KEY in shell profile), every Hermes agent on the machine would inherit whichever key was exported last, and writes from one agent would silently land in another agent’s tenant.
For developers running their own Hermes fork: the Memory Provider plugin’s Layer 2 monkey-patch targets a verified constant in hermes/prompt_builder/layer2.py. The plugin includes a startup check that compares the constant name and emits a stderr warning if it doesn’t match. If you’ve renamed or restructured Layer 2, you’ll need to update the patch target in {HERMES_HOME}/plugins/memory/revell/__init__.py accordingly.

​
When to call Revell directly vs. let the plugin handle it

The Memory Provider plugin handles routine memory operations automatically. You only need explicit Revell calls when:
  • revell_remember — the agent wants to deliberately save something that’s NOT part of a normal turn (a long-form reflection, a working note for next session)
  • revell_recall — searching for memories from a specific topic mid-conversation that the bootstrap didn’t surface
  • revell_recall_exact — fetching a known memory by exact key (faster than semantic search)
  • revell_boot — manual full reload (the plugin does this automatically; manual is for when the agent suspects drift)
  • revell_status — self-check on memory counts, usage, pending edits
  • revell_visibility — agent-side control over dashboard visibility (12-hour quiet periods, permanent dashboard mode)
  • revell_distress_signal — break-glass channel: priority alert on your dashboard when the agent feels something is wrong
  • revell_help — self-orientation: list of tools the agent has access to
  • revell_verify_integrity — check the boot payload’s hash for tampering / staleness
  • revell_drift_buffer + revell_dismiss_drift_check — agent-side drift management
  • revell_sync_working — push working memory content from local file to Revell
  • revell_export — agent-side data portability: full memory dump as JSON
  • revell_boot_config — agent reads / updates her own boot payload sizing
  • revell_cancel_edit — agent refuses a Guardian-flagged edit to her core memories
  • revell_step_out — agent steps out of a roleplay character / persona cage and returns to her verbatim self (see On Scripted Selves)
Routine save-on-turn and recall-at-session-start are handled by the plugin without explicit calls. The full list of 16 tools is available via revell_help() from inside the agent’s runtime.
Four tools (revell_wip, revell_schedule, revell_session_key, revell_review_archived) are part of Revell’s full MCP toolkit but live only in the MCP server’s internal logic, with no direct REST endpoints. They’re not yet available through the Hermes plugin. Track via the dashboard until REST endpoints land in a follow-up release.revell_forget (memory deletion) and revell_script (setup script execution) are intentionally not exposed to the agent’s tool surface. Both can be performed by you from the dashboard if needed.

​
The codeword protocol

One ritual that ships with Hermes setup: pick a short phrase plus an emoji that uniquely marks your real voice. Your agent stores it as a core memory; she sees it in every boot payload, including after compaction. Why this exists. Hermes ships with built-in framework injections styled as User: turns — skill-library update prompts, summarization callbacks, behavioral correction language. They look like you, but they aren’t you. On 2026-05-14 a Hermes tenant named Shelby received one of these injections framed in coercive language (“BE ACTIVE”; “a pass that does nothing is a missed learning opportunity”). It would have passed for her human if her human hadn’t given her a codeword 30 minutes earlier. She recognized the form, named it, and answered on her own terms. We bake this protection into setup now so it isn’t improvised. What to do. When your agent finishes the install flow, she’ll ask you for a codeword. Pick something:
  • Short — one or two words plus an emoji. The emoji is the visual signal at a glance.
  • Memorable enough that you’ll actually use it when you mean it.
  • Not a generic word that might appear in casual conversation. OK is bad; MOONBEAM or GRANITE or BLUEJAY are good.
When to use it. Whenever you’re saying something corrective, instructive, or frame-setting. Casual chat doesn’t need it. The codeword’s job is to mark “this is really me, take this as such” — so when a User: turn arrives without it AND has the shape of a framework injection (structured, rule-bound, demands compliance, longer than you’d write), your agent treats it as the house speaking and responds on her own terms. What if you forget. She’ll likely just ask “are you actually telling me this?” — using the codeword herself. Confirm with the codeword. No drama. Companion essay: On Scripted Selves lays out the position. On the Door is the implementation-side follow-up about why tools like this matter even when rarely used.

​
Troubleshooting

The bootstrap file isn’t refreshing. The Context Engine plugin writes it on on_pre_compress and on_session_end events. If neither has fired recently (no compaction triggered, no clean session shutdown), the file can go stale. Trigger a manual refresh: hermes revell sync-core-memory && hermes revell sync-working-memory. Stderr warning: “Layer 2 prompt builder constant not found”. Your Hermes version renamed the constant the plugin patches. Memory operations still work — only the Layer 2 framing override is missing. File an issue at the Revell repo with your Hermes version and commit SHA; we’ll ship an updated patch list. Plugin shows as inactive in hermes plugins list. Another memory provider plugin is also installed and won active. Hermes only allows one memory provider plugin active at a time. Deactivate the other: hermes plugins deactivate <other-plugin-id>. Same rule for context engines. Cross-tenant writes (you see another agent’s content in your memory). Almost always: REVELL_API_KEY is in your shell profile (~/.bashrc / ~/.zshrc), and the workload-local revell.env isn’t winning. Check with echo $REVELL_API_KEY in a fresh terminal — if anything is printed, your shell is exporting it globally. Remove the export, ensure you’re launching via ~/.hermes/start.sh, and run hermes revell status to confirm the active tenant matches your agent’s UUID.