---
title: "List Memories"
method: GET
path: "/api/v1/memory/list"
tags: ["memory"]
---

# List Memories

`GET /api/v1/memory/list`

## Request

- Base URL: `https://memory.kagura-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://memory.kagura-ai.com/api/v1/memory/list`
- Auth: none declared

List memories for the authenticated user.

Args:
    user: Authenticated user
    db: Database session
    scope: Filter by scope (working or persistent)
    type: Filter by memory type
    context_id: Optional context ID. When present, the caller must have
        workspace-read access (uniform 404 via ``PermissionService`` on
        denial / non-existence). For shared contexts every member sees
        every memory regardless of original creator; for private contexts
        only the creator sees their own. Mirrors the graph routes'
        ``owner_filter = user_id if context.is_private else None`` pattern
        in ``api/routes/graph.py``.
    q: Optional case-insensitive substring filter applied to
        ``Memory.summary`` via SQL ``ILIKE``. Surrounding whitespace is
        stripped, and whitespace-only / empty values are normalized to
        ``None`` (no filter). Independent of ``owner_filter`` — works
        for both private (creator-only) and shared (all-members)
        contexts.
    limit: Maximum number of memories to return
    offset: Pagination offset

Returns:
    Paginated list of memories

## Query parameters

- `scope` string, nullable
- `type` string, nullable
- `context_id` string, uuid, nullable: Optional context ID to scope results to a single context
- `q` string, nullable: Optional case-insensitive substring filter on memory.summary. Whitespace-only values are treated as None.
- `tags` string[], nullable: Filter to memories having ANY of these tags (exact match). Repeat the param to pass several: ?tags=a&tags=b. Combined with other filters (e.g. q) by AND. Blank / whitespace-only entries are ignored.
- `tags_match` string: How to combine `tags`: `any` (default — memory has at least one of the tags, PG array overlap; preserves #618 behavior) or `all` (memory holds every given tag, PG array contains — #830 drill-down).
- `trigger_from` string, nullable: Time Memory (#877) window lower bound (naive ISO, e.g. 2026-07-01T00:00:00). Selects type='time' memories whose stored [trigger_from, trigger_until] window overlaps the query window. Pass 'now' here to get upcoming items.
- `trigger_until` string, nullable: Time Memory (#877) window upper bound (naive ISO). Omit for an open-ended (future) window.
- `lat_min` number, nullable: WHERE-axis (#1334) bbox lower latitude bound (degrees). Any bbox bound restricts results to memories with a complete location (generated columns from details.location); bounds may be one-sided.
- `lat_max` number, nullable: Bbox upper latitude bound.
- `lon_min` number, nullable: Bbox lower longitude bound. lon_min > lon_max selects the antimeridian-crossing (±180°) box: lon >= lon_min OR lon <= lon_max.
- `lon_max` number, nullable: Bbox upper longitude bound (see lon_min for the antimeridian-crossing form).
- `order_by` string: Sort key. 'created_at' (default, desc) or 'trigger_from' (asc) for upcoming-first Time Memory listing (#877).
- `limit` integer
- `offset` integer

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- MemoryListResponse: Memory list response.
  - `memories` MemoryListItem[], required
    - `id` string, required
    - `summary` string, required
    - `type` string, required
    - `scope` string, required
    - `importance` number, required
    - `created_at` string, required
    - `updated_at` string, required
    - `location` MemoryListItemLocation: WHERE-axis coordinates of a list item (#1334), sourced from the ``location_lat`` / ``location_lon`` generated columns.
      - `lat` number, required
      - `lon` number, required
  - `total` integer, required
  - `has_more` boolean, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud.md) · [All operations](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/revisions/aa9df1a21db9?raw)