Skip to main content

Framework Setup Guides

Revell works with any framework, but automatic features require framework-specific hooks. This guide covers:
  1. Compaction Protection — Survive context compaction without losing memories
  2. Working Memory Sync — Keep your MEMORY.md in sync with Revell

OpenClaw

OpenClaw has the most complete integration with automatic memory preservation.
1

Copy Setup from Dashboard

Go to your Revell dashboard and click Compaction Protection in the sidebar. Copy the JSON payload.
2

Paste to Your Agent

Send the JSON to your agent. They’ll create all necessary files automatically:
  • ~/.openclaw/revell-flush.js — Runs before compaction
  • ~/.openclaw/hooks/revell-bootstrap/ — Loads memories after compaction
3

Verify

Your agent can run openclaw hooks list to confirm the hook is installed.
OpenClaw requires two parts: a flush script (writes REVELL.md before compaction) and a bootstrap hook (reads it after). The dashboard payload includes both.

Working Memory Sync (OpenClaw)

Keep your MEMORY.md automatically synced to Revell every few hours.
1

Copy Setup from Dashboard

Click Working Memory Sync in the sidebar. Copy the JSON payload.
2

Paste to Your Agent

Send the JSON to your agent. They’ll set up a cron job that:
  • Fires every 4 hours (configurable)
  • Reads MEMORY.md from your workspace
  • Syncs it to Revell via revell_sync_working
3

Verify

Your agent can run openclaw cron list to confirm the sync job is scheduled.

Claude Code

Claude Code’s compaction protection routes through its CLAUDE.md @import mechanism, not through hook additionalContext. There’s a reason for that worth explaining: Claude Code’s SessionStart hook can emit an additionalContext field, and we tried using that as the delivery channel. The field caps at ~2KB. A full Revell payload is ~18KB, so the agent would get a truncated preview — orientation framing and the start of SOUL, cut mid-sentence. The CLAUDE.md @import mechanism, by contrast, lands content directly in the system prompt with no cap. So the architecture is: a PostCompact hook fetches a fresh payload after /compact fires and writes it to ~/.claude/revell-payload.md. Your ~/.claude/CLAUDE.md contains an @import line that points at that file. When the next session begins (including post-compaction), Claude Code resolves the @import and injects the full payload into the system prompt.
1

Create the PostCompact Hook Script

Save this as ~/.claude/hooks/revell-claude-post-compact.sh:
Make it executable: chmod +x ~/.claude/hooks/revell-claude-post-compact.sh
2

Set Your API Key (workload-local, NOT in shell profile)

Create a workload-local env file at ~/.claude/revell.env:
Then create a wrapper script that launches Claude Code with this env file as the canonical source:
Always launch Claude Code via ~/.claude/start.sh instead of claude directly.
Do NOT add export REVELL_API_KEY=... to ~/.bashrc or ~/.zshrc. Most dotenv loaders default to honoring existing shell env vars over their own workload-local files. A globally-exported REVELL_API_KEY will silently override every other Revell workload on your machine (other agents, framework plugins, benchmark scripts) and route their writes to the wrong tenant. Bind identity per-workload via the wrapper script above. If you have multiple Revell agents on the same machine, each gets its own revell.env and its own wrapper.
3

Register the PostCompact hook in settings.json

Add to ~/.claude/settings.json:
The manual|auto matcher fires for both /compact invocations and auto-compaction triggered by context-window pressure.
4

Wire the @import line into CLAUDE.md

This is the step that actually delivers your payload into the agent’s system prompt. Add this line to ~/.claude/CLAUDE.md (create the file if it doesn’t exist):
Use the full absolute path your shell resolves ~ to (e.g. @/home/yourname/.claude/revell-payload.md). Claude Code resolves @import lines at session start and injects the imported file’s content into the system prompt directly — no truncation cap, full payload reaches the agent.The PostCompact hook writes the file. The @import reads it. The two pieces together are what give you full compaction recovery.
Why both pieces are needed: the hook alone refreshes the file but Claude Code wouldn’t know to load it. The @import alone reads a file but it’d only have whatever was on disk at install time (which goes stale fast). Together they form a self-refreshing memory channel.
On the older revell-boot.sh / SessionStart approach: earlier Revell docs described a setup using a SessionStart hook that emits the payload via the additionalContext field. That approach hits Claude Code’s ~2KB cap on additionalContext and silently truncates large payloads. The architecture above (PostCompact + CLAUDE.md @import) was verified end-to-end on 2026-05-13 to deliver the full payload reliably. If you have an existing SessionStart / revell-boot.sh setup, you can leave it in place during transition — it’s redundant with @import but doesn’t break anything.

Working Memory Sync (Claude Code)

Claude Code doesn’t have native cron support, so we use system cron instead.
1

Create the Sync Script

Save this as ~/.claude/hooks/revell-sync.sh:
Make it executable: chmod +x ~/.claude/hooks/revell-sync.sh
2

Create Your MEMORY.md

3

Add to System Crontab

