> ## Documentation Index
> Fetch the complete documentation index at: https://mantle.rasa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# memory.yml

> Memory schema: skill and project scopes, field types, and visibility.

`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`

```yaml skills/card_replace/memory.yml theme={null}
schema:
  public:
    replacement_reason:
      type: categorical
      enum_values: [lost, stolen, damaged, not_received]
      description: Why the card is being replaced.
      llm_settable: true
    selected_card_id:
      type: text
  private:
    eligibility_checked:
      type: bool
```

The top-level key is **`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.

```yaml memory.yml theme={null}
authenticated:
  type: bool
caller_phone:
  type: text
  seed: true
  pii: true
```

These resolve to the `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](https://mantle.rasa.com/reference/system-prompt.md) and
[Prompt templates](https://mantle.rasa.com/reference/prompt-templates.md).

### Seeding from session start

If you want to populate a project field from channel metadata, set `seed: 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:

```yaml memory.yml theme={null}
caller_phone:
  type: text
  seed: true
  pii: true

authenticated:
  type: bool
```

If the channel sends this metadata at connect:

```json theme={null}
{
  "metadata": {
    "caller_phone": "+15551234567",
    "authenticated": true
  }
}
```

`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 root `memory.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:

```yaml memory.yml theme={null}
authenticated:
  type: bool
  writable_by: [auth]

language:
  type: text
  mutable: true
  writable_by: [change_language]
```

| Rule | Behavior |
| - | - |
| Default | Project field is write-once after the first tool, step, button, or seed write |
| `mutable: true` | The field may be overwritten for the rest of the session |
| `writable_by: [skill_id, …]` | Only listed skills may write the field (tools, `set_memory` steps, static `set:` buttons). Independent of `mutable` |
| Omitted or empty `writable_by` | Every skill may write. Later writes still require `mutable: true` |
| Skill ids | Each id is the skill **directory name** under `skills/<id>/` (not frontmatter `name:`). It must name a skill the agent knows at train time (your project skills and [engine default skills](https://mantle.rasa.com/reference/builtin-skills.md)) |
| Seed | First session-start metadata copy into an **unset** `seed: true` field bypasses `writable_by`; seed never overwrites an existing value |
| LLM | `set_memory` and `collect` never write project fields, including a revision of an earlier value |

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

| | Project | Skill |
| - | - | - |
| File | `memory.yml` at the agent root | `skills/<id>/memory.yml` |
| Put here | Session facts: authenticated, a verified customer id, a seeded caller phone | That skill's task: chosen card, card list, loaded transactions |
| Who writes | Tool, [memory validation tool](https://mantle.rasa.com/reference/tools.md#memory-validation-tools), session-start seeding, or a `set:` button | That skill's tools, the LLM (`set_memory` / collect), or a `set:` button |
| After the first write | Locked unless `mutable: true` | Stays writable |
| When the owning skill starts again | Unchanged | Reset to `initial_value` |
| Other skills | Read `session.project.<name>` | Read **public** fields as `session.<skill_id>.<name>` (or `context.memory.get("<skill_id>.<name>")`). They cannot write those fields |

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`](https://mantle.rasa.com/reference/skill-md#precondition) on the skill and bind its
`satisfied_when` condition and resolver in
[`agent.yml`](https://mantle.rasa.com/reference/agent-yml#preconditions) (`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.

| Attribute | Default | Description |
| - | - | - |
| `type` | `any` | Value type: see below |
| `description` | `null` | Text the model sees when it sets the field. Required when the model can set the field, unless a collect step describes it. Allowed only when the field is `llm_settable` or a collect step fills it. |
| `enum_values` | `[]` | Allowed values; meaningful with `type: categorical` |
| `llm_settable` | `false` | Whether the LLM may write this via `set_memory` (skill fields only; rejected on project) |
| `seed` | `false` | Project fields only: copy this field from session-start metadata. See [Seeding from session start](#seeding-from-session-start) |
| `pii` | `false` | Withholds the value from prompts and, when the privacy pipeline is active, anonymizes the value on published events |
| `anonymization` | mask | How a `pii: true` field is anonymized. Invalid unless `pii: true`. See [Anonymization](#anonymization) |
| `initial_value` | `null` | Value the entry holds before anything writes to it. Skill fields return to this when that skill starts a new run |
| `mutable` | `false` | **Project only:** allow overwrites after the first write |
| `writable_by` | `[]` | **Project only:** skill directory ids allowed to write. Empty or omitted: any skill may write. Does not change write-once; later writes still need `mutable: true` |

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`](https://mantle.rasa.com/reference/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`](https://mantle.rasa.com/reference/agent-yml#privacy).
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`](https://huggingface.co/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.

```yaml theme={null}
credit_card_number:
  type: text
  pii: true
  anonymization:
    type: redact
    redaction_char: "#"
    keep_right: 4
```

| Key | Required | Description |
| - | - | - |
| `type` | yes | `redact` replaces characters; `mask` replaces the whole value with `[SLOT_NAME]` |
| `redaction_char` | no | Single character used by `redact`. Default `*` |
| `keep_left` | no | Characters left intact at the start. Must be greater than 0 |
| `keep_right` | no | Characters left intact at the end. Must be greater than 0 |

### Types

| `type` | JSON schema type used for `set_memory` |
| - | - |
| `text` | `string` |
| `bool` | `boolean` |
| `int` | `integer` |
| `float` | `number` |
| `list` | `array` |
| `categorical` | `string`, plus an `enum` from `enum_values` |
| `json` | `string` |
| `any` | `string` |

Write the type name exactly as it appears in the left column.

### `enum_values`

```yaml theme={null}
replacement_reason:
  type: categorical
  enum_values: [lost, stolen, damaged, not_received]
```

A `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.

```yaml theme={null}
# the user's stated decision, recorded by the LLM
replacement_reason:
  type: categorical
  enum_values: [lost, stolen, damaged, not_received]
  llm_settable: true

# derived by a tool; the LLM must never invent it
account_replace_eligible:
  type: bool
```

The entries the LLM may set for a turn are the union of:

* 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](https://mantle.rasa.com/reference/responses-yml.md#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

| Scope | Readable by |
| - | - |
| `schema.public` | The owning skill, and every other skill |
| `schema.private` | The owning skill only |
| project (root `memory.yml`) | Every skill |

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` (or `null` if unset). Tracker
  history still holds the old values. That reset happens **before** an
  `utter:` `on: activate` response is selected, so conditional variants that
  read this skill's fields usually see the default wording unless those fields
  declare a matching `initial_value` — prefer project memory or a `when:`
  trigger for values written after activation (see
  [Conditional variants](https://mantle.rasa.com/reference/responses-yml.md#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:

| Declared in | Fully-qualified name | Referenced in conditions as | Referenced in instruction prose as | Referenced in responses as | Referenced in tools (`context.memory`) as |
| - | - | - | - | - | - |
| `skills/card_replace/memory.yml` | `card_replace.replacement_reason` | `session.card_replace.replacement_reason` | `@memory.card_replace.replacement_reason` | `{session.card_replace.replacement_reason}` | `replacement_reason` or `card_replace.replacement_reason` |
| root `memory.yml` | `project.authenticated` | `session.project.authenticated` | `@memory.project.authenticated` | `{session.project.authenticated}` | `authenticated` or `project.authenticated` |

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:

```python theme={null}
reason = context.memory.get("replacement_reason")
selected_card_id = context.memory.get("card_disambiguation.selected_card_id")
```

The same tool writes with a bare 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:

```python theme={null}
context.memory.set("replacement_reason", "stolen")
context.memory.set("card_replace.replacement_reason", "stolen")
context.memory.set("project.authenticated", True)
# context.memory.set("card_disambiguation.selected_card_id", ...)  # rejected
```

`system.*` is reserved for engine internals and can never be declared.
`@memory.system.*` is not supported.

> [!NOTE]
>
> 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](https://mantle.rasa.com/concepts/memory.md): when to declare what
* [Conditions](https://mantle.rasa.com/reference/conditions.md): referencing entries in `requires:` / `if:`
* [skill.md](https://mantle.rasa.com/reference/skill-md.md): `@memory` in instruction prose
* [Tools reference](https://mantle.rasa.com/reference/tools.md): `context.memory` read/write rules


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.