> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorylake.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 获取 Agent 事实变更历史

> 返回 Agent 事实及其所有变更记录

```
GET /openapi/memorylake/api/v3/workspaces/{workspaceId}/agents/{agentId}/facts/{factId}/trace
```

在一次响应中返回某个 Agent 的一条事实及其完整变更历史，按时间倒序排列。每条记录对应一次变更（事实被添加、更新或遗忘），并说明变更的来源：从会话中提取，或直接通过 API 操作。

对于从会话中提取的变更，记录中带有 `conversation_id` 以及来源消息的 `source_entry_ids`。将它们传给[批量获取消息](/features/memorylake/api-reference/conversations/batch-get-messages)即可读取这些消息。

遗忘事实不会抹去它的历史。已遗忘的事实仍然可以获取变更历史，包括遗忘前的文本；返回的事实本身 `expired` 为 `true`。

<Note>
  **所需权限：** `workspace_agent:fact_read`
</Note>

### 路径参数

<ParamField path="workspaceId" type="string" required>
  工作空间 ID
</ParamField>

<ParamField path="agentId" type="string" required>
  Agent ID
</ParamField>

<ParamField path="factId" type="string" required>
  事实 ID
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://app.memorylake.cn/openapi/memorylake/api/v3/workspaces/ws-fe314186ccd18cde04d6af48a5afd79f/agents/agent-f8bf71ab17ed8eccad8c0e8ae708273f/facts/fact-11a0e057d09877c9c492633fd60424fc/trace' \
    -H 'Authorization: Bearer sk_xxxxxx'
  ```
</RequestExample>

### 响应

<ResponseField name="data" type="object">
  <Expandable title="事实历史">
    <ResponseField name="fact" type="object">事实的当前状态，与[获取 Agent 事实](/features/memorylake/api-reference/facts/get-agent-fact)返回的对象相同。事实已被遗忘时 `expired` 为 `true`。</ResponseField>

    <ResponseField name="trace" type="array">
      变更历史，按时间倒序排列。一次返回全部历史，不分页。

      <Expandable title="变更记录">
        <ResponseField name="history_id" type="string">本次变更的唯一标识符</ResponseField>
        <ResponseField name="event" type="string">变更类型：`ADD`、`UPDATE` 或 `FORGET`</ResponseField>
        <ResponseField name="source_kind" type="string">变更方式：`COOK` 表示从会话中提取；`MANUAL` 表示直接通过 API 操作（添加、更新或遗忘事实）</ResponseField>
        <ResponseField name="old_fact" type="string">变更前的事实文本。`ADD` 记录中没有此字段</ResponseField>
        <ResponseField name="new_fact" type="string">变更后的事实文本。`FORGET` 记录中没有此字段</ResponseField>
        <ResponseField name="conversation_id" type="string">提取出本次变更的会话。`MANUAL` 变更没有此字段</ResponseField>
        <ResponseField name="source_entry_ids" type="string[]">提取出本次变更的消息 ID；`MANUAL` 变更为空数组。之后被删除的消息不会出现在批量获取消息的结果中</ResponseField>
        <ResponseField name="source_event_id" type="string">产生本次变更的操作的不透明标识符。同一次提取产生的变更共享同一个值</ResponseField>
        <ResponseField name="timestamp" type="string">变更时间</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Success (200) theme={null}
  {
    "success": true,
    "data": {
      "fact": {
        "id": "fact-11a0e057d09877c9c492633fd60424fc",
        "fact": "Replies to support tickets in the customer's language",
        "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": "Replies to support tickets in English",
          "new_fact": "Replies to support tickets in the customer's language",
          "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": "Replies to support tickets in English",
          "conversation_id": "conv-0a0c350c96034fd6a3092fd3bba70bcc",
          "source_entry_ids": [
            "conv-entry-393ddf4c71f0423eb9dce5f0ddc221af",
            "conv-entry-ef0d7f55c7484f1dae5b88db99c443d4"
          ],
          "source_event_id": "cookrun-fdc3db03e81944da8bbf511416a65881",
          "timestamp": "2025-06-10T14:30:00Z"
        }
      ]
    }
  }
  ```
</ResponseExample>

### 读取来源消息

要查看提取某次变更时的对话内容，将该记录的 `conversation_id` 和 `source_entry_ids` 传给[批量获取消息](/features/memorylake/api-reference/conversations/batch-get-messages)：

```bash theme={null}
curl -X POST 'https://app.memorylake.cn/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"]}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.