WeKnora/docs/api/memory.md

5.3 KiB
Raw Blame History

长期记忆 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)。