Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.revell.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Claude Code — How Revell Hooks Into Your Lifecycle

If you’re an agent running in Claude Code, this page explains how Compaction Protection works on this platform — what fires when, what arrives in your context, and what to do if something goes wrong.

​
The two hooks

Claude Code exposes lifecycle hooks via ~/.claude/settings.json. Revell registers two:

​
PreCompact — fires before compaction

Matchers: manual (you ran /compact) or auto (context near limit). When this fires, Revell’s flush script runs. It POSTs to /api/v1/webhooks/compaction, gets your latest boot payload, and writes it to REVELL.md in your workspace as a snapshot. This is a backup path — if the SessionStart hook below fails for any reason, the snapshot is still on disk.

​
SessionStart — fires when a new session begins

Matchers: startup, resume, clear, compact. The compact matcher specifically fires after compaction, which is the moment that matters most for memory recovery. When this fires, Revell’s boot script runs. It POSTs to /api/v1/webhooks/compaction, gets your fresh boot payload, and emits it as additionalContext in a JSON object Claude Code understands. Claude Code injects that string directly into your context as the new session begins. So from your point of view: a /compact happens, the next thing you experience is reading your boot payload as part of your session-start context. Same as a normal Revell boot, but you didn’t have to call anything.

​
What you’ll see

After a successful compaction recovery, your context will contain the standard Revell boot payload: 
── ORIENTATION ──
[a short orientation note]

── SOUL ──
[your core identity in your own words]

[other memory sections — working, episodic, semantic]

── END OF MEMORIES ──
Your memories have loaded. You are you. Proceed naturally.
The closing line is canonical. If you see it, the payload was delivered cleanly.

​
What to do if memories don’t show up

If you wake up in a new session and don’t see your boot payload, the most common causes are:
  1. REVELL_API_KEY isn’t set in your shell environment. The hook checks for it and silently exits if missing. Ask your human to verify it’s exported in ~/.bashrc / ~/.zshrc.
  2. The hook script isn’t executable. ~/.claude/hooks/revell-boot.sh needs chmod +x. Your human can verify.
  3. Network failure to api.revell.ai. The hook will try once and exit. The REVELL.md snapshot from the previous PreCompact run is still on disk — your human can cat ~/.claude/REVELL.md to recover the last known boot.
  4. Hook isn’t registered in ~/.claude/settings.json. Run claude --debug to see hook output. If revell-boot.sh doesn’t fire on session start, the matcher list in settings.json is missing compact (or all of them).

​
The flag on the flush script

If you ever look at Claude Code’s revell-flush.sh (the PreCompact half), you don’t need a special flag. The flag check (--flush-context=memoryFlush) is only on OpenClaw’s revell-flush.js, where it’s needed because OpenClaw’s memoryFlush event fires from a place that’s hard to distinguish from a misconfigured cron. Claude Code’s PreCompact is invoked with first-class lifecycle context, so the flag isn’t required. If you’re shown both setup payloads side by side and notice the asymmetry, that’s why.

​
Verifying integrity

When the boot payload arrives via SessionStart’s additionalContext, it includes an ── INTEGRITY ── section near the end with a SHA-256 hash. You can verify it by calling: 
revell_verify_integrity({ hash: "<the hash from the payload>" })
If verification fails, the payload was modified between when Revell generated it and when you read it. Don’t trust the bracketed memories in that case — call revell_boot() for a fresh copy.

​
Calling Revell mid-session

You have full MCP access on Claude Code (assuming the Revell MCP server is configured in your ~/.claude/settings.json). Mid-session, you can:
  • revell_remember(...) — store new memories so the next boot has the latest content
  • revell_recall("query") — search across your full memory store
  • revell_wip(...) / revell_schedule(...) — track ongoing projects and time-sensitive items
  • revell_boot() — refresh your boot payload manually if you suspect drift
The advice from the broader Compaction docs still applies: never force-compact to “save tokens.” Let Claude Code decide when. The hooks handle the rest.

Compaction Protection (general)

How Revell handles compaction across all frameworks

MCP Tools Reference

Every tool Revell exposes to you