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

# Memories

> Read, import and delete what your agents remember, by user_memory_tag.

A **memory** is one fact. Memories live in a **container** named by a `user_memory_tag`, scoped to your workspace. Every agent with memory on that runs a call under a tag reads that container at the start and adds what it learned at the end. See [Memory](/capabilities/participant-memory) for how calls pick their container.

Scoped API keys need `memories:read` for `GET` and `memories:write` for `POST` / `DELETE`.

## The memory object

```json theme={null}
{
  "id": "452f76ca-c6cd-4ab9-9beb-ded26e54d903",
  "user_memory_tag": "crm_48213",
  "content": "Prefers calls after 6pm IST",
  "token_estimate": 7,
  "source": "import",
  "source_scenario_id": null,
  "source_meeting_id": null,
  "external_id": "note_91",
  "created_at": "2026-05-01T00:00:00.000Z"
}
```

| Field | Description |
| - | - |
| `source` | `meeting` (learned on a call), `import` (added via `POST /memories`) |
| `source_scenario_id` | The agent that learned it, for `meeting` facts |
| `source_meeting_id` | The call it was learned on |
| `external_id` | Its id in the system you imported it from |

## Import memories

`POST /memories`

```json theme={null}
{
  "user_memory_tag": "crm_48213",
  "memories": [
    "Founder of a B2B logistics startup called Shipwise",
    { "content": "Renewal is due in March", "external_id": "note_92", "created_at": "2026-03-01T00:00:00Z" }
  ]
}
```

* `user_memory_tag` — up to 128 characters of letters, digits and `. _ : @ + - / | =`.
* `scenario_id` *(optional)* — one of your agents; the facts are then listed under that agent (`GET /memories/tags?scenario_id=`) and in its Settings.
* `memories` — up to 500 entries, each a string or `{ content, external_id?, created_at? }`. Each fact is at most 1,000 characters; a multi-line string becomes one memory per line, with leading bullets and numbering removed.
* Facts already in the container (compared ignoring case, spacing, bullets and a trailing full stop) are skipped.

**201**

```json theme={null}
{ "user_memory_tag": "crm_48213", "created": [ /* memory objects */ ], "skipped": 0 }
```

## List memories under a tag

`GET /memories?user_memory_tag=crm_48213&limit=100`

Returns `{ "data": [memory, …] }`, newest first. `limit` is 1–1000 (default 400).

## List containers

`GET /memories/tags`

Every tag in the workspace that holds at least one memory, newest activity first. Add `?scenario_id=` for only the containers that agent has written into.

```json theme={null}
{
  "data": [
    {
      "user_memory_tag": "crm_48213",
      "subject": null,
      "memory_count": 7,
      "token_total": 52,
      "first_memory_at": "2026-03-01T00:00:00.000Z",
      "last_memory_at": "2026-10-09T11:24:16.000Z",
      "agents": [{ "id": "…", "name": "Founder coach", "memory_enabled": true }]
    }
  ]
}
```

`subject` is set for the default containers Waterr creates for a person when a call names no tag (`membership:<id>` / `participant:<id>`), and `null` for your own tags.

## Get one container

`GET /memories/tags/{tag}` — the container summary plus `memories`, newest first. URL-encode the tag. **404** when nothing is stored under it.

## Get one memory

`GET /memories/{id}` — the memory object. **404** when it does not exist in your workspace.

## Update a memory

`PATCH /memories/{id}`

```json theme={null}
{ "content": "Lives in Bangalore (previously Mumbai)", "external_id": "note_91" }
```

* `content` — one fact on one line, at most 1,000 characters.
* `external_id` — a string of at most 255 characters, or `null` to clear it.
* `user_memory_tag` and the `source*` fields cannot change; to move a fact to another tag, delete it and import it there.

**200** with the updated memory. **409** when the new content is already remembered under the same tag.

## Delete one memory

`DELETE /memories/{id}` — **204**.

## Delete a container

`DELETE /memories/tags/{tag}` — deletes every memory under the tag, for every agent. **204**; **404** when nothing is stored under it.


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