Overview · twin memory

What one end user's memory holds - its top directories, its counts and the head of its written index - before you search it.

POST /v1/memory/overviewAuth: read key

A search against a memory whose shape you cannot see is a guess, and an empty answer to a guess reads like an absence. Overview is the first call an agent that has never looked should make. It takes no arguments; send {}. Makes no model call.

Headers

Authorizationstringrequired

Bearer tm_…. A read key is enough.

X-Twin-Accountstringrequired

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

X-Request-Idstring

Your id for this request, echoed on the response.

Body

{}objectrequired

An empty object.

Response

directoriesstring[]

The top entries of the tree, as ls with {} returns them.

manifestobject

Counts and stamps: built_at, events, passages, threads, owner (the person whose memory this is, once known), embedding_model, embedding_dim and identity_kept.

indexstring

The first 4,000 characters of the memory's written index page. Empty until the memory has been folded once.

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.

503unavailable

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

Request

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

200 OK

{
  "directories": ["passages/", "raw/", "threads/", "timeline/"],
  "manifest": {
    "built_at": "2026-10-21T10:23:40.600320+00:00",
    "events": 4,
    "passages": 3,
    "threads": 3,
    "owner": "Alice Chen",
    "embedding_model": null,
    "embedding_dim": null,
    "identity_kept": true
  },
  "index": ""
}