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

写入、提炼、审核、更正和遗忘记忆,以及离线整理记忆。

记忆模型

/v2/memories 用统一结构返回三种来源:账户记忆、以 Entry 写入的记忆、从 Entry 提炼的事实。只有以 Entry 写入的记忆,id 才是 Entry id。提炼的事实通过 provenance 关联到 Entry 和版本。

每条记忆有一个范围和一个状态:范围决定记忆归谁(DevMemoryScope),状态决定检索是否使用它(DevMemoryStatus)。

遗忘是物理删除,没有正文可返回,所以没有 forgotten 状态。

写入记忆

一句始终成立的陈述,例如偏好或决定,用 POST /v2/memories 写入。写入后立即为 confirmed,此后的上下文和回答都会使用。同一内容不会重复写入,各范围需要的权限见参考。

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": "'$SPACE_ID'", "kind": "decision", "text": "Releases go out on Thursdays."}'

从对话中提炼记忆

若要提出候选而非直接写入,请导入对话:POST /v2/spaces/{space_id}/ingest 带 kind: conversation、session_id 和 messages,返回 202。一个批次是一个 Entry,无论有多少轮。发送时持有 memory:confirm,提炼出的事实即是 confirmed,否则是 candidate;回执的 memory_status 说明是哪一种。

curl
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/ingest" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Idempotency-Key: chat-42-batch-1" \
  -H "Content-Type: application/json" \
  -d '{"kind": "conversation", "session_id": "chat-42", "messages": [
    {"role": "user", "content": "Let us ship on Thursdays from now on.", "timestamp": 1762416000000},
    {"role": "assistant", "content": "Noted: releases on Thursdays."}
  ]}'

提炼在索引完成后进行,因此处理任务变为 succeeded 时,记忆可能尚未生成。轮询 GET /v2/entries/{entry_id}/processing,直到 memory.state 不再为 pending:ready 时用 GET /v2/memories?entry_id= 列出该批次生成的记忆;skipped 表示该版本不提炼,原因见下文;failed 表示提炼失败。

curl
# Repeat until memory.state is no longer "pending".
# "skipped" means the batch is not distilled: memory.reason says why.
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/processing" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Then list what the batch wrote.
curl "https://api.mirabase.dev/v2/memories?entry_id=$ENTRY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
  • 同一批次重复导入会产生两个 Entry,因此重试时请携带 Idempotency-Key,见 幂等。
  • 持续记录同一段对话时,每个批次使用相同的 session_id。该 id 也会存为元数据键 session_id,因此 GET /v2/entries?metadata={"session_id":"…"} 可将它们一并列出,检索时可用 filter.metadata 限定到该对话。
  • proposal 模式的 Agent 导入时,提炼结果总是 candidate。

提炼被跳过的原因

写入回执、处理状态和任务中的 memory 是同一个对象。state 为 skipped 时,reason 说明原因;原因可以处理时还带 remediation,按其中的 remediation.action 处理,例如部署没有配置提炼模型时,改为直接 写入记忆。部署不提炼记忆或 Entry 带有 memory_exclude 时,写入回执即为 skipped,无需轮询。distill_disabled、model_not_configured 和 distill_paused 涉及部署配置和账户用量,只有属于 tenant_admin 或持有 knowledge:manage、且未收窄到 Space 或元数据范围的 Key 能看到;其他 Key 看到的是 distill_unavailable(替代前两个);distill_paused 不返回原因,状态仍为 pending。部署停止提炼之前已经提炼完成的版本仍为 ready。全部原因和对应的处理方式见 DevMemoryProcessingReason 和 remediation。

审核、更正和遗忘记忆

curl
# Candidates waiting for review in one Space.
curl "https://api.mirabase.dev/v2/memories?space_id=$SPACE_ID&status=candidate" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Confirm one, or send "reject".
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"}'

# Replace it with what is true now. The response is a new memory whose supersedes names the old one.
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": "Releases go out on Wednesdays."}'

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

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

MEMORY.md

