@kanyun-ai-infra/agenthub 1.4.0 → 1.5.0

package/README.md

@@ -132,6 +132,55 @@ Agents 和 runtime templates 都是 **project-scoped**。Version 必须在同一
 > 本文一律用主词汇 **agent / version**；它们是底层 wire 名 `workload` / `revision`
 > 的别名，SDK 两套都接受，规范名与别名同传会抛 `ALIAS_CONFLICT`，细节见下方「完整参考」。
 
+## 记忆（agenthub.memories）
+
+让 agent 知道**你的系统已经掌握的事实**，而不是指望模型从对话里猜。写入的条目
+只有在会话**声明了对应主体**时才会被注入。
+
+```ts
+// 1. 写入你掌握的事实。confidence 缺省是 "confirmed"（权威事实）；自家抽取出来的
+//    推断传 "suggested"。单批 ≤100 条，content ≤500 字。
+const written = await agenthub.memories.write(projectId, {
+  items: [
+    {
+      subjectKind: "room", // 注意：策略表用的是 subjectType，两者刻意不同
+      subjectId: "room-42",
+      memoryKind: "fact", // "fact" | "preference"（"working" 会被拒）
+      content: "这个班在周三下午上课",
+    },
+  ],
+});
+// 逐条结果是**返回值不是异常**：inserted / strengthened / promoted / suppressed /
+// agent_disabled / quota_exceeded / rejected。整批被压制也是 200，用
+// written.results[i].outcome 对账，别指望 try/catch。
+
+// 2. 建会话时声明主体——这一步才让上面写的记忆到得了 agent。不声明 = 本会话没有
+//    业务主体记忆，不会回落到任何推断值。最多 8 个；agent 主体由平台自动附加。
+const session = await agenthub.sessions.create({
+  projectId,
+  agentId,
+  stage: "test",
+  memorySubjects: [{ type: "room", id: "room-42" }],
+});
+
+// 3. 反查对账（keyset 分页，新的在前）。要全量就用 listAll，它替你翻 nextCursor。
+for await (const memory of agenthub.memories.listAll(projectId, {
+  subjectKind: "room",
+  subjectId: "room-42",
+})) {
+  // memory.content / memory.confidence / memory.createdAt
+}
+```
+
+其余方法：`confirm(projectId, memoryId, { expectedContentHash })` 转达用户在你自己
+App 里点的"对"；`purge(projectId, { subjectKind, subjectId })` 按主体清空（不可逆，
+且会落墓碑——之后再写同一段内容会返回 `suppressed`）；
+`memories.policies.list/put` 声明**主体类型**策略（写者基数 `writers`、抽取档位
+`extractionMode`，⚠️ 这里的字段是 `subjectType`，不是上面的 `subjectKind`）。
+
+这些端点需要 `memories:write` / `memories:read` scope，且**只认 platform token**
+（门户登录态会被 403 `PLATFORM_TOKEN_REQUIRED` 挡掉）。
+
 ## 完整参考
 
 下面这些内容日常写业务代码用不到，需要时查
@@ -141,6 +190,7 @@ Agents 和 runtime templates 都是 **project-scoped**。Version 必须在同一
 | 你想找 | 链接 |
 | --- | --- |
 | 资源方法速查（projects / agents / stages / environments / sessions / files / profiles） | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#sdk-methods> |
+| 记忆接口（写入 / 读回 / 确认 / 清空 / 策略）逐端点字段、outcome 与 REST 对照 | <https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk/memories> |
 | "发布 → 部署 → 晋级 → 灰度 → 回滚"完整六幕示例 | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#release-loop> |
 | Client 配置全部选项、获取 token | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#sdk-client-config> |
 | Runtime template 解析顺序 | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#runtime-template> |