企业官网建设流程全解析

5分钟锁住AI智能体记忆：Hindsight备份与恢复实战

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight

如果你在用 Hindsight 为 AI 智能体积累长期记忆，大概率担心过一件事：数据库故障、误操作发生时，这些记忆数据怎么办？这篇文章直接围绕内置的 hindsight-admin 命令行工具，带你完成第一次记忆备份、走通恢复流程，并学会把整个记忆银行迁到新实例。

三步完成第一次 Hindsight 记忆备份

hindsight-admin 随 hindsight-api 包一起提供，pip install hindsight-api装完即可用。它不走 HTTP 接口，而是直连 PostgreSQL 读同一份配置，所以备份是数据库层的一致性快照。注意它只支持 PostgreSQL 部署。

1. 用HINDSIGHT_API_DATABASE_URL指向要保护的那个库（不设则默认连本地嵌入的 pg0 开发库）；
2. 执行备份，几分钟内得到一个 zip 全量快照；
3. 需要时一条命令恢复。

hindsight-admin backup /backups/hindsight-0115.zip hindsight-admin restore /backups/hindsight-0115.zip --yes

这个 zip 的内容很完整：记忆银行及配置、文档与分块、实体及关系、记忆单元（事实、经验、观察）、心智模型、指令、webhook，连异步队列、审计日志这类运维表都包含在内。整个备份在REPEATABLE READ隔离级别的事务里完成，保证所有表停留在同一时刻，不会出现"文档是新版的、实体是旧版的"这种撕裂。

按三种常见角色选对备份方式

个人开发者：本机实例一键全量

单实例开发场景下，什么都不用配，直接对默认publicschema 备份。zip 文件就是全部记忆，丢进备份目录或同步到云盘，恢复时对着同一个库执行 restore 即可。

运维工程师：在容器里执行备份

API 跑在 Docker 里时不用单独准备环境，直接 exec 进 API 容器执行，容器已带正确配置和网络可达：

docker exec -it hindsight-api hindsight-admin backup /data/backup.zip

Kubernetes 同理：kubectl exec deploy/hindsight-api -- hindsight-admin backup /data/backup.zip。好处是备份命令永远和线上配置保持同一状态，不会出现"备份脚本连错库"的低级错误。

平台团队：多记忆银行独立备份

一个实例承载多个租户时，用--schema把备份粒度拆到 schema 级：

hindsight-admin backup /backups/tenant-acme.zip --schema tenant_acme

恢复时也按同样粒度还原，某个租户的数据出了问题，不会牵连整个实例。

进阶配置：值得留意的四个设置

最后一条容易被漏掉：正常建库时索引会自动维护，但逻辑恢复出来的银行不走创建路径，必须手动跑一次hindsight-admin repair-bank --all。它用并发方式建索引，不阻塞在线读写，幂等可重复执行。

常见坑与排查

现象：恢复后检索变慢、结果变少。原因：恢复路径没自动补建银行级部分向量索引，银行悄悄退回"全局索引+后置过滤"。处理：跑一次repair-bank --all。

现象：恢复后pending_consolidation只增不减，任务卡在 processing。原因：Docker 重启后容器名变化，worker ID 跟着变，旧任务成了没人认领的孤儿。处理：先用hindsight-admin worker-status找出卡住的 worker，再decommission-worker <id>释放；分不清死没死就用decommission-workers整体释放。长期方案是把HINDSIGHT_API_WORKER_ID固定成稳定值。

现象：import-bank报目标银行已存在。原因：导入是整库还原而非合并，同名银行存在时直接拒绝。处理：先删旧银行，或用--target-bank换个新 ID 导入。

现象：恢复演练把生产数据清掉了。原因：restore 会先清空目标 schema 的全部数据再导入，这是设计行为。处理：演练前先打一份新备份，且演练在专用 schema 或测试实例上进行，别在生产库上试。

实战场景：把整个记忆银行搬到新嵌入模型

假设你想把 384 维的嵌入模型换成 1024 维的，而库里已经攒了几十万条事实。原地改不了——向量维度与 schema 绑定，旧向量无法拉伸。推荐路径是蓝绿迁移：起一个新实例配上新嵌入模型，维护窗口内先打一份安全备份，然后在源实例执行hindsight-admin export-bank --bank my-bank --output my-bank.zip（只读，可在线跑），在目标实例执行hindsight-admin import-bank --archive my-bank.zip。导出永远不含嵌入向量，目标实例用自己的模型重新嵌入并重建索引；事实、文档、心智模型和配置则原样还原，全程不需要 LLM 重新抽取。导入后跑几条有代表性的检索查询核对质量，确认无误再切流量，老实例留作随时可回滚的退路。

备份一条命令、恢复一条命令、跨实例迁移一对 export/import，Hindsight 的记忆备份链路到这里就闭环了。完整参数清单和迁移 runbook 见 admin-cli.md，备份恢复逻辑的测试用例在 test_admin_backup_restore.py。

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight