Items

An item is one thing you add for an end user: a chat message, a document or a note. You send items to /v1/memory/add, up to 500 at a time.

Three kindsCopy Anchor Link

Use message for what people said to each other or to your assistant. Use document for longer text you want searchable in pieces. Use note for a fact your backend already knows, such as a preference from your CRM.

The id is the item's identityCopy Anchor Link

Give every item an id that is stable in your system, such as your message id.

• The same id again is the same item. Sending it again with the same content changes nothing. A retry is always safe.
• The same id with changed content is an edit. The stored copy is replaced and the conversation it is in is filed again. Earlier versions are kept for your backend; see Versions & edits.
• An edit fixes; a change is a new item. Reuse an id only to fix the same statement, such as a typo or a mistake. When something changes, such as a new address or a new plan, add a new item with a new id: memory keeps both, each with its date, and shows them newest first. An edit replaces the old words, and the new words keep the old item's date, so an edit used for a change loses the earlier value and misdates the new one.
• A field you leave out is kept. Sending an id again replaces its text and keeps its about, metadata, expires and author unless the request sends them. Send null to clear one.
• The time is fixed once memory holds the item. An edit keeps the at the item first had, even if you send a new one. To move an item in time, forget it, then add it again.

An item without an id is named for you:

• With an at, it is named by its kind, session, author, role, text and time. Sending the same words at the same time again is the same item.
• Without an at, it gets a random id. Sending it twice adds it twice.

So send an id, or send an Idempotency-Key header with the request.

SessionsCopy Anchor Link

session groups messages into conversations. Use your conversation or chat id.

• The messages of one session on one day are one conversation, called a thread. A session that runs for months is many threads, one a day. This keeps the cost of each add to the size of that day, not of the whole session.
• The session as a whole is still one thing you can forget by name, across all its days.
• Messages with no session are cut into conversations by time, the way a chat channel's loose messages are.

session applies to messages. Documents and notes are each a thread of their own.

Who said itCopy Anchor Link

author is a name, or an object that says who the person is:

{
  "author": { "id": "u_42", "name": "Alice Chen", "email": "alice@example.com", "self": true }
}

• id is your stable id for the person. It is the strongest thing memory can be told: two spellings of one name with one id are one person, and one name with two ids is two people.
• email and handle join the person to themselves where the same person appears elsewhere.
• self: true marks the end user whose memory this is.

role says what kind of speaker it is:

• "user" marks the end user, when author.self is not given.
• "assistant", "agent", "bot", "tool" and "system" mark a machine. A machine's turns are read for what they offer, and a machine is never the subject of what is known about the person.

Title, about and metadataCopy Anchor Link

• title names a document or a note. It heads every passage cut from it.
• about lists the pieces of work an item belongs to, as kind:name, such as project:lisbon-trip or ticket:4512. A bare name is filed as a topic. Up to 20 per item. Memory gathers the sessions about one piece of work by these.
• metadata is any JSON object. It is stored with the item and returned by read. Nothing filters on it yet Soon.

ExpiryCopy Anchor Link

expires is a date or time after which the item is forgotten, with everything learned from it. See Expiry.

FieldsCopy Anchor Link

A time without an offset is taken as UTC.

RelatedCopy Anchor Link

• Add reference: the request and response.
• Records & reading: what happens to an item after it lands.
• Documents & notes: when to use each kind.