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

# Memory

> Persist information across agent executions using Memory Objects

Memory Objects let agents persist data across executions. Use them to store user preferences, summaries, workflow state, or other information that should survive beyond a single run.

## What Memory Is For

Memory is best suited for:

* Storing structured or semi-structured context that should persist over time
* Personalizing responses based on previous interactions
* Tracking progress in multi-step workflows
* Saving summaries instead of replaying full chat history every time

Memory is **not** the same as chat history. For most conversational use cases, use the AI Model step's built-in **Include Chat History** setting first, and use Memory only when you need more control.

## Create a Memory Object

<Steps>
  <Step title="Open your project">
    Navigate to **Projects** and select the project you want to work in.
  </Step>

  <Step title="Go to the Memory tab">
    Open the **Memory** tab from the top navigation.
  </Step>

  <Step title="Create a Memory Object">
    Click **New Memory**, then enter a name for the Memory Object.
  </Step>

  <Step title="Configure scoping">
    Optionally configure how the memory should be isolated. See [Memory Scoping](#memory-scoping).
  </Step>
</Steps>

## Use Memory in an Agent

There are two ways to work with Memory in an agent:

<Tabs>
  <Tab title="Memory Steps">
    Use **Memory Steps** when memory access should happen deterministically on every execution.

    1. Open your agent in **Agent Studio**.
    2. Drag a **Memory Load** or **Memory Store** step onto the canvas.
    3. Open the step configuration and select the Memory Object.
    4. Connect the step into your workflow.
    5. In the AI Model step's **Instructions** field, add `<memory value="Your Memory Name" />` exactly where you want the memory contents inserted

    **Recommended pattern**

    * Place **Memory Load** near the start of the workflow
    * Send both the user input and loaded memory into the **AI Model** step
    * Place **Memory Store** after the AI Model step to save updated context

    <Warning>
      Connecting a **Memory Load** step to the AI Model step is not enough by itself. The AI Model prompt must explicitly include a `<memory>` tag that references the Memory Object by name.
    </Warning>

    <Tip>
      Use Memory Steps when memory should always be loaded or saved as part of the workflow.
    </Tip>
  </Tab>

  <Tab title="Memory Tools">
    Use **Memory Tools** when you want the LLM to decide whether memory should be read or updated.

    1. Go to **Tools**
    2. Add **Load Memory** and/or **Store Memory**
    3. Configure each tool to point to the correct Memory Object
    4. Add the tools to your **AI Model** step

    See [Integrate Memory Objects as Tools](/integrations/Tools/Airia%20Components/memory-objects) for full setup details.

    <Tip>
      When using Memory Tools, add prompt instructions explaining what the memory contains and when the model should use it.
    </Tip>
  </Tab>
</Tabs>

## Required: Reference Memory in Your Prompt

<Warning>
  **The `<memory>` tag is required for Memory Steps to work.**

  Adding a **Memory Load** step does **not** automatically make the AI Model use the memory. You must explicitly reference the Memory Object in the AI Model prompt using the `<memory>` tag. Without this tag, the loaded memory is **not injected into the model's prompt context**.
</Warning>

Use this syntax in the AI Model step's **Instructions** field:

```xml theme={null}
<memory value="My Memory Name" />
```

The `value` must match the **exact name** of the Memory Object, not its ID.

Example:

```text theme={null}
You are a helpful assistant. Use the following memory from previous interactions:

<memory value="Chat History Summary" />

Use this information when it is relevant to the user's request.
```

You can place the tag anywhere in the prompt where you want the memory contents to appear. That placement determines where the loaded memory is inserted into the model context.

<Note>
  The canvas connection shows data flow between steps, but it does **not** inject memory into the AI Model prompt automatically. The `<memory>` tag in the AI Model **Instructions** field is what makes the loaded memory available to the model.
</Note>

## Load vs Store

### Memory Load

Retrieves the current contents of a Memory Object and passes them downstream.

### Memory Store

Writes data into a Memory Object.

By default, **Memory Store overwrites the full contents** of the Memory Object.

If you enable **Append Text**, new content is added to the existing memory instead of replacing it.

<Warning>
  When **Append Text** is off, Store replaces everything currently in memory. If you need to preserve existing content, first load the memory, merge the new data, and then store the combined result.
</Warning>

## Memory Scoping

Scoping determines how memory is isolated.

| Scope                   | `isUserSpecific` | `isConversationScoped` | Behavior                                          |
| ----------------------- | ---------------: | ---------------------: | ------------------------------------------------- |
| **Global**              |          `false` |                `false` | One shared memory for all users and conversations |
| **User-specific**       |           `true` |                `false` | Each user has a separate memory                   |
| **Conversation-scoped** |          `false` |                 `true` | Each conversation has a separate memory           |
| **User + Conversation** |           `true` |                 `true` | Separate memory per user per conversation         |

<Note>
  When both `isUserSpecific` and `isConversationScoped` are enabled, memory is isolated by the combination of user and conversation.
</Note>

## Pass Identity for Scoped Memory

If your Memory Object uses user or conversation scoping, execution requests must include the relevant identifiers.

* **`userId`** or **`externalUserId`** for user-specific memory
* **`conversationId`** for conversation-scoped memory

```json theme={null}
POST /v2/PipelineExecution/{pipelineId}
{
  "userInput": "What's the weather like?",
  "userId": "user-123",
  "conversationId": "conv-456"
}
```

<Warning>
  If scoped memory is configured but the required identifiers are missing, Memory Load may return empty results or target the wrong memory instance.
</Warning>

## Common Use Cases

<AccordionGroup>
  <Accordion title="User preferences">
    Store persistent settings such as tone, language, interests, or formatting preferences.

    ```
    Typical flow:
    1. Load the existing preferences
    2. Detect updates from the current interaction
    3. Save the updated preferences
    4. Use isUserSpecific: true
    ```
  </Accordion>

  <Accordion title="Session state">
    Track progress in multi-step tasks such as onboarding, form completion, or guided workflows.

    ```
    Typical flow:
    1. Load the current state
    2. Determine the next step
    3. Store the updated state
    4. Use isUserSpecific and isConversationScoped when the workflow should stay isolated to a single user session
    ```
  </Accordion>

  <Accordion title="Conversation summaries">
    Store a rolling summary of prior conversations instead of sending raw message history on every run.

    ```
    This is useful when:
    - Full chat history is too long
    - Only key facts should persist
    - You want lower token usage with retained context
    ```
  </Accordion>

  <Accordion title="Shared project context">
    Use global memory for data that should be shared across all executions, such as common instructions, shared reference context, or team-level settings.

    ```
    Only use this when the data is truly shared.
    ```
  </Accordion>
</AccordionGroup>

## Chat History vs Memory

For most chatbot use cases, start with the AI Model step's built-in **Include Chat History** setting.

Use **Chat History** when:

* You want recent messages automatically included
* You do not need custom storage logic
* You want the fastest setup

Use **Memory** when:

* You want to persist summaries or extracted facts
* You need custom control over what gets stored
* You want memory to outlive a single conversation
* You need deterministic read/write behavior in a workflow

## Troubleshooting

<AccordionGroup>
  <Accordion title="Memory is not persisting">
    Check the following:

    * A **Memory Store** step is connected and actually executes
    * The correct Memory Object is selected
    * Scoped executions are passing the same `userId` and/or `conversationId`
  </Accordion>

  <Accordion title="Memory is empty">
    Common causes:

    * No prior write has occurred
    * A Store step overwrote the memory with empty or partial content
    * Scoped identifiers do not match the expected user or conversation
  </Accordion>

  <Accordion title="Loaded memory is not affecting the AI Model output">
    This usually means the AI Model prompt does not include a `<memory>` tag.

    ```
    Check the following:
    - The AI Model Instructions field includes <memory value="Your Memory Name" />
    - The value matches the exact Memory Object name
    - The Memory Load step runs before the AI Model step

    Without the <memory> tag, the loaded memory is not injected into the model's
    prompt context, even if the steps are connected on the canvas.
    ```
  </Accordion>

  <Accordion title="Wrong memory is being returned">
    Verify:

    * Scoping is configured correctly
    * The execution request includes the expected identifiers
    * The same user and conversation values are used consistently across runs
  </Accordion>
</AccordionGroup>

## Best Practices

* Default to **user-specific** memory unless the data should truly be shared
* Keep memory concise to reduce token usage and latency
* Prefer storing **summaries, facts, and state**, not raw transcript dumps
* Load before Store when you need to preserve existing content
* Use **Memory Steps** for deterministic workflows
* Use **Memory Tools** when the LLM should decide when memory is relevant
* Always add a `<memory>` tag in the AI Model prompt when using **Memory Load** steps

## Recommended Pattern

For most agents, this is the safest starting pattern:

1. **Load** memory at the beginning of the workflow
2. Add `<memory value="Your Memory Name" />` in the AI Model step's **Instructions** field where you want the memory to appear
3. Let the AI Model generate a response and/or updated state
4. **Store** the updated memory after the model step

This pattern gives you predictable behavior while keeping memory easy to reason about.