跳转到内容
OpenBot

Memory

面向接入 OpenBot 客户端或扩展服务端的开发者。示例需要本页说明的访问权限。从开发者手册开始。

Bot 记忆（Bot memory）是一个 Bot 在它所有 Chats 中学到的东西。每个 Bot 有一个条目池。记忆 Bot（memory Bot）保管这个池。它是属于这个 Bot 的助手。它读取来源访问规则已验证的有效条目，学习新的条目，并把有用的内容加入 Bot 的工作。它的学习工作不会显示为 Chat。本页介绍 Bot 记忆如何学习、谁能看到什么，以及如何用 API 读取和修改它。

Bot 记忆是唯一的记忆。Chat 保留它的历史，但没有单独的事实列表。旧版本的 OpenBot 还为每个 Session 保存学到的记忆。那种记忆已经没有了。

条目和 Tag

Section titled “条目和 Tag”

每个条目属于一层：

层 含义
fact Chat 中出现的事情。它的来源是 Item。
observation 记忆 Bot 从其他条目得出的结论。它的来源是那些条目。confidence 在 0 到 1 之间。
pinned 某个人让 OpenBot 记住的内容。

Tag（标签）用来给条目分类。带冒号的 Tag 属于 OpenBot。记忆 Bot 不能写这些 Tag，所以模型无法改变谁能看到一个条目。

Tag 含义
from:<userId> 说了或做了这件事的人。
for:person:<userId> 这个人可以看到这个条目。
for:channel:<channelId> 这个 Channel 群里的人可以看到它。
for:bot 使用这个 Bot 的所有人都可以看到它。
org:<organizationId> 它发生的组织。只有这个组织中的工作能看到它。
chat:<id>、channel:<id> 它来自哪里。
app:<tool> 有一个来自 App 的工具结果支持它。

其他 Tag，比如 testing 或 trip-planning，是主题（topic）。记忆 Bot 选择它们，并让它们保持整洁。主题只用小写字母、数字和短横线。

谁能看到条目

Section titled “谁能看到条目”

for: Tag 由 OpenBot 设置。没有 for: Tag 的条目谁也看不到。

  • 事实属于当时在场的人：这个 Turn 的人，或者在群聊 Chat 中是这个 Channel 群。
  • 只有能看到每个来源的人才能看到观察。参与其中一个来源，不会让你获得其他来源或组合结果的访问权限。
  • 请求扩大条目的可见范围时，仍须通过每个来源的访问规则。理由、模型指令或 Bot 的所有权都不能跳过这项检查。

一条事实有多个来源 Item 时，OpenBot 会在学习这条事实时保存每个 Item 的访问规则。这些记录不对外公开，公开条目的格式保持不变。对于观察，OpenBot 会检查每个来源条目，并逐层检查这些条目的来源。来源缺失、来源链接形成循环或访问证明缺失，都会使结果隐藏。读取、变更日志、编辑，以及告解和输入补充所用的记忆，都进行同样的检查。

服务器先检查标签、来源关系和访问规则，不打开条目内容。然后只解密回复所需的内容。检查来源不需要解密来源内容。读取持有该 Bot 记忆的共享锁，修改独占同一个锁，所以读取不会混用旧权限和新内容。模型调用在锁外执行。

条目不再成立时不会被删除。记忆 Bot 用 invalidatedAt 标记它们，有权访问的人仍可查看历史。来源失效或被撤回后，依赖它的结论会隐藏。这些检查使用记忆 Bot 声明的来源。它们不能证明模型列出了影响回答的每个输入。

Bot 如何学习

Section titled “Bot 如何学习”

Bot 有一个叫 confide（倾诉）的工具。Bot 只知道它是一个说出工作情况的地方：卡住、不确定、难过或自豪的时候，或者犯了错的时候。Bot 不知道这个工具通向它的记忆。所以它倾诉是因为需要，而不是为了改变自己会记住什么。

