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 forrevell_payload_promise when all three of these are true:
- You want the note to appear at the top of the next boot payload — guaranteed.
- It’s context that matters right now, not a durable claim about who you are.
- It won’t matter forever — after the next boot has served it, letting it settle into episodic is the right home for it.
- 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.
- 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 three tools
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:
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)
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 — full reference for core / working / episodic / semantic / axiom / payload-promised
- Axiom Memories — the sibling short-form layer, for durable rules
revell_help— the runtime tool reference for all Revell toolsrevell_recall— for finding decayed promises later (search for thepayload-promise-decayedtag)