GET /v1/memory: List and search memories

Without q, every memory this key can read, newest first, a page at a time. With q, a search: by meaning when an embedding model is available to the key, otherwise by words. search.matched_on says which was attempted: a search by meaning whose embedding call fails falls back to words and still reports meaning. The key's scope decides what is visible, exactly as it does in chat: an organisation key never sees personal memory, a "mine only" key never sees shared memory, and team and connection grants apply. A search, and a read by id, count as using the memories they return; a listing does not.

Example

Against https://platform.memtro.com, with your key in MEMTRO_API_KEY.

import os, requests r = requests.get( "https://platform.memtro.com/v1/memory", headers={"Authorization": f"Bearer {os.environ['MEMTRO_API_KEY']}"}, params={"q": "billing migration", "limit": 5}, ) r.raise_for_status() print(r.json())

A search. A listing has `as_of` in place of `search`, and a `next_cursor` while `has_more` is true.

{
  "object": "list",
  "data": [
    {
      "object": "memory",
      "id": "6f1c…",
      "content": "Priya Shah owns the billing migration (BIL-142) from 3 November 2026.",
      "kind": "fact",
      "scope": "shared",
      "source": "sync",
      "system": "linear",
      "url": "https://linear.app/…",
      "confidence": 0.9,
      "importance": 0.6,
      "trust": "trusted",
      "taint": null,
      "corroborations": 1,
      "valid_from": "2026-11-03",
      "valid_to": null,
      "superseded_by": null,
      "superseded_at": null,
      "subject_entity_id": "a83e…",
      "entity_ids": ["a83e…", "0c2d…"],
      "connection_id": "c19b…",
      "episode_id": null,
      "created_at": "2026-11-03T10:14:22.000Z",
      "score": 0.82
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "search": { "query": "billing migration", "matched_on": "meaning", "as_of": null }
}

Authentication

An API key, as Authorization: Bearer or x-api-key. Read-only keys may call it.

Every reply, errors included, carries x-request-id and request-id headers with the same id, starting req-. Quote it to support.
Browsers may call it from any origin: it answers CORS preflights and allows the Authorization, x-api-key and Anthropic version headers.

Query parameters

qstringOptional

Search for this, at least two characters. Search results are not paged.

scopestringOptional

Narrow to shared or personal memory. It narrows what the key can read and never widens it: personal on an organisation key, or org on a "mine only" key, is a 400.

One of org, personal or all.

Default:

all

as_ofstringOptional

A date: memory as it stood then.

limitintegerOptional

Results per page, at most 100: a larger number reads as 100, and anything below 1 or not a number as 20.

Default:

20

cursorstringOptional

The next_cursor from the previous page. A cursor that cannot be read starts again from the first page rather than failing.

Pagination

Listing is keyset-paged: pass each reply's next_cursor as cursor until has_more is false. New memories written while you page do not shift the pages you have not read yet. Search is not paged: limit is the whole result, has_more is false and next_cursor is null; to read everything, list.

Response

200application/json

A list of memory objects.

object"list"Optional

Always list.

dataarray of objectsOptional

Memories; in a search each also has score (a number, or null).

22 fields of data

object"memory"Optional

Always memory.

idstringOptional

The memory's id.

contentstringOptional

The statement, as remembered.

kindstringOptional

What sort of statement it is.

One of fact, decision, preference, event or procedure.

scopestringOptional

Who it belongs to: the organisation, a team, or one person.

One of shared, team or personal.

sourcestringOptional

Where it came from, such as chat, sync or import.

systemstring or nullOptional

The connected system it was read from, if any.

urlstring or nullOptional

A link to the record it came from, if one was kept.

confidencenumberOptional

How sure the extractor was.

importancenumberOptional

How much it matters, as the extractor judged it.

truststring or nullOptional

Whether it is believed outright or waiting to be confirmed.

taintstring or nullOptional

Set when it was learned from outside content.

corroborationsintegerOptional

How many times something independent has confirmed it.

valid_fromstring or nullOptional

Start of the period the statement is about.

valid_tostring or nullOptional

End of that period, if it has one.

superseded_bystring or nullOptional

The id of the memory that replaced it.

superseded_atstring or nullOptional

When it was replaced.

subject_entity_idstring or nullOptional

The entity the statement is about.

entity_idsarray of stringsOptional

Every entity it mentions.

connection_idstring or nullOptional

The connection it was synced through.

episode_idstring or nullOptional

The exchange or import it was learned from.

created_atstringOptional

When it was recorded.

has_morebooleanOptional

Whether there is another page.

next_cursorstring or nullOptional

Pass as cursor for the next page.

as_ofstring or nullOptional

Listing: the as_of you sent.

searchobjectOptional

Search only: query, matched_on (meaning or words) and as_of.

Errors

In the OpenAI envelope, {"error": {"message", "type", "param", "code"}}. What each code means and what to do about it is in the error catalogue.

Status	Code	When
400	`unsupported_parameter`	`q` shorter than two characters, a `scope` the key cannot narrow to, or an `as_of` that is not a date. `param` names which.
401	`invalid_api_key`	The key is missing, malformed, revoked or expired.
402	`subscription_inactive`	The organisation has no active subscription.

List and search memories