/.mirabase/memory/MEMORY.md 是生成的只读视图,供开始工作的 Agent 读取该 Space 的记忆。同样的记忆产生同样的字节,ETag 是内容哈希,适合做 prompt 缓存前缀。用 GET /v2/spaces/{space_id}/files 读取;它只有原始字节,写入返回 405 virtual_file。在默认写法中,从对话提炼的事实不包含在内,请使用 GET /v2/memories 或检索。开启了离线整理的部署改用索引写法,并增加 RECENT.md,见 索引写法。

curl
# Send back the ETag you have. 304 means nothing changed.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/.mirabase/memory/MEMORY.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H 'If-None-Match: "<etag>"'

离线整理(dreams)

Agent 不在工作时,后台会整理已有的记忆。API 将一次整理运行称为一个 dream。它只整理、不生成:不写新记忆,不改记忆的正文,每个动作都带证据,都可以撤销。合并和取代只生成提案,模型不会自行修改任何记忆,经人工批准后才生效。

离线整理是部署可选的功能。未开启该功能的部署上,本节和下面两节的接口都返回 404,MEMORY.md 保持上面的默认写法,也没有 RECENT.md。

它做什么

  • 核对引文:将每条提炼记忆的逐字引文与来源 Entry 的当前版本比对。若所有引文均不再存在,则将该记忆标为休眠(quote_missing)。
  • 找出闲置的记忆:长期未被取用、也无人确认过的提炼记忆,默认只写进报告,设置为 apply 时标为休眠(unused),再次被取用时恢复。
  • 统计重复:找出表达同一内容的记忆组,并在报告里记录整理前后生效记忆的条数和 token 数(view)。
  • 比较记忆:Space 所有者显式开启 d4 后,才会调用模型比较成对的提炼记忆,判断是否重复、谁取代谁、是否矛盾,结论只会成为 整理提案。默认不调用模型。
  • 自动运行:某个范围有新记忆时自动运行,也可以手动发起。

它不做什么

  • 不生成:不写新记忆,不改记忆正文,不写 Entry、文件或版本,除 MEMORY.md 和 RECENT.md 外不写入任何内容。
  • 模型不直接修改:模型只说明两条记忆的关系,并逐字引用来源,不写任何会进入记忆的文字,也不直接改动记忆。auto 档位尚未开放。
  • 不改动人工确认的内容:审核通过的候选和带 memory:confirm 导入的对话里提炼出的记忆,既不会因为找不到引文而被标记,也不会因为闲置而休眠;以 Entry 写入的记忆和账户记忆,整理都不修改。只有未经人工审核就生效的提炼记忆才可能休眠,它们的状态也是 status: "confirmed"。
  • 不恢复已遗忘的记忆:撤销一次整理也不会使其恢复。
  • 不越界:只在一个范围里整理(Space 的项目记忆,或一个 Agent 的私有记忆),不跨范围,不跨 Space,不在分支上运行。
  • 不删除:整理本身最重的动作是标记休眠;关闭一条记忆只发生在人批准提案之后,也可以撤销。物理删除只来自调用方的遗忘和彻底删除。

记忆分层

不同的记忆适用不同的规则:很少用到却重要的规则,不应因为较少使用而被搁置;事件有先后顺序,不应作为重复项合并。层由记忆的 kind 和有效时间决定,在整理时计算;记忆本身没有这个字段,提案和判定上带 layer。

四个层各包含哪些记忆、哪些层参与比较和生成整理提案,见 DevMemoryLayer;记忆闲置多久会休眠,见 DevMemoryDormancyReason。

取代只在模型判断的新旧与来源的时间先后一致时才成立,否则降为矛盾(conflict),仅供人工查看。

休眠与唤醒

休眠的记忆带 dormant: {reason, dream_id}。它不再进入 RECENT.md,也不参与模型比较,但仍可列出和搜索。MEMORY.md 里只有人工写入和人工确认过的记忆,这些从不休眠。两种原因的条件和清除方式见 DevMemoryDormancyReason。

  • 解除休眠不需要调用专门接口:通过 GET /v2/memories/{memory_id} 读取记忆,或搜索、上下文包、回答返回这条记忆时,记忆即被唤醒。读取 MEMORY.md、RECENT.md 和列表不算。
  • 从 apply 改回 report 不清除已有的标记,如需清除请撤销那次整理。

