append_memory MCP tool

The append_memory tool appends a batch of items to a conversation’s durable, ordered memory log, used for conversational memory management. It returns the assigned sequence range (first_seq to last_seq, inclusive) as a durability acknowledgment. Each item is one self-describing JSON object, stored verbatim; the batch commits atomically and in order. This tool requires the site’s Basic credentials.

Request (AppendMemoryRequest)

Field	Type	Description
conversation_id	string	The pseudonymous handle of the conversation to append to, minted by the client: 8-64 characters from [A-Za-z0-9_-], stable for one conversation, never derived from personal data. A malformed ID is rejected outright — it never falls back to a fresh conversation. To discover which conversations exist for your site, use list_conversations.
items	array of object	The items to remember, in order. Each item is one JSON object whose keys make it self-describing; contents are stored verbatim, never interpreted. The batch commits atomically — all items or none. The array must contain between 1 and 250 items. Each item’s serialized JSON payload must not exceed 256 KiB. The sum of all items’ serialized JSON payloads in one batch must not exceed 1 MiB. The total number of items in a conversation cannot exceed 100,000.

Response (AppendMemoryResponse)

Field	Type	Description
first_seq	number (uint64)	Sequence number assigned to the first item of the batch. Sequence numbers are per conversation, 0-based, gapless, in append order.
last_seq	number (uint64)	Sequence number assigned to the last item of the batch; the batch occupies the inclusive range [first_seq, last_seq].

Conversation ID Rule

The conversation_id is a pseudonymous handle the client mints itself: an opaque string of 8-64 characters from [A-Za-z0-9_-] (UUIDs and nanoids fit), stable for one conversation, and never derived from personal data such as names, e-mail addresses, or account IDs. To discover which conversations exist for your site, use list_conversations.

Durability Semantics

Memory must never block the conversation: the append acknowledgment is a durability signal, not flow control. Permanent validation errors include: the conversation’s site exceeding its rate limit (which returns an error with a Retry-After header), an item’s serialized JSON payload exceeding 256 KiB, the batch’s total serialized JSON payload exceeding 1 MiB, or the conversation exceeding 100,000 items. Any other failure is safe to retry after buffering the batch, and duplicates from retries are tolerated.