Everything must be declared
A memory entry has to exist in a schema before anything can write to it. A tool that writes an undeclared key failsrasa train with undeclared_memory_write.
skills/card_replace/memory.yml
schema:, not memory:.
publicvalues are readable by every other skill.privatevalues stay internal to this skill.
Who is allowed to write
Three different actors write memory, and they’re governed separately:- Tools write whatever the skill declares, via
context.memory.set(). - The LLM may only write entries flagged
llm_settable: true, or entries owned by acollect:step. It does so through the built-inset_memorytool, or through the optionalmemory_itemsobject onactivatewhen starting a skill. - Static
set:buttons write a declared field on tap as an engine write (llm_settableis not required). See Static buttons.
set_memory.
The LLM never writes project memory. Those fields are filled by a tool, a
memory validation tool, session-start
metadata on fields marked seed: true, or a
set:session.project.<entry>=… button tap. By default a set project field
stays locked for the rest of the session. mutable: true allows later
overwrites. writable_by optionally limits which skills may write the field,
including the first write, and does not require mutable: true. Use
writable_by alone when one skill may set a fact that must then stay set,
such as authenticated with writable_by: [auth]. Use both when that skill
may also replace the value later, such as language. See
memory.yml.
Sharing between skills
Values shared across skills go in a project-levelmemory.yml at the agent
root. It is a flat map of entry name to attributes:
memory.yml
project. namespace. This is how a skill depends on
authentication without depending on the authentication skill:
agent.yml with
satisfied_when: session.project.authenticated. The only contract between the
two skills is the key. Put session-wide facts in project memory; keep
collectable labels and working state on the skill. By default the engine
refuses a second write to a set project field. mutable: true allows a later
overwrite. writable_by optionally limits which skills may write that fact,
including the first write. It can be set without mutable: true when only
one skill may set the fact and it must stay set. See
memory.yml.
Skill public and private are working state for the current run. They stay after
complete or cancel so other skills can still read leftover public, and they
reset when that same skill starts again. Put facts that must last the whole
conversation in project memory.
Branching on memory
Acategorical value can drive
scoped instructions, so the LLM only ever
sees the relevant branch:
session.<skill_id>.<entry> or session.project.<entry>. See
Conditions. To put a live value into instruction
prose itself, use @memory.… — see skill.md.
Tracker events
When Mantle persists a write, the tracker recordsmemory_set (with the key
and value) or memory_cleared (key only). See
Tracker events.
Reference
For every field attribute, the full type list, visibility rules, and naming, see thememory.yml reference.