记忆遗忘

更新时间:
复制 MD 格式

记忆遗忘用于让不再需要的记忆退出搜索,同时保留数据以便随时找回。它帮助业务在用户要求“忘掉”某些信息、或记忆库长期膨胀时,安全、可逆地管理记忆的生命周期。

解决的问题

在未使用记忆遗忘时,记忆生命周期管理可能出现以下问题:

  • 用户要求删除某条信息,直接硬删除不可逆,误操作无法挽回。

  • 长期闲置的陈旧记忆不断被搜索命中,干扰 Agent 对用户当前状态的理解。

  • 记忆数量持续增长,缺少统一的清理手段。

主要能力

能力

说明

归档即退出搜索

归档后的记忆不会再出现在搜索结果中,Agent 不再受其影响。

可恢复

归档不删除数据,随时可以单条或按用户整体恢复,恢复后立即回到正常状态。

自动遗忘

开启后,系统每天自动把长期没有任何活动的记忆归档,记忆库保持精干。

管理可见

归档记忆仍然可以通过管理接口查询到,方便核对清单后再做进一步处理。

永久删除

确认不再需要时,可以按用户整体永久删除已归档记忆,释放空间。

适用场景

  • 用户明确提出“忘掉某件事”,需要立即让该信息退出 Agent 的认知。

  • 合规场景下要求某些信息停止被使用,同时保留必要的处置记录。

  • 记忆库长期使用后堆积大量陈旧记忆,希望自动清理长期无人问津的内容。

  • 需要按用户维度批量管理记忆(如用户注销时的数据处理)。

如何使用

操作

接口

说明

归档单条记忆

POST /memories/{memory_id}/archive

重复归档不报错。

查询归档列表

POST /memories/archived

分页,按用户筛选。

恢复单条

POST /memories/{memory_id}/restore

恢复后立即可被搜索。

按用户批量恢复

POST /memories/restore?user_id=xxx

恢复该用户全部已归档记忆。

按用户永久删除

DELETE /memories/archived?user_id=xxx

不可逆,删除全部已归档记忆。

查询归档列表时,在请求体中指定用户和分页:

curl -sS -X POST "${MEMORY_URL}/memories/archived" \
  -H "Authorization: Token ${MEMORY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"user_id": "demo-user-001"}, "page": 1, "page_size": 100}'

filters 必须包含 user_id、agent_id、run_id 中的至少一个(否则返回 400);page_size 范围 1–200。返回中 count 为归档记忆总数,next / previous 为下一页 / 上一页的 URL(没有则为 null),results 为记忆列表。

开启自动遗忘

自动遗忘默认关闭,需要时通过配置接口开启:

curl -sS -X POST "${MEMORY_URL}/configure" \
  -H "Authorization: Token ${MEMORY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"enable_memory_forget": true}'

开启后,系统每天凌晨自动把 3 个月内没有任何活动(未被写入、更新或搜索命中)的记忆归档。经常用到的记忆不会被误归档。

说明

归档只是退出搜索,不释放存储空间;只有永久删除才释放。更新一条已归档的记忆会使它自动恢复。

示例

以下示例直接调用线上服务,演示归档、确认退出搜索、再恢复的完整流程。

说明

API Key 建议通过环境变量传入,不要直接写在代码或公共文档中。

步骤一:配置服务地址和认证信息

export MEMORY_URL="https://api-longmemory-cn-beijing.opentrust.net"
export MEMORY_API_KEY="<替换为您的 API Key>"
export USER_ID="demo-user-001"

步骤二:写入一条记忆并归档

curl -sS -X POST "${MEMORY_URL}/memories" \
  -H "Authorization: Token ${MEMORY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"我对花生过敏"}],"user_id":"'${USER_ID}'","async_mode":false}'

从返回中记下该记忆的 id(记为 MEMORY_ID),然后归档:

curl -sS -X POST "${MEMORY_URL}/memories/${MEMORY_ID}/archive" \
  -H "Authorization: Token ${MEMORY_API_KEY}"

返回:

{"message": "Memory archived successfully", "memory_id": "xxxxxxxx"}

步骤三:确认已退出搜索

搜索结果中不再包含“花生过敏”这条记忆。

步骤四:恢复记忆

curl -sS -X POST "${MEMORY_URL}/memories/${MEMORY_ID}/restore" \
  -H "Authorization: Token ${MEMORY_API_KEY}"

返回:

{"message": "Memory restored successfully!", "memory": {"id": "xxxxxxxx", "memory": "用户对花生过敏"}}

恢复后,该记忆重新参与搜索。

使用建议

  • 优先归档,慎用永久删除:归档可逆,永久删除不可逆;建议先查询归档列表确认清单,再执行永久删除。

  • 合规“停止使用”诉求用归档:归档即可满足信息退出使用的要求;需要审计记录时可同时开启 trace 配置。

  • 批量操作按用户维度进行:恢复和永久删除都支持按 user_id 整体操作,无需维护记忆 id 列表。

  • 开启自动遗忘前先试运行:先手动归档个别记忆,确认业务侧召回行为符合预期,再开启自动模式。

  • 更新会触发恢复:如果希望某条记忆保持归档状态,不要再对它执行更新操作。