Shadow：如何设计一个好用的、透明可控的 AI 记忆系统，其核心在于平衡“长期存储的稳定性”与“短期上下文的灵活性” 。

基于 OpenClaw及Memsearch等项目的技术实践，可以总结出以下四个维度的设计要点：

一、 核心哲学：Markdown 作为“唯一真理来源”

透明与可控的前提是数据必须以人类可读的形式存在。

• 非二进制存储：弃用复杂的数据库黑盒，将 Markdown 文件作为规范数据存储，任何开发者或用户都可以通过文本编辑器查看 Agent “知道”什么
• Git 友好性：Markdown 允许利用 Git 进行版本控制，实现记忆的全版本历史追溯、分支管理和冲突解决
• 去中心化与零锁定：纯文本格式保证了记忆的无缝迁移，不依赖于特定的数据库引擎或供应商，确保了数据的持久主权
• 派生索引架构：向量数据库（如 Milvus 或 SQLite-vec）仅作为加速检索的“派生索引”层，可以随时从本地 Markdown 文件中重新构建，从而解决索引损坏或陈旧的问题

二、 空间架构：三层记忆层级设计

为了防止信息过载并提高检索精度，系统应采用分层架构管理记忆

1. 第一层：每日日志 ( memory/YYYY-MM-DD.md)：这是原始记录层，以追加模式记录 Agent 每天的所有活动、对话片段和执行结果，提供无限量的细节支撑
2. 第二层：精选记忆 ( MEMORY.md)：这是核心层，通过 LLM 定期从日志中提取的关键事实、用户偏好和决策，通常限制在较小的 Token 范围内（如 <2500字符）以保证加载速度
3. 第三层：长期归档 (Archives)：将高价值但非即时相关的历史内容（如项目总结、周报、决策 JSON）进行归档，仅通过向量检索按需调取

三、 动态维护：从“被动记录”转向“主动学习”

一个可控的系统需要自动化的维护机制来保持记忆的“卫生”

• 智能检查点 (Checkpoints)：每隔固定时间（如6小时）触发 LLM 扫描最近的日志，提取今日成就、学习收获和重要决策，并自动更新至精选记忆文件
• 预压缩内存冲洗 (Silent Memory Flush)：当会话上下文接近模型限制即将触发“自动压缩”时，系统先执行一次静默轮次，提醒 Agent 将当前对话中的关键点写入磁盘，防止重要事实在压缩中丢失
• 决策日志 (Decision Logging)：不仅记录结果，更记录决策的背景、备选项和原因，确保 Agent 的行为具有可追溯的因果关系
• 自愈与优化：在系统空闲时（如夜间），自动检测过时、孤立或重复的内容，修复记忆中的冗余，并构建知识图谱分析主题关联

四、 检索与索引：混合检索策略

为了解决“大海捞针”式的查询难题，检索层必须兼顾语义与精确匹配

• 混合搜索 (Hybrid Search)：结合“稠密向量（语义相似度）”与“BM25（关键字匹配）”两种信号，既能理解“我想喝水”的意图，也能精确找到“ERR_404”这种特定错误代码
• 语义去重：利用 SHA-256 内容哈希对记忆块进行唯一标识，避免重复嵌入（Embedding）同一内容，从而降低 API 开销并减少冗余数据
• 按需加载 (On-demand Loading)：Agent 在运行前仅读取最近两天的日志和核心精选记忆，其他深度背景信息通过调用 memory_search工具按需拉取，以维持上下文窗口的精简

总结：一个优秀的记忆系统应该是本地优先 (Local-first) 的，所有敏感数据和记忆链路都保存在用户控制的设备上 。这种设计不仅大幅提升了隐私安全性，还通过“自动提取-精简存储-混合检索”的闭环，使 AI 助理能够随着时间的推移不断进化，真正成为用户的“数字孪生”

相关推荐：

个人 AI 助理系统构建指南 (Prompt 模板)，来自OpenClawd的上下文工程设计经验