Memory
How agents keep a checkpoint, named slots and an archive of notes across runs, and who can read them.
A run starts with a fresh sandbox, so anything the agent should remember must be written to the platform. Appstrate gives agents three kinds of persistent state. They live in one store and are written with two opt-in runtime tools, note and pin.
| Kind | Written with | Visible to the agent | Typical use |
|---|---|---|---|
| Pinned slot | pin(key, content) | Injected into the prompt of every run | Persona, goals, preferences |
| Checkpoint | pin("checkpoint", content) | Injected as the Checkpoint section | Where the last run stopped: cursors, processed ids |
| Archive memory | note(content) | Only on demand, through recall_memory | Facts and discoveries worth keeping |
To use them, add the tools to runtime_tools. Excerpt of the agent manifest:
{ "runtime_tools": ["output", "note", "pin"] }Pinned slots and the checkpoint
pin upserts a named slot, last write wins per scope and key. A key is 1 to 64 characters of lowercase letters, digits and underscores. The content can be any JSON value, and plain strings are rendered as text. The reserved key checkpoint is the carry-over slot: it is shown to the next run in its own section, and it is also snapshotted onto the run (checkpoint in the run resource), which is what run_history returns for earlier runs.
Pinned slots cost prompt tokens on every run. Keep them small and put long material in the archive or in files.
Archive memories
note appends a memory of up to 2000 characters. Archive memories are not put in the prompt. The agent searches them with recall_memory, a case-insensitive substring search that returns the newest matches first (10 by default, at most 50).
At most 100 archive memories are kept per agent, space and scope. When the cap is reached, further notes are dropped. There is no automatic pruning and no expiry: delete old entries to make room.
A third form, a keyless pinned memo (shown in the prompt under Memory), exists in the store. No agent tool writes one: pin always takes a key.
Scope: private or shared
Every note and pin takes a scope:
actor(default): private to the identity the run executes as, a member or an end-user. For a scheduled run that is the schedule's actor. Different members never read each other's private memory.shared: visible to every actor of the space. Use it for facts about a shared resource, such as the structure of a shared inbox or an API quirk.
A run reads its own private rows plus the shared ones. Memory is also partitioned by space: the same agent in two spaces has two separate memories.
Inspecting and deleting memory
In the web app, the agent page has a memory tab that lists slots and memories, with their scope and the run that wrote them. Through the API, with your own credential (an API key cannot carry the persistence permissions, so it cannot read or delete memory):
# Pinned slots and archive memories visible to you
curl "https://your-instance/api/agents/@acme/support-triage/persistence?kind=memory" \
-H "Cookie: ..." -H "X-Org-Id: <org id>" -H "X-Space-Id: spc_..."| Method and route | Purpose | Permission |
|---|---|---|
GET /api/agents/{scope}/{name}/persistence | List slots and memories. Filters: kind (pinned, memory), actor_type and actor_id (callers holding persistence:delete), runId. | persistence:read |
DELETE /api/agents/{scope}/{name}/persistence | Delete memories, and the checkpoint when actor_type and actor_id select one scope. Returns memories_deleted and checkpoint_deleted. | persistence:delete |
DELETE /api/agents/{scope}/{name}/persistence/memories/{id} | Delete one memory. | persistence:delete |
DELETE /api/agents/{scope}/{name}/persistence/pinned/{id} | Delete one pinned slot. | persistence:delete |
Without persistence:delete you see your own scope plus shared rows. A caller holding it (the admin and builder space roles) who inspects an agent without a filter sees every actor's pinned slots. Reading is granted to all five preset space roles. Deleting is held by the admin and builder space roles. See roles and permissions.
There is no endpoint that writes memory directly. Memory only changes when an agent run calls the tools, or when someone deletes it. It lives in the platform database.