Get Actor Fact Change History

curl -X GET 'https://app.memorylake.ai/openapi/memorylake/api/v3/workspaces/ws-fe314186ccd18cde04d6af48a5afd79f/actors/actor_5e4d3c2b1a0f/facts/fact-11a0e057d09877c9c492633fd60424fc/trace' \
  -H 'Authorization: Bearer sk_xxxxxx'

{
  "success": true,
  "data": {
    "fact": {
      "id": "fact-11a0e057d09877c9c492633fd60424fc",
      "fact": "User's primary programming language is Python",
      "metadata": {},
      "expired": false,
      "created_at": "2025-06-10T14:30:00Z",
      "updated_at": "2025-06-12T09:15:00Z"
    },
    "trace": [
      {
        "history_id": "facthist-6ee3e00169cf409699c9d214c1ab1ae8",
        "event": "UPDATE",
        "source_kind": "MANUAL",
        "old_fact": "User's primary programming language is Java",
        "new_fact": "User's primary programming language is Python",
        "source_entry_ids": [],
        "source_event_id": "api-0c048db26b904f11b7feff8549f7e47e",
        "timestamp": "2025-06-12T09:15:00Z"
      },
      {
        "history_id": "facthist-93b16a154fe74bbe8a0be7c938123c98",
        "event": "ADD",
        "source_kind": "COOK",
        "new_fact": "User's primary programming language is Java",
        "conversation_id": "conv-0a0c350c96034fd6a3092fd3bba70bcc",
        "source_entry_ids": [
          "conv-entry-393ddf4c71f0423eb9dce5f0ddc221af",
          "conv-entry-ef0d7f55c7484f1dae5b88db99c443d4"
        ],
        "source_event_id": "cookrun-fdc3db03e81944da8bbf511416a65881",
        "timestamp": "2025-06-10T14:30:00Z"
      }
    ]
  }
}

curl -X GET 'https://app.memorylake.ai/openapi/memorylake/api/v3/workspaces/ws-fe314186ccd18cde04d6af48a5afd79f/actors/actor_5e4d3c2b1a0f/facts/fact-11a0e057d09877c9c492633fd60424fc/trace' \
  -H 'Authorization: Bearer sk_xxxxxx'

{
  "success": true,
  "data": {
    "fact": {
      "id": "fact-11a0e057d09877c9c492633fd60424fc",
      "fact": "User's primary programming language is Python",
      "metadata": {},
      "expired": false,
      "created_at": "2025-06-10T14:30:00Z",
      "updated_at": "2025-06-12T09:15:00Z"
    },
    "trace": [
      {
        "history_id": "facthist-6ee3e00169cf409699c9d214c1ab1ae8",
        "event": "UPDATE",
        "source_kind": "MANUAL",
        "old_fact": "User's primary programming language is Java",
        "new_fact": "User's primary programming language is Python",
        "source_entry_ids": [],
        "source_event_id": "api-0c048db26b904f11b7feff8549f7e47e",
        "timestamp": "2025-06-12T09:15:00Z"
      },
      {
        "history_id": "facthist-93b16a154fe74bbe8a0be7c938123c98",
        "event": "ADD",
        "source_kind": "COOK",
        "new_fact": "User's primary programming language is Java",
        "conversation_id": "conv-0a0c350c96034fd6a3092fd3bba70bcc",
        "source_entry_ids": [
          "conv-entry-393ddf4c71f0423eb9dce5f0ddc221af",
          "conv-entry-ef0d7f55c7484f1dae5b88db99c443d4"
        ],
        "source_event_id": "cookrun-fdc3db03e81944da8bbf511416a65881",
        "timestamp": "2025-06-10T14:30:00Z"
      }
    ]
  }
}

GET /openapi/memorylake/api/v3/workspaces/{workspaceId}/actors/{actorId}/facts/{factId}/trace

