1. 项目概述为AI助手构建一个可读、可控的长期记忆系统如果你和我一样在深度使用AI助手比如OpenClaw进行项目协作时常常会感到一种割裂感每一次对话都像是一次全新的开始。助手可能记得几分钟前你让它改的代码但完全不记得上周你们一起定下的那个关于“所有API响应必须包含请求ID”的核心架构决策。这种“健忘症”让协作效率大打折扣也让一些需要长期上下文的任务变得异常繁琐。市面上不缺各种复杂的“向量数据库知识库”方案但它们往往像黑盒数据存进去容易想看看里面到底记了什么、为什么这么记却难上加难。今天要聊的Agent Memory项目就是针对这个痛点的一个“反直觉”解法。它不是一个试图吞噬一切知识的大胃王而是一个极简、可读、长期的记忆系统。它的核心思想非常朴素把AI助手需要记住的、真正有价值的东西用人类也能轻松看懂的Markdown笔记存起来然后用一个明确的检索层QMD来查找。整个系统设计的目标就是“小、可审查、易迁移”。说白了它不想成为你的第二个大脑它只想成为你AI助手的一个可靠、透明的“外置硬盘”存什么、怎么存、怎么取你都能看得一清二楚。为什么我觉得这个思路值得一试因为它解决了信任问题。当记忆系统过于复杂和隐蔽时你根本不敢放心让它参与重要决策。而Agent Memory把存储Obsidian笔记库和检索QMD都摆在明面上记忆笔记就是普通的.md文件你可以随时打开、编辑、批注。这种“透明性”对于需要长期、稳定协作的场景至关重要尤其适合开发者、项目经理或者任何需要与AI助手进行持续性、项目制工作的朋友。2. 核心设计哲学为什么“小而美”优于“大而全”在开始动手部署之前理解这个项目的设计哲学至关重要。这能帮你判断它是否适合你也能让你在后续使用中避开很多误区。2.1 精准定义记忆的边界什么该记什么不该记很多记忆系统失败的原因在于“贪婪”。它们试图记录对话中的每一个事实、每一个概念结果就是记忆库迅速膨胀充满噪音真正重要的信息反而被淹没。Agent Memory从一开始就划清了严格的边界。它的记忆模型只包含六种持久性记忆类型偏好比如“用户喜欢在代码审查时先看整体结构再抠细节”。决策比如“项目决定使用SQLite作为本地缓存而非JSON文件”。陷阱比如“在模块A中调用API B之前必须手动初始化上下文否则会报错”。人物记录协作者的关键信息或沟通风格。项目状态比如“v2.3版本的核心功能已开发完成当前阻塞在第三方服务认证上”。身份规则定义助手在特定场景下的行为边界比如“在回复用户关于预算的询问时必须引用最新财务报告中的数字”。这个清单非常短但覆盖了协作中最需要延续的上下文。所有不属于这些类型的信息都不应该进入“记忆库”。一次性的技术问答、临时的代码片段、随手查的资料这些应该留在对话历史或你的个人知识库里而不是污染这个精心维护的长期记忆。注意最难的部分不是技术实现而是纪律。你需要和你的AI助手共同遵守这个边界。在项目初期我建议完全采用“手动模式”由你来判断和创建记忆笔记这能帮你深刻理解什么信息值得被“长期化”。2.2 存储与检索分离用简单工具搭建可靠管道这个项目在技术选型上贯彻了“Unix哲学”每个工具只做好一件事然后通过清晰的接口把它们组合起来。存储层Obsidian。一个基于本地Markdown文件的笔记工具。选择它是因为“可读性”是最高优先级。记忆笔记以纯文本形式存在你可以用任何编辑器打开版本控制如Git可以轻松管理它们的历史迁移成本几乎为零。它就是一个结构化的文件夹。检索层QMD。一个本地运行的语义搜索和检索工具。它的职责很单纯为记忆笔记建立索引qmd update生成嵌入向量qmd embed然后根据查询返回最相关的结果qmd query。它不负责存储也不负责理解只负责快速查找。这种分离带来了巨大的灵活性。如果未来有比QMD更优秀的本地检索工具你可以替换检索层而存储层的所有笔记不受任何影响。反之亦然。2.3 工作流从对话到记忆的蒸馏过程整个系统的核心工作流是一个经典的“蒸馏”过程我把它总结为以下四步1. 【记录】实时对话 - 保存为原始日志10_Journal/ 2. 【蒸馏】原始日志 - 提炼为规范记忆笔记20_Agent-Memory/ 3. 【索引】记忆笔记 - 通过QMD建立索引和向量嵌入 4. 【检索】助手提问 - QMD从记忆库中召回相关笔记步骤1是保留所有原始素材。10_Journal/目录下的文件是完整的对话转录相当于“原始数据库”。步骤2是关键的价值提炼环节将原始对话中符合那六种类型的信息提取并格式化成结构化的记忆笔记。步骤3和4是使记忆“可用”的过程让助手在需要时能快速找到它们。这个流程的美妙之处在于你可以在任何环节进行人工干预。你可以审查日志可以修改自动提取的记忆笔记可以检查QMD的检索结果。整个系统没有“魔法黑箱”。3. 从零开始手把手搭建你的第一个记忆系统理论讲完了我们进入实战环节。我会以macOS系统为例带你走通从安装到第一次成功检索的全流程。整个过程大约需要20-30分钟。3.1 基础环境准备安装核心工具首先我们需要两个核心工具Obsidian 和 QMD。1. 安装 Obsidian访问 Obsidian 官网下载安装包。安装完成后打开Obsidian我们需要创建一个全新的库Vault来作为记忆仓库。点击“创建新库”。库名称建议用AgentMemoryVault便于识别。位置选择是关键我强烈建议将它放在一个同步盘目录下比如 iCloud Drive 或 Dropbox 的同步文件夹中。这样可以在多设备间同步记忆。按照项目默认我们可以创建在~/Library/Mobile Documents/iCloud~md~obsidian/Documents/AgentMemoryVault这个路径是iCloud为Obsidian预留的同步目录能保证笔记的实时同步。创建完成后暂时关闭Obsidian即可我们后续主要通过文件系统操作它。2. 安装 QMDQMD 是一个命令行工具需要通过包管理器安装。打开终端Terminal。如果你有 Homebrew这是最简单的方式brew install qdrant/qdrant/qmd安装完成后验证是否成功qmd --version。如果能显示版本号说明安装成功。3.2 配置记忆仓库的结构现在我们在刚创建的Obsidian库中建立约定的文件夹结构。这就像为记忆系统搭建一个清晰的文件柜。在终端中导航到你的仓库目录并创建子文件夹cd ~/Library/Mobile\ Documents/iCloud~md~obsidian/Documents/AgentMemoryVault mkdir -p 10_Journal 20_Agent-Memory10_Journal/存放原始对话日志。编号“10”保证了它在文件列表中最先显示符合工作流顺序。20_Agent-Memory/存放提炼后的规范记忆笔记。这是QMD将要索引的核心区域。3.3 配置 QMD 索引规则QMD需要知道它应该索引哪些文件。我们需要编辑它的配置文件。创建或编辑QMD的全局配置文件mkdir -p ~/.config/qmd nano ~/.config/qmd/index.yml你也可以使用vim或code等你喜欢的编辑器将以下配置内容写入index.yml文件# ~/.config/qmd/index.yml indexes: agent_memory: path: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/AgentMemoryVault/20_Agent-Memory include: - **/*.md exclude: - **/node_modules/** - **/.git/** embed: model: all-MiniLM-L6-v2 # 这是一个轻量且效果不错的开源句子嵌入模型 store: type: sqlite path: ~/.local/share/qmd/agent_memory.sqlite配置解读我们创建了一个名为agent_memory的索引。path指向了我们的规范记忆文件夹20_Agent-Memory/。注意我们不索引10_Journal/因为原始日志不需要被检索它们只是原材料。include规则指定索引所有.md文件。embed.model指定了用于生成文本向量的模型。all-MiniLM-L6-v2是一个很好的默认选择它平衡了速度和效果且完全在本地运行。保存并退出编辑器。3.4 创建并索引你的第一条记忆现在让我们创建第一条记忆笔记并测试整个检索链路是否通畅。创建记忆笔记 在20_Agent-Memory/文件夹中创建一个名为preference-editor-indentation.md的文件。# 用户偏好代码缩进风格 **类型** preference **项目** 通用 **创建日期** 2023-10-27 **置信度** 高 ## 内容 用户在所有编程项目中明确偏好使用 **空格** 进行缩进而非制表符Tab。具体规则为 - Python、JavaScript/TypeScript、Go 语言使用 **4个空格** 作为一级缩进。 - Shell脚本、YAML/JSON配置文件使用 **2个空格**。 - 用户表示这种一致性有助于在不同编辑器和环境中保持代码外观统一并避免因Tab宽度设置不同导致的格式混乱。 ## 来源 来源于多次代码审查对话中的确认。用户曾纠正过助手使用Tab生成的代码片段。 ## 影响范围 此偏好适用于所有由助手生成或建议的代码块。在提供代码示例、编写脚本或进行代码重构时必须首先检查并确保符合此缩进规则。这份笔记遵循了清晰的结构类型、项目、核心内容、来源和影响范围。这大大提升了笔记的可读性和后续检索的准确性。让 QMD 学习这条记忆 在终端中依次执行以下命令# 让QMD扫描目标文件夹发现新文件 qmd update # 为发现的所有文本内容生成语义向量嵌入 qmd embed如果一切顺利这两条命令不会有太多输出。你可以通过qmd status查看索引状态确认agent_memory索引下有一个文档。进行第一次检索测试 现在让我们模拟助手需要查询用户偏好的场景qmd query 用户写代码时用什么缩进喜欢Tab吗 --index agent_memory如果配置正确QMD会返回与你刚创建的笔记高度相关的结果并显示相似度分数。你应该能看到你笔记中的关键内容被提取出来作为摘要。恭喜至此你已经成功搭建了一个最小可用的、完全受你控制的AI助手长期记忆系统。你现在可以手动管理这个记忆库并通过QMD进行查询。4. 进阶集成与OpenClaw助手自动化协作手动管理记忆库虽然透明但长期来看效率不高。接下来我们将把Agent Memory系统与OpenClaw助手连接起来实现半自动化的记忆沉淀与读取。4.1 自动化保存对话日志首先我们需要让OpenClaw在对话结束后能自动将对话记录保存到10_Journal/中。获取并配置Agent Memory项目脚本 你需要将agent-memory-public项目中的脚本复制到你的工作环境。假设你克隆到了~/Projects/下。cd ~/Projects git clone agent-memory-public的仓库地址 cd agent-memory-public理解保存脚本 核心脚本是scripts/save_to_raw.py。它通常需要从OpenClaw的某个会话存储目录中根据会话IDsession key找到对应的对话记录并将其转换为Markdown格式保存到10_Journal/中文件名通常包含时间戳和会话ID。配置环境变量 为了让脚本知道你的Obsidian仓库和OpenClaw数据在哪最简单的方法是设置环境变量。在你的Shell配置文件如~/.zshrc或~/.bashrc中添加export AGENT_MEMORY_VAULT$HOME/Library/Mobile Documents/iCloud~md~obsidian/Documents/AgentMemoryVault export OPENCLAW_SESSIONS_DIR$HOME/.openclaw/sessions # 假设OpenClaw的会话存储在此然后执行source ~/.zshrc使配置生效。测试保存功能 你需要先找到OpenClaw中某次对话的会话ID或标识符。然后运行cd ~/Projects/agent-memory-public python3 scripts/save_to_raw.py your_session_key_here检查10_Journal/文件夹下是否生成了一个类似20231027-143022_sessionkey.md的文件里面包含了完整的对话记录。4.2 半自动化提炼记忆笔记这是最具挑战也最核心的一环。我们需要从冗长的对话日志中识别出哪些片段值得转化为那六类规范记忆。目前完全可靠的自动化还很困难因此项目采用了“AI建议 人工确认”的半自动模式。了解提炼脚本scripts/journal_to_memory.py是这个过程的核心。它的工作原理是读取一篇日志文件。使用一个预定义的提示词prompts/journal_to_memory_v1.md来引导一个大语言模型比如通过OpenClaw的LLM接口分析文本。要求模型识别出所有潜在的“偏好”、“决策”、“陷阱”等。输出结构化的记忆笔记草案。运行一次提炼尝试python3 scripts/journal_to_memory.py --source /path/to/your/journal-note.md脚本会调用LLM并输出结果。请注意首次运行你可能需要根据你的OpenClaw配置修改脚本中调用LLM的API端点或方式。人工审核与定稿 脚本的输出不应该直接保存到20_Agent-Memory/。你应该将其输出重定向到一个临时文件然后仔细审阅信息是否准确有没有误解对话上下文归类是否合理这个内容真的属于“决策”而不是“偏好”吗表述是否清晰是否符合你定义的笔记模板 经过人工编辑和确认后再将最终的笔记手动保存到20_Agent-Memory/目录中。实操心得在项目初期我强烈建议你完全手动执行提炼步骤。亲自为前20-30条对话创建记忆笔记。这个过程能极大地训练你对“什么值得记忆”的直觉也能帮你优化后续给AI的提示词。自动化应该是为了放大你已经验证有效的模式而不是代替你建立模式。4.3 设置自动化索引更新记忆笔记创建或更新后需要及时更新QMD的索引以便助手能检索到最新内容。我们可以用一个简单的脚本和定时任务来实现。使用刷新脚本 项目提供了scripts/qmd_refresh.py它本质上就是顺序执行qmd update和qmd embed。python3 scripts/qmd_refresh.py创建定时任务Cron Job 你可以让系统每隔一段时间比如每小时自动运行一次刷新。使用crontab -e编辑你的定时任务# 每小时的第5分钟运行一次记忆库索引更新 5 * * * * cd /Users/yourname/Projects/agent-memory-public /usr/bin/python3 scripts/qmd_refresh.py /tmp/qmd_refresh.log 21这样你手动添加到20_Agent-Memory/的笔记最多在一小时内就会被索引并可供检索。4.4 在OpenClaw中集成记忆检索最后我们需要让OpenClaw助手在对话中能够主动查询这个记忆库。这通常需要在OpenClaw的工具Tools或技能Skills配置中添加一个调用QMD查询的命令。具体实现取决于OpenClaw的扩展方式。一个典型的思路是创建一个OpenClaw可调用的脚本或API端点例如query_memory.py。该脚本接收用户的查询文本作为参数。在脚本内部调用qmd query “$user_query” --index agent_memory。将QMD返回的结果格式化后返回给OpenClaw助手。助手在生成回复时可以将这些相关的记忆作为上下文参考。这样当你在和助手讨论“代码风格”时它就可以自动查询记忆库并说出“根据我们之前的记录您偏好使用4个空格进行缩进我会在接下来的代码中遵循这一规则。”5. 实战避坑指南与效能提升技巧在实际使用这套系统几个月后我积累了一些文档里不会写的经验和教训希望能帮你绕过我踩过的坑。5.1 常见问题与排查清单问题现象可能原因排查步骤qmd query返回空或无相关结果1. 笔记未被索引。2. 查询语句与笔记内容语义不匹配。3. 嵌入模型未成功生成向量。1. 运行qmd status检查目标索引下文档数是否为0。2. 运行qmd update和qmd embed重新索引。3. 尝试更具体或更接近笔记原文的查询词。脚本执行报错“路径不存在”环境变量AGENT_MEMORY_VAULT未正确设置。1. 终端中执行echo $AGENT_MEMORY_VAULT检查变量值。2. 确认路径字符串中的空格已正确转义或引用。Obsidian 中看不到10_Journal/下的新文件Obsidian 的缓存未刷新。在Obsidian中按CmdR(Mac) 或CtrlR(Win/Linux) 强制刷新文件列表。记忆提炼脚本输出质量差1. 提示词Prompt不适合你的对话风格。2. 使用的LLM能力不足。1. 仔细研究并修改prompts/journal_to_memory_v1.md加入更具体的例子和规则。2. 尝试更换更强大的LLM模型如GPT-4。自动化保存失败找不到会话OPENCLAW_SESSIONS_DIR路径错误或会话存储格式发生变化。1. 检查OpenClaw的配置文档确认会话存储位置。2. 手动查看该目录确认文件命名和格式。5.2 让记忆系统更高效的四个技巧为记忆笔记建立“索引页”在20_Agent-Memory/根目录下创建一个INDEX.md文件。使用Obsidian的双向链接语法手动维护一个按项目或类型分类的索引。例如# 记忆库总览 ## 按项目 - [[项目-Alpha]]涉及决策[[决策-使用SQLite缓存]] 陷阱[[陷阱-API B初始化上下文]] - [[项目-Beta]]涉及偏好[[偏好-周会报告格式]] ## 按类型 - **决策**[[决策-使用SQLite缓存]], [[决策-主色调定为深蓝]] - **陷阱**[[陷阱-API B初始化上下文]]这在你需要人工快速浏览记忆库时非常有用它提供了QMD语义搜索之外的另一个视图。定期进行“记忆清理”长期记忆不是只增不减的。每个季度花点时间回顾20_Agent-Memory/下的笔记。有些“决策”可能已经过时有些“项目状态”早已完结。为这些笔记添加一个“归档”标签或者移动到30_Archive/文件夹并在QMD配置中排除这个文件夹。这能保持活跃记忆库的简洁和检索准确性。标准化笔记标题和标签虽然QMD支持语义搜索但良好的命名习惯能极大提升可维护性。我采用的格式是[类型]-[项目]-[简短描述].md例如decision-alpha-use-sqlite-cache.md。在笔记内部使用固定的YAML Frontmatter或Markdown表格来存储元数据类型、项目、日期、状态便于未来可能的脚本化处理。从“手动”到“自动”的渐进过渡不要一开始就追求全自动化。遵循项目的哲学先手动后自动。先用两周时间坚持在每次重要对话后手动创建1-2条记忆笔记。这个过程会让你更深刻地理解记忆的边界。打磨出最适合你的笔记模板。积累一批高质量的记忆样本。 之后当你运行自动化提炼脚本时就可以用你自己创建的优质笔记作为示例Few-shot Learning写入提示词中从而大幅提升AI提炼的准确率。这套系统的价值会随着你记忆笔记的积累而指数级增长。它开始可能只是一个简单的“缩进偏好”记录器但几个月后它会成为你项目不可或缺的“集体记忆”确保你的AI助手在任何时候都能基于完整的历史上下文与你协作而不是一次次地从零开始。