Latest · twin memory

The most recent passages, newest first, or every passage between two dates. Ordered by time, never ranked.

POST /v1/memory/latestAuth: read key

Recency is not a similarity: a search for "the latest message" scores those words against the text. Latest orders by time instead. With no dates it returns the newest few passages; with after or before it returns what happened in that window. Makes no model call.

Headers

Authorizationstringrequired

Bearer tm_…. A read key is enough.

X-Twin-Accountstringrequired

The end user whose memory to read. See End users.

X-Request-Idstring

Your id for this request, echoed on the response.

Body

kinteger

How many passages. 1 to 50, default 10.

placestring

Either segment of a passage path under passages/, such as memory or notes. Default "", everywhere. Up to 512 characters.

afterdate

Only passages from this day on, as YYYY-MM-DD or a full ISO time.

beforedate

Only passages from before this day.

Response

placestring

The place as sent, or a sentence saying the whole memory was searched.

windowstring

The dates applied, such as the beginning to now.

foundinteger

How many passages came back.

passagesobject[]

Newest first, each with path, id, thread and text (up to 1,400 characters). Each also carries content: "stored" and roles, who spoke in it (user, assistant), so you can quote it as data; see Using memory with an LLM.

placesstring[]

When a place matched nothing: the places this memory holds, so the next call can name one.

whystring

With places: why the list is empty.

Errors

400bad request

X-Twin-Account is missing or not a usable id.

401unauthorized

The bearer is not a key this service issued.

404not found

no memory for end user 'user_42' yet.

422invalid

A k outside 1 to 50, or a date that is not a real day.

503unavailable

At capacity, or this end user is being rebuilt. Retry after Retry-After seconds.

Request

curl https://api.twinmemory.dev/v1/memory/latest \
  -H "Authorization: Bearer $TWIN_MEMORY_API_KEY" \
  -H "X-Twin-Account: user_42" \
  -H "Content-Type: application/json" \
  -d '{ "k": 2 }'

200 OK

{
  "place": "everywhere, except this twin's own Claude Code sessions",
  "window": "the beginning to now",
  "found": 2,
  "passages": [
    {
      "path": "passages/memory/documents/th_a4c4bfb9e995f6bc/p_0001.md",
      "id": "th_a4c4bfb9e995f6bc/p_0001",
      "thread": "th_a4c4bfb9e995f6bc",
      "text": "Context: documents (memory), 3 Oct 2026. Porto trip plan.\n\nDay 1: train from Lisbon to Porto at 08:00. …"
    },
    {
      "path": "passages/memory/notes/th_1c3a2421d280764f/p_0001.md",
      "id": "th_1c3a2421d280764f/p_0001",
      "thread": "th_1c3a2421d280764f",
      "text": "Context: notes (memory), 2 Oct 2026. …\n\nAlice is vegan and allergic to peanuts."
    }
  ]
}

200 OK, a place that matches nothing

{
  "place": "slack",
  "window": "the beginning to now",
  "found": 0,
  "passages": [],
  "places": ["memory/documents", "memory/messages", "memory/notes"],
  "why": "nothing under 'slack'. `places` lists what this store actually holds."
}