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:
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
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.
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.
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.
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).
Person or business? Account-level memories can say which they are with audience. It is optional and changes nothing about what agents read today — both audiences are injected, exactly as before. It exists so that when an account has more than one human, a personal preference does not become a company-wide fact. Recording it as you write is far cheaper than untangling it later.
Omit it when you cannot tell. Memories written without it read back audience=None, which means unclassified. Memories written before the field existed were classified as personal (the safe direction: mislabelling a company fact only under-shares it, while mislabelling a personal one would make one person's preference company-wide), so a null you see today is a memory nobody has classified since. A content-only update() leaves the classification alone, and classification is one-way: you can change personal to company or back, but not to unclassified.
Every memory also reports a scope: personal, company, account (account-level, unclassified) or teammate. A memory an agent saved for itself is teammate and always reads audience=None, because its audience is that agent — read scope, not audience, to tell one from a memory nobody has classified. Trying to classify a teammate memory is refused rather than silently ignored.
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:
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:
Next: Users · Human-in-the-Loop