Ls · twin memory

List the entries of one directory of an end user's memory, to see its shape before reading.

POST /v1/memory/lsAuth: read key

An end user's memory is a tree of files: raw/ holds the ledger of what was added, passages/ the passages cut from it, and further directories hold what was built from them. Ls lists one directory. Makes no model call.

Headers

Authorizationstringrequired

Bearer tm_…. A read key is enough.

X-Twin-Accountstringrequired

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

X-Request-Idstring

Your id for this request, echoed on the response.

Body

pathstring

The directory, such as passages/memory. Up to 512 characters. Default "", the top of the tree.

Response

pathstring

The directory as sent, or / for the top.

entriesstring[]

Its entries. 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

A path over 512 characters.

503unavailable

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

Request

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

200 OK

{
  "path": "passages/memory",
  "entries": ["documents/", "messages/", "notes/"]
}

200 OK, with {}

{
  "path": "/",
  "entries": ["passages/", "raw/", "threads/", "timeline/"]
}