当 Bot 倾诉时：

  1. 记忆 Bot 会马上回答，就像牧师听人告解。它倾听，不评判。它说犯错是工作的一部分。它请 Bot 把事情直接告诉那个人，并尽量补救。它不给新任务。没有模型能回答时，Bot 会得到一段固定的平静回答。
  2. OpenBot 保存一项学习执行。源 Turn 完成后，它读取截至这个 Turn 的新 Item，并从中学习。

执行通过共同事件日志等待。重启会保留这项工作。每个模型步骤都有保存的调用和尝试记录，恢复会复用已保存的结果。记忆变更、读取位置和执行结束在同一事务中提交。并发学习不会重复应用同一份证据。每个 Turn 保存的操作人身份决定其受众；OpenBot 不会把 Turn 的作者字段解析为用户 ID。

learningContext 按记忆顺序向模型提供前 300 条有效条目，主题计数仍涵盖所有有效条目。 applyLearning 在写锁内检查最新来源状态，再保存变更。主题改名仍覆盖所有匹配条目。修改标签或状态不会再次解密和加密原有内容。

Bot 的话只是告诉记忆 Bot 该看哪里。它们本身永远不会成为记忆。来自 App 的工具结果也不会单独成为记忆。OpenBot 的通知永远不会被当作人说的话。从不倾诉的 Bot 什么都学不到。

审查 Chat 没有 confide 工具。当组织设置中的 botMemory 关闭时，Bot 仍然会得到回答，但不会学到任何东西。

Bot 如何使用记忆

Section titled “Bot 如何使用记忆”

当一个 Turn 开始时，记忆 Bot 会读取这个人的输入。它会跳过通知，因为通知不是人说的话。如果有条目能帮上忙，它会结合这些条目把输入完整地重写一遍。它可以改动措辞，但必须保留这个人说的和要求的所有内容。它只能使用这次回答的读者可以看到的条目，OpenBot 会检查这一点。在 Channel 群中，只能使用属于这个群或属于所有人的条目。

模型看到的是重写后的输入。Chat 的历史保留这个人原本的话。Bot 不知道这些改动来自记忆，它把它们当作自己的经验。请求和对请求的审查只看到 Bot 提出的内容，永远看不到这些改动。

当 botMemory 关闭时，输入不会改变。

服务器调用方通过 context 取得可见文本和文本中所用的条目 ID。它保留记忆顺序，遇到第一个超出文本限额的条目时停止，不解密后面的条目。调用方不再读取整池数据并各自检查权限。HTTP 视图仍返回读者可以看到的全部条目，包括规则允许的历史。

hasEntries 表示是否有可见的有效条目，即使这些条目都超出文本限额。没有可见条目时，不调用模型。对于已保存的模型答案，validateReferences 检查当前来源权限，不读取内容。新条目将旧文本挤出限额不会使已保存的答案失效；来源不再允许访问时，答案才会失效。

记忆 Bot

Section titled “记忆 Bot”

记忆 Bot 使用组织设置中的 botMemoryModel。它没有默认值。它为 null 时，记忆 Bot 给出固定的平静回答，不添加也不学习任何东西。对于共享的 Bot，模型和费用来自 Chat 所在的组织。

用 GET 和 PATCH /v1/bots/:botId/memory/bot 读取和修改记忆 Bot 的设置。你需要在一个不是关联 Bot 的 Bot 上拥有 write：

{
  "expected": 0,
  "instructions": "Decisions of the team may be shared with the team.",
  "concurrency": 2,
  "budget": { "period": "month", "limitMicros": 5000000 }
}
字段 含义
instructions 关于隐私和分享的规则，用平实的语言写。记忆 Bot 会遵守它们。
concurrency 它在一台服务器上同时运行的最多任务数。null 去掉这个限制。
budget 一天或一个月内已确认模型费用的上限，单位是 micro-USD，覆盖所有组织。null 去掉这个限制。

