Memory - Hexel Studio

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

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"
  }'

string

required

Display name for the store.

string

required

One of TASK, SESSION, AGENT, WORKSPACE.

Response

string

Unique store identifier.

string

Display name.

string

The scope this store uses.

string

ISO 8601 creation timestamp.

Write a memory item

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."}'

string

required

The information to store. Keep items concise and self-contained.

Search memory

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}'

string

required

Search query. Length: 1–10,000 characters.

integer

default:"10"

Number of results to return. Range: 1–100.

Reset a memory store

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

curl -X POST https://api.hexelstudio.com/data/v1/memory/YOUR_STORE_ID/reset \
  -H "Authorization: Bearer $TOKEN"

Delete a memory store

curl -X DELETE https://api.hexelstudio.com/data/v1/memory/YOUR_STORE_ID \
  -H "Authorization: Bearer $TOKEN"

Deleting a store removes all its items permanently.

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.

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.

Scope selection guide

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.

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.

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.

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.

Rate limits

Knowledge Stores

Reference content versus accumulated memory.

Context Bundles

Combine knowledge and memory for a run.

Knowledge & Memory

Conceptual overview.

Orchestration

How memory supports running tasks.

Next steps

Continue to Connectors.

​Key concepts

​Memory scopes and TTL

​Operations

​Create a memory store

​Response

​Write a memory item

​Search memory

​Reset a memory store

​Delete a memory store

​Errors

​Security

​Scope selection guide

​Rate limits

​Related pages

Knowledge Stores

Context Bundles

Knowledge & Memory

Orchestration

​Next steps

Key concepts

Memory scopes and TTL

Operations

Create a memory store

Response

Write a memory item

Search memory

Reset a memory store

Delete a memory store

Errors

Security

Scope selection guide

Rate limits

Related pages

Next steps