Grep · twin memory

Find every passage that holds an exact phrase, ignoring case. For a quoted phrase, an id or an error code that a similarity search would blur.

POST /v1/memory/grepAuth: read key

Grep matches a substring, ignoring ASCII case, against each passage's text and heading. It does not rank. It returns where the phrase is and a fragment around the start of each passage, so the next call can read or around it. Makes no model call.

Headers

Authorizationstringrequired

Bearer tm_…. A read key is enough.

X-Twin-Accountstringrequired

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

X-Request-Idstring

Your id for this request, echoed on the response.

Body

patternstringrequired

The exact text to find. 1 to 2,000 characters. % and _ are matched literally.

scopestring

A path prefix to search under, such as passages/memory/notes. Up to 512 characters.

limitinteger

How many matches to return. 1 to 50, default 50.

Response

patternstring

The pattern as sent.

totalinteger

How many passages match, before limit.

matchesobject[]

Each match: path, id (the passage id) and text, the first 320 characters of the passage.

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 pattern, or a limit outside 1 to 50.

503unavailable

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

Request

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

200 OK

{
  "pattern": "peanuts",
  "total": 1,
  "matches": [
    {
      "path": "passages/memory/notes/th_1c3a2421d280764f/p_0001.md",
      "id": "th_1c3a2421d280764f/p_0001",
      "text": "Alice is vegan and allergic to peanuts."
    }
  ]
}