Replay Memory MCP Tool

The replay_memory tool provides a positional read of a conversation’s durable, ordered memory log. It enables clients to rebuild conversation state from a specific point, for example, after a system restart or to analyze historical interactions.

Authentication

This tool requires the site’s Basic credentials. Clients authenticating with a read-only token (Bearer token) will be rejected with an unprocessable_parameters error, indicating that Basic authentication is required.

Functionality

replay_memory retrieves a sequence of memory items starting from a specified offset and returning up to limit items. The items are returned in ascending sequence order.

• Paginating through a conversation: To restore a whole conversation, start at offset 0. After each page, update the offset to the last returned item’s sequence number plus one. Stop when a page shorter than limit (including an empty one) is returned, as this signals the end of the log.
• Sequence Numbers: Sequence numbers are per-conversation, 0-based, and gapless, so an offset directly corresponds to a position in the log. There is no separate cursor token.
• Empty Results: An unknown but well-formed conversation_id, or an offset past the end of the log, yields an empty list of items, not an error.
• Related Tools:
  • For retrieving only the most recent items of a conversation, use Recall Memory.
  • To discover which conversations exist for your site, use List Conversations.

Request: ReplayMemoryRequest

{
  "properties": {
    "conversation_id": {
      "description": "The pseudonymous handle of the conversation to read, 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; an unknown one reads as an empty list.",
      "type": "string"
    },
    "limit": {
      "description": "Maximum number of items to return, in ascending sequence order starting at `offset`. A page shorter than `limit` — including an empty one — signals that the end of the log was reached. Max 1000.",
      "format": "uint64",
      "minimum": 0,
      "maximum": 1000,
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "Sequence number to start reading from; sequence numbers are per conversation, 0-based, and gapless, so this is also the position in the log. Defaults to 0.",
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "conversation_id",
    "limit"
  ],
  "title": "ReplayMemoryRequest",
  "type": "object"
}

Response: ReplayMemoryResponse

{
  "properties": {
    "items": {
      "description": "The items from `offset` onward, in ascending sequence order. Fewer than `limit` items means the end of the log was reached. An unknown conversation or an `offset` past the end yields an empty list.",
      "items": {
        "$ref": "#/$defs/McpMemoryItem"
      },
      "type": "array"
    }
  },
  "required": [
    "items"
  ],
  "title": "ReplayMemoryResponse",
  "type": "object",
  "$defs": {
    "McpMemoryItem": {
      "properties": {
        "payload": {
          "additionalProperties": true,
          "description": "The remembered JSON object, exactly as it was appended — contents are stored verbatim, never interpreted.",
          "type": "object"
        },
        "recorded_at": {
          "description": "Server-side commit time of the item's batch, as an RFC3339 timestamp; all items appended in one batch share it.",
          "type": "string"
        },
        "seq": {
          "description": "Sequence number of the item: per conversation, 0-based, gapless, in append order.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "seq",
        "recorded_at",
        "payload"
      ],
      "type": "object"
    }
  }
}