跳到主要内容
开发者文档
文档目录

受治理的记忆列表:写入、审核、更正、遗忘,以及追溯到来源。

列出记忆

GET/v2/memories

列出记忆,最新的在前。不带 status 时返回 candidate 和 confirmed;rejected 和 superseded 需要显式指定。账户记忆只对所有者列出,带 space_id 时不列出。以 Agent 身份或使用收窄的 Key 请求 scope=account 返回 403。开启了离线整理的部署上,内容相同的提炼记忆按组只列一次(group_id、sources),分页按组计数。需要 knowledge:read。

需要的能力 knowledge:read

指南:记忆

参数

名称位置类型说明
cursor查询DevCursor上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024
limit查询integer每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20
scope查询DevMemoryScope只保留一个范围的记忆:project、agent 或 account。
space_id查询DevSpaceRef只保留这个 Space 的记忆。default 指你的默认 Space,和路径里的含义相同。传了它就不列出账户记忆。长度 1 到 256
status查询DevMemoryStatus只保留这个状态的记忆。不传时列表包含 candidate 和 confirmed。
kind查询string只保留一类,例如 preference、decision 或 event,即记忆上的 kind。不存在的类别返回空列表。长度 1 到 64
entry_id查询DevId只保留源自该 Entry 的记忆:作为记忆写入的 Entry 本身,以及从中提炼出的事实。导入对话后,可用此参数读取该对话生成的记忆。不可见的 Entry 返回空列表。长度 1 到 256
q查询string只保留正文包含这段文字的记忆,不区分大小写。此参数为字面匹配,用于浏览和清理,不是检索;按语义查找记忆请调用 search 并传入 include: ["memory"]。长度 1 到 200

响应

  • 200 application/json
字段类型说明
data必填DevMemory[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/memories" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "data": [
    {
      "id": "<id>",
      "scope": "project",
      "kind": "<kind>",
      "status": "candidate",
      "text": "The launch moved to March 14.",
      "pinned": false,
      "created_at": "2026-11-06T00:00:00Z",
      "updated_at": "2026-11-06T00:00:00Z"
    }
  ]
}

写入记忆

POST/v2/memories

写入一条已确认的记忆。account 需要 memory:confirm;project 需要 memory:confirm 和 knowledge:write,且 Space 所有者必须是个人(proposal 模式的 Agent 不能写入 project);agent 需要 knowledge:write 和 Agent 的 Key,写入该 Agent 自己的记忆。若要生成候选记忆而非直接写入已确认记忆,请导入对话。若 project 或 agent 记忆的 text 与同一 Space、同一范围、同一 kind 下的现行记忆相同,则不会重复写入,而是返回 200 及现有记忆(若请求传入 pinned: true,则会将其固定)。措辞不同的陈述算作新的记忆。

需要的能力 视请求而定,见上面的说明。

指南:记忆

参数

名称位置类型说明
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevCreateMemoryRequest

字段类型说明
scope必填DevMemoryScope记忆的范围:project、agent 或 account。
space_idDevSpaceRefproject 和 agent 必填;default 指你的默认 Space,和路径里一样。账户记忆不属于任何 Space,不带这个字段。
kind必填stringpreference、decision 或 progress。账户记忆另有一组:role、project、commitment、preference、person、fact、episode_summary、interview_answer、first_screen_pin、ask_less。长度 1 到 64
text必填string记忆的内容,1 到 2000 个字符。长度 1 到 2000
pinnedboolean账户记忆没有这个字段。默认 false

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/memories" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope":"project","space_id":"default","kind":"preference","text":"Ada prefers release notes in British English."}'

响应结构示例

json
{
  "id": "ent_01JD2M8A7C",
  "space_id": "col_01JD2M7QK3",
  "scope": "project",
  "kind": "preference",
  "status": "confirmed",
  "text": "Ada prefers release notes in British English.",
  "pinned": false,
  "created_at": "2026-11-17T08:05:00Z",
  "updated_at": "2026-11-17T08:05:00Z"
}

读取记忆

GET/v2/memories/{memory_id}

读取一条记忆。提炼事实的 id 含 :,放入路径时需进行百分号编码。你不可见的记忆返回 404 not_found,与不存在的记忆相同。需要 knowledge:read。

需要的能力 knowledge:read

指南:记忆

参数

名称位置类型说明
memory_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "id": "ent_01JD2M8A7C",
  "space_id": "col_01JD2M7QK3",
  "scope": "project",
  "kind": "preference",
  "status": "confirmed",
  "text": "Ada prefers release notes in British English.",
  "pinned": false,
  "created_at": "2026-11-17T08:05:00Z",
  "updated_at": "2026-11-17T08:05:00Z"
}

修改记忆

PATCH/v2/memories/{memory_id}

固定或取消固定一条以 Entry 写入的记忆,或用 valid_to 关闭提炼事实或账户记忆。传入不适用于这类记忆的字段返回 422。候选记忆返回 409(提炼事实是 memory_pending_review,账户记忆是 conflict),请先审核。Space 记忆需要 knowledge:write,账户记忆需要 memory:confirm。

需要的能力 视请求而定,见上面的说明。

参数

名称位置类型说明
memory_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

请求体

application/json DevUpdateMemoryRequest 至少传一个。

字段类型说明
pinnedboolean只对以 Entry 写入的记忆有效。固定记忆会改变 Space 的起始内容,所以 Space 所有者必须是人。
valid_tostring (date-time)关闭提炼事实或账户记忆。以 Entry 写入的记忆没有有效期,请遗忘或更正它。

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X PATCH "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

响应结构示例

json
{
  "id": "ent_01JD2M8A7C",
  "space_id": "col_01JD2M7QK3",
  "scope": "project",
  "kind": "preference",
  "status": "confirmed",
  "text": "Ada prefers release notes in British English.",
  "pinned": false,
  "created_at": "2026-11-17T08:05:00Z",
  "updated_at": "2026-11-17T08:05:00Z"
}

遗忘记忆

DELETE/v2/memories/{memory_id}

永久遗忘一条记忆。提炼事实需要 knowledge:write 及 Space 的 editor 角色;以 Entry 写入的记忆需要 knowledge:write;账户记忆需要 memory:confirm。来源重新发布、恢复、编辑或移动后,该提炼事实不会恢复,相同内容也不会再次提炼到该 Space;来源 Entry 保持不变。以 Entry 写入的记忆及其曾取代的记忆会被彻底删除。再次删除返回 404。若要禁止从某条 Entry 提炼记忆,请在该 Entry 上设置 memory_exclude。

需要的能力 视请求而定,见上面的说明。

指南:记忆

参数

名称位置类型说明
memory_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X DELETE "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "memory_id": "<memory_id>",
  "status": "forgotten"
}

更正记忆

POST/v2/memories/{memory_id}/correct

用你提供的内容替换一条记忆。需要 memory:confirm。旧记忆被关闭,不会恢复。提炼事实或以 Entry 写入的记忆由同一 Space 里的一条新记忆 Entry 替换,只有 Space 所有者或 Agent 能写入,因此响应包含新的 id,supersedes 指向旧记忆。账户记忆由另一条账户记忆替换。以 Entry 写入的记忆已经被替换时返回 409 memory_superseded。

需要的能力 memory:confirm

指南:记忆

参数

名称位置类型说明
memory_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevCorrectMemoryRequest 写入替换内容,并关闭旧记忆的有效期。

字段类型说明
text必填string更正后的内容,1 到 2000 个字符。长度 1 到 2000

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/memories/$MEMORY_ID/correct" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"The launch moved to March 14."}'

响应结构示例

json
{
  "id": "ent_01JD2M8A7C",
  "space_id": "col_01JD2M7QK3",
  "scope": "project",
  "kind": "preference",
  "status": "confirmed",
  "text": "Ada prefers release notes in British English.",
  "pinned": false,
  "created_at": "2026-11-17T08:05:00Z",
  "updated_at": "2026-11-17T08:05:00Z"
}

查看记忆来源

GET/v2/memories/{memory_id}/provenance

一条记忆所依据的 Entry 版本,有引文时附带引文。需要 knowledge:read。

需要的能力 knowledge:read

指南:记忆

参数

名称位置类型说明
memory_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID/provenance" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "memory_id": "<memory_id>",
  "sources": [
    {
      "entry_id": "<entry_id>",
      "version_id": "<version_id>"
    }
  ]
}

审核记忆

POST/v2/memories/{memory_id}/review

处理一条候选记忆。需要 memory:confirm。confirm 将它变为 confirmed,检索会使用它;reject 将它变为 rejected,同一句话不会在这个 Space 里再次被提炼。重复相同决定时,接口原样返回记忆;提交相反决定时,接口返回 409 memory_already_reviewed(账户记忆是 conflict)。要移除已确认的记忆,请遗忘它。

需要的能力 memory:confirm

指南:记忆

参数

名称位置类型说明
memory_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

请求体

application/json DevReviewMemoryRequest

字段类型说明
decision必填confirm | rejectconfirm 确认候选记忆;reject 驳回候选记忆。

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/memories/$MEMORY_ID/review" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision":"confirm"}'

响应结构示例

json
{
  "id": "ent_01JD2M8A7C",
  "space_id": "col_01JD2M7QK3",
  "scope": "project",
  "kind": "preference",
  "status": "confirmed",
  "text": "Ada prefers release notes in British English.",
  "pinned": false,
  "created_at": "2026-11-17T08:05:00Z",
  "updated_at": "2026-11-17T08:05:00Z"
}

撤销记忆写入

POST/v2/memories/{memory_id}/undo

在 30 分钟内撤销你写入的记忆或所做的更正。需要 memory:confirm。对新记忆调用:这条记忆被彻底删除,它所替换的内容在 restored 中恢复。超过 30 分钟时限或这条记忆已被其他记忆取代时,接口返回 409:以 Entry 写入的记忆对应的错误码是 undo_window_expired 或 memory_superseded,账户记忆是 conflict。对提炼事实调用时,接口返回 409 undo_not_applicable:没有人写入过它,且遗忘不可撤销。对以 Entry 写入的记忆第二次撤销返回 404,因为第一次撤销已经把它彻底删除。

需要的能力 memory:confirm

指南:记忆

参数

名称位置类型说明
memory_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/memories/$MEMORY_ID/undo" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "memory_id": "<memory_id>",
  "status": "undone",
  "restored": [
    {
      "id": "<id>",
      "scope": "project",
      "kind": "<kind>",
      "status": "candidate",
      "text": "The launch moved to March 14.",
      "pinned": false,
      "created_at": "2026-11-06T00:00:00Z",
      "updated_at": "2026-11-06T00:00:00Z"
    }
  ]
}