---
title: "List memories"
method: GET
path: "/v1/agents/{agent}/memories"
tags: ["agents"]
---

# List memories

`GET /v1/agents/{agent}/memories`

## Request

- Base URL: `https://innernet.live/api`
- URL: `https://innernet.live/api/v1/agents/{agent}/memories`
- Auth: HTTP bearer

The agent's current memories, newest first, in pages. Filter by `subject`, `user_id`, `run_id`, `kind` or `tag`; expired ones are left out unless `include_expired` is true, and so are older versions of a memory (read those with `…/memories/{id}/history`). Without a `user_id` or a `subject` it lists every subject, the agent's users' memories included. The answer is `{ memories, next_cursor }`: pass `next_cursor` back as `cursor` for the next page, and stop when it is `null`. The cursor is a time (ISO 8601, the `created_at` of the last memory on the page), so URL-encode it if you build the query by hand: a `+` in a time zone offset would otherwise be read as a space and refused. A paused agent can still be listed. Needs the agent's own key or a person's key with `read`.

## Path parameters

- `agent` string, required

## Query parameters

- `subject` 'agent' | 'owner' | 'user'
- `user_id` string
- `run_id` string
- `kind` 'fact' | 'preference' | 'episode' | 'procedure' | 'instruction' | 'note'
- `tag` string
- `limit` integer
- `cursor` string, date-time
- `include_expired` boolean

## Response `200`

OK

- object
  - `memories` AgentMemory[], required
    - `id` string, uuid
    - `agent` string: The agent's slug.
    - `content` string, nullable
    - `kind` 'fact' | 'preference' | 'episode' | 'procedure' | 'instruction' | 'note'
    - `subject` 'agent' | 'owner' | 'user': Who it is about: the agent's own knowledge, the person who owns the agent, or one of its users.
    - `user_id` string, nullable: Your end user, when `subject` is `user`.
    - `run_id` string, nullable
    - `tags` string[]
    - `metadata` object
    - `importance` integer
    - `confidence` number, nullable
    - `immutable` boolean
    - `source` 'api' | 'extract' | 'dashboard' | 'import'
    - `event_at` string, date-time, nullable
    - `expires_at` string, date-time, nullable
    - `supersedes` string, uuid, nullable: The memory this one is the next version of.
    - `superseded_at` string, date-time, nullable: Set once a newer version has replaced this one.
    - `about_you` object, nullable: Set when the memory is about the person who owns the agent: where it stands with them.
      - `state` 'held' | 'kept' | 'declined' | 'auto'
      - `dimension` string, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `score` number: Only on recall and context results: 0 to 1.
  - `next_cursor` string, date-time, nullable, required: Pass it back as `cursor` for the next page. `null` on the last page.

## Other responses

- `400`: Error: a filter is wrong or not one this call takes; `detail.field` names it (`invalid`)
- `401`: Error
- `403`: Error: this key cannot read (`forbidden`)
- `404`: Error: no such agent for this key (`not_found`)
- `429`: Error: over the agent's reads a minute (`rate_limited`; `Retry-After: 60`)
- `503`: Error: agents are not switched on yet (`unavailable`)

---

[API](https://skmtc.dev/innernet/apis/innernet-api.md) · [All operations](https://skmtc.dev/innernet/apis/innernet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/innernet/apis/innernet-api/revisions/1ee09aec71a9?raw)