memory.yml declares what a skill remembers. Every value a tool writes must be
declared here (or in the project-level file): rasa train rejects an
undeclared write.
There are two kinds of memory.yml, with different shapes.
Skill memory: skills/<id>/memory.yml
skills/card_replace/memory.yml
schema:. It splits into public: and private:;
both are optional.
Unknown keys are ignored and not used by the engine.
Project memory: memory.yml at the agent root
Values shared across skills live in a project-level file. Its shape is
different: a flat map of entry name to attributes, with no
schema:/public:/private: wrapper.
memory.yml
project. namespace, so a condition refers to
session.project.authenticated. This is the mechanism behind cross-skill state:
one skill writes authenticated, another gates on it, and neither references
the other.
Project memory is shared across skills for the rest of the session. After the
first write a field stays locked unless you set mutable: true on that field.
Put facts every skill can rely on here (authenticated, a verified customer id,
a seeded caller phone). Keep collectable, correctable values on the owning
skill as schema.public (for example a chosen card label).
How set project values appear in the prompt is documented on
System Prompt and
Prompt templates.
Seeding from session start
If you want to populate a project field from channel metadata, setseed: true.
By default, seed is false: the engine does not copy channel metadata into
project memory unless you opt in.
Use it for channel facts such as caller phone or language. The copy uses the
same name as the field and is the first write from metadata. When the field
is also mutable: true, listed skills (or any skill if writable_by is
empty) may overwrite that value later; seeding itself is not limited by
writable_by.
Channel metadata often uses the same names as project fields. A matching name
is not enough: only fields you mark are copied, so a client cannot lock
authenticated (or any other unmarked field) by sending that key.
Here is an example. You have these project memory fields:
memory.yml
caller_phone is set from metadata. authenticated stays unset until a tool
or a memory validation tool writes it.
On session start, channel metadata may fill a project field marked
seed: true only while that field is still unset. That first copy does
not check writable_by (no skill is active yet). After the field has a value,
another reconnect or /session_start does not replace it — including when
the field is mutable and a listed skill wrote the current value.
A missing metadata key, or a value that fails type coercion, leaves the field
unset. seed: true on skill schema.public or schema.private fails
rasa train.
Mutable and writable_by
These attributes apply only to project fields in rootmemory.yml.
rasa train fails if either flag appears on schema.public or
schema.private in a skill’s memory.yml — declare them on project memory
instead.
They may appear on the same field as seed: true. The first session-start
metadata write still fills an unset seeded field and does not check
writable_by. Skill writes check writable_by on the first write and on
later writes.
Use mutable: true when a session-wide fact may change after the first write.
Use writable_by to limit which skills may write the field, including a
write-once field:
memory.yml
Train time:
rasa train checks literal writes to project memory in
skill tools (context.memory.set(…)), set_memory: steps, and static
set: button payloads against writable_by when the key targets a project
field. Put the tool under a listed skill’s skills/<id>/tools.py, or adjust
the list.
Same name on skill and project: a bare memory.set("entry", …) in a
skill’s tools writes the skill field, not project memory. Use
memory.set("project.entry", …) when you mean project. Train warns on that
pattern in skill-local tools. Shared agent/tools/*.py is not fully linted for
bare names; runtime still enforces writable_by for the invoking skill.
Static buttons without an active skill omit project keys that are restricted by
writable_by from their writable set.
Skill vs project memory
Use project memory for facts every skill should rely on. Use skill memory for values that belong to one task.
The LLM cannot write project fields (
set_memory, collect).
rasa train rejects llm_settable: true and collect: on a project field.
A static set:session.project.<entry>=… button can write a project field
(write-once unless the field is mutable: true, and subject to writable_by
when set).
Typical pattern: collect the user-facing value on the skill, then have that
skill’s tool or run_after_setting_<skill_field> memory validation tool
write project.*.
Completing or reactivating a skill does not clear project values.
If a skill needs a project fact before it starts, declare a semantic
precondition on the skill and bind its
satisfied_when condition and resolver in
agent.yml (orchestrator.preconditions).
Do not declare working state in root memory.yml: write-once would lock the
first value for the rest of the session.
Field attributes
Every attribute is optional; a bare entry (my_field: {}) is a valid any field.
If your deployment requires PII present in your agent’s events to be anonymized,
configure
stream_pii: false and an anonymization topic on the event broker in
integrations.yml (see the event_broker
section). Fields marked pii: true are anonymized on published events and in the
tracker store after the session ends. Omit anonymization to mask the whole
value ([SLOT_NAME]). Set it to choose redact or mask. Tracker-store cron jobs
stay in the privacy block of agent.yml.
Session-start call metadata (system.session_started_metadata) is masked whenever a
pii: true field or that privacy block is present. A stored
session_started_metadata event is still masked. Free-text PII the user
speaks without a matching memory field can be covered by optional GLiNER-based
detection when you install the pii extra and provide the
urchade/gliner_multi_pii-v1
model (same model used in the Mantle PII integration tests).
anonymization
Valid only on a field with pii: true. rasa train rejects it otherwise.
Types
Write the type name exactly as it appears in the left column.
enum_values
categorical field with enum_values gets an enum constraint in the
set_memory schema, so the LLM can only record one of the listed values. It is
also what makes the field usable in if: markers with confidence about the
value space.
llm_settable
This is the switch that decides whether the LLM may write a value at all.
- fields flagged
llm_settable: true, and - fields owned by a
collect:step in the active skill (settable regardless of the flag. The engine asked the user for them directly).
llm_settable also gates whether an already-set field can be revised through
set_memory. Leave engine-derived values (eligibility results, lock state,
computed flags) at the default so the model can neither set nor revise them.
llm_settable is skill memory only. A project field with this flag fails
rasa train.
A field the model can set — llm_settable: true, or a field a collect step
fills — needs one description the model will see. Put it on the memory field,
or on the collect step. Whitespace does not count. When both are set, training warns
and keeps the memory description in the file. The collect-step description is
still the one the model sees when setting the field,
correcting it, and confirming a value filled ahead of the ask. It is also the
description embedded for skill retrieval.
Static set: buttons are engine writes: they do not need this flag. A tap
can still fill a collect target or another writable field. See
Set-memory payloads.
description
The model sees this text when it writes the field through set_memory,
including a revision of an earlier value.
rasa train accepts a description only on a field the model can set:
llm_settable: true, or a collect: step fills it. A description on any
other skill field fails training with
mantle.validation.memory.description_not_exposed. Remove the description, or
mark the field settable. Bundled default skills are checked the same way.
A project field cannot be llm_settable and a collect step cannot fill it, so
a description on a project field fails training too. Remove it.
Visibility
Concretely, while skill
A is active it can read A’s own public and
private fields, every other skill’s public fields, and all project fields.
A skill can write its own declared fields and project fields (project is
write-once unless mutable: true, and may be limited by writable_by). It
cannot write another skill’s fields.
public is your skill’s API. Keep it small and stable: another skill gating on
session.project.authenticated should depend on that key, not on the auth
skill’s internals.
Lifetime
Skill public and private memory is working state for the current run, not session-long truth.- After a skill completes or is cancelled, its live values stay. Other skills can still read that skill’s public fields (for example a selected card id). Private fields stay set but are not readable by others.
- When the same skill starts again in the session (it is no longer on the
stack), the engine resets that skill’s public and private fields to
initial_value(ornullif unset). Tracker history still holds the old values. That reset happens before anutter:on: activateresponse is selected, so conditional variants that read this skill’s fields usually see the default wording unless those fields declare a matchinginitial_value— prefer project memory or awhen:trigger for values written after activation (see Conditional variants). - Interrupt and resume do not reset: the parked skill keeps its memory.
project.*is never cleared because a skill finished or started again. Put facts that must last the whole conversation there (authenticated, verified customer id), not in skill public.
Undeclared writes
context.memory.set("foo", 1) where foo is in neither the skill’s schema:
nor the project file fails rasa train with undeclared_memory_write. Fix it
by declaring the entry with its type.
The same applies to a collect: step target and to any key named in a
requires: or if: condition.
Fully-qualified names
The scope an entry is declared in determines its full name:
In tools, get may use either form in that last column. set may use a
bare name,
project.<entry>, or <own_skill_id>.<entry> only — not another
skill’s fully-qualified name.
Use session.* in structured places (requires:, if:, tool parameters).
Use @memory.* when instruction prose needs the live value inline.
Use {session.*} in response templates. Do not put session.* in free
prose — train fails and suggests @memory.… instead.
While skill card_replace is active, a tool reads its own field with the
bare name and another skill’s public field with the fully-qualified name:
project.<entry>, or its own skill
id. project. always writes project memory (even when the skill declares the
same name). <own_skill_id>. writes that skill’s field only (no project
fallback). Another skill’s fields cannot be written here:
system.* is reserved for engine internals and can never be declared.
@memory.system.* is not supported.
The namespace is the skill directory name, not the
name: in frontmatter. A
skill in skills/card_replace/ with name: Card Replace is always
session.card_replace.* / @memory.card_replace.*.See also
- Memory concept: when to declare what
- Conditions: referencing entries in
requires:/if: - skill.md:
@memoryin instruction prose - Tools reference:
context.memoryread/write rules