Returns a fact scoped to an actor together with its full change history, newest first, in a single response. Each entry records one change — the fact being added, updated, or forgotten — and how it was made: extracted from a conversation, or made directly through the API. For a change extracted from a conversation, the entry carries the conversation_id and the source_entry_ids of the messages it came from. Pass them to Batch Get Messages to read those messages. Forgetting a fact does not erase its history. You can still get the history of a forgotten fact, including the text it had before it was forgotten; the fact itself comes back with expired set to true. For an agent’s facts, use Get Agent Fact Change History.

Permission required: workspace_actor:fact_read

Path Parameters

string

required

Workspace ID

string

required

Actor ID

string

required

Fact ID

curl -X GET 'https://app.memorylake.ai/openapi/memorylake/api/v3/workspaces/ws-fe314186ccd18cde04d6af48a5afd79f/actors/actor_5e4d3c2b1a0f/facts/fact-11a0e057d09877c9c492633fd60424fc/trace' \
  -H 'Authorization: Bearer sk_xxxxxx'

Response

object

Show Fact history

object

The fact in its current state — the same object Get Actor Fact returns. expired is true if the fact has been forgotten.

array

Change history, newest first. The whole history is returned at once; it is not paginated.

Show Change entry

string

Unique identifier of this change

string

The kind of change: ADD, UPDATE, or FORGET

string

How the change was made: COOK — extracted from a conversation; MANUAL — made directly through the API (adding, updating, or forgetting a fact)

string

The fact text before the change. Absent for ADD

string

The fact text after the change. Absent for FORGET

string

The conversation the change was extracted from. Absent for a MANUAL change

string[]

IDs of the messages the change was extracted from; empty for a MANUAL change. Batch Get Messages leaves out messages that have been deleted since

string

Opaque identifier of the operation that made the change. Changes extracted in the same run share it

string

When the change was made

{
  "success": true,
  "data": {
    "fact": {
      "id": "fact-11a0e057d09877c9c492633fd60424fc",
      "fact": "User's primary programming language is Python",
      "metadata": {},
      "expired": false,
      "created_at": "2025-06-10T14:30:00Z",
      "updated_at": "2025-06-12T09:15:00Z"
    },
    "trace": [
      {
        "history_id": "facthist-6ee3e00169cf409699c9d214c1ab1ae8",
        "event": "UPDATE",
        "source_kind": "MANUAL",
        "old_fact": "User's primary programming language is Java",
        "new_fact": "User's primary programming language is Python",
        "source_entry_ids": [],
        "source_event_id": "api-0c048db26b904f11b7feff8549f7e47e",
        "timestamp": "2025-06-12T09:15:00Z"
      },
      {
        "history_id": "facthist-93b16a154fe74bbe8a0be7c938123c98",
        "event": "ADD",
        "source_kind": "COOK",
        "new_fact": "User's primary programming language is Java",
        "conversation_id": "conv-0a0c350c96034fd6a3092fd3bba70bcc",
        "source_entry_ids": [
          "conv-entry-393ddf4c71f0423eb9dce5f0ddc221af",
          "conv-entry-ef0d7f55c7484f1dae5b88db99c443d4"
        ],
        "source_event_id": "cookrun-fdc3db03e81944da8bbf511416a65881",
        "timestamp": "2025-06-10T14:30:00Z"
      }
    ]
  }
}

Read the source messages

To see what was said when a change was extracted, pass its conversation_id and source_entry_ids to Batch Get Messages:

curl -X POST 'https://app.memorylake.ai/openapi/memorylake/api/v3/conversations/conv-0a0c350c96034fd6a3092fd3bba70bcc/messages/batch-get' \
  -H 'Authorization: Bearer sk_xxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"entry_ids": ["conv-entry-393ddf4c71f0423eb9dce5f0ddc221af", "conv-entry-ef0d7f55c7484f1dae5b88db99c443d4"]}'

MemoryLake API

Memory Router API

Get Actor Fact Change History

Path Parameters

Response

Read the source messages

​Path Parameters

​Response

​Read the source messages

Path Parameters

Response

Read the source messages