Around · twin memory

The passages either side of one passage you already hold, in its own thread. Addressed, never ranked.

POST /v1/memory/aroundAuth: read key

A passage is a piece of one thread: a day of a session, a document, a note. When a hit is the middle of a conversation, around returns what came before and after it, in order. 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

passage_idstringrequired

A passage id from a search, grep or latest result, such as th_8b5e5d4c8946d815/p_0001. 1 to 512 characters.

widthinteger

How many passages on each side. 1 to 5, default 2.

Response

ofstring

The passage id as sent.

passagesobject[]

The passage and its neighbours in thread order, each with path, id, thread and text (up to 1,400 characters). A thread with one passage returns that passage alone. 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.

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

An empty passage_id, or a width outside 1 to 5.

503unavailable

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

Request

curl https://api.twinmemory.dev/v1/memory/around \
  -H "Authorization: Bearer $TWIN_MEMORY_API_KEY" \
  -H "X-Twin-Account: user_42" \
  -H "Content-Type: application/json" \
  -d '{ "passage_id": "th_1c3a2421d280764f/p_0001", "width": 1 }'

200 OK

{
  "of": "th_1c3a2421d280764f/p_0001",
  "passages": [
    {
      "path": "passages/memory/notes/th_1c3a2421d280764f/p_0001.md",
      "id": "th_1c3a2421d280764f/p_0001",
      "thread": "th_1c3a2421d280764f",
      "text": "Context: notes (memory), 2 Oct 2026. Alice is vegan and allergic to peanuts..\n\nAlice is vegan and allergic to peanuts."
    }
  ]
}