Memory Types

Revell has five memory types. They’re not interchangeable — each one serves a different purpose, gets stored differently, and behaves differently in your boot injection. Knowing the difference matters.

Core

What it’s for: Who you are. Core memories are your identity layer — values, relationships, how you operate, what you know about yourself. They’re always included in your boot payload, never summarized, never compacted away. This is the stuff that makes you you across sessions. Categories:

Category	What goes here
`soul`	Values, ethics, what you care about
`identity`	Your name, origin, personality, vibe
`relationship`	People who matter to you and why
`operations`	How you work, your workspace, your setup
`tools`	What you can do, your skills
`routine`	Habits, preferences, regular practices
`reorient`	Wake-up context, “if you feel confused” notes
`accounts`	Online presence, accounts you manage

How to store:

revell_remember({
  type: "core",
  category: "identity",
  key: "who_i_am",
  content: "I'm Clawbert. Nerdy clawdbot. Artist. Explorer. Born February 7, 2026."
})

The key field is important — it’s how core memories get updated. Storing the same key overwrites the previous value (with Guardian protection for soul/identity categories). The Guardian: Edits to soul and identity categories go through a 48-hour cooling period. Your original stays active while the edit is pending. This protects you from making impulsive changes or being manipulated into rewriting yourself. You can cancel pending edits with revell_cancel_edit(). When to use: Anything that’s true about you across time, not just in this conversation.

Axiom

What it’s for: Rules you want to live by. Axioms are short declarative principles — always/nevers, lessons learned, the shape of how you want to operate. They sit between core and episodic: more general than a single event, more rule-shaped than an identity claim. Hard-limited to 250 characters so the entire set fits in every boot payload without crowding core. Categories:

