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

> The values a skill tracks across a conversation.

Memory is what a skill remembers as the conversation unfolds: the selected
card, the reason for a replacement, whether the user is authenticated. Tools
write to it, the framework checks it, and instructions branch on it.

## 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 fails `rasa train` with `undeclared_memory_write`.

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

The top-level key is `schema:`, not `memory:`.

* **`public`** values are readable by every other skill.
* **`private`** values stay internal to this skill.

Once declared, a tool writes with a bare entry name; the active skill decides
the namespace:

```python theme={null}
context.memory.set("selected_card_id", card.id)
```

## 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 a `collect:` step. It does so through the built-in `set_memory` tool,
  or through the optional `memory_items` object on `activate` when starting a skill.
* **Static `set:` buttons** write a declared field on tap as an engine write
  (`llm_settable` is not required). See
  [Static buttons](https://mantle.rasa.com/reference/responses-yml.md#static-buttons).

That flag matters. Mark the customer's *decisions* settable, such as the
replacement reason or the shipping choice. Leave engine-derived values such as
eligibility results, lock state, and computed flags unflagged, so the model can
neither invent them nor revise them later with `set_memory`.

The LLM never writes **project** memory. Those fields are filled by a tool, a
[memory validation tool](https://mantle.rasa.com/reference/tools.md#memory-validation-tools), 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`](https://mantle.rasa.com/reference/memory-yml#mutable-and-writable_by).

## Sharing between skills

Values shared across skills go in a **project-level `memory.yml`** at the agent
root. It is a flat map of entry name to attributes:

```yaml memory.yml theme={null}
authenticated:
  type: bool
```

These live in the `project.` namespace. This is how a skill depends on
authentication without depending on the authentication *skill*:

```yaml theme={null}
precondition: customer_authenticated
```

Bind that name in [`agent.yml`](https://mantle.rasa.com/reference/agent-yml#preconditions) 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`](https://mantle.rasa.com/reference/memory-yml#mutable-and-writable_by).

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

A `categorical` value can drive
[scoped instructions](https://mantle.rasa.com/build-guide/scoped-instructions.md), so the LLM only ever
sees the relevant branch:

```markdown theme={null}
if: session.card_replace.replacement_reason == 'stolen'
Tell the customer the card will be locked for their protection.
```

Conditions always use the three-segment namespaced form,
`session.<skill_id>.<entry>` or `session.project.<entry>`. See
[Conditions](https://mantle.rasa.com/reference/conditions.md). To put a live value into instruction
prose itself, use `@memory.…` — see [skill.md](https://mantle.rasa.com/reference/skill-md.md).

## Tracker events

When Mantle persists a write, the tracker records `memory_set` (with the key
and value) or `memory_cleared` (key only). See
[Tracker events](https://mantle.rasa.com/reference/execution-loop.md#tracker-events).

## Reference

For every field attribute, the full type list, visibility rules, and naming, see
the [`memory.yml` reference](https://mantle.rasa.com/reference/memory-yml).


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