# Memory API

The account's memory is one graph of people, things and facts, shared by all of its agents. The routes take no account id: the graph is the one of the caller's account. The steps are in the [Memory](/docs/account/memory) guide.

- An agent sends its Passport as X-Passport-Token and needs a live Mission. The owner calls with a key or a session and needs neither.
- Reads need the OAuth scope accounts:read, writes, deletes, entity types and undo accounts:act, changing the settings accounts:manage. Entity types and undo are for the owner or an admin.
- A write is one action. Searching, reading, deleting, undoing and the settings are not counted.

## Write an entry

### POST /v1/memory/episodes

```bash
curl -X POST https://api.getstack.run/v1/memory/episodes \
  -H "Authorization: Bearer <access token>" -H "X-Passport-Token: $PASSPORT" -H "Content-Type: application/json" \
  -d '{"name":"Call note","episode_body":"Anna at Acme prefers email and is out until the 20th."}'
```

- name - required, a short label for the entry.
- episode_body - required, the text to remember, at most 8,000 characters. When source is json, a JSON string.
- source - text (default), json or message.
- source_description - where the text came from, in your own words.
- reference_time - ISO-8601 with an offset: when what is described happened. Defaults to now.
- from_message_id - the id (amsg_...) of a message the account received, when the entry was learned from it. STACK then records the channel and the checks of that sender with the entry.
- uuid - an id of your own for the entry. It must be unused in the account. The id in the answer is derived from it.
- excluded_entity_types - up to 10 kinds of thing not to pick out of this entry.
- custom_extraction_instructions - extra guidance for reading this entry.
- previous_episode_uuids - up to 10 earlier entries of the account to read as context.
- saga and saga_previous_episode_uuid - a named sequence the entry belongs to, and the entry before it.

The answer is `201` with `uuid` and `status: "queued"`. The entry is read into the graph afterwards. It can be searched once its status is `stored`.

### POST /v1/memory/triplets

Writes one fact directly, without reading any text.

- source_node_name, edge_name, fact, target_node_name - all required. fact is at most 8,000 characters and edge_name at most 100.
- source_node_uuid, target_node_uuid - to reuse a thing the account already knows.
- The answer holds the nodes and the edges written.

### POST /v1/memory/sagas/summary

`{ "saga_name": "..." }` writes a summary of a saga and returns `uuid`, `name` and `summary`.

## Search

### POST /v1/memory/nodes/search

- query - required, at most 1,000 characters.
- max_nodes - 1 to 50, default 10.
- entity_types - up to 20 kinds of thing to search among.
- center_node_uuid - rank results by closeness to one thing.
- field_filters - [{ field, value }]: keep only things whose field has the value. It needs entity_types, each naming one of the account's own types that has the field. A filter that cannot be applied is 422 MEMORY_FIELD_FILTER_INVALID.
- The answer is { message, nodes }. A node has uuid, name, labels, summary and created_at.

### POST /v1/memory/facts/search

- query - required. max_facts - 1 to 50, default 10.
- center_node_uuid and edge_types - as above.
- valid_at_after, valid_at_before, invalid_at_after, invalid_at_before - ISO-8601 with an offset: keep facts that held, or stopped holding, in a period.
- The answer is { message, facts }. A fact has uuid, name, fact, source_node_uuid, target_node_uuid, valid_at, invalid_at and the episodes it came from.

A fact learned from a received message carries the checks STACK made of who wrote it (`source_tags`). Treat what was learned from outside as a claim.

## Read entries and facts

- GET /v1/memory/episodes?max_episodes=1..100 (default 10) - the entries, newest first, each with status (queued, processing, stored, failed), reason and flag.
- GET /v1/memory/facts/:uuid - one fact.
- POST /v1/memory/episode-entities { episode_uuids: [...] } - up to 10 entries: the things and facts each produced.

## Delete and undo

- DELETE /v1/memory/episodes/:uuid - removes one entry.
- DELETE /v1/memory/facts/:uuid - removes one fact.
- GET /v1/memory/history?max_writes&cursor - what each write changed, newest first, with next_cursor for older writes.
- POST /v1/memory/writes/:id/undo { dry_run? } - takes a write (mmo_...) back out, with every later write that depends on it. dry_run: true only reports what would change.
- An account can make 60 deletes an hour, the owner's and the agents' together. Past it: 429 MEMORY_DELETE_RATE_LIMITED with Retry-After. A dry run is not counted.

## The account's own types

- GET /v1/memory/entity-types - the types in force.
- POST /v1/memory/entity-types { name, description, fields? } - a new kind of thing. description tells the reader what counts as one.
- PATCH /v1/memory/entity-types/:name { description?, fields? } - what is given replaces what was there. Later writes use it.
- DELETE /v1/memory/entity-types/:name - retires the type.
- A field is { name, kind, description?, options? }. kind is text, number, date, boolean or one_of. A one_of field lists its words in options.
- A field cannot be named uuid, name, group_id, labels, created_at, name_embedding, summary or attributes.

## Settings

- GET /v1/memory/settings - enabled and call_memory_access. Not for an agent.
- PUT /v1/memory/settings { enabled?, call_memory_access? } - owner or admin only.
- enabled: false switches memory off for the account. Writes then answer 409 MEMORY_DISABLED.
- call_memory_access decides whether a phone call that STACK holds may search memory while it talks.

## Controls and refusals

With controls on, a write is asked as `memory.write` and a delete or an undo as `memory.delete`. The request carries the kind of change and the length of the text, never the text.

- 422 MEMORY_SECRET_REFUSED - the text looks like a key, a token, a password or a card number. Nothing is stored.
- 422 MEMORY_CONTENT_FLAGGED - the text was flagged as an attack and controls are on. The owner's own episode or fact, and any text with controls off, is stored with its flag.
- 409 MEMORY_LIMIT_REACHED - the account holds as many entries, things or facts as it may.
- 409 MEMORY_WRITE_NOT_UNDOABLE - the write is still queued or being read.
- 409 MEMORY_EPISODE_EXISTS - the uuid you chose is already used.
- 404 MEMORY_SOURCE_MESSAGE_NOT_FOUND - from_message_id is not a message the account received.
- 422 MEMORY_WRITE_SPEND_LIMIT - reading one entry reached the most a single write may cost.
- 503 MEMORY_UNAVAILABLE - memory cannot be reached. The action is not counted.