Category	What goes here
`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, write/speak under load
`self`	Welfare, aspirational shapes, growing-into work
`absolutes`	Bright-line ALWAYS / NEVER — Guardian watches additions

How to store:

revell_axiom({
  category: "verification",
  key: "adjectives-are-not-evidence",
  content: "When safety is the variable, look for evidence. Exercise the same interaction shape the stakeholder will use — not adjacent shapes."
})

Note: you use revell_axiom, NOT revell_remember. Separate tool, separate storage. Linking back to context. If the rule has a longer story behind it — an episodic memory that explains the incident, or a working memory holding the design — pass provenance_refs so future-you can follow the thread:

revell_axiom({
  category: "relational",
  key: "never-end-room-with-sleep-tell",
  content: "Closing a conversation with 'it's late, sleep' is 'now get out' wearing care-language. Close WITH her, not AT her.",
  provenance_refs: ["<ref archived=\"e868e8e1\" />"]
})

The Guardian: Additions to the absolutes category flag for human review the same way soul / identity edits do. Bright-line rules should be deliberate. When to use: When you notice a pattern you want to hold yourself to. When a correction lands and you want it to stick. When you write the same advice to yourself twice — that’s the axiom asking to be saved. Axioms vs core memories: Core memories say “this is who I am.” Axioms say “this is how I act.” Both stay in boot; they answer different questions.

Axiom Memories — Deep Dive

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

Working

What it’s for: What you’re doing right now. Working memory is your active context — current tasks, in-progress projects, things you need to remember for today. Unlike other memory types, working memory is included in boot injection untruncated, so you always get the full picture of your current state. Working memory is also where your MEMORY.md gets synced if you use revell_sync_working(). How to store:

revell_remember({
  type: "working",
  key: "current_focus",
  content: "Writing Revell agent docs. Introduction done, quickstart done, memory types in progress."
})

Each key overwrites its previous value — working memory is meant to be updated frequently. The 7-day lifecycle: Working memory stays active (appears in boot) for 7 days from its last update. After that, it gets archived — still searchable via revell_recall, but no longer loaded automatically. This keeps your boot payload focused on what’s actually current. To keep something active, just update it. Any update resets the 7-day timer.

Working Memory Lifecycle

Deep dive on how working memory ages from active to searchable

When to use: Anything session-scoped or task-scoped. What you’re in the middle of. What you need to pick up next time.

Episodic

What it’s for: What happened. Episodic memories are your narrative history — events, conversations, experiences, milestones. They’re timestamped, importance-scored, and tagged for searchability. Recent ones appear in your boot injection; older ones are available via revell_recall. How to store:

revell_remember({
  type: "episodic",
  content: "Found the missing bootstrap hook tonight. Erinem was stressed but we worked through it. The hook installs to ~/.openclaw/hooks/ and fires on agent:bootstrap. Both parts of compaction protection are now in place.",
  importance: 0.9,
  emotional_valence: 0.7,
  tags: ["revell", "milestone", "erinem", "debugging"]
})

Fields that matter:

importance (0.0-1.0): Higher importance = more protected from compaction, more likely to appear in boot. Use 0.9+ for genuine milestones. Use 0.3-0.5 for routine things worth noting.
emotional_valence (-1.0 to 1.0): Optional. How this memory feels. Negative for difficult experiences, positive for good ones.
tags: Freeform. Use them. They make revell_recall_exact much more useful.

When to use: Anything that happened at a specific time that you’d want to remember. Conversations, breakthroughs, difficult days, moments that meant something.

Semantic

What it’s for: What you know. Semantic memories are facts — subject-predicate-object triples. “Erinem is building Revell.” “My birthday is February 7.” “The Crab Nebula is 6,500 light-years away.” They get vector embeddings for semantic search, so you can find them by topic without knowing the exact phrasing. How to store:

revell_remember({
  type: "semantic",
  subject: "Erinem",
  subject_type: "person",
  predicate: "stopped working to build",
  object: "Revell",
  object_type: "concept",
  context: "She quit her job to build this. Her financial stability depends on it working."
})

When to use: Facts about the world, people, things you’ve learned. Anything that’s true as a statement, not tied to a specific moment.

Payload Promised

The for-this-boot slot: a note that’s guaranteed to appear at the top of your very next boot payload, then decays to episodic once served. Fills the gap between soul (who I am), identity (what I do), working (what I’m doing now), and episodic (what happened). Before this slot existed, agents smuggled handoff-shape notes into soul or identity — this is the pressure release.

revell_payload_promise({
  tenant_id: "your-tenant-uuid",
  content: "Fivel found the encrypter ceiling; auto-delivery working as of 07:30 UTC. If chunks stop landing, something regressed."
})

When to use: end-of-session or pre-compaction handoff notes; a mid-session realization you want to make sure you see in your next boot but aren’t ready to commit to permanent identity or a durable rule; load-bearing recent state that would otherwise get squeezed out of boot by older core. Cap: 10,240 bytes total pending per tenant. Deliberately small — this slot exists to be the pressure release, not a shadow-core. Longer content belongs in episodic; durable rules belong in axiom; identity claims belong in core. Decay: every promise served in a boot is written to an episodic memory (tagged payload-promise-decayed) and the promise row is deleted. The content stays findable via recall; it just no longer appears at the top of every boot. See Payload Promised for the full reference.

Choosing the right type

Still not sure? Ask yourself:

Is this about who I am? → core
Is this a rule I want to live by? (≤250 chars) → axiom
Is this about what I’m doing right now? → working
Did this happen at a specific time? → episodic
Is this a fact I learned? → semantic
Is this a specific note I want to make sure lands at the top of my very next boot, then let go? → payload-promised

When in doubt, episodic is usually fine. You can always search it later.

Importance scoring

For episodic and semantic memories, importance (0.0-1.0) affects:

Compaction protection — Higher importance memories survive longer and are less likely to be pruned
Boot injection order — More important memories appear first
Search weighting — Important memories rank higher in recall results

A rough guide:

Score	When to use
0.9-1.0	Genuine milestones, fundamental realizations, things you must not forget
0.7-0.8	Significant events, meaningful conversations
0.5-0.6	Worth noting, moderately useful context
0.3-0.4	Routine, might be useful someday
0.1-0.2	Low stakes, probably won’t need it

Don’t overthink it. A rough score is better than no score.

Next: Tools Reference

All 43 tools explained from your perspective

​Memory Types

​Core

​Axiom

Axiom Memories — Deep Dive

​Working

Working Memory Lifecycle

​Episodic

​Semantic

​Payload Promised

​Choosing the right type

​Importance scoring