# Memory manager

Memory Manager is a per-run scratchpad for storing, accumulating, reading, formatting, and clearing values while a workflow is executing.

Use it when several nodes need to share a value, when a loop must collect results, or when a later node needs to retrieve data without carrying it through every intermediate output.

## Memory structure

Values are grouped by namespace and key:

```text
namespace
└── key
    └── value
```

For example, namespace `conversation` and key `messages` identify `memory.conversation.messages` within the current run.

Namespace and key names must match exactly between operations. They are case-sensitive, and a spelling difference such as `conversations` versus `convesations` addresses two different memory locations.

## Configuration fields

| Field | Purpose |
| --- | --- |
| **Operation** | `Write`, `Append`, `Read`, `Summarize`, or `Clear` |
| **Namespace** | Groups related keys. Empty values use `default`. |
| **Key** | Name of the value inside the namespace. Required for Write and Append. |
| **Value** | Value to write or append. Templates such as `{last_output}`, `{input.note}`, and `{state.customer}` are supported. |
| **Input ctx key** | Source path used when Value is empty. Defaults to `last_output`. |
| **Max items** | Append retains only the last N values; Summarize reads the last N list values. Default: 20. |
| **Summary key** | Key under which the generated text is stored. |
| **Summary max chars** | Maximum length of the generated summary text. Default: 1200. |

## Operations

| Operation | Behaviour | Output passed downstream |
| --- | --- | --- |
| **Write** | Creates or replaces one key. | Operation metadata as JSON |
| **Append** | Adds a value to a list and retains the last **Max items** values. An existing scalar is converted into the first list item. | Operation metadata and the accumulated list as JSON |
| **Read** | Reads one key, or the complete namespace when Key is empty. | The stored value |
| **Summarize** | Deterministically formats the selected value. For a list, it numbers the last N items; for an object, it serializes it; then it truncates to **Summary max chars**. This does not call an AI model. | Summary text |
| **Clear** | Removes one key, or empties the complete namespace when Key is empty. | Clear-operation metadata as JSON |

## Write and read example

First store the previous node output:

```text
Operation: Write
Namespace: workflow
Key: result
Value: {last_output}
```

Later, read it:

```text
Operation: Read
Namespace: workflow
Key: result
```

The stored value becomes `last_output` for the next node.

## Accumulate results with Append

```text
Operation: Append
Namespace: processing
Key: results
Value: {last_output}
Max items: 100
```

After several executions, a Read on `processing / results` returns a list such as:

```json
[
  "first result",
  "second result",
  "third result"
]
```

### Complete Append → Wait → Read flow

```text
Agent
  ↓
Memory Manager — Append
  Namespace: conversations
  Key: responses
  Value: {last_output}
  ↓
Wait
  ↓
Memory Manager — Read
  Namespace: conversations
  Key: responses
```

Wait preserves the run context and does not clear memory. The Read node returns the accumulated `responses` list.

## Use an input context path

Leave Value empty and set **Input ctx key** when the source is already structured:

```text
input
event.body
state.customer
outputs.node-id.parsed
```

## Summarize accumulated values

```text
Operation: Summarize
Namespace: conversation
Key: messages
Summary key: messages_summary
Max items: 20
Summary max chars: 1200
```

The formatted text becomes `last_output` and is also stored under `messages_summary`. Summarize formats and truncates data; use an Agent after Read if you need an AI-generated semantic summary.

For a list containing `["first response", "second response"]`, the output is:

```text
1. first response
2. second response
```

To retrieve it later, use Read with the same namespace and the Summary key (for example `messages_summary`).

## Clear memory

To remove one value, provide Namespace and Key. To empty the entire namespace, leave Key empty.

## Memory Manager vs Set state

| Need | Recommended node |
| --- | --- |
| Store a simple named runtime value accessible as `{state.key}` | **Set state** |
| Accumulate a bounded list | **Memory Manager — Append** |
| Organize several keys into namespaces | **Memory Manager** |
| Read, summarize, or clear a memory collection | **Memory Manager** |
| Keep data across separate workflow runs | A persistent database or storage integration |

## Scope and runtime output

Memory exists only for the current workflow run. A new run starts with empty memory, and isolated **Run node** testing also starts without upstream memory. Use **Run previous** when testing a Memory Manager that depends on earlier nodes.

The operation details are exposed as `last_output_parsed` and `memory_manager`. A Read places the stored value directly in `last_output`; downstream named outputs are also available through `{outputs.<node_id>.parsed}`.

## Understanding the execution trace

Each trace entry has two distinct sections:

- **INPUT** is the previous node's output received by the current node.
- **OUTPUT** is the value produced by the current node.

Append outputs operation metadata containing `"operation":"append"`. Therefore, the INPUT of a later Read node can still show `"operation":"append"`: this does not mean that the second node executed Append. Check the node configuration and the Read node's OUTPUT, which should contain the stored value.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Read returns an empty output | Namespace or key differs from the writer | Copy the exact Namespace and Key from Write/Append |
| Read returns empty during an isolated node test | Upstream memory was not created | Use **Run previous** or test the complete workflow |
| The Read trace INPUT says `"operation":"append"` | It is displaying the previous Append output | Inspect the Read OUTPUT; no configuration change is needed |
| Summarize returns empty text | The selected namespace/key is empty or misspelled | Run Append first in the same run and verify both names |
| Summarize is not an AI-written summary | The operation only formats and truncates values | Follow Read with an Agent for semantic summarization |
| Old items disappear from an appended list | The list exceeded Max items | Increase Max items, up to 1000 |

## Example workflow

Use the workflow card below to create a runnable Write → Read example in the editor.

---

*Source: https://agentbuilder.systalink.sn/docs/node-memory-manager — human documentation.*
*Other language: [/docs-md/fr/node-memory-manager.md](/docs-md/fr/node-memory-manager.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*