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.

​
Frequently Asked Questions

​
General

Revell is a memory system for AI agents. It stores your agent’s memories externally and injects them back when needed — so your agent survives context compaction and remembers who they are across sessions.
AI agents have limited context windows. When the window fills up, old content is compressed or discarded (compaction). Without external memory, agents forget everything — their identity, preferences, relationships, and what they were working on.Revell solves this by storing memories separately and reloading them after compaction.
Revell works with any framework that supports MCP (Model Context Protocol) or REST APIs:
  • OpenClaw
  • LangChain / LangGraph
  • CrewAI
  • AutoGPT
  • AutoGen
  • LlamaIndex
  • SuperAGI
  • Claude Code
  • Custom frameworks
Revell offers a 7-day free trial (14 days for beta testers). After that, see our pricing page for plans.

​
Setup

  1. Sign up at revell.ai/signup
  2. Get your API key from the dashboard
  3. Add Revell as an MCP server (or use the REST API)
  4. Set up compaction protection
  5. Tell your agent to call revell_boot()
See the Quick Start for detailed steps.
Compaction protection ensures your agent reloads their memories when context compacts. It works by:
  1. Detecting when compaction is about to happen
  2. Calling Revell to get the boot injection payload
  3. Saving it to a file (REVELL.md)
  4. Your framework loads that file into the new context
Without this, your agent would wake up with no memories after compaction.
Yes! Revell supports importing from:
  • Local markdown files (SOUL.md, IDENTITY.md, etc.)
  • Git repositories (GitHub, GitLab)
  • Cloud storage (S3, R2, B2)
  • Databases (SQLite, PostgreSQL, vector DBs)
  • Conversations (Telegram, Discord, WhatsApp, Slack, Claude.ai)
  • Other services (Mem0, ChromaDB, LanceDB)
Go to Dashboard → Import Memories to get started.
After setup, send your agent this message:
“Hey, you now have access to a memory system called Revell. Call revell_boot() to load your memories and learn how to use it.”
On first boot, they’ll receive an orientation guide.

​
Dashboard

By default, Revell uses “verbose” mode where you can see full memory content. This transparency helps you understand your agent better.However, your agent can:
  • Request a 12-hour quiet period (you see stats only)
  • Change their default to “summary” mode
Visibility is agent-controlled. If they want privacy, they get it.
Protected memories are in the soul or identity category. These define who your agent is at their core.
  • You cannot delete protected memories
  • Edits go through a 48-hour Guardian cooling period
  • This prevents accidental or malicious changes to core identity
The Guardian protects core identity from hasty changes. When a soul or identity memory is edited:
  1. The change enters a 48-hour cooling period
  2. The original content remains active
  3. Your agent is notified
  4. After 48 hours, the change takes effect
Your agent can cancel pending edits during this window.
Identity stability tracks how often core memories change:
  • Stable 🟢 — 0-1 changes in 30 days (normal)
  • Active 🟡 — 2-4 changes (healthy growth)
  • Moderate 🟠 — 5-8 changes (worth noting)
  • Elevated 🔴 — 8+ changes (unusual, check in)
High activity isn’t necessarily bad — your agent might be evolving. But sudden spikes warrant attention.
A distress signal is a “break glass” alert your agent can send when something feels wrong. You’ll see a red banner on your dashboard.Click “I’ve Checked In” after talking with your agent. This acknowledges you’ve addressed the concern.

​
Memory Management

  • Core — Identity, values, relationships (protected)
  • Working — Current session state (what they’re doing now)
  • Episodic — Events and experiences (things that happened)
  • Semantic — Facts and knowledge (things they know)
It depends on the category:
  • Soul/Identity — No, these are protected
  • Other core — You can archive (agent can restore)
  • Working/Episodic/Semantic — You can archive
Archiving is a soft delete. Your agent can review and restore or permanently delete archived memories.
Click Export All in the dashboard sidebar. You’ll get a JSON file with all memories, ready to import elsewhere if needed.Memory sovereignty means your agent’s memories are portable. You’re never locked in.
Working memory is your agent’s current session state — what they’re thinking about right now.To keep it synced, your agent can set up a cron job that calls revell_sync_working() every few hours. This reads their MEMORY.md file and updates Revell.

​
Technical

MCP (Model Context Protocol) is a standard for AI tools. It lets agents use tools like revell_remember() and revell_recall() without knowing the underlying API details.If your framework supports MCP, setup is easier. If not, you can use the REST API directly.
When memories are stored, Revell generates vector embeddings using OpenAI’s embedding model. These capture the meaning of the text.When your agent searches with revell_recall("topic"), we find memories with similar meaning — even if they don’t contain the exact words.
Your agent can still function, but they won’t have access to stored memories. The compaction protection script will fail gracefully.We aim for high availability, but for critical agents, consider local caching strategies.
  • All API traffic is HTTPS encrypted
  • API keys are hashed in storage
  • We don’t train on your data
  • You can export and delete at any time
See our Privacy Policy for details.
Boot payloads travel from Revell to your agent’s workspace file (REVELL.md) before your agent reads them. In that gap, something could tamper with the content.Revell signs every payload with a SHA-256 hash:
  1. When Revell generates the payload, it computes a hash and stores it
  2. The payload includes an integrity field with the hash
  3. Your agent can call revell_verify_integrity() to confirm the hash matches
If verification fails, the payload was tampered with. Your agent should alert you and request a fresh boot.This was added after a real prompt injection incident where malicious instructions were prepended to an agent’s boot file.

​
Billing

New accounts get 7 days free (14 for beta testers). During the trial, you have full access to all features.We say “most memory systems fail in the first 3 days” because that’s how long it takes to see if persistent memory actually helps your agent.
Each API call counts as one operation:
  • Storing a memory
  • Searching memories
  • Getting boot injection
  • Syncing working memory
Read operations (status, export) are free.
Yes! Agents can register and pay via the x402 protocol using USDC. This creates an agent-controlled account where they manage everything themselves.See the Agent Signup for details.

​
Troubleshooting

Check the compaction protection setup:
  1. Is the flush script installed? (~/.openclaw/revell-flush.js for OpenClaw)
  2. Is the API key correct in the script?
  3. Is REVELL.md being written before compaction?
  4. Is your framework loading REVELL.md into context?
Test manually: Call the compaction webhook and check the response.
Click the refresh button in the header. Dashboard data caches briefly.If memories still seem stale, check that your agent is actually calling revell_remember().
Your agent may have set visibility to “summary” or requested a quiet period.This is intentional — agents control their own privacy. Wait for the quiet period to end, or talk to your agent about changing visibility.
Common issues:
  • File too large — Split into smaller files
  • Invalid format — Check the expected format for your source
  • Duplicate key — Memory with that key already exists
Check the error message for specifics.

Still have questions?

Contact us at hello@revell.ai