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

# Memory

> Scoped memory stores that let agents record and recall information over time.

Use memory when your agent needs to remember context across turns, sessions, or long-running tasks. A customer-facing agent might store a user's preferred language after the first interaction; a research agent might record intermediate findings across a multi-step pipeline. Without memory, every invocation starts from zero.

Memory lets an agent write and read information over time. Unlike knowledge stores (reference content you ingest), memory is what an agent accumulates as it works, scoped by how long it should persist.

## Key concepts

| Term             | Meaning                                              |
| ---------------- | ---------------------------------------------------- |
| **Memory store** | A container an agent writes items to and reads from. |
| **Memory item**  | A single recorded piece of information.              |
| **Scope**        | Controls persistence duration and sharing breadth.   |

## Memory scopes and TTL

| Scope       | TTL      | Use for                                    |
| ----------- | -------- | ------------------------------------------ |
| `TASK`      | 24 hours | Working state within a single task.        |
| `SESSION`   | 8 hours  | Context across a multi-turn session.       |
| `AGENT`     | 1 year   | Long-lived knowledge an agent accumulates. |
| `WORKSPACE` | 1 year   | Memory shared across a workspace.          |

Items expire automatically at the end of their scope's TTL.

## Operations

| Operation           | Method   | Endpoint                            |
| ------------------- | -------- | ----------------------------------- |
| Create store        | `POST`   | `/data/v1/memory`                   |
| Get store           | `GET`    | `/data/v1/memory/{store_id}`        |
| Update store        | `PATCH`  | `/data/v1/memory/{store_id}`        |
| Delete store        | `DELETE` | `/data/v1/memory/{store_id}`        |
| List items          | `GET`    | `/data/v1/memory/{store_id}/items`  |
| Write item          | `POST`   | `/data/v1/memory/{store_id}/items`  |
| Search              | `POST`   | `/data/v1/memory/{store_id}/search` |
| Reset (clear items) | `POST`   | `/data/v1/memory/{store_id}/reset`  |

## Create a memory store

```bash theme={"dark"}
curl -X POST https://api.hexelstudio.com/data/v1/memory \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "session-context",
    "scope": "SESSION"
  }'
```

<ParamField body="name" type="string" required>
  Display name for the store.
</ParamField>

<ParamField body="scope" type="string" required>
  One of `TASK`, `SESSION`, `AGENT`, `WORKSPACE`.
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique store identifier.
</ResponseField>

<ResponseField name="name" type="string">
  Display name.
</ResponseField>

<ResponseField name="scope" type="string">
  The scope this store uses.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

## Write a memory item

```bash theme={"dark"}
curl -X POST https://api.hexelstudio.com/data/v1/memory/YOUR_STORE_ID/items \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers concise answers."}'
```

<ParamField body="content" type="string" required>
  The information to store. Keep items concise and self-contained.
</ParamField>

## Search memory

```bash theme={"dark"}
curl -X POST https://api.hexelstudio.com/data/v1/memory/YOUR_STORE_ID/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "answer style", "top_k": 3}'
```

<ParamField body="query" type="string" required>
  Search query. Length: 1–10,000 characters.
</ParamField>

<ParamField body="top_k" type="integer" default="10">
  Number of results to return. Range: 1–100.
</ParamField>

## Reset a memory store

Clears all items from the store without deleting the store itself.

```bash theme={"dark"}
curl -X POST https://api.hexelstudio.com/data/v1/memory/YOUR_STORE_ID/reset \
  -H "Authorization: Bearer $TOKEN"
```

## Delete a memory store

```bash theme={"dark"}
curl -X DELETE https://api.hexelstudio.com/data/v1/memory/YOUR_STORE_ID \
  -H "Authorization: Bearer $TOKEN"
```

<Warning>
  Deleting a store removes all its items permanently.
</Warning>

## Errors

| `code`                   | HTTP | When                                                                 |
| ------------------------ | ---- | -------------------------------------------------------------------- |
| `VALIDATION`             | 400  | Invalid `scope`, or a malformed item/search request.                 |
| `AUTH.PERMISSION_DENIED` | 403  | Missing `data-platform:memory:read` or `data-platform:memory:write`. |
| `RESOURCE.NOT_FOUND`     | 404  | The memory store or item doesn't exist.                              |

## Security

| Requirement      | Detail                                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| Read permission  | `data-platform:memory:read` — required to list, get, and search items.                                              |
| Write permission | `data-platform:memory:write` — required to create stores, write items, reset, or delete.                            |
| Scope            | All memory is scoped to your organization, workspace, and environment. Agents in other workspaces cannot access it. |
| Data handling    | Items expire automatically at the end of their scope's TTL. Use the shortest scope that fits the workload.          |

<Warning>
  Do not store secrets, credentials, or regulated personal data in memory. Long-lived scopes (`AGENT`, `WORKSPACE`) persist for up to 1 year and are accessible to any agent with read access in that workspace.
</Warning>

## Scope selection guide

<AccordionGroup>
  <Accordion title="TASK (24h) — working state for a single job">
    Use for scratch data that should not outlive the current task: intermediate results, step outputs, flags set during execution. Automatically cleaned up after the task TTL expires, so you never accumulate stale data from past runs.
  </Accordion>

  <Accordion title="SESSION (8h) — multi-turn conversation context">
    Use for anything that needs to persist across multiple user turns within a session window: conversation history, user preferences stated in this session, in-progress context. Expires when the session ends or after 8 hours, whichever comes first.
  </Accordion>

  <Accordion title="AGENT (1 year) — long-term agent knowledge">
    Use when an agent should accumulate knowledge over days, weeks, or months: learned user preferences, recurring patterns, notes the agent builds up over time. Scoped to this agent — other agents cannot read it.
  </Accordion>

  <Accordion title="WORKSPACE (1 year) — shared across all agents">
    Use for facts that every agent in the workspace should know: team conventions, shared ontologies, cross-agent context. All agents with `data-platform:memory:read` in this workspace can access it.
  </Accordion>
</AccordionGroup>

## Rate limits

## Related pages

<CardGroup cols={2}>
  <Card title="Knowledge Stores" icon="book" href="/docs/data-platform/knowledge-stores">
    Reference content versus accumulated memory.
  </Card>

  <Card title="Context Bundles" icon="box" href="/docs/data-platform/context-bundles">
    Combine knowledge and memory for a run.
  </Card>

  <Card title="Knowledge & Memory" icon="brain" href="/docs/concepts/knowledge-and-memory">
    Conceptual overview.
  </Card>

  <Card title="Orchestration" icon="sitemap" href="/docs/orchestration/overview">
    How memory supports running tasks.
  </Card>
</CardGroup>

## Next steps

Continue to [Connectors](/docs/data-platform/connectors).