Documents and notes

Not everything worth remembering is a chat turn. An item of kind document holds a longer text, such as a plan, a contract or a page of a knowledge base. An item of kind note holds one statement to keep, such as a preference your CRM knows.

Which kind to useCopy Anchor Link

Use a note for a fact you already know, such as "Alice is vegetarian and allergic to peanuts." Use a document for text the user wrote or shared that a question may need a part of.

Add a documentCopy Anchor Link

curl https://api.twinmemory.dev/v1/memory/add \
  -H "Authorization: Bearer $TWIN_MEMORY_API_KEY" \
  -H "X-Twin-Account: user_42" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "trip-doc",
        "kind": "document",
        "title": "Porto trip plan",
        "at": "2026-10-03T08:00:00Z",
        "text": "Day 1: train from Lisbon to Porto at 08:00. Day 2: Ribeira walk and port tasting."
      },
      {
        "id": "pref-diet",
        "kind": "note",
        "text": "Alice is vegetarian and allergic to peanuts.",
        "metadata": {"source": "crm"}
      }
    ]
  }'

metadata is stored with the item and returned when you read it. Nothing filters on it.

Edit by idCopy Anchor Link

The id is the item's identity. Send the same id again with new text, a new title or new metadata, and it is an edit: the item is replaced, and when its words change its passages are cut again. Each version is kept, and versions returns them. about, metadata, expires and author you leave out are kept; null clears one.

Edit a note only to fix it, such as a typo or a wrong figure. When something changes, such as a new address, add a new note with a new id: memory keeps both, each dated, and shows the newest first. A document revised in place, such as a policy page, is an edit.

The time of an item is fixed once it is held. To move a document in time, forget it and add it again.

Temporary documentsCopy Anchor Link

Give a document an expires time when it should not outlive a purpose, such as a booking that ends:

{ "id": "trip-doc", "kind": "document", "title": "Porto trip plan", "expires": "2026-12-31", "text": "..." }

From that time no read returns it, or anything learned from it, and every copy and every version is erased. Send the item again with the same id and a new expires to move it, or with "expires": null to keep it. See Expiry.

SizeCopy Anchor Link

A request body is at most 1,000,000 bytes, and an add carries at most 500 items. A document's text has no bound of its own beyond the body. Split a very large document into parts, each an item with its own id and a title such as "Handbook, part 3", and send them across several requests.

Find them againCopy Anchor Link

• search finds passages by meaning and by words. Pass "scope": "passages/memory/documents" to search documents only.
• grep finds an exact phrase, ignoring case, such as an order number or a quoted line.
• read returns one passage whole by the path a search or grep gave you.
• ls lists what is under a path, such as passages/memory, which holds documents/, messages/ and notes/.

{
  "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."
    }
  ]
}