Read · twin memory

Read one file of an end user's memory whole, by the exact path a search, grep or ls gave you.

POST /v1/memory/readAuth: read key

Every result in twin memory carries a path. Read returns that file verbatim: a passage with its header, a ledger entry as it was stored, or a page built from the facts. No ranking. Makes no model call.

A path that does not exist is not an error: the answer says so and lists what is next to it.

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

pathstringrequired

The file's path, such as passages/memory/notes/th_1c3a2421d280764f/p_0001.md. Up to 512 characters. A ledger entry, under raw/, holds an item as it was added, metadata included.

Response

pathstring

The path as sent.

textstring

The file's contents. Present when the file exists.

errorstring

no such file, when it does not.

siblingsstring[]

With error: the entries of the directory the path names. Directories end in /.

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

read needs a path; /memory/ls lists them, for an empty path.

503unavailable

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

Request

curl https://api.twinmemory.dev/v1/memory/read \
  -H "Authorization: Bearer $TWIN_MEMORY_API_KEY" \
  -H "X-Twin-Account: user_42" \
  -H "Content-Type: application/json" \
  -d '{ "path": "passages/memory/notes/th_1c3a2421d280764f/p_0001.md" }'

200 OK

{
  "path": "passages/memory/notes/th_1c3a2421d280764f/p_0001.md",
  "text": "---\npath:     passages/memory/notes/th_1c3a2421d280764f/p_0001.md\nthread:   th_1c3a2421d280764f\nwhen:     2026-10-02T12:00:00+00:00 → 2026-10-02T12:00:00+00:00\nspeakers: [system]\nturns:    [ev_50d009638ecf9772]\n---\nContext: notes (memory), 2 Oct 2026. Alice is vegan and allergic to peanuts..\n\nAlice is vegan and allergic to peanuts.\n"
}

200 OK, no such file

{
  "path": "passages/memory/notes/nope.md",
  "error": "no such file",
  "siblings": ["th_1c3a2421d280764f/"]
}