1. 项目概述为AI智能体构建去中心化、可验证的记忆系统在AI智能体Agent的开发浪潮中如何让智能体拥有持久、安全且可验证的“记忆”一直是个核心挑战。传统的解决方案要么依赖中心化数据库存在单点故障和数据泄露风险要么将记忆存储在本地无法实现跨会话、跨设备的持久化更难以验证其完整性和真实性。AegisMemory 正是为了解决这些问题而生。它是一个专为 OpenClaw 框架设计的生产级加密记忆存储系统其核心思想是将 AI 的每一次对话、每一次思考都转化为加密的、内容寻址的数据块并锚定在 X1 区块链上形成一个不可篡改、可公开验证的记忆链。简单来说你可以把它想象成给 AI 智能体装上一个“加密日记本”。这个日记本不是写在纸上而是写在去中心化的 IPFS 网络上每一页即一次对话都用只有你自己能打开的锁钱包私钥加密。同时这本日记的目录摘要每天都会被公证一次记录在 X1 区块链这个“全球公证处”里。这样一来你的 AI 智能体不仅能记住过去的所有对话而且这些记忆的完整性和时间戳都是可验证、不可抵赖的。这对于构建需要长期上下文、可信交互或审计追踪的 AI 应用如客服助手、个人知识库、自动化工作流等至关重要。2. 核心架构与设计哲学为什么是“加密链上锚定”AegisMemory 的设计并非凭空而来它是对当前 AI 记忆存储痛点的一次系统性回应。其架构可以概括为“两层存储一个链条”。2.1 双层存储模型性能、成本与安全的平衡第一层是IPFS 存储层用于存放加密后的记忆数据本身。选择 IPFS 而非传统云存储如 S3或数据库是基于其去中心化、内容寻址和抗审查的特性。在 AegisMemory 中通过与 X1 Vault 的集成实现了免费的 IPFS 存储。每次对话结束后记忆会被立即加密并上传到 IPFS生成一个唯一的 Content Identifier (CID)。这个 CID 就像是这份记忆数据的指纹只要数据不变CID 就永远不变。这层解决了海量记忆数据低成本、持久化存储的问题。第二层是X1 区块链存储层用于存放记忆的“存在性证明”。区块链不适合存储大量数据但极其擅长为少量数据提供时间戳和不可篡改的证明。AegisMemory 会定期默认每天将最新的记忆 CID 及其 SHA256 哈希值通过一笔微小的 Solana Memo 交易记录在 X1 区块链上。这笔交易的成本极低约 0.000005 SOL但它提供了一个铁证在某个区块高度对应一个确切时间点这份记忆的指纹已经存在。这层解决了记忆的完整性验证和抗篡改问题。设计考量为什么不把数据直接上链因为成本。一次完整的对话记忆可能包含数千字节直接上链的 Gas 费用是天文数字。而只将几十字节的 CID 和哈希上链成本几乎可以忽略不计却能达到相同的可信效果。这是一种典型的“链下存储数据链上锚定证明”的扩容方案。2.2 密码学链条构建可验证的记忆历史仅仅存储孤立的记忆块是不够的。AegisMemory 引入了CID 链的概念。每一份新的记忆在存储时都会包含一个指向上一份记忆 CID 的prev_cid字段。这就形成了一个密码学上的链表结构。记忆块N: {cid: QmABC..., data: ..., prev_cid: QmXYZ...} 记忆块N1: {cid: QmDEF..., data: ..., prev_cid: QmABC...}这种设计带来了两个关键优势完整性验证你可以从最新的记忆开始沿着prev_cid指针一路回溯验证整个记忆链的连续性。任何中间环节的篡改都会导致哈希不匹配从而破坏链条。高效检索结合链上锚定的“检查点”每天的最新 CID你可以快速定位到某一天的记忆链头部然后进行回溯或前向遍历无需扫描所有数据。2.3 零知识架构与用户档案从 v3.0 开始引入的Cyberdyne Profiles功能将上述架构应用到了用户档案管理上。其核心是“零知识”理念AI 智能体服务端永远不需要看到用户档案的明文。所有档案数据在客户端用户钱包侧进行加密只有加密后的密文被存储到 IPFS。当需要验证用户声誉或身份时可以通过密码学证明如签名来完成而无需解密数据。这最大程度地保护了用户隐私符合数据最小化原则。3. 核心模块深度解析与实操要点理解了宏观架构我们深入到各个核心模块看看它们是如何协同工作的以及在实操中需要注意什么。3.1 加密模块钱包即密钥cryptoBox.js模块负责所有加密解密操作。其核心是使用 AES-256-GCM 算法。但密钥从哪里来AegisMemory 的创新在于直接使用用户的Solana 钱包私钥来派生加密密钥。原理用户的 Ed25519 钱包密钥对本身并不直接用作 AES 密钥。模块会使用钱包私钥对一段固定的上下文信息如“aegismemory-encryption-key”进行签名然后将这个签名的哈希值作为 AES-256 的密钥种子。这种方式确保了密钥唯一性每个钱包对应唯一的加密密钥。密钥不可导出加密密钥由私钥派生但无法从加密密钥反推私钥。便捷性用户无需管理另一套密钥体系钱包就是万能钥匙。实操要点密钥安全是根本.env文件中的AEGISMEMORY_WALLET_SECRET_KEY或钱包 JSON 文件是你的最高机密必须妥善保管绝不能提交到代码仓库。非随机性AES-GCM 每次加密都需要一个唯一的随机数Nonce/IV。模块会生成一个 12 字节的随机 IV 与密文一起存储。解密时必须使用相同的 IV。认证加密GCM 模式不仅提供保密性还提供完整性认证。任何对密文的篡改都会在解密时被检测出来并导致失败。3.2 IPFS 存储与 TOON 格式ipfsFetch.js和toon.js模块负责数据的存储和序列化。存储的目标是 X1 Vault 提供的 IPFS 网关。TOON 格式详解TOON 并非简单的 JSON 压缩。它是一种受 Telegram 数据格式启发的人类可读序列化格式。对比 JSON它的优势在于去除冗余符号JSON 中的大括号、引号、逗号在 TOON 中被大量精简。更紧凑的数组和对象表示使用[messages]和缩进层级来定义结构。可读性强即使加密前也便于开发者调试。一个 TOON 格式的记忆文件结构如下aegismemory.v1 agent: my_agent wallet: 9SksTs4... time: 2024-05-27T10:30:00.000Z cid: QmCurrent... prev_cid: QmPrevious... sha256: abc123... [messages] - role: user content: 你好今天天气如何 time: 2024-05-27T10:30:00.000Z - role: assistant content: 今天天气晴朗气温25度。 time: 2024-05-27T10:30:05.000Z上传流程记忆数据被序列化为 TOON 格式字符串。计算该字符串的 SHA256 哈希。使用上述加密模块对字符串进行加密得到密文。将密文通过fetchAPI 发送到https://vault.x1.xyz/ipfs/api/v0/add。网关返回 CID此 CID 即为该记忆在 IPFS 网络上的永久地址。注意事项X1 Vault 的公共网关https://vault.x1.xyz/ipfs/CID可能被禁用读取。因此AegisMemory 在读取时使用的是https://vault.x1.xyz/ipfs/api/v0/cat?argCID这个 API 端点。这是与公共 IPFS 网关如 ipfs.io的一个重要区别。3.3 链上锚定模块anchorModule.js模块负责与 X1 区块链交互。X1 是一条基于 Solana 的区块链因此其交易构造与 Solana 完全兼容。锚定交易的本质它是一笔调用 Solana Memo Program 的交易。Memo Program 是一个系统程序允许用户在交易中附带一段文本信息。AegisMemory 将以下信息作为文本写入 MemoAegisMemory Anchor CID: QmCurrent... SHA256: abc123... Timestamp: 2024-05-27T00:00:00.000Z这笔交易由用户的钱包签名并支付极少的交易费约 0.000005 SOL然后被广播到 X1 网络。一旦确认这段信息就和该笔交易一起被永久记录在区块链上。频率控制逻辑模块内部维护一个lastAnchoredDate状态。每次运行锚定检查时它会比较当前 UTC 日期和lastAnchoredDate。如果日期不同则执行锚定操作并更新状态如果相同则跳过。这确保了“每日一锚”的默认行为。你也可以通过环境变量AEGISMEMORY_ANCHOR_FREQUENCYevery_save将其改为“每次保存都锚定”但这会显著增加链上成本。实操心得钱包需有余额锚定需要支付 SOL 作为交易费。务必确保配置的钱包地址在 X1 网络上有少量 SOL0.01 SOL 就足够数千次锚定。RPC 稳定性AEGISMEMORY_ANCHOR_RPC_URL配置的 RPC 节点需要稳定可靠。如果节点无响应锚定会失败但记忆的本地和 IPFS 存储不受影响。交易确认在测试网或网络拥堵时交易确认可能需要几秒到几十秒。生产环境建议使用付费的私有 RPC 节点以获得更好的稳定性。3.4 跨智能体记忆共享v3.1 引入的跨智能体记忆共享是 AegisMemory 走向协作网络的关键一步。其设计非常巧妙完全基于现有的密码学原语和去中心化存储。共享模型授权智能体 A 使用自己的钱包私钥对智能体 B 的钱包公钥进行加密生成一个“共享密钥密文”。这个密文被存储在智能体 A 本地的权限列表中。分享当智能体 A 想分享某个具体记忆CID时它会用该记忆的解密密钥由 A 的主密钥派生加密记忆内容或直接分享密钥然后将加密后的密钥和源 CID、源钱包地址一起打包成一个aegis://协议的分享令牌。导入智能体 B 拿到令牌后首先用自己的私钥解密出智能体 A 的“共享密钥密文”这一步需要 A 事先授权然后用这个共享密钥解密出目标记忆的解密密钥最终读取记忆。安全核心权限是基础没有事先授权grant即使拿到分享令牌也无法解密出用于解密记忆的密钥。密钥不直接传递分享令牌中传递的是加密后的密钥且每次分享可以生成不同的密钥。去中心化所有权限数据和分享令牌的验证都不需要中心化服务器完全通过 IPFS 和本地状态完成。使用场景团队知识库多个客服机器人共享常见问题解答FAQ记忆。记忆迁移将旧机器人的记忆安全地迁移到新机器人。上下文传递用户在与智能体 A 的对话中提到了某项目当转接到更专业的智能体 B 时可以共享相关记忆片段实现无缝衔接。4. 完整部署、配置与运维指南4.1 环境准备与安装系统要求Node.js 18.0.0。推荐使用 nvm 管理 Node 版本。Solana CLI 工具主要用于钱包管理和余额查询AegisMemory 本身使用 solana/web3.js 库与链交互。安装 Solana CLI# 安装 Solana CLI sh -c $(curl -sSfL https://release.solana.com/stable/install) # 安装完成后根据提示将 solana 添加到 PATH # 例如如果是 bash执行 echo export PATH$HOME/.local/share/solana/install/active_release/bin:$PATH ~/.bashrc source ~/.bashrc # 验证安装 solana --version solana config set --url https://rpc.mainnet.x1.xyz # 将默认 RPC 设置为 X1 网络安装 AegisMemory 有两种方式推荐通过 OpenClaw 插件安装以实现深度集成。# 方式一作为 OpenClaw 插件安装推荐 cd ~/.openclaw # 或你的 OpenClaw 配置目录 openclaw plugins install Xenian84/aegismemory openclaw plugins enable aegismemory # 方式二手动克隆用于开发或独立使用 git clone https://github.com/Xenian84/aegismemory.git cd aegismemory npm install4.2 钱包配置与资金准备这是最关键的一步关系到记忆的安全和链上功能的可用性。生成或导入钱包 如果你没有 Solana 钱包可以使用 Solana CLI 生成一个新钱包。# 生成一个新的密钥对文件 solana-keygen new --outfile ~/.config/solana/id.json # 这会输出公钥地址请务必保存好生成的 id.json 文件或者如果你已有钱包可以将助记词或私钥导入。获取测试网 SOL X1 主网使用 SOL 作为 Gas 费。你需要向配置的钱包地址转入少量 SOL。从其他支持 X1 网络的交易所或钱包提现 SOL 到你的钱包地址。或者如果使用开发网可以通过 X1 或 Solana 的官方水龙头获取测试币请注意X1 主网没有免费水龙头。验证余额solana balance 你的钱包地址 --url https://rpc.mainnet.x1.xyz确保余额大于 0.01 SOL这足以支持数千次锚定操作。4.3 OpenClaw 集成配置AegisMemory 作为 OpenClaw 的 Memory Slot Provider需要在 OpenClaw 的配置中启用。编辑 OpenClaw 的配置文件通常是~/.openclaw/openclaw.json{ plugins: { entries: { aegismemory: { walletPubkey: YOUR_WALLET_PUBLIC_KEY_HERE, walletSecretKeyPath: ~/.config/solana/id.json, agentId: my_telegram_bot, memoryFormat: toon, anchorEnabled: true, anchorRpcUrl: https://rpc.mainnet.x1.xyz, memoryLimit: 100, captureStrategy: full } }, slots: { memory: aegismemory } } }配置项详解walletPubkey你的 Solana 钱包公钥。walletSecretKeyPath钱包私钥文件路径。强烈建议使用文件路径而非将私钥明文放在配置中。agentId智能体的唯一标识符用于区分不同智能体的记忆流。memoryFormat:toon推荐或json。anchorEnabled: 是否启用链上锚定。anchorRpcUrl: X1 网络的 RPC 端点。memoryLimit: 本地保留的记忆条数上限LRU 策略。captureStrategy:full保存完整消息summary可配置为保存 AI 生成的对话摘要需要智能体支持。4.4 运行测试与状态检查配置完成后重启你的 OpenClaw 智能体。AegisMemory 插件会自动挂接到智能体的生命周期钩子如agent_end。你可以使用内置的 CLI 工具进行测试# 进入 AegisMemory 目录如果是手动安装 cd /path/to/aegismemory # 检查系统状态 ./bin/aegismemory.js status一个成功的status命令输出应包含钱包地址和余额。当前代理 ID。记忆队列状态待处理/已完成任务数。最新的记忆 CID。上次链上锚定的日期和交易 ID。现在让你的 OpenClaw 智能体开始一次对话。对话结束后AegisMemory 会自动捕获、加密并上传记忆。你可以通过./bin/aegismemory.js recall --limit 5来查看最近 5 条记忆的解密内容。5. 高级功能与场景化应用5.1 语义搜索与记忆检索v2.1 引入的语义搜索功能让记忆检索从基于时间的简单过滤升级为基于内容理解的智能搜索。背后原理当记忆被保存时系统会使用一个轻量级的句子嵌入模型如all-MiniLM-L6-v2生成 384 维向量将记忆中的文本内容转换为向量并存储起来。当进行搜索时查询语句也会被转换为向量然后通过计算余弦相似度在向量数据库内存或本地索引中找出最相关的记忆。实操命令# 基础搜索 ./bin/aegismemory.js search 如何配置区块链节点 # 跨智能体搜索需权限 ./bin/aegismemory.js search 项目进度 --agent THEO_AGENT_WALLET_ADDR # 设置相关性阈值 ./bin/aegismemory.js search 错误处理 --min-score 0.8性能与精度权衡嵌入模型在本地运行无需网络调用但会消耗少量 CPU 资源。向量索引存储在内存中重启后需要重新构建从 IPFS 重新加载记忆并计算嵌入。对于记忆量很大的场景建议将索引持久化到磁盘当前版本可能需要自行扩展。--min-score参数可过滤低相关性结果值越高结果越精确但可能遗漏相关表述不同的内容。5.2 记忆管理与维护随着时间推移记忆库会不断增长。AegisMemory 提供了一系列管理工具。导出与备份# 导出单条记忆为明文 JSON用于分析或迁移 ./bin/aegismemory.js export --cid QmXYZ... --out ./backup/memory_123.json # 导出所有记忆的 CID 列表 ./bin/aegismemory.js status | grep -A 10 Recent CIDs重要提示导出的 JSON 文件包含解密后的明文记忆。请务必在安全的环境下操作和存储这些文件。验证记忆完整性 这是 AegisMemory 的核心价值所在。你可以随时验证任何记忆的真实性。# 本地验证检查解密、哈希和 CID 链 ./bin/aegismemory.js verify --cid QmXYZ... # 链上验证额外检查该 CID 是否在特定日期被锚定上链 ./bin/aegismemory.js verify --cid QmXYZ... --rpc链上验证会查询 X1 区块链寻找包含该 CID 的 Memo 交易。如果找到则证明该记忆在交易时间点之前就已经存在。HTML 可视化查看 对于调试或分享可以使用view命令生成一个美观的 HTML 页面。./bin/aegismemory.js view --cid QmABC...这个命令会生成一个带有时间线、对话者颜色区分例如用户蓝色助手绿色的 HTML 文件并自动在浏览器中打开。这对于回顾长对话或向他人展示交互过程非常有用。5.3 Cyberdyne 用户档案系统实战Cyberdyne Profiles 是一个独立但紧密集成的功能用于管理加密的用户声誉档案。创建档案./bin/aegismemory.js cyberdyne-create \ --telegram-id 123456789 \ --username alice_in_blockchain \ --score 850 \ --rank 15 \ --tier HARMONIC \ --contributions [{type: bug_report, count: 5}, {type: community_help, count: 20}] \ --achievements [early_supporter, documentation_contributor]这个过程在本地完成加密然后将密文上传到 IPFS。返回的 CID 就是该档案的唯一标识。在 OpenClaw 智能体中使用 在你的智能体工具函数中可以调用// 当用户首次交互时创建或更新其档案 const profileCid await ctx.tools.cyberdyne_create_profile({ telegram_id: ctx.message.from.id, username: ctx.message.from.username, score: calculateInitialScore(ctx), rank: await fetchUserRank(ctx.message.from.id) }); // 在后续交互中获取档案以提供个性化服务 const profile await ctx.tools.cyberdyne_get_profile({ telegram_id: ctx.message.from.id }); if (profile.reputation.tier HARMONIC) { // 为高声誉用户提供优先支持或高级功能 await ctx.reply(尊敬的Harmonic成员您的问题将被优先处理。); }零知识验证示例假设有一个“持证发言”功能需要用户证明其声誉分数大于 500。传统的做法是智能体解密档案查看分数。在零知识模式下可以设计一个流程客户端用户钱包用私钥对“分数500”这个陈述生成一个零知识证明ZKP智能体只需验证这个证明的有效性而无需知道具体分数。虽然当前 v3.0 版本尚未集成成熟的 ZKP但其加密存储架构为未来实现此类高级隐私功能铺平了道路。6. 故障排查、性能优化与安全实践6.1 常见问题与解决方案问题1记忆保存成功但链上锚定失败。症状status显示最新的 CID但lastAnchored日期很久没更新或者 CLI 报错Failed to anchor transaction。排查步骤检查钱包余额./bin/aegismemory.js status查看余额是否充足。检查 RPC 连接curl -s https://rpc.mainnet.x1.xyz -X POST -H Content-Type: application/json -d {jsonrpc:2.0,id:1, method:getHealth}。应返回ok。检查网络状态访问 X1 区块浏览器查看最新区块是否在正常出块。查看详细日志设置环境变量DEBUGaegismemory:*然后运行命令查看具体的错误信息。解决方案余额不足向钱包地址转入 SOL。RPC 问题尝试更换备用 RPC 节点需在配置中修改anchorRpcUrl。网络拥堵稍后重试或提高交易优先级需要修改代码使用更高优先级费用。问题2无法从 IPFS 读取记忆Recall/Search 失败。症状recall或search命令报错Failed to fetch from IPFS。排查步骤验证 CID使用verify --cid CID确认 CID 本地有效。直接访问 IPFS 网关在浏览器中打开https://vault.x1.xyz/ipfs/api/v0/cat?argCID。如果返回错误可能是 Vault 服务暂时问题或 CID 未被成功钉住pinned。检查本地网络确保服务器可以访问外部网络。解决方案如果是 Vault 服务问题可以等待服务恢复或者修改代码尝试使用公共网关如https://ipfs.io/ipfs/CID但注意公共网关可能有速率限制和延迟。确保上传流程ipfsFetch.js中的add函数成功并返回了 CID。问题3跨智能体共享记忆时导入令牌失败。症状import --token ...报错Invalid token或Permission denied。排查步骤检查令牌格式令牌必须是aegis://CID/WALLET/ENCRYPTED_KEY格式。确认授权状态在源智能体上运行./bin/aegismemory.js permissions确认目标智能体的钱包地址已在授权列表中。检查钱包匹配确保执行import命令的智能体其配置的钱包私钥与分享令牌中指定的目标钱包地址匹配。解决方案让源智能体重新执行grant授权。重新生成分享令牌。6.2 性能优化建议记忆索引优化默认的语义搜索索引在内存中。如果记忆数量超过万条首次加载或重建索引可能变慢。可以考虑将向量索引持久化到本地数据库如 SQLite 或 LevelDB。IPFS 网关回退策略在ipfsFetch.js中实现多网关回退逻辑。优先使用 X1 Vault API失败时尝试公共网关ipfs.io, cloudflare-ipfs.com提高读取可靠性。锚定交易批处理在“每次保存都锚定”模式下频繁的小额交易可能不经济。可以改为在本地队列中积累一定数量的 CID然后批量提交一笔包含多个 Memo 的交易需自定义 Solana 程序。状态文件备份~/.aegismemory/state.json文件记录了最新的 CID、锚定日期等关键状态。建议定期备份此文件或将其纳入版本控制系统注意不要包含敏感信息。6.3 安全最佳实践私钥管理至高无上永远不要将walletSecretKey明文提交到版本控制系统如 Git。始终使用.env文件或通过walletSecretKeyPath引用文件。.env文件应设置严格的文件权限如chmod 600 .env。考虑使用硬件钱包或密钥管理服务KMS进行签名但这需要修改anchorModule.js的签名逻辑以支持外部签名。最小权限原则用于锚定的钱包只存入少量用于支付交易费的 SOL。不要将大量资产或主钱包用于此目的。在跨智能体共享时仔细审核授权对象。定期使用permissions命令审查并清理不必要的授权。定期审计与验证定期运行verify --cid latest_cid --rpc抽查记忆的链上锚定状态确保整个系统的可验证性在持续工作。监控链上交易记录确认锚定交易按预期发生。依赖安全定期运行npm audit检查项目依赖的安全漏洞。锁定关键依赖如加密库noble/*的版本避免自动升级引入不兼容或存在漏洞的版本。网络与端点安全确保配置的 RPC 端点anchorRpcUrl是可信的。恶意 RPC 节点可能返回虚假的区块链数据。如果处理敏感记忆考虑在私有 IPFS 网络或加密的私有存储上运行但这需要大幅修改存储层。AegisMemory 将一个复杂的多组件系统——AI 智能体、加密学、去中心化存储和区块链——优雅地整合在一起为解决 AI 记忆的持久性、安全性和可信性问题提供了一个切实可行的生产级方案。它的模块化设计也意味着你可以根据需求进行裁剪例如如果暂时不需要链上锚定可以关闭该功能以节省成本如果对隐私要求极高可以增强加密模块或集成硬件安全模块HSM。随着 v3.1 跨智能体共享功能的加入它正从一个单机记忆库演变为一个协作记忆网络的基础设施其想象空间和应用前景非常广阔。