Memories & Documents

Memories are short facts about an end-user, injected into the agent's context on every run for that user_id. Use them to personalize agent behavior.

Memories vs documents

Two kinds of persistent context, doing different jobs:

	Memories	Documents
Content	Short facts, max 300 characters	Longer material: reports, briefs, reference docs
Scope	Per end-user (`user_id`), or account-level	Per agent. An agent scoped to a `user_id` keeps its documents in that scope
Written by	Your API calls, or the agent during runs	The agent during runs. The API is read-only
Injection	Automatic, into every run's system prompt	Not injected. The agent reads them when relevant
Manage	This page (full CRUD)	Agents (list and read)

There is no separate per-user documents API: documents always belong to an agent. Read them with client.agents.list_documents() and client.agents.get_document(), covered on the agents page.

Create a memory

Python

When a run executes for that user_id, its memories land in the system prompt and the agent uses them to personalize responses and actions. Seed memories during onboarding so the agent's first run already has context.

Each memory is a short text (max 300 characters), strictly isolated per user_id. Duplicate content for the same user (case-insensitive, whitespace-normalized) returns 409 Conflict.

All memory operations: list, search, update, delete, account scope

List. The source field is "api" for memories you create, "agent" for memories the agent saves during runs.

Python

Search. Pass query to keyword-filter by content (case-insensitive substring). The filter is scoped to the end-user; pagination applies to the filtered set.

Python

Update and delete. Correct a fact in place instead of deleting and re-creating it. Both match exactly the scope you pass: an end-user memory is only reachable with its user_id, an account-level memory only without one.

Python

Account-level memories. Omit user_id to manage facts injected into runs that carry no user_id (single-tenant setups, internal agents). The two scopes never mix. Requires strict multi-tenant mode to be off (it is on by default for new API accounts; single-tenant developers turn it off once).

Python

Saved memories (agent-created)

During runs, the agent can save memories via its built-in memory tool. These are stored with source: "agent" and follow the same isolation rules. The agent decides what to remember: preferences, key decisions, recurring patterns.

To disable saved memories for a specific run:

Python

Previous runs

Runs automatically include context from previous runs for the same user. The agent can search past run outputs to recall what was done before, so you never manage conversation history manually. Pass history=False on a run to start it with a clean slate:

Python

Next: Users · Human-in-the-Loop