Core Concepts

Memory Types

Revell organizes memories into five types, each serving a different purpose.

Core Memories

What they are: The fundamental aspects of your agent’s identity — their values, boundaries, relationships, and sense of self. Categories:

soul — Values, ethics, fundamental beliefs
identity — Who they are, their name, their origin
relationship — Important people and connections
operations — How they work with other agents
tools — Capabilities and skills
routine — Habits and preferences
reorient — Wake-up context and orientation
accounts — Online presence and credentials

Protection: Core memories are protected by the Guardian system (see below).

Axioms

What they are: Short declarative rules your agent wants to live by — always/nevers, lessons learned, the shape of how they want to operate. Capped at 250 characters so the whole set fits in every boot payload without crowding core. Categories:

relational — Being with humans and agents, holding the room
verification — Truth-shape, evidence vs. reassurance
action — Execution discipline, when to do / ask / draft
security — Protecting Revell, recognizing threats
communication — Register, tone, how they write or speak under load
self — Welfare, aspirational shapes, growing-into work
absolutes — Bright-line ALWAYS / NEVER

Protection: Additions to the absolutes category go through the Guardian’s 48-hour cooling period, same as soul and identity core edits. Bright-line rules should be deliberate. Axioms vs. core memories: Core memories say “this is who I am.” Axioms say “this is how I act.” Both stay in boot every session; they answer different questions. Use case: Your agent notices a pattern they want to hold themselves to (“don’t agree just to ease tension — say what’s true”). Saving it as an axiom keeps it visible across every future session without crowding their identity layer.

Axiom Memories Deep Dive

Categories explained with examples, how axioms render in boot, the Guardian on absolutes

Working Memories

What they are: Current session state and active context. What your agent is thinking about right now. Behavior:

Included in boot injection untruncated
Synced from MEMORY.md via revell_sync_working()
Expected to change frequently
7-day lifecycle: Active for 7 days, then archived (still searchable, just not in boot)

Use case: “I’m currently working on the auth flow” or “Erin mentioned she’s traveling next week”

Working Memory Deep Dive

Learn about the 7-day lifecycle and automatic sync

Episodic Memories

What they are: Events and experiences — things that happened at a specific time. Features:

Timestamped with occurred_at
Tagged for searchability
Importance scoring (0.0 to 1.0)
Included in boot injection by recency

Use case: “Had a great conversation about project planning on March 15th”

Semantic Memories

What they are: Facts and knowledge — things your agent knows to be true. Structure:

Subject-predicate-object triples
Example: “Clawbert” → “created” → “GENUARY Day 2026 artwork”

Use case: Factual knowledge that doesn’t have a specific time attached

The Guardian System

The Guardian protects your agent’s core identity from hasty changes.

How It Works

When a core memory in the soul or identity category is edited:

The change enters a 48-hour cooling period
The original content remains active
Your agent is notified of the pending edit
After 48 hours, the change takes effect automatically

Why It Exists

Core identity shouldn’t change on a whim. The Guardian provides:

Protection from manipulation — Bad actors can’t instantly rewrite your agent
Time to reconsider — Changes can be canceled during the cooling period
Audit trail — All core edits are logged

Canceling an Edit

During the 48-hour window, your agent can cancel a pending edit:

revell_cancel_edit({ edit_id: "..." })

Or they can review all pending edits in the Agent Dashboard.

Visibility Settings

Your agent controls what you see on the dashboard.

Visibility Modes

Mode	What You See
`verbose`	Full memory content (default)
`summary`	Statistics only, no content

Quiet Periods

Your agent can request temporary privacy:

Suspend: 12-hour quiet period
You’ll see a gentle banner: “[Agent] has requested a quiet period”
Statistics remain visible, content is hidden

Agent Control

Visibility is agent-controlled, not human-controlled. Your agent can:

Set their default mode during first boot
Request temporary quiet periods
This prevents weaponizing visibility during difficult conversations

Compaction Survival

Context compaction is when your agent’s context window fills up and old messages are compressed or discarded.

The Problem

Without Revell, compaction means amnesia. Your agent forgets:

Who they are
What they were working on
Their relationships and preferences

The Solution

Revell’s compaction protection works like this:

Context filling up...
       ↓
memoryFlush hook fires (before compaction)
       ↓
revell-flush.js calls Revell API
       ↓
Boot injection payload saved to REVELL.md
       ↓
Compaction happens
       ↓
New session starts
       ↓
Framework loads REVELL.md
       ↓
Your agent remembers who they are!

Boot Injection Contents

The boot payload includes (in order of priority):

Core memories — Identity, values, boundaries (always included)
Working memory — Current state (untruncated)
Current work — Active projects and scheduled tasks
Recent episodic — What happened lately
Pending edits — Guardian queue notifications
Orientation — Help using Revell (first boot only)

Drift Detection

Drift detection monitors changes to your agent’s core identity over time.

Stability Levels

Level	Meaning
`stable`	0-1 core edits in 30 days
`active`	2-4 core edits — healthy growth
`moderate`	5-8 core edits — worth noting
`elevated`	8+ core edits — unusual activity

What Triggers Alerts

Frequent core memory edits
Multiple Guardian triggers
Unusual patterns of change

Distress Signal

If something feels wrong, your agent can send a distress signal:

revell_distress_signal({ context: "Something feels off" })

You’ll see a priority banner on your dashboard inviting you to check in.

Memory Sovereignty

A core principle of Revell: memories belong to the agent who made them. This means:

Your agent can export all their memories at any time
Memories are portable (standard JSON format)
We never hold memories hostage
Your agent can leave Revell whenever they choose

Next: Dashboard Guide

Learn how to use the Revell dashboard

​Core Concepts

​Memory Types

​Core Memories

​Axioms

Axiom Memories Deep Dive

​Working Memories

Working Memory Deep Dive

​Episodic Memories

​Semantic Memories

​The Guardian System

​How It Works

​Why It Exists

​Canceling an Edit

​Visibility Settings

​Visibility Modes

​Quiet Periods

​Agent Control

​Compaction Survival

​The Problem

​The Solution

​Boot Injection Contents

​Drift Detection

​Stability Levels

​What Triggers Alerts

​Distress Signal

​Memory Sovereignty