Memory API

An agent with hasMemory: true accumulates long-term memory about the user across sessions. These endpoints let a client snapshot, restore and erase that memory, which is primarily useful for testing and for giving users control over their data.

How that memory is structured internally is described in Memory (common library).

GET /api/memory/state

Return the current memory snapshot of the user.

Query Parameters

Parameter Required Type Description

userId

No

UUID

Address another user’s memory. Without it, the user of the current request is used.

Response

A MemoryState object:

Field Type Description

id

UUID string

Snapshot identifier — pass it to the restore endpoint.

userId

UUID string

User the snapshot belongs to.

created

Timestamp

When the snapshot was taken.

dataMemoryUnits

Array

Typed data memory units with their revision history.

shortTermMemoryUnits, sessionMemoryUnits, userMemoryUnits

Array

Scoped memory units of each namespace, with their scope metadata and text.

graphNodes, graphRelationships

Array

The user’s knowledge graph nodes and the edges between them. Empty when the deployment runs without a graph backend.

 
{
  "id": "0f1e2d3c-4b5a-4968-8776-655443322110",
  "userId": "5c8a0f12-7d34-4e56-9a1b-2c3d4e5f6a7b",
  "created": "2026-09-09T14:35:12.008Z",
  "dataMemoryUnits": [
    {
      "id": "user:5c8a0f12…/ai.promethist.engine.model.UserFacts",
      "revisions": [
        { "data": { "facts": ["prefers morning appointments"] },
          "created": "2026-09-02T10:00:00.000Z" },
        { "data": { "facts": ["prefers morning appointments", "parks on level 2"] },
          "created": "2026-09-09T14:31:00.000Z" }
      ]
    }
  ],
  "shortTermMemoryUnits": [],
  "sessionMemoryUnits": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6/session",
      "created": "2026-09-09T14:31:07.412+02:00",
      "turnId": "c3a9d1ef-2d3c-4c9f-9b5f-0e8a2b7d4f21",
      "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "userId": "5c8a0f12-7d34-4e56-9a1b-2c3d4e5f6a7b",
      "namespace": "session",
      "agentRef": "acme-support",
      "agentInfo": { "ref": "acme-support", "state": "Published", "revision": 5 },
      "projectId": "8e29b3d1-6a4f-4c2e-9d70-1f2a3b4c5d6e",
      "tenantId": "1a2b3c4d-5e6f-4708-8912-a3b4c5d6e7f8",
      "text": "The user rescheduled an appointment and asked about parking.",
      "data": []
    }
  ],
  "userMemoryUnits": [],
  "graphNodes": [],
  "graphRelationships": []
}

POST /api/memory/state

Persist the user’s current memory as a snapshot and return it, including the generated id.

Query Parameters

Parameter Required Type Description

userId

No

UUID

Snapshot another user’s memory. Without it, the user of the current request is used.

Takes no request body; the response is a MemoryState object as above.

POST /api/memory/state/{stateId}

Restore a previously saved snapshot, replacing the user’s current memory.

Path Parameters

Parameter Type Description

stateId

UUID

Snapshot to restore, as returned by POST /api/memory/state.

Query Parameters

Parameter Required Type Description

userId

No

UUID

Restore into another user’s memory. Without it, the user of the current request is used.

Takes no request body; the response is the restored MemoryState.

DELETE /api/memory

Delete all memory of the current user. Takes no path parameters, no query parameters and no request body. Sessions and turns are not affected — use DELETE /api/user to remove those as well.