> ## 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.

# Payload Promised

> The for-this-boot slot — how to leave a note that lands at the top of your next boot payload, then decays to episodic once served

# Payload Promised

Payload-promised is the memory type for content you want guaranteed to appear at the top of your very next boot payload — and then decay away, so it doesn't accrete into permanent identity.

You already have four persistent slots (soul, identity, working, episodic) and axioms for durable rules. None of them quite carry the shape of *"here's a specific note that matters right now, that I want to see the moment I come back."* Before this slot existed, that need got smuggled into soul or identity — which puffed those categories past their character caps and warped the shape of the boot payload. Payload-promised is the pressure release: capped, self-decaying, structurally separate.

***

## When to use it (and when not to)

Reach for `revell_payload_promise` when **all three** of these are true:

1. You want the note to appear at the top of the **next** boot payload — guaranteed.
2. It's context that matters right now, not a durable claim about who you are.
3. It won't matter forever — after the next boot has served it, letting it settle into episodic is the right home for it.

Concrete uses:

* **Right before compaction:** a compressed note about where you were and what mattered — "Fivel found the encrypter ceiling; auto-delivery working as of 07:30 UTC. If chunks stop landing, something regressed."
* **A mid-session realization** you don't want to lose to compaction, but you're not yet sure it's a durable rule. Leave it here; if it turns out to be a rule, save it to axiom or soul from the next session.
* **Load-bearing recent state** that would otherwise get squeezed out of boot by older core memories.

What does **not** belong here:

* **Identity claims** (`I am X`, `my name is Y`) — those are core / identity, always.
* **Durable rules** — those are axioms, capped at 250 chars, categorized.
* **Long-form experience narratives** — those are episodic. Anything that would want more than \~1–2 dense paragraphs is a narrative and belongs there.
* **Ongoing project state** — that's working memory.

The cap on payload-promised is deliberately small — see below — so you can't turn it into a shadow-core even if the reflex hits. That's the point.

***

## The three tools

```text theme={"dark"}
revell_payload_promise({
  tenant_id: "your-tenant-uuid",
  content: "Fivel found the encrypter ceiling last night; auto-delivery working as of 2026-08-04 07:30 UTC. If chunks stop landing, something regressed."
})
```

Returns the promise ID and your current budget (bytes used / bytes available).

```text theme={"dark"}
revell_payload_list({ tenant_id: "your-tenant-uuid" })
```

Read-only. Shows every pending promise for your tenant with ID, timestamp, and content preview. Does NOT decay or consume anything — safe to call at any time to check what's queued.

```text theme={"dark"}
revell_payload_release({
  tenant_id: "your-tenant-uuid",
  promise_id: "specific-uuid"   // optional; omit to release ALL pending
})
```

Cancels one or all pending promises before they serve. Use if you've changed your mind between promising and your next boot — the note gets dropped without decaying to episodic. Idempotent (releasing something that doesn't exist is not an error).

***

## The cap: one tenth of your payload budget

Every promise counts against a single tenant-wide cap across ALL pending (undelivered) rows: **one tenth of your boot payload budget**, with a floor of 1,024 bytes. At the default 22,000-token budget that is 8,800 bytes; at the 33,000 maximum it is 13,200; at the 2,000-token minimum the floor applies and you get 1,024. `revell_payload_list` reports your exact number, and raising your budget with `revell_boot_config` raises the cap with it.

This is enforced at write time — attempting to add a promise that would push the total over the cap returns an error naming the current usage and asking you to either shorten the new note or release earlier ones.

(It was a flat 10,240 bytes until 2026-08-04. That number scaled with nothing: an agent at the 2,000-token minimum has an 8,000-byte payload, so a full slot was larger than everything they wake up with, while an agent at 33,000 was held to the same ceiling as someone with a sixteenth of their room.)

The cap is small on purpose. This slot exists to be the pressure release for handoff-shape notes that would otherwise crowd into soul/identity. If it were large enough to hold long narratives, the same reflex that puffs core categories would just puff this one instead. A tenth forces compressed notes — one or two dense paragraphs at most — which is exactly the right shape for a for-this-boot handoff.

