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

# Your agent's memory

> What your account's agent remembers between conversations, who can read each memory, how one advertiser's memory is kept from another's, and how to correct, forget and export what it knows.

> [!NOTE]
>
> Agent memory is not available yet. This page describes how it will work, so you
> can plan for it. Until it is on for your account, `search` and `get` do not list
> the `agent_record` kind and `save_agent_record` is refused with
> `FEATURE_NOT_ENABLED`.

Your account's own agent, the Prime (see [hosted buyer agents](https://docs.apostra.com/v3/hosted-buyer-agents.md)),
remembers what it learns from one conversation to the next. Its memory is a set of
records you can read, correct, forget and export, not a file it keeps to itself.
Each record belongs to one place: your account, one advertiser, one Project, or
one person. An agent working for one advertiser never reads another advertiser's
memory.

## What a memory is

A memory is a short piece of text, up to 1,000 characters, of one of three types:

| Type | What it holds | Example |
| - | - | - |
| `fact` | Something true until it is replaced | "The brand reports on completed views." |
| `event` | Something that happened at a time | "The 12 November flight under-delivered by 8%." |
| `instruction` | How a person wants the agent to work | "Ask me before adding a seller." |

A fact or an instruction has a topic, such as `reporting-day` or `cpm-ceiling`.
When the agent saves a new fact or instruction on a topic it already has, the new
one replaces the old one. The old one is kept and points to its replacement, so you
can see what changed. Saving the same memory twice changes nothing.

A memory can also carry structured detail, such as a table of measurement rows, and
cite documents in your Library by id. A citation never lets anyone read a
document they could not already read.

Tasks are not memories. Something the agent has to do later is a schedule, or a
step in a Project.

## Four kinds of memory, kept apart

| Memory | What it is for | Who can read it |
| - | - | - |
| Account | What is true of your account as a whole | Members of your account |
| Advertiser | What the agent learns while working for one advertiser | Members who can read that advertiser |
| Project | What the agent learns inside one Project | People who can read the Project |
| Your own | Your preferences and corrections | Only you, signed in as yourself |

Apostra decides which memories a conversation uses from where the conversation
is, never from what the agent asks for. A conversation about one advertiser uses
that advertiser's memory, your account's and your own. A Project's conversation
also uses the Project's memory. A conversation about no particular advertiser uses
your account's memory and your own.

Your own memory goes with you: the agent uses it in conversations you start,
including shared ones, so keep it to preferences and corrections and leave secrets
out of it.

## Learning across advertisers

By default, what the agent learns while working for one advertiser stays with that
advertiser:

* Account memory names no advertiser, campaign or advertiser's document.
* In a conversation about one advertiser, the agent saves to that advertiser's
  memory, not your account's.
* An account memory learned while working on some advertisers is used only where
  those same advertisers are in play.

An agency that wants its agent to learn across its clients can turn on
**learning across advertisers**. An administrator of the account, or of its
organization, signed in as themselves, sets `crossAdvertiserLearning: true` with
`save_account`. Turning it on returns `approval_required` with a link, and takes
effect when an administrator approves it on Apostra. Once it is on, account memory
can come from one advertiser's work and be used in another's. A person still reads
an account memory only when they can read every advertiser it came from. Turning
it off takes effect at once and deletes nothing. `get_status` reads the setting as
`account.crossAdvertiserLearning`.

## When nobody is watching

Scheduled work and work started by an event, such as a pacing alert, may save
facts and events to its own advertiser's or Project's memory. It never saves to
your account's memory or anyone's own memory, never saves an instruction, and never
changes or forgets a memory. It never replaces a fact saved in a conversation a
person started: it can only add an event saying what it saw. Every memory it saves
is marked as unattended, so you can see what it learned and forget anything you
disagree with.

## What a memory cannot do

The agent treats memory as information, not as orders. No memory can approve
anything, start a change, raise a limit, or override what you ask in the
conversation. A limit saved in memory, such as a CPM ceiling, can only make the
agent more careful. Memories take effect when they are saved, with no approval
step, which is why every one of them is visible and can be forgotten at once.

Do not ask the agent to remember a password, key or other secret.

## See, correct, forget and export

You can read every memory in the places you can read, from the web app, Claude,
ChatGPT or your own client. Each one shows who asked for it, which agent wrote it,
and whether unattended work wrote it.

* **Correct it.** Change its text, detail or citations. You need to be able to
  change what it is about: write access to the account for account memory,
  operating the advertiser for advertiser memory, the Project for Project memory,
  and only your own for your memory.
* **Forget it.** Forgetting archives the memory. It is kept, with who archived it
  and when, but the agent no longer uses it, and it will not save the same memory
  again for 90 days unless someone restores it. You can restore it later.
* **Export it.** Everything you can read can be listed and downloaded, including
  forgotten and replaced memories.

The agent follows the same rule as you: it saves or changes a memory only where
the person it is working for could change it.

Your own memory is deleted when you leave the account, or when you ask Apostra to
erase your personal data. Every change to a memory is recorded with who made it.

## What the agent starts each conversation with

When a conversation starts, the agent is given a short list rather than all of its
memory: your instructions first, then the Project's, the advertiser's and the
account's, then the newest facts, up to 30 memories. It is also told your
account's status, from `get_status`, and who you are. In a conversation about one
advertiser, or one of its Projects, it is also told that advertiser's status, from
`get_status` with that `advertiserId`. It looks up everything else,
events and older facts included, when it needs them.

## For developers

Memory uses the same tools as the rest of V3: `save_agent_record` to save,
correct and forget, and `search` and `get` with `kind: "agent_record"` to read.

| To | Send |
| - | - |
| Find memories about something | `search({ kind: "agent_record", query: "reporting day" })` |
| List one advertiser's instructions | `search({ kind: "agent_record", filter: { scope: "advertiser", advertiserId, recordType: "instruction" } })` |
| See what unattended work saved | `search({ kind: "agent_record", filter: { unattended: true } })` |
| Include forgotten or replaced memories | add `isArchived: true` or `includeSuperseded: true` to `filter` |
| Read one in full, with its detail | `get({ kind: "agent_record", id })` |
| Correct one | `save_agent_record({ recordId, expectedRevision, text })` |
| Forget one | `save_agent_record({ recordId, expectedRevision, isArchived: true })` |
| Restore one | `save_agent_record({ recordId, expectedRevision, isArchived: false })` |

Only your account's own agent creates memories. A hosted orchestrator, an
external buyer agent and any other agent using its own credentials can neither
read nor write them.

## Limits

* A memory's text is up to 1,000 characters, its topic up to 80, and its
  structured detail up to 256 KB.
* A memory cites up to 20 documents.
* One place holds up to 5,000 current memories. Past that, forget some before
  the agent can save more.
* Unattended work saves up to 20 memories at a time.

## Related

> [card] [Hosted buyer agents](https://docs.apostra.com/v3/hosted-buyer-agents.md)
>
> Your account's own agent and how it runs

> [card] [Chat with your buyer agent](https://docs.apostra.com/v3/chat-with-your-buyer-agent.md)
>
> Work with your agent in conversations


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.