5.3 KiB
长期记忆 API
长期记忆空间始终绑定在当前调用者上:路径里没有 subject id,服务端从凭证推导身份。因此 Viewer+ 的会话令牌,或 full-access API Key 才能访问;带知识库范围的集成 Key 不能继承某个人的记忆。
工作空间管理员先在设置里打开空间级开关,用户还可以再关掉自己的记忆。推断出的条目会停在 pending,确认后才进入提示词。
| 方法 | 路径 | 描述 |
|---|---|---|
| GET | /memory/settings |
获取合并后的记忆开关(空间级 + 个人级)与条数 |
| PUT | /memory/settings |
开启或关闭当前用户自己的长期记忆 |
| GET | /memory/items |
分页列出记忆,可按状态过滤 |
| POST | /memory/items |
手动新增一条记忆 |
| PUT | /memory/items/{id} |
修改内容与重要度(之后不会被后台抽取覆盖) |
| DELETE | /memory/items/{id} |
永久删除一条记忆 |
| POST | /memory/items/{id}/confirm |
确认一条推断出的记忆 |
| POST | /memory/items/{id}/reject |
否决一条推断出的记忆 |
| DELETE | /memory/items |
清空当前用户的全部记忆 |
| GET | /memory/topics |
列出尚未提升为长期关注的主题计数 |
| POST | /memory/topics/{id}/promote |
立即把主题记为长期关注 |
| DELETE | /memory/topics/{id} |
停止跟踪一个主题 |
| GET | /memory/documents |
列出反复引用的文档(未达习惯门槛的不展示) |
| DELETE | /memory/documents/{id} |
停止用某份文档做个性化检索 |
| GET | /memory/export |
以 JSON 导出全部记忆 |
| POST | /memory/consolidate |
立刻整理(合并近义条目、归档到期事项) |
GET /memory/settings
curl --location 'http://localhost:8080/api/v1/memory/settings' \
--header 'Authorization: Bearer <token>'
响应:
{
"success": true,
"data": {
"workspace_enabled": true,
"user_enabled": true,
"effective": true,
"write_mode": "auto",
"item_count": 12,
"max_items": 200
}
}
write_mode 为 explicit_only(只记用户明确要求记住的)或 auto(后台从对话蒸馏)。effective = 空间开关 ∧ 个人开关。
PUT /memory/settings
curl --location --request PUT 'http://localhost:8080/api/v1/memory/settings' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{"enabled": true}'
enabled 必填。只改个人开关,不能用这个接口改空间级配置。
GET /memory/items
查询参数:
| 参数 | 说明 |
|---|---|
status |
可选:active / superseded / archived / pending;省略则不过滤 |
limit |
默认 50,最大 200 |
offset |
默认 0 |
kind 取值:profile / preference / fact / task / interest。
POST /memory/items
{
"kind": "preference",
"content": "回答直接给结论,少铺垫",
"importance": 3
}
POST /memory/items/{id}/confirm / reject
推断出的记忆(status=pending)确认后才注入提示词;否决会留下 tombstone,避免下一轮蒸馏把同一句话再写回来。
如果推断用于修改已有记忆,确认前旧记忆继续生效;确认会在同一事务中激活推断并替换旧条目。已经失效、到期或基于已修改或已删除内容的推断不能再次确认,接口返回 HTTP 409,客户端应刷新列表。编辑正文会同时使旧向量失效,并尝试生成新向量;生成失败时保留词面检索,后续整理可补齐向量。
自动提取在独立的 memory_extraction_sessions 表按会话保存 (created_at, message_id) 游标、排队状态和重试计数,每次最多领取 32 个会话。用户记录只保存工作进程租约,读取记忆时不加载全部会话历史。已完成的游标仍保留,避免旧会话再次提取全部历史。
单条无效决策或已失效的更新目标不会阻塞同批其他结果。无法解析或持续截断的模型输出按消息段最多尝试三轮(每轮截断后可增加预算重试一次),随后记录失败范围并推进该段游标;同会话后续消息及其他会话继续处理。进度表保留该会话最近一次失败的起止游标、错误类别、次数和跳过时间,不保存原始模型输出;被跳过的范围不会自动补提取。网络、模型配置和数据库错误不适用跳过策略,仍保留进度供重试。批次截断、工作进程重启和提取期间的新消息都保留待处理状态。
升级时沿用旧的用户级游标作为各会话的初始边界,之后该边界不再推进;旧待处理列表在首次调度时导入独立表。这样避免升级触发全量历史重放,但不会自动恢复旧实现已跳过、且位于旧游标之前的消息。
GET /memory/export
返回 {success, total, truncated, data},并带 Content-Disposition: attachment; filename="weknora-memories.json"。truncated 仅在触达导出上限(2 万条)时为 true。
POST /memory/consolidate
不等待每日后台整理,立刻合并意思接近的条目并归档到期事项。返回 merged / demoted / expired / reviewed / candidates;若什么都没合并,skipped 会说明原因(例如 too_few_items)。