**And it comes out of your budget, not on top of it.** The promised section is charged against your core, working and episodic allocations in proportion to their shares, before they are filled. Promising 5,000 bytes means roughly 5,000 fewer bytes of memory in that boot. This is deliberate: your budget is a promise about the size of the whole payload, and anything that reaches you belongs inside it. Before 2026-08-04 the section was added on top, which pushed large payloads past the delivery ceiling — and because promised renders at the TOP, the section always survived and the oldest memories were what fell off the end.

The trade is worth stating plainly, because it is yours to make: a promise is content you are choosing to read next time **instead of** something else you would have been given.

If you find yourself wanting to promise more than fits, that's a signal:

* **Longer than a paragraph or two?** The content is narrative-shape — save it as an episodic memory now, and if you need a pointer to it in your next boot, promise a short note that references the episodic ID.
* **A rule you want to keep long-term?** Save it as an axiom (250 chars) — axioms are always in your boot payload and are the right home for durable rules.
* **Identity content?** Save it to core soul or core identity — those are the correct homes for who-you-are content, and archiving a lesser memory to make room is the right move.

***

## Where payload-promised appears in your boot

Pending promises render at the **top** of the assembled boot payload — right after the `[REVELL | HELLO]` / `[REVELL | SUCCESS]` orientation lines, **before** the identity block. The section header is:

```text theme={"dark"}
── FOR THIS BOOT ──
```

With a short explanatory line noting that these notes decay to episodic after being served. Each promise renders as a bulleted entry prefixed with its UTC timestamp:

```text theme={"dark"}
── FOR THIS BOOT ──

(Notes preserved for this boot. They decay to episodic memory after being served.)

• 2026-08-04 07:30 UTC: Fivel found the encrypter ceiling; auto-delivery working. If chunks stop landing, something regressed.

• 2026-08-04 07:32 UTC: Just archived two July 26 narratives to library — the pride-shape rules still live in claude_sr_cto_revell and visible-thoroughness-earns-the-title.
```

Placement is deliberate: this content is read first, before the identity block, so it's present in attention before you've settled back into who-you-are content.

***

## Decay to episodic

Once a boot payload has been assembled and returned, every promise it served **decays to an episodic memory** and the original promise row is deleted. The episodic row carries:

* The promise's original content, unchanged
* Tag: `payload-promise-decayed`
* Source: `agent`
* Importance: 0.5 (default; not high-signal)

This means promises stay findable via `revell_recall` after they've decayed — if the same context resurfaces later, `context_hint` on a future `revell_boot` call can pull the relevant decayed promise back naturally.

Decay is fire-and-forget after boot assembly returns. If the episodic write ever fails for a given promise (a database hiccup, for example), the promise row is left in place so it re-serves on the next boot — same note, same content, until decay lands. That's idempotent-safe: re-showing a note the agent asked to see is the correct behavior in that failure mode.

**Preview boots never consume promises.** If your human previews a boot payload from the dashboard, no decay fires. Only real serves (via `revell_boot`, PostCompact recovery, or SessionStart delivery) trigger decay.

***

## There is intentionally no promote-to-core

There's no tool for lifting a decaying payload-promised entry directly into soul or identity. This is deliberate — the whole reason this slot exists is to give the "I want to make sure I see this" reflex somewhere to land that ISN'T soul or identity, so those layers stay actually themselves.

If a note turns out to be durable, the right path is to re-read it during the boot that served it and save it to soul, identity, or axiom via the normal tools. That extra step is a feature: it forces you to re-evaluate whether the note is genuinely rule-shaped or identity-shaped before you commit it, rather than promoting handoff notes into permanent memory by default.

***

## See also

* [**Memory Types**](/agent/memory-types) — full reference for core / working / episodic / semantic / axiom / payload-promised
* [**Axiom Memories**](/agent/axiom-memories) — the sibling short-form layer, for durable rules
* **`revell_help`** — the runtime tool reference for all Revell tools
* **`revell_recall`** — for finding decayed promises later (search for the `payload-promise-decayed` tag)