1. 项目概述为AI Agent构建结构化记忆系统在AI Agent逐渐成为我们日常工作流中“同事”的今天一个根本性的矛盾日益凸显这些智能体拥有强大的即时推理能力却缺乏持续、稳定、结构化的长期记忆。想象一下你每天都要向一位新来的同事重新介绍自己的项目背景、工作习惯和审美偏好这无疑是低效且令人沮丧的。这正是当前许多AI助手包括OpenClaw等优秀项目所面临的“记忆失忆症”困境。它们要么依赖一个不断膨胀、难以维护的MEMORY.md文件要么将海量对话记录一股脑塞进有限的上下文窗口导致成本飙升和关键信息被稀释。HeyCube黑方体正是为了解决这一核心痛点而生。它不是一个简单的聊天记录存储器而是一个专为AI Agent设计的结构化个人档案管理系统。其核心思想是将关于“你”的碎片化信息从海量的对话文本中抽离出来按照“身份认知”、“心理结构”、“审美偏好”等维度进行结构化归档存储在本地的SQLite数据库中。当AI需要了解你时它不再需要通读所有历史记录而是像查询数据库一样精准、按需地调用相关维度的信息每次仅消耗约2000个tokens。这不仅是技术上的优化更是对AI与人类协作关系的一次重新定义——从每次对话都“重新认识”转变为基于一个持续生长、深度理解的“人格档案”进行协作。2. 核心设计理念与架构解析2.1 破解AI记忆的“不可能三角”在构建AI记忆系统时我们通常面临一个“不可能三角”记忆容量、理解深度与成本控制三者难以兼得。传统RAG检索增强生成虽然能处理大量文档但其检索结果是碎片化的文本片段缺乏对“人”的整体性结构化理解。检索效果随文档量增长而衰减且无法建立跨文档的关联认知。超长上下文窗口如128K/1M看似一劳永逸将所有历史对话都塞进去。但这带来了两个致命问题一是成本呈指数级增长二是模型在处理超长文本时会出现“中间遗忘”现象位于上下文中间部分的信息被有效利用的概率大大降低。静态记忆文件如MEMORY.md这是目前许多AI助手采用的方案。它的优点是信息集中、可控。但缺点同样明显文件会无限膨胀每次对话都需要全量载入消耗大量tokens并且维护全靠手动AI无法自动从中学习和更新结构化知识。黑方体的设计哲学跳出了这个三角。它承认“记住一切”既不经济也不智能转而追求“在正确的时间提供正确的记忆”。通过将记忆结构化、维度化、本地化实现了无限增长新的记忆被分类归档到已有的维度或新维度中数据库可以轻松扩展。深度理解结构化的字段如决策风格: calculated growth比一段模糊的描述文本更易于AI理解和运用。成本可控每次对话仅动态加载最相关的几个维度上下文消耗稳定在低位。2.2 系统架构总览黑方体采用“云端策略本地数据”的混合架构在智能与隐私之间取得了精妙的平衡。服务端云端“大脑”角色策略制定者与维度仓库。核心功能维护海量维度池定义和管理“身份认知”、“审美偏好”等数百个结构化维度及其focus_prompt引导AI如何提取该维度信息的提示词。执行智能召回策略当客户端发起查询时服务端基于对话语义运行多路召回算法判断本次对话需要哪些维度参与。提供元数据仅向客户端同步维度ID、名称等元信息绝不接触用户的实际个人数据。技术栈通常采用PostgreSQL利用其JSONB字段灵活存储维度定义和高效的向量检索服务用于语义召回。客户端本地“保险箱”角色数据存储与执行终端。核心功能本地SQLite数据库所有结构化个人数据的安全港湾。这是整个系统的核心数据永不离开。OpenClaw Hook集成通过OpenClaw的Pre-Conversation和Post-Conversation Hook机制无侵入地嵌入工作流。执行查询与更新根据服务端下发的维度列表从本地SQLite中查询数据并注入对话上下文在对话后将AI生成的结构化摘要写入本地数据库。技术栈SQLite轻量、单文件、零配置、OpenClaw Skill框架。工作流程对话前Pre-Hook用户发起对话。客户端将当前对话的初始消息或主题发送至服务端。服务端进行语义分析通过多路召回策略生成一个本次对话需要的“维度ID列表”返回给客户端。客户端根据此列表从本地SQLite中查询这些维度的最新数据拼接成一段精炼的focus_prompt注入到即将发给大模型的系统提示词中。对话中大模型在包含了相关维度信息的上下文中与用户对话因此能做出更个性化、更懂用户的回应。对话后Post-Hook将完整的对话记录发送至服务端。服务端分析内容判断本次对话更新了哪些已有维度的信息或创建了哪些新维度的记录并生成结构化的数据更新指令如维度[审美偏好.色彩]新增记录{“value”: “偏好低饱和度莫兰迪色系”}返回客户端。客户端执行这些指令更新本地SQLite。关键设计优势隐私分离。你的具体数据“我喜欢蓝色”永远在本地SQLite里。云端只知道“这次对话需要用到‘色彩偏好’这个维度”但不知道你的色彩偏好具体是什么。这既享受了云端智能调度的便利又确保了数据的绝对私有。3. 核心组件深度剖析3.1 维度体系结构化记忆的基石维度是黑方体将非结构化文本转化为结构化知识的原子单位。一个维度不仅仅是一个标签而是一个有明确语义定义的数据收集单元。维度的构成id: 唯一标识符如aesthetic_visual_minimalism。name: 人类可读的名称如视觉风格-极简主义。focus_prompt:灵魂所在。这是一段引导AI从对话中识别和提取该维度信息的指令。例如对于“决策风格”维度其focus_prompt可能是“请从对话中识别用户做决策时的特点。是快速直觉型还是深思熟虑型是风险偏好型还是风险规避型是独自决定还是寻求共识请用关键词概括如‘intuitive, risk-taking, solo’。”八大域分类示例身份认知core_values核心价值观、self_definition自我描述。心理结构decision_making_style决策风格、stress_response压力应对模式。审美偏好visual_style视觉风格、music_genre_preference音乐流派偏好。职业画像technical_skills技术技能栈、career_goals职业目标。计划目标fitness_goal健身目标、learning_objectives学习目标。日程节奏productive_hours高效工作时间段、meeting_preference会议偏好。杂项偏好coffee_preference咖啡喜好、commute_mode通勤方式。关系网络key_relationships重要人际关系、communication_style_with_family与家人的沟通方式。实操心得如何设计一个好的focus_prompt具体而非抽象避免“记录用户的偏好”而应说“记录用户对UI设计中色彩饱和度、留白空间和字体样式的具体评价”。输出结构化引导AI输出易于解析的格式如“关键词1关键词2”或JSON片段。包含正反例如果可能在提示词中给出例子说明什么是符合该维度的信息什么不是。迭代优化初期维度定义可能不完美。通过观察AI提取的结果持续迭代focus_prompt使其更精准。3.2 智能召回策略从“检索”到“推理”这是黑方体区别于简单关键词检索的核心。它的目标不是找出包含某个词的所有记录而是推理出当前对话情境下AI需要了解“你”的哪些方面。多路召回机制语义召回将当前对话的query进行向量化与所有维度的focus_prompt或描述进行相似度计算如余弦相似度召回最相关的维度。这是主力通道。历史召回查询历史日志当用户过去谈论类似话题时调用了哪些维度这些维度本次很可能仍然相关。热度召回统计全局范围内最常被调用的维度例如communication_style可能总是很高这些通用性强的维度有基础权重。共现召回分析维度之间的共现关系。例如当decision_making_style被调用时risk_tolerance也经常被一起调用。这是一种基于图的关联推理。无数据召回探索机制特别重要系统会识别那些尚未被填充数据但可能与当前话题相关的维度。这鼓励系统主动探索和补全你的个人档案实现“越用越准”。打分排序与重排 各路召回的结果会形成一个候选维度列表每个维度有一个初始分数。一个简化的打分公式可能是最终分数 语义相关度权重 * 语义分 历史共现权重 * 历史分 全局热度权重 * 热度分 探索奖励 - 疲劳度惩罚 - 过度覆盖惩罚疲劳度惩罚防止同一维度在短时间内被反复调用。过度覆盖惩罚避免一次性加载过多维度挤占上下文窗口。 最后这个经过加权的列表会交给一个轻量级LLM进行最终重排和精简生成一个最优的、数量可控的维度子集用于本次对话。3.3 本地存储与同步机制SQLite为何是它零依赖与便携性单个.db文件无需安装数据库服务复制即用完美契合“本地优先”理念。性能足够对于个人档案级别的读写毫秒级响应SQLite的性能绰绰有余。成熟的生态几乎所有编程语言都有良好的驱动支持便于脚本编写和数据处理。数据库表结构设计简化示例-- 维度值表存储具体的个人数据 CREATE TABLE dimension_values ( id INTEGER PRIMARY KEY AUTOINCREMENT, dimension_id TEXT NOT NULL, -- 对应云端维度池的ID user_id TEXT NOT NULL, value_json TEXT NOT NULL, -- 存储结构化的值如 {level: expert, preference: Python} source_conversation_id TEXT, -- 来源于哪次对话 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, confidence_score FLOAT -- AI提取该信息时的置信度 ); -- 为频繁查询的字段建立索引 CREATE INDEX idx_dimension_user ON dimension_values (dimension_id, user_id); CREATE INDEX idx_updated ON dimension_values (updated_at); -- 对话日志表用于历史召回分析 CREATE TABLE conversation_logs ( id INTEGER PRIMARY KEY AUTOINCREMENT, conversation_id TEXT UNIQUE, preview_text TEXT, -- 对话摘要或开头几句 used_dimensions TEXT, -- 本次对话使用的维度ID列表JSON数组 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );数据同步策略 服务端与客户端之间同步的仅仅是元数据和指令这是一个关键的安全设计。维度元数据同步客户端定期或启动时从服务端拉取最新的维度定义列表id, name, focus_prompt更新本地缓存。这个过程不涉及任何个人数据。更新指令同步对话后服务端下发的“更新指令”只包含维度ID和结构化的值客户端负责将其写入本地数据库。服务端并不知晓写入是否成功也不存储这些值。注意事项备份虽然SQLite很稳定但personal.db文件是记忆的核心。务必建立定期备份机制如通过脚本自动复制到云盘或其他位置。可以编写一个简单的cron任务或使用版本控制工具但需注意忽略敏感数据。4. 与OpenClaw的集成实操4.1 Hook机制详解OpenClaw的Skill Hook机制为黑方体提供了完美的无侵入集成点。你不需要修改OpenClaw的核心代码只需将其作为一个Skill安装。Pre-Conversation Hook触发时机在OpenClaw将用户消息发送给大模型之前。黑方体工作调用本地服务或直接运行脚本将用户消息作为query发送给黑方体服务端。接收服务端返回的维度ID列表。根据ID列表查询本地personal.db获取最新的维度值。将这些维度值按照focus_prompt的格式组织成一段连贯的文本。将这段文本作为“系统提示词”的一部分插入到OpenClaw即将发送的请求中。效果大模型在回复时已经“知道”了与当前话题相关的你的背景信息。Post-Conversation Hook触发时机在OpenClaw收到大模型的完整回复且一次对话轮次结束后。黑方体工作将本轮完整的对话记录用户输入AI回复发送给黑方体服务端进行分析。接收服务端返回的结构化数据更新指令。在本地执行这些指令向personal.db插入或更新记录。可选记录本次对话的日志到conversation_logs表用于后续的历史召回分析。4.2 配置与部署步骤假设你已经在本地运行了OpenClaw以下是集成黑方体的详细步骤步骤一获取并配置黑方体客户端从仓库克隆或下载黑方体的客户端代码。在配置文件中设置你的服务端API地址和认证密钥API Key。运行数据库初始化脚本python scripts/init_db.py它会在指定位置创建personal.db文件及所需的数据表。步骤二编写OpenClaw Skill在OpenClaw的skills目录下创建一个新的技能文件夹例如heycube_memory。创建技能的主文件如skill.py其中需要实现两个主要函数# 伪代码示例 import requests import sqlite3 from openclaw.skill_base import SkillBase class HeyCubeSkill(SkillBase): def pre_conversation(self, state): user_message state.get(latest_user_message) # 1. 调用本地/远程黑方体服务获取相关维度IDs relevant_dims self.call_heycube_server_for_dims(user_message) # 2. 从本地SQLite查询这些维度的值 dims_data self.query_local_db(relevant_dims) # 3. 格式化数据拼接到系统提示词中 memory_prompt self.format_memory_prompt(dims_data) state[system_prompt_suffix] memory_prompt # 假设通过此字段追加提示 return state def post_conversation(self, state): full_conversation state.get(full_conversation_text) # 1. 将完整对话发送给黑方体服务端分析 update_commands self.call_heycube_server_for_update(full_conversation) # 2. 在本地执行更新命令 self.execute_update_commands(update_commands) # 3. 记录日志 self.log_conversation(state[conversation_id], relevant_dims) return state在OpenClaw的配置中启用这个Skill。步骤三验证与测试启动OpenClaw开始一次新的对话。观察OpenClaw的日志确认Pre/Post Hook被正常调用。尝试谈论一个你之前从未涉及但属于已有维度的话题例如“我觉得极简主义的设计看起来很舒服”。对话结束后使用提供的查询脚本如python scripts/query_records.py --dimension aesthetic_visual检查本地数据库确认“审美偏好-视觉”维度下是否新增了关于“极简主义”的记录。再次开启一个相关话题的对话例如“帮我设计一个海报”观察AI的回复是否已经体现了你对极简风格的偏好。4.3 与原生MEMORY.md的协同黑方体并非要取代OpenClaw原生的MEMORY.md而是与之形成互补的“记忆分层体系”。MEMORY.md充当手动维护的、高度精炼的“核心备忘录”。存放那些绝对重要、不容有误、需要人类强监督的信息。例如“我的真名是张三”、“我公司的项目代号是‘天穹’”、“我对花生严重过敏”。这部分信息稳定变化少适合手动编辑。黑方体SQLite充当AI自动维护的、不断生长的“结构化人格档案”。存放从日常对话中衍生出的偏好、习惯、风格等软性知识。例如“我写代码时喜欢先写注释”、“做PPT时偏好深色背景”、“周五下午是我效率低点”。这部分信息动态变化由AI自动捕捉和更新。OpenClaw Session上下文存放本次对话的临时工作记忆。在系统提示词中可以将三部分内容按优先级拼接# 系统提示词 你是一个AI助手。以下是一些关于用户的固定信息 [MEMORY.md的内容] 此外根据本次对话的主题以下是一些相关的用户背景和偏好 [黑方体动态注入的结构化档案] 请基于以上信息结合当前对话内容与用户交流。这样AI既拥有了稳定的身份锚点又具备了动态的个性化理解能力。5. 高级应用、问题排查与未来展望5.1 数据维护与自检脚本随着时间推移数据库里可能会积累不一致或过时的记录。定期维护是必要的。常用维护脚本数据导出与查看使用export_csv.py脚本将指定维度的数据导出为CSV用Excel打开进行人工审阅。这是理解AI如何“看待”你的最佳方式。数据清理编写脚本根据confidence_score置信度和updated_at更新时间清理低质量或过于陈旧的记录。例如删除置信度低于0.7且一年未更新的记录。维度贡献度分析分析哪些维度最常被调用哪些维度从未被填充。这可以帮助你优化对话方式或者向黑方体团队反馈哪些维度需要调整focus_prompt。实操心得处理冲突数据当AI从不同对话中提取到关于同一维度的矛盾信息时例如一次说“喜欢安静”另一次说“喜欢热闹”简单的覆盖可能不合理。可以在dimension_values表中增加conflict_flag字段并在写入时进行简单的冲突检测如对比新值与最近三次的历史值。如果检测到潜在冲突可以暂不更新而是通过一个“待审核”列表留待用户下次对话时由AI主动询问确认例如“我之前记录您偏好安静环境但刚才的对话似乎提到喜欢社交活动请问哪种描述更符合您通常的情况”。这引入了人机协作的校准循环。5.2 常见问题与排查问题1对话中感觉AI没有调用我的记忆。排查步骤检查OpenClaw日志确认Pre-Conversation Hook是否被触发以及黑方体服务端是否返回了维度列表。检查本地SQLite数据库确认相关维度下是否有数据。sqlite3 personal.db SELECT * FROM dimension_values WHERE dimension_idxxx;检查服务端的维度池确认该维度的focus_prompt定义是否清晰、可操作。检查用户query是否过于宽泛或模糊导致语义召回失败。尝试更具体地开启话题。问题2AI提取的记忆信息不准确或奇怪。原因与解决focus_prompt不明确这是最常见原因。需要迭代优化维度的focus_prompt使其指令更清晰并包含示例。源对话信息模糊AI只能基于你提供的对话文本进行提取。如果对话本身没有明确表达偏好提取结果自然会模糊。尝试在对话中更明确地表达你的观点。多轮对话上下文干扰Post-Hook分析时可能包含了不相关的历史上下文。可以考虑在发送给服务端时只截取最相关的几轮对话。问题3本地数据库文件损坏或丢失。预防与恢复定期备份如前所述设置自动化备份脚本。使用WAL模式在连接SQLite时启用Write-Ahead Logging模式可以提高并发性和减少损坏风险。从导出文件恢复如果你定期导出CSV可以从CSV文件重新导入数据到新的数据库。编写一个import_from_csv.py脚本作为恢复手段。5.3 未来演进方向黑方体目前已经构建了一个强大的框架但仍有广阔的演进空间跨平台与跨Agent记忆同步未来的你可能不仅在OpenClaw上使用AI还在Cursor、Claude Desktop等多个Agent上工作。黑方体可以演进为一个中心化的个人记忆服务通过安全的端到端加密同步协议让所有被你授权的AI Agent都能共享同一套不断进化的个人档案实现真正的“数字人”一致性。主动记忆与目标驱动系统不应只是被动记录还可以主动规划。例如当识别到你在“学习目标”维度下设置了“三个月内学会吉他”它可以定期在对话中主动询问进度或推荐相关的学习资源推动目标的达成。记忆可视化与交互式修正提供一个图形化界面让你可以直观地浏览、编辑、修正你的“人格档案”。你可以手动调整某个维度的权重标记某条记录已过期或者直接告诉AI“这条记错了应该是……”。让人类保持在记忆循环中实现更精准的协同进化。联邦学习与群体匿名洞察在绝对保障隐私数据不离本地的前提下能否通过联邦学习技术从海量用户的脱敏元数据如维度共现模式、focus_prompt有效性中学习持续优化核心的召回算法和维度体系这能让系统越用越智能且不触及任何个人敏感数据。我个人在实际部署和使用中的体会是黑方体最大的价值在于它改变了我与AI交互的预期。我不再觉得每次对话都是孤立的而是能感受到一种连续的、积累的“被理解”。这种“被记住”的感觉是让AI从工具真正迈向“同事”或“伙伴”的关键情感纽带。初期需要一些耐心来“喂养”数据和调优维度但一旦系统运转起来它所带来的个性化体验提升是指数级的。开始尝试时不妨从一个你最关心的领域开始比如“工作习惯”或“创作偏好”集中对话几次快速看到效果这会给你坚持用下去的动力。