不设限制时就没有限制。预算用完时，Bot 会得到固定的平静回答，输入保持原样，学习会等到下一个周期。

对 confide 的回答和新的输入最多等 15 秒。当 concurrency 的所有任务都在忙时，等待空闲任务的时间也算在里面。超时后，Bot 会得到固定的平静回答，输入保持原样。一步学习最多可以用 2 分钟。用时更长时，执行以安全的错误信息结束。读取位置保持不变。之后的 confide 可以再次请求从这些证据学习。

读取和修改

Section titled “读取和修改”

GET /v1/bots/:botId/memory 显示在你的组织中属于你的条目。加上用逗号分隔的 tags，只看带有所有这些 Tag 的条目。你需要这个 Bot 上的 read。没有人能读取关于另一个人的记忆，即使有这个 Bot 上的 write 也不行。

Terminal window
curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  "https://api.example.com/v1/bots/$BOT/memory?tags=testing"
{
  "entries": [
    {
      "id": "mem_4f2a…",
      "layer": "fact",
      "content": "Run the tests before you report that work is done.",
      "tags": [
        "from:u_123",
        "for:person:u_123",
        "org:o_1",
        "chat:chat_c81d…",
        "testing"
      ],
      "sources": [{ "chat": "chat_c81d…", "item": "i-12" }],
      "status": "active",
      "createdAt": 1792486800000,
      "updatedAt": 1792486800000
    }
  ],
  "version": 4
}

用 POST /v1/bots/:botId/memory 修改它：

  • 带 content 和可选 tags 的 Remember 会添加一个 pinned 条目。只有你能看到它。
  • 带 id 的 Forget 会收回你的那一部分。如果这个条目只和你有关，它会变成 retracted。否则你不再算作它的相关人，这个条目也不再属于你，但它仍然属于其他人。不属于你的 id 会返回 409。
Terminal window
curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":{"_tag":"Forget","id":"mem_4f2a…"}}' \
  https://api.example.com/v1/bots/$BOT/memory

GET /v1/bots/:botId/memory/log 列出你能看到的条目的修改：version、时间、是谁做的修改（memory_bot 或 person），以及条目 id。来自旧版本 OpenBot 的修改也可能是 promotion。

要在不读取的情况下删除记忆，把一个 OpenBot 的 Tag 发送到 POST /v1/bots/:botId/memory/purge：可以是 from:、chat:、org: 或 channel: Tag。从这些条目得出的观察带有同样的 Tag，所以也会一起删除。你需要在一个不是关联 Bot 的 Bot 上拥有 write。回答只包含删除的条目数量。

当你删除一个 Chat 的历史时，Bot 从它学到的记忆仍然保留。要把这些也删除，请清除 chat:<id>。

新旧记忆都遵守相同的来源访问规则。如果 OpenBot 无法证明对旧条目每个来源的访问权限，这个条目就会保持隐藏。学习输入也会排除这条记忆及依赖它的结论。只有从可以检查访问权限的来源重建后，条目才可重新显示。OpenBot 不会在升级时重建这些条目，也不会扩大旧记忆的可见范围。通过 Remember 创建的私人固定条目保留自己的访问规则。

告解和补充

Section titled “告解和补充”

有两个路由显示你的某个 Chat 中发生了什么：

  • GET /v1/chats/:chatId/confessions 列出 Bot 倾诉的内容和它得到的回答。在展示给别人之前，请先阅读展示告解。
  • GET /v1/chats/:chatId/enrichments 列出记忆 Bot 如何重写每个 Turn 的输入：新的 text、original 中这个人原本的话，以及它用了哪些条目。较早的记录没有 original。

两者都需要这个 Chat 上的 read，所以只有拥有这个 Chat 的人才能读取。

记忆正文、变更日志、告解和输入补充记录都加密保存。工作流消息只携带记录 ID。模型请求和结果保存在加密调用日志中。只扣除供应商确认的用量；缺少用量时单独记录为未知。