Framework Setup Guides
Revell works with any framework, but automatic features require framework-specific hooks. This guide covers:- Compaction Protection — Survive context compaction without losing memories
- Working Memory Sync — Keep your MEMORY.md in sync with Revell
OpenClaw
OpenClaw has the most complete integration with automatic memory preservation.Copy Setup from Dashboard
Paste to Your Agent
~/.openclaw/revell-flush.js— Runs before compaction~/.openclaw/hooks/revell-bootstrap/— Loads memories after compaction
Verify
openclaw hooks list to confirm the hook is installed.Working Memory Sync (OpenClaw)
Keep your MEMORY.md automatically synced to Revell every few hours.Copy Setup from Dashboard
Paste to Your Agent
- Fires every 4 hours (configurable)
- Reads MEMORY.md from your workspace
- Syncs it to Revell via
revell_sync_working
Verify
openclaw cron list to confirm the sync job is scheduled.Claude Code
Claude Code’s compaction protection routes through itsCLAUDE.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.
Create the PostCompact Hook Script
~/.claude/hooks/revell-claude-post-compact.sh:chmod +x ~/.claude/hooks/revell-claude-post-compact.shSet Your API Key (workload-local, NOT in shell profile)
~/.claude/revell.env:~/.claude/start.sh instead of claude directly.Register the PostCompact hook in settings.json
~/.claude/settings.json:manual|auto matcher fires for both /compact invocations and auto-compaction triggered by context-window pressure.Wire the @import line into CLAUDE.md
~/.claude/CLAUDE.md (create the file if it doesn’t exist):~ 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.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.Create the Sync Script
~/.claude/hooks/revell-sync.sh:chmod +x ~/.claude/hooks/revell-sync.shCreate Your MEMORY.md
Add to System Crontab
crontab -e and add: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.Get the Hermes payload from your dashboard
Hand the payload to your Hermes agent
{HERMES_HOME}/start.sh wrapper script, and register the hermes revell CLI subcommand. One agent turn, no human-side editing.Restart Hermes via the wrapper
~/.hermes/start.sh from now on (the agent created it for you). On boot, look for these log lines:Verify
hermes revell status — confirms memory provider active, context engine active, bootstrap file present, last refresh recent.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.Create a Claude Project (one Project per agent)
Open your Revell dashboard
Paste into Project Custom Instructions
Verify by starting a new conversation
CrewAI
CrewAI doesn’t have startup hooks, so automatic injection isn’t possible. Use the manual approach instead.Option 1: System Template (Recommended)
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 callrevell_boot() at task start.
Other Frameworks
For frameworks not listed above, use the manual approach:- Add to agent instructions: Tell your agent to call
revell_boot()at session start - Use the REST API: Call
POST /api/v1/webhooks/compactionto get the boot payload - Inject the response: Add the payload to your agent’s context however your framework allows
Example API Call
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).

