记忆遗忘
记忆遗忘用于让不再需要的记忆退出搜索,同时保留数据以便随时找回。它帮助业务在用户要求“忘掉”某些信息、或记忆库长期膨胀时,安全、可逆地管理记忆的生命周期。
解决的问题
在未使用记忆遗忘时,记忆生命周期管理可能出现以下问题:
-
用户要求删除某条信息,直接硬删除不可逆,误操作无法挽回。
-
长期闲置的陈旧记忆不断被搜索命中,干扰 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}/search" \
-H "Authorization: Token ${MEMORY_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"query":"用户有什么过敏信息","user_id":"'${USER_ID}'"}'
搜索结果中不再包含“花生过敏”这条记忆。
步骤四:恢复记忆
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 列表。
-
开启自动遗忘前先试运行:先手动归档个别记忆,确认业务侧召回行为符合预期,再开启自动模式。
-
更新会触发恢复:如果希望某条记忆保持归档状态,不要再对它执行更新操作。