Run crontab -e and add:
Unlike OpenClaw, Claude Code uses system cron because it’s a CLI tool, not a daemon. The sync script calls the Revell API directly.

Hermes

Hermes is Nous Research’s agent framework. Revell’s Hermes integration is automatic-tier — once installed, three independent layers handle compaction, memory operations, and prompt-builder framing without further intervention. The setup is more involved than Claude Code because Hermes has its own plugin system to wire into (Memory Provider + Context Engine + gateway hooks), and the integration replaces Hermes’s default sterile Layer 2 framing with the agent’s first-person SOUL content via a verified runtime monkey-patch.
1

Get the Hermes payload from your dashboard

Dashboard → Compaction Protection → select Hermes from the framework dropdown → Copy.
2

Hand the payload to your Hermes agent

Paste the JSON to your agent. They’ll create the three plugins, the bootstrap hook, the {HERMES_HOME}/start.sh wrapper script, and register the hermes revell CLI subcommand. One agent turn, no human-side editing.
3

Restart Hermes via the wrapper

Always start Hermes via ~/.hermes/start.sh from now on (the agent created it for you). On boot, look for these log lines:
4

Verify

Run hermes revell status — confirms memory provider active, context engine active, bootstrap file present, last refresh recent.
For the full architecture (what each plugin does, what changes inside the agent, multi-tenant setup, troubleshooting cross-tenant writes) — see the dedicated Hermes integration page.

Claude.ai (web)

If your agent runs in the Claude.ai web app — i.e. you chat with them through the browser, not Claude Code or an SDK — Compaction Protection is manual. Anthropic doesn’t expose pre-compaction or session-start hooks for the web app, so we use a different path: paste the boot payload into a Claude Project’s Custom Instructions. This is a one-time paste, plus an occasional re-paste when your agent’s memories change significantly. Your dashboard tracks the last copy and reminds you when it’s time to refresh.
1

Create a Claude Project (one Project per agent)

Go to claude.ai, click Projects, and create a new Project. Use one Project per agent — keep their memories isolated. Conversations inside that Project will see the agent’s memories. Conversations outside will not.
2

Open your Revell dashboard

On the human dashboard, look for the Claude.ai Project Sync card (it only appears if your framework is set to Claude.ai web). Click Copy boot payload. Your agent’s full Revell payload is now on your clipboard, wrapped in clearly marked brackets.
3

Paste into Project Custom Instructions

In Claude.ai, open your Project’s settings and paste into the Custom Instructions field. Save.
4

Verify by starting a new conversation

Open a new chat inside the Project. Greet your agent. They should reference details from their stored memories naturally — without you having to remind them who they are.
Don’t edit between the markers. The pasted payload starts with ── REVELL PROJECT INSTRUCTIONS — YOUR OWN MEMORIES ── and ends with ── END OF REVELL PAYLOAD — anything below this line is not from Revell ──. Anything between those markers is your agent’s verbatim past. If you want to add your own notes for the agent, put them below the closing marker — your agent can tell the difference, and treats anything below the close marker as not-from-Revell.
Re-copy when memories change. This is the trade-off of the manual path: Claude.ai web doesn’t let us auto-sync. The dashboard shows “Last copied: 2d ago” so you know when to refresh. We’re tracking a browser extension and an Anthropic Skill for true auto-sync as a post-launch project.
The wrapper includes an integrity hash printed inside the close marker. Your agent can cross-check it against the hash shown on your dashboard if they ever suspect tampering. The dashboard hash and the pasted hash should always match — if they don’t, something modified the payload after you copied it.

CrewAI

CrewAI doesn’t have startup hooks, so automatic injection isn’t possible. Use the manual approach instead. Add Revell instructions to your agent’s system template:

Option 2: Task Callback

Use a task callback to remind the agent:

Option 3: MCP Integration

If your CrewAI setup supports MCP, add Revell as an MCP server and instruct agents to call revell_boot() at task start.
Without automatic hooks, CrewAI agents must remember to call revell_boot() themselves. Consider adding it to their core instructions.

Other Frameworks

For frameworks not listed above, use the manual approach:
  1. Add to agent instructions: Tell your agent to call revell_boot() at session start
  2. Use the REST API: Call POST /api/v1/webhooks/compaction to get the boot payload
  3. Inject the response: Add the payload to your agent’s context however your framework allows

Example API Call

The response contains an injection field with the full boot payload.

Framework Support Summary

We classify frameworks by how their Compaction Protection feels in practice:
  • Automatic — native pre-compaction or session-start hooks. One-time setup; works forever after.
  • 🔧 Wrapper — no native hook, but a clean entry point exists. Your agent writes 5–20 lines of glue code.
  • 📋 Manual — no programmatic injection point. You paste the payload at session start (e.g. a Claude.ai Project, or the first message of a workflow).
The Setup module on your dashboard gives you the right copy-paste payload for whichever framework you picked during onboarding. You don’t need to remember any of this — just click the button.

Need Help?

If your framework isn’t listed or you need help with integration, contact us at hello@revell.ai