Long-Term Memory (Honcho)

核心用法

honcho-setup 是 OpenClaw 生态的记忆系统迁移工具，用于将传统基于 Markdown 文件的记忆架构（USER.md、MEMORY.md、memory/ 目录等）无缝迁移至 Honcho 智能记忆 API。执行流程分为七个严格阶段：

1. 插件安装：通过 openclaw plugins install @honcho-ai/openclaw-honcho 安装官方插件
2. 连接验证：支持两种模式——托管模式（需 HONCHO_API_KEY，默认连接 api.honcho.dev）或本地自托管（通过 HONCHO_BASE_URL 指向私有实例）
3. 文件扫描：自动识别 9 类记忆文件及 memory/、canvas/ 目录内容
4. 数据上传：使用 Honcho SDK 的 session.uploadFile() 接口，区分用户文件（owner peer）与智能体文件（openclaw peer）
5. 安全归档：所有文件强制备份至 {workspace_root}/archive/ 后才允许删除原文件
6. 文档更新：将 SOUL.md、AGENTS.md、BOOTSTRAP.md 中的旧式文件引用替换为 Honcho 工具（honcho_profile、honcho_context、honcho_search、honcho_recall、honcho_analyze）

显著优点

• 双重模式灵活部署：既可用托管云服务零运维启动，也可完全自托管掌控数据主权
• 零数据丢失保障：强制归档机制确保任何删除操作前必有可验证的备份副本
• 精细权限控制：两次显式用户确认（上传前、归档前），完整披露目标 URL 与文件清单
• 敏感信息最小化：仅读取 HONCHO_API_KEY 单个环境变量，不触碰其他配置
• 开源透明：Honcho SDK 与插件代码完全开源，无隐藏行为

潜在局限

• 网络依赖：托管模式必须连接外部 API，离线环境仅限自托管方案
• 迁移单向性：设计为从文件系统迁出，无内置回滚至纯文件模式的机制
• Node 生态锁定：依赖 Node.js/npm 环境，对纯 Python 或其他运行时用户增加栈复杂度
• 手动冲突处理：若 archive/ 目录存在同名文件，自动追加时间戳，需用户后续手动整理

适合人群

• 已在使用 OpenClaw 文件式记忆、希望升级至结构化 API 记忆的用户
• 需要 AI 智能体长期记忆持久化与跨会话上下文的开发者
• 对数据隐私敏感、希望选择自托管方案的企业或团队
• 愿意接受托管服务便捷性以换取运维成本的个人开发者

常规风险

| 风险类别 | 具体说明 | 缓解措施 |

|---------|---------|---------|

| 数据外泄 | 用户记忆内容上传至第三方 API | 强制确认流程 + 自托管选项 + 仅传输必要文件 |

| 误删数据 | 迁移失败可能导致文件丢失 | 先归档验证、后删除；上传失败则中止全流程 |

| 凭证泄露 | API Key 被不当读取 | 仅读取单个指定变量，不解析整个 .env 文件 |

| 服务依赖 | 托管服务可用性影响功能 | 支持完全离线自托管，消除外部依赖 |

> 关键安全承诺：此技能绝不执行无备份的删除操作，绝不在用户确认前上传任何数据，绝不多读取任何非必要的配置信息。

核心用法

honcho-setup 是一款专为 OpenClaw 框架设计的记忆系统迁移工具，用于将传统的文件型记忆架构迁移至 Honcho 云端/本地 API 服务。该 skill 通过七个标准化步骤完成整个迁移流程：安装 Honcho 插件、验证连接配置、扫描遗留记忆文件、执行安全上传、归档本地备份、更新工作区文档，最终完成确认报告。

用户可通过环境变量灵活选择 托管模式（连接 api.honcho.dev，需 API Key）或 自托管模式（连接本地 Honcho 实例，无需认证）。迁移范围涵盖用户画像文件（USER.md、IDENTITY.md、MEMORY.md）、代理配置（SOUL.md、AGENTS.md 等）以及结构化记忆目录（memory/、canvas/）。所有操作均需用户逐步确认，确保数据处理的透明可控。

显著优点

架构现代化：将分散的 Markdown 文件迁移至结构化 API，实现 AI 代理记忆的持久化存储、语义检索与跨会话关联，彻底解决文件系统的版本冲突与检索低效问题。

部署灵活性：双模式设计兼顾不同安全需求——托管模式零运维成本快速启动；自托管模式通过 Docker Compose 一键部署，数据完全自主可控。

安全机制完善：采用"确认-备份-验证-删除"四重保障：上传前显式确认文件清单与目的地；自动创建时间戳归档；验证备份成功后方可删除源文件；任意步骤失败则中断流程保留原始数据。

最小权限访问：敏感文件读取范围严格限定——仅提取 HONCHO_API_KEY 与工作区路径，不触碰其他环境变量；所有操作日志对用户完全透明。

开源可信：Honcho SDK 与插件代码均开源，Plastic Labs 作为 AI 基础设施领域的活跃贡献者，项目活跃度与社区治理具备 T2 级来源可信度。

潜在缺点与局限性

网络依赖风险：托管模式下，AI 代理的记忆功能绑定外部 API 可用性，存在单点故障可能；自托管模式虽规避此问题，但需用户承担运维责任。

数据迁移粒度：当前实现采用全量文件上传策略，缺乏增量同步或差异比对机制，大规模记忆库迁移时效率受限。

格式转换局限：仅支持文本类文件（Markdown、JSON、纯文本、PDF）上传，二进制资源或复杂富媒体需额外处理流程。

生态锁定倾向：迁移后工作区文档深度绑定 Honcho 工具集（honcho_profile、honcho_search 等），逆向迁移回文件系统需人工干预。

适合的目标群体

• OpenClaw 深度用户：已构建复杂代理配置、依赖文件型记忆系统但面临检索瓶颈的开发者
• 多会话 AI 应用：需要跨对话保持用户上下文、构建长期个性化体验的 Agent 产品团队
• 隐私敏感型企业：通过自托管模式实现数据主权控制，满足金融、医疗等合规要求的组织
• AI 基础设施研究者：希望探索记忆层抽象、对比不同记忆架构方案的工程团队

常规使用风险

性能考量：首次迁移大量记忆文件时，API 上传可能成为瓶颈；建议分批次执行或选择非业务高峰期操作。托管模式的 API 响应延迟（50-200ms 典型值）将影响实时记忆检索体验。

依赖项管理：插件依赖 Node.js 运行时与 npm 生态，若 OpenClaw 网关与插件版本不兼容可能导致加载失败。文档中提及的 npm install 手动修复流程暗示存在依赖解析的已知缺陷。

配置漂移风险：HONCHO_BASE_URL 等环境变量的误配置可能导致数据误投至非预期端点，建议在生产迁移前通过沙箱环境验证连接参数。

长期备份策略：本地 archive/ 目录的备份文件缺乏自动清理机制，长期运行可能消耗显著磁盘空间，需用户建立独立的备份生命周期管理策略。