设置:默认只出提案

每个 Space 有三个设置:memory_dreaming(默认 propose,整理照常运行;off 停止)、dormancy(默认 report,闲置的记忆只写进报告;apply 标为休眠)和 d4(默认 off,不调用模型;shadow 只记录判定;propose 把通过校验的判定写成提案)。在 propose 下,整理本身只做可撤销、不修改正文的标记;合并重复的记忆、用新记忆取代旧记忆、标出互相矛盾的记忆、把 Agent 的私有记忆提升到项目,这类改动只生成 整理提案,由人工决定。只有 Space 所有者能修改设置。

curl
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/settings" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Stop dreams for this Space. What they already did stays; undo a dream to take it back.
curl -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/settings" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"memory_dreaming": "off"}'

# Mark unused memories dormant, and let a model propose merges and supersessions.
curl -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/settings" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dormancy": "apply", "d4": "propose"}'
  • 先读一次报告再把 dormancy 改为 apply。
  • 先用 shadow 运行一段时间并查看判定,再改为 propose:已记录的判定直接转为提案,无需再次调用模型。
  • 响应里的 d4_available 为假时,这个部署不调用模型,无论 d4 如何设置。

发起、查看和撤销整理

POST /v2/spaces/{space_id}/memory/dreams 立即发起一次整理,返回 202,job_id 即整理 id,用 GET /v2/jobs/{job_id} 跟进。GET /v2/memory/dreams/{dream_id} 是报告,GET /v2/memory/dreams/{dream_id}/actions 列出每个改动和理由,GET /v2/memory/dreams/{dream_id}/judgments 列出模型比较过的每一对。POST /v2/memory/dreams/{dream_id}/undo 撤销整次整理。一个范围同一时间只有一次整理。

curl
# Start one now. job_id is the dream id (drm_...).
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/dreams" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": "project"}'

# Poll until status is succeeded or failed.
curl "https://api.mirabase.dev/v2/jobs/$DREAM_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# The report, then every change with its reason.
curl "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
curl "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID/actions" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Every pair a model was asked about, proposed or not.
curl "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID/judgments" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Take it back.
curl -X POST "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID/undo" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
  • 撤销针对整次整理,逐条进行:休眠标记清除,未处理的提案变为 withdrawn,已批准的合并和取代被还原。之后变更过的记忆保持不变,计入 conflict_skipped。
  • 报告和动作只统计来源对调用方可见的记忆;agent 范围的整理只对对应 Agent 和 Space 所有者可见。

整理提案

离线整理提出但不自行执行的改动称为整理提案,与 文件提案 不同。整理提案的种类见 DevMemoryProposalKind,状态见 DevMemoryProposalStatus。调用方必须能看到每个成员的来源才能看到该整理提案。

只有 Space 的 d4 设置为 propose 且当前部署已配置模型(d4_available 为真)时,整理才会生成提案;否则列表为空。

逐字引文

模型不生成结论文字,因此目前始终不返回 proposed_text。判断依据都来自来源原文:evidence 每个条目带 memory_id、entry_id、version_id 和逐字的 quote,times 是决定新旧顺序的日期,plan 写明批准后保留哪条(keep)、关闭哪些(close)。引文必须在对应记忆的来源中逐字匹配,否则整组判定会被丢弃,不会成为提案。

curl
# Open proposals of one dream, oldest first.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/proposals?dream_id=$DREAM_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Read the exact version a quote came from.
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/content?view=text&version=$VERSION_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Carry it out. It takes effect only now.
curl -X POST "https://api.mirabase.dev/v2/memory/proposals/$PROPOSAL_ID/approve" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Or close it without changing any memory.
curl -X POST "https://api.mirabase.dev/v2/memory/proposals/$OTHER_PROPOSAL_ID/reject" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

批准和驳回

POST /v2/memory/proposals/{proposal_id}/approve 执行 merge 或 supersede:plan.close 中的记忆关闭,plan.keep 保留,正文不变。POST /v2/memory/proposals/{proposal_id}/reject 关闭提案,不修改任何记忆。

  • conflict 和 promote 不能批准。矛盾需要通过 更正或遗忘 其中一条来解决,或者直接驳回。
  • 撤销批准:撤销那次整理。撤销针对整次整理,不能只撤销其中一条提案。

从记忆查找提案

开启了离线整理的部署上,GET /v2/memories 和 GET /v2/memories/{memory_id} 会在有待处理提案时返回 pending_proposals:关于这条记忆(或它所在组的成员)的提案 id,最早的在前,只包含调用方可见的提案,没有时不返回。要在界面上为这条记忆显示“待处理”标记,用这个字段即可。

curl
# pending_proposals is present only when there are open proposals you can see.
curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

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

MEMORY.md 的索引写法与 RECENT.md

开启了离线整理的部署上,MEMORY.md 是一份索引:按“规则和偏好”“决定和进度”“事实”分节,一行一条记忆,行尾是 [m1] 这样的引用号,文件末尾的 References 表把引用号映射到记忆 id。内容是人工写入的记忆(账户记忆、以 Entry 写入的记忆)和人工确认过的提炼记忆,这些都不会休眠;内容相同的记忆只出现一次。

markdown
# Memory

## Rules and preferences

- Keep answers short and in English. [m1]

## Decisions and progress

- Releases go out on Thursdays. [m2]

## Facts

- The staging database runs PostgreSQL 16. [m3]

## References

[m1]: mem_5d02
[m2]: ent_9a41
[m3]: distill:ent_7f20:fact_31
  • 整份最多 2,000 token,其中提炼记忆最多占 800 token。写不下的不截断,整条略去,最后一行写 … N more: GET /v2/memories?space_id=...。
  • 不写日期和时间。排序只随内容变化:先列人工写入的记忆,再列人工确认过的提炼记忆,提炼记忆按新近度和 id 排序,不看取用次数。所以检索命中不会让 ETag 变化,它以 mf2. 开头,仍然适合做 prompt 缓存前缀。

/.mirabase/memory/RECENT.md 是第二个生成文件:这个 Space 最近 7 天写入的项目记忆和 Agent 记忆,包括尚未审核的候选,最新的在前,最多 50 条、1,000 token。每行标明类型和状态,引用号格式为 [r1],ETag 以 rf1. 开头。账户记忆和休眠的记忆不在其中。读写规则与 MEMORY.md 相同。

markdown
# Recent memory

- (decision, confirmed) Releases go out on Thursdays. [r1]
- (preference, candidate) Use metric units in reports. [r2]

## References

[r1]: ent_9a41
[r2]: distill:ent_7f20:fact_44
curl
# The stable part: send back the ETag you have, 304 means nothing changed.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/.mirabase/memory/MEMORY.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H 'If-None-Match: "mf2.<sha256>"'

# The part that moves: what was written in the last 7 days.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/.mirabase/memory/RECENT.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
  • 把 MEMORY.md 放在提示词前部做稳定前缀,RECENT.md 放在后部经常变化的地方。
  • 两个文件都只包含调用方可见的记忆,因此不同调用方可能获得不同的字节和 ETag。

按 id 读取记忆

索引里只有一句话和一个 id。如需详情,按 References 里的 id 调用 GET /v2/memories/{memory_id};如需查看依据的版本和引文,再调用 GET /v2/memories/{memory_id}/provenance。

curl
# An id from the References table.
export MEMORY_ID="distill:ent_7f20:fact_31"
curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# The versions and quotes it rests on.
curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID/provenance" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

通过 MCP 工作的 Agent 用工具 mira.memory.get:输入 memory_id,默认连同来源返回 {memory, provenance};传 include_provenance: false 只取记忆。它只在开启了离线整理的部署上出现在工具清单里。

json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "mira.memory.get",
    "arguments": {
      "memory_id": "distill:ent_7f20:fact_31"
    }
  }
}

开启了离线整理的部署上,内容相同的提炼记忆在列表中合并为一组,带 group_id 和 sources;遗忘、更正和审核仍然按单条 id 调用。

下一步