受治理的记忆列表:写入、审核、更正、遗忘,以及追溯到来源。
列出记忆
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 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevMemory[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/memories" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevCreateMemoryRequest
| 字段 | 类型 | 说明 |
|---|---|---|
scope必填 | DevMemoryScope | 记忆的范围:project、agent 或 account。 |
space_id | DevSpaceRef | project 和 agent 必填;default 指你的默认 Space,和路径里一样。账户记忆不属于任何 Space,不带这个字段。 |
kind必填 | string | preference、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 |
pinned | boolean | 账户记忆没有这个字段。默认 false |
响应
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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."}'响应结构示例
{
"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
指南:记忆
参数
响应
200application/jsonDevMemory
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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。
需要的能力 视请求而定,见上面的说明。
参数
请求体
application/json DevUpdateMemoryRequest 至少传一个。
| 字段 | 类型 | 说明 |
|---|---|---|
pinned | boolean | 只对以 Entry 写入的记忆有效。固定记忆会改变 Space 的起始内容,所以 Space 所有者必须是人。 |
valid_to | string (date-time) | 关闭提炼事实或账户记忆。以 Entry 写入的记忆没有有效期,请遗忘或更正它。 |
响应
200application/jsonDevMemory
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X PATCH "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'响应结构示例
{
"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。
需要的能力 视请求而定,见上面的说明。
指南:记忆
参数
响应
200application/jsonDevMemoryForgetReceipt
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X DELETE "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevCorrectMemoryRequest 写入替换内容,并关闭旧记忆的有效期。
| 字段 | 类型 | 说明 |
|---|---|---|
text必填 | string | 更正后的内容,1 到 2000 个字符。长度 1 到 2000 |
响应
200application/jsonDevMemory
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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."}'响应结构示例
{
"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
指南:记忆
参数
响应
200application/jsonDevMemoryProvenance
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID/provenance" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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
指南:记忆
参数
请求体
application/json DevReviewMemoryRequest
| 字段 | 类型 | 说明 |
|---|---|---|
decision必填 | confirm | reject | confirm 确认候选记忆;reject 驳回候选记忆。 |
响应
200application/jsonDevMemory
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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"}'响应结构示例
{
"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
指南:记忆
参数
响应
200application/jsonDevMemoryUndoReceipt
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X POST "https://api.mirabase.dev/v2/memories/$MEMORY_ID/undo" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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"
}
]
}