1. 项目概述为AI Agent构建持久化记忆层在AI Agent的开发与部署实践中一个普遍存在的挑战是“金鱼记忆”问题Agent在单次会话中表现出色但一旦会话结束所有上下文、决策和学到的知识便烟消云散。下次交互时Agent又得从头开始无法形成连贯的、有“成长性”的智能体。这正是council-memory这个技能Skill要解决的核心痛点。它不是一个独立的应用程序而是一个专为“Council Room”这类多智能体协作框架设计的持久化记忆模块旨在让AI Agent拥有跨越会话的、可检索的长期记忆。简单来说council-memory为你的AI Agent们提供了一个共享的、结构化的“大脑皮层”。它允许Agent将重要的决策、发现的事实、每日进展以及从错误中学到的教训系统地写入到本地文件系统中。更重要的是在后续的会话中Agent可以主动读取、搜索这些记忆并将最相关的上下文“注入”到自己的提示词Prompt中。这意味着你的Agent永远不会忘记“Lucy是谁”、“DataFlow项目当前的目标是什么”或者“上周我们决定采用哪种技术方案”。这种记忆能力是构建真正实用、可信赖的AI助手的关键一步。这个技能特别适合那些正在基于类似OpenClaw、LangChain、AutoGen等框架构建复杂AI工作流的开发者、研究者和技术团队。如果你厌倦了每次都要向Agent重复背景信息或者希望你的智能体能够从历史交互中学习并持续优化其行为那么理解并集成这样一个记忆层将是至关重要的。接下来我将深入拆解其架构、核心操作并分享在实际集成和使用中的关键细节与避坑经验。2. 记忆架构深度解析从短期日志到长期知识库council-memory的设计精髓在于其分层的记忆架构。它没有将所有信息混为一谈而是模仿了人类处理信息的方式将其分为短期、长期和结构化知识库每种类型对应不同的存储路径和用途。理解这个架构是有效使用该技能的基础。2.1 四层记忆模型及其职责第一层是短期记忆Short-term Memory对应memory/YYYY-MM-DD.md文件。这相当于Agent的“工作日志”或“流水账”。所有日常的、原始的事件记录、会议摘要、临时想法都写入这里。例如一次站立会议的记录、一个临时发现的Bug、一次与用户的简短对话。它的特点是高频率、低密度、未经深度加工。按日期分割文件使得回溯某一天的具体活动变得非常容易但也意味着信息是碎片化的。第二层是长期记忆Long-term Memory核心文件是MEMORY.md。这是经过“ curation”策展的记忆。并非所有每日笔记都会进入这里只有那些被判定为重要、需要长期记住的事实、决策和原则才会被提炼并写入。你可以把它想象成项目的“核心宪法”或“百科全书”。例如“Lucy是印度尼西亚的SaaS创业者”、“DataFlow的核心技术栈是Python FastAPI PostgreSQL”、“项目预算上限为X美元”。这个文件需要手动或通过智能规则进行维护确保其简洁、准确、不过时。第三层是Agent事实库Agent Facts存储在Obsidian Vault的特定目录下如vault/00_System_Core/。Obsidian是一个基于本地Markdown文件的知识管理工具其强大的双向链接和图形视图功能使得管理Agent之间的复杂关系网络成为可能。这一层用于存储更结构化、更具关联性的知识比如某个特定Agent如“Rafael”负责OCR的Agent的学习心得、最佳实践、故障处理手册等。它连接了离散的事实形成知识图谱。第四层是Council知识库Council KB即council_memory.json文件。这是整个系统的“结构化记忆中枢”。它采用JSON格式定义了明确的模式Schema用于存储所有Agent需要共享的、机器可读的关键信息。其核心价值在于支持高效的查询和程序化访问。Agent可以通过API快速获取“当前OCR准确率”、“最新的三个决策”或“Lucy的偏好”而无需去解析冗长的Markdown文档。注意这四层并非互斥而是互补的。一个重要的决策例如“决定采用Tesseract 5.0作为OCR引擎”可能会同时被记录在1当天的每日笔记中事件2MEMORY.md的“技术决策”章节长期事实3council_memory.json的decisions数组里结构化记录。这种冗余确保了记忆的可靠性和可访问性。2.2 路径配置与工作空间理解所有路径都围绕一个中心工作空间展开/home/openclaw/.openclaw/workspace/。这是OpenClaw框架的默认工作目录所有技能、脚本和生成内容都位于此。council-memory技能本身被安装在workspace/skills/council-memory/下。Vault路径 (/home/openclaw/livesync-bridge/vault/): 这暗示了项目可能使用了一个实时同步工具如livesync来桥接Obsidian。Obsidian Vault本身只是一个文件夹将其放在同步目录下可以实现多设备间的记忆同步这对于团队协作至关重要。Council内存文件路径: 直接位于council-room项目的data目录下表明它是Council Room智能体框架的核心数据文件。每日笔记路径: 直接在workspace/memory/下按日期组织。在实际部署时你需要确保这些目录都存在且有正确的写入权限。如果使用Obsidian需要提前初始化好Vault。council_memory.json文件如果不存在需要在首次运行时被创建技能脚本应包含此逻辑。3. 核心操作详解与实战脚本剖析council-memory通过一个统一的Python脚本memory_op.py暴露了所有核心功能。让我们逐一拆解每个操作看看背后发生了什么以及在实际使用时需要注意什么。3.1 读取记忆会话开始前的必备动作python3 ~/.openclaw/workspace/skills/council-memory/scripts/memory_op.py read这个命令看似简单但它是确保Agent“上下文感知”的关键。它不应该只打印出所有记忆而应该返回一个结构化的摘要或者至少将关键信息加载到环境变量中。一个健壮的read操作实现可能会做以下几件事检查并合并来源读取council_memory.json解析其facts,decisions,kpis等部分。获取近期动态读取最近几天的memory/*.md文件提取摘要。生成上下文摘要将上述信息整合成一段连贯的文本例如“当前用户是LucyDataFlow项目的OCR准确率KPI为87%目标提升至95%。过去三天的主要决策包括1. 目标用户定位为有5年以上经验的簿记员2. 决定采用新的数据预处理流程。”输出或存储将生成的摘要输出到标准输出或者写入一个临时文件供后续的Agent提示词模板引用。实操心得不要只在会话开始时调用一次read。在长时间、多轮次的对话中可以在关键决策点后再次调用read以确保Agent始终基于最新的全局状态进行思考。可以将read操作封装成一个函数在Agent的初始化阶段自动调用。3.2 写入事实将瞬时信息转化为持久知识python3 ~/.openclaw/workspace/skills/council-memory/scripts/memory_op.py write \ --fact \Lucy decided to target bookkeepers with 5 years experience\ \ --category \decisions\这是记忆系统的“写入”接口。--fact参数是要记录的具体内容--category指定了将其归入哪个逻辑类别如decisions,facts,lessons。脚本内部逻辑推测参数解析与验证检查--category是否属于预设的合法类别列表如[‘facts‘ ‘decisions‘ ‘kpis‘ ‘lessons‘]。加载现有JSON读取council_memory.json文件到内存中。结构化存储根据类别将事实插入到对应的JSON数组中。一个完整的记录可能不仅包含事实字符串还应包含元数据例如{ \decisions\: [ { \id\: \dec_20231027_001\, \fact\: \Lucy decided to target bookkeepers with 5 years experience\, \date\: \2023-10-27\, \agent\: \strategy_agent\, // 哪个Agent做出的决策 \rationale\: \Higher conversion rate and LTV based on preliminary survey.\ // 决策依据 } ] }持久化保存将更新后的JSON对象写回文件。这里有一个关键风险点并发写入。如果多个Agent同时调用write可能导致文件损坏或数据丢失。可选的后置操作根据类别脚本可能还会更新MEMORY.md文件。例如对于category“decisions”可能会在MEMORY.md的“## 决策日志”部分追加一条新记录。避坑指南并发写入问题。在多人或多Agent协作环境下直接读写JSON文件是危险的。解决方案包括a) 使用文件锁fcntl或portalocker库b) 将记忆服务化通过一个简单的HTTP API服务来处理所有读写请求数据库可以使用SQLite甚至内存数据库c) 采用写入队列所有写入请求先入队由单个消费者顺序处理。3.3 搜索记忆让Agent拥有“回想”能力python3 ~/.openclaw/workspace/skills/council-memory/scripts/memory_op.py search \ --query \bookkeeper validation\搜索功能是记忆系统价值的放大器。它允许Agent主动在历史记忆中寻找相关信息而不是被动地接受注入的上下文。实现搜索的几种策略简单字符串匹配在council_memory.json的所有文本字段和MEMORY.md内容中进行grep式的搜索。实现简单但无法处理语义相似性。向量语义搜索推荐这是更高级和实用的方式。具体步骤 a.嵌入Embedding当写入一个事实时同时使用一个嵌入模型如OpenAI的text-embedding-3-small或本地运行的BAAI/bge-small-en将事实文本转换为一个高维向量。 b.存储向量将这个向量与事实文本一起存储可以存到council_memory.json的扩展字段或单独的向量数据库如Chroma、Qdrant中。 c.查询时将搜索查询“bookkeeper validation”也转换为向量。 d.相似度计算计算查询向量与所有记忆向量之间的余弦相似度。 e.返回结果返回相似度最高的前N条记忆及其相似度分数。这样即使Agent搜索“如何验证用户资质”也能找到之前记录的“target bookkeepers with 5 years experience”因为它们在语义上是相关的。混合搜索结合关键词匹配和向量搜索先通过关键词快速过滤再对候选集进行语义排序。注意事项如果采用向量搜索需要考虑嵌入模型的更新和维护。对于本地部署选择一个轻量级且性能良好的开源模型至关重要。同时要定期清理或归档旧的、不相关的记忆向量以保持搜索效率。3.4 追加每日笔记与注入上下文daily和context操作是更具体的应用。daily操作纯粹是追加日志。脚本会获取当前日期定位或创建memory/YYYY-MM-DD.md文件然后在文件末尾追加带有时间戳的笔记。这个操作应该非常轻量和快速。context操作这是连接记忆系统和Agent的桥梁。当启动一个针对特定Agent如--agent “rafael”的新会话时此操作会读取通用记忆council_memory.json中的facts 特别是关于Lucy和DataFlow的描述。读取该Agent的专属记忆例如从vault/Lessons/rafael.md中读取它学到的经验教训。读取最新的KPI和决策。将所有信息组合成一个精心结构的提示词前缀Context Prefix。例如返回的字符串可能是**会话上下文 [Agent: Rafael, Date: 2023-10-27]** *用户背景* Lucy是DataFlow的创始人一位位于印度尼西亚UTC8的SaaS创业者。DataFlow是一个专注于为有5年以上经验的簿记员提供AI OCR解决方案的项目。 *项目状态* 当前核心KPI - OCR准确率为87%下一个冲刺目标是将准确率提升至95%。本周预算剩余1200美元。 *近期决策* 1. 决定采用新的图像预处理流水线2023-10-26。2. 将用户验证流程从两步改为一步2023-10-25。 *给Rafael的提示* 你上次发现Tesseract在处理手写数字时准确率下降建议尝试结合CNN模型。请基于此继续优化。然后这个字符串会被自动添加到发送给LLM如GPT-4的最终提示词的开头。这样LLM在生成回复时就已经具备了所有这些背景知识。4. 记忆写入策略与场景化指南原文档中的表格给出了很好的指引但我们可以进一步细化并补充背后的思考逻辑。情境写入位置原因与操作细节重要决策达成MEMORY.mdcouncil_memory.json原因决策需要长期可见和可追溯。MEMORY.md供人类阅读和回顾council_memory.json供程序化查询。操作调用write命令category“decisions”并确保在MEMORY.md的“决策日志”部分手动或自动添加一条带日期的记录。日常事件/进展memory/YYYY-MM-DD.md原因保留原始的工作流水账用于事后复盘或查找具体时间点的细节。操作调用daily命令。内容应简洁、客观例如“14:30 - 与前端团队同步了新UI设计稿的反馈。”Agent专属经验教训vault/Lessons/agent.md原因不同Agent的专长和犯错领域不同。集中记录有助于该Agent的个性化“成长”。操作这通常由Agent自身在任务失败或成功总结后触发。例如一个爬虫Agent在遇到特定网站反爬后可以将应对策略记录到自己的Lesson文件中。发现用户偏好MEMORY.md的“How Lucy Works”部分原因用户偏好是高度稳定且重要的长期事实需要放在最核心、最易找到的位置。操作例如发现“Lucy更喜欢用bullet points而不是段落来总结报告”这是一个关键事实应更新到MEMORY.md中并同时在council_memory.json的facts里添加{“entity“: “Lucy“ “preference“: “summary_format“ “value“: “bullet points“}。指标/KPI更新council_memory.json的categories.kpis原因KPI是动态的、结构化的数据最适合用JSON存储便于图表生成、趋势分析和条件触发如“当准确率90%时通知”。操作应有专门的监控Agent或脚本定期运行更新KPI值。格式如{“name“: “ocr_accuracy“ “value“: 0.87 “target“: 0.95 “last_updated“: “2023-10-27“}。技术决策MEMORY.md的“Technical Decisions”部分原因技术选型、架构变更等决策会影响长期开发需要文档化其理由避免日后争论或遗忘。操作记录决策内容、备选方案、最终选择的理由、决策日期和参与人。例如“2023-10-26选择FastAPI而非Flask因为其对异步的原生支持更好自动生成API文档且性能基准测试高出15%。”核心原则一次生成多处记录。对于最高优先级的信息如核心决策应同时在人类可读Markdown和机器可读JSON的媒介中保存以确保信息的可访问性和持久性。5. 自动上下文注入的实现与优化自动上下文注入是council-memory技能的“杀手级应用”。它的目标是在Agent开始思考前就为其构建一个丰富的认知背景从而避免生成通用、脱节的回答。5.1 上下文注入的工作流程触发时机会话开始时当用户与某个Agent如“Rafael”启动新对话时。任务切换时当Agent从一个任务如“代码审查”切换到另一个任务如“撰写周报”时。定时刷新在长时间会话中可以每小时自动刷新一次上下文以获取最新的KPI或决策。内容组装逻辑 脚本memory_op.py context --agent “rafael”内部会执行一个复杂的查询和组装过程# 伪代码示意 def generate_context(agent_name): context_parts [] # 1. 获取核心事实关于Lucy和DataFlow core_facts load_json(‘council_memory.json‘)[‘facts‘] lucy_desc find_fact(core_facts “description“ “Lucy“) project_desc find_fact(core_facts “description“ “DataFlow“) context_parts.append(f“**User**: {lucy_desc}\n**Project**: {project_desc}“) # 2. 获取最新决策例如最近3条 recent_decisions get_recent_items(‘decisions‘ count3) context_parts.append(“**Recent Decisions**:\n“ format_list(recent_decisions)) # 3. 获取当前KPIs current_kpis load_json(‘council_memory.json‘)[‘kpis‘] context_parts.append(“**Current Status**:\n“ format_kpis(current_kpis)) # 4. 获取该Agent的专属经验 agent_lessons read_file(f“vault/Lessons/{agent_name}.md“) if agent_lessons: context_parts.append(f“**Notes for {agent_name}**:\n{extract_recent_lessons(agent_lessons)}“) # 5. 获取今日/昨日摘要 todays_notes get_daily_notes(days_back1) context_parts.append(“**Recent Activity**:\n“ todays_notes) return “\n\n“.join(context_parts)提示词工程集成 生成的上下文字符串不会直接扔给LLM。最佳实践是将其作为“系统提示词System Prompt”的一部分或者放在用户提问之前。例如在OpenAI的ChatCompletion API中messages [ {“role“: “system“ “content“: “You are Rafael an AI assistant specialized in OCR optimization. Always refer to the context below.“}, {“role“: “user“ “content“: f“{generated_context}\n\nNow answer the following: {user_question}“} ]这样LLM就能在正确的角色和丰富的上下文中进行回复。5.2 优化技巧与常见问题问题1上下文太长导致Token超出限制或干扰主要任务。解决方案实施“摘要”和“裁剪”策略。摘要对于较长的记忆如完整的会议记录在注入前先用另一个LLM调用或摘要算法生成一个简短版本。裁剪只注入最相关的部分。可以通过计算查询用户问题与每条记忆的语义相似度只注入Top-K条最相关的记忆。这就是上文提到的向量搜索的用武之地。分层注入将上下文分为“核心上下文”始终注入如Lucy身份和“动态上下文”根据会话主题选择性注入。问题2过时或冲突的记忆导致错误回答。解决方案建立记忆的“保鲜”和“冲突解决”机制。版本控制/时间戳每条记忆都必须有创建日期和最后更新日期。context操作可以优先选择更新时间更近的记忆。置信度评分为记忆添加置信度来源如“来自官方文档”、“来自用户口头确认”、“来自Agent推测”。高置信度记忆优先。冲突检测定期运行脚本检查council_memory.json和MEMORY.md中是否存在对同一事实的矛盾描述例如一个说“Lucy喜欢简洁报告”另一个说“Lucy喜欢详细报告”。发现冲突时触发一个“记忆清理”任务让管理Agent或人类来裁决。问题3如何让Agent主动更新记忆解决方案设计Agent的“反思”环节。在完成一个重要任务或对话轮次后让Agent自己生成一个总结并提出“哪些信息值得存入长期记忆”。然后可以自动或经人工确认后调用write命令。这实现了从“被动记录”到“主动学习”的跨越。6. 数据模式设计与扩展性考量council_memory.json的模式Schema是整个系统的骨架。一个好的模式设计能确保数据的规范性、可查询性和可扩展性。6.1 基础模式设计参考项目描述一个增强版的模式可能如下所示{ “$schema“: “./council_memory_schema.json“, “version“: “1.1“, “last_updated“: “2023-10-27T08:30:00Z“, “facts“: [ { “id“: “fact_001“, “entity“: “Lucy“, “attribute“: “role“, “value“: “SaaS founder based in Indonesia UTC8“, “category“: “persona“, “source“: “user_input“, “confidence“: 1.0, “created_at“: “2023-10-01“, “updated_at“: “2023-10-01“ } ], “decisions“: [ { “id“: “dec_20231027_001“, “title“: “Target experienced bookkeepers“, “description“: “Lucy decided to target bookkeepers with 5 years experience“, “rationale“: “Preliminary market survey indicates higher willingness to pay and lower churn rate in this segment.“, “status“: “approved“, // approved pending deprecated “made_by“: “strategy_agent“, “approved_by“: “Lucy“, “date“: “2023-10-27“, “related_kpis“: [“customer_acquisition_cost“ “lifetime_value“] } ], “kpis“: [ { “name“: “ocr_accuracy“, “current_value“: 0.87, “target_value“: 0.95, “unit“: “percentage“, “trend“: “improving“, // improving declining stable “last_updated“: “2023-10-27“, “history“: [ // 可选用于存储历史值 {“date“: “2023-10-20“ “value“: 0.82}, {“date“: “2023-10-27“ “value“: 0.87} ] } ], “lessons“: [ { “id“: “lesson_001“, “agent“: “rafael“, “context“: “Optimizing OCR for handwritten invoices“, “insight“: “Tesseract 5.0 performs poorly on cursive handwriting. A hybrid approach with a custom CNN model for character segmentation improved accuracy by 15%.“, “date_learned“: “2023-10-26“, “applicable_to“: [“ocr_tasks“] // 标签用于检索 } ], “sessions“: [ // 可选记录重要会话的元数据 { “session_id“: “sess_20231026_am“, “agents_involved“: [“rafael“ “strategy_agent“], “topic“: “Q4 Planning“, “summary_file“: “memory/2023-10-26.md#heading-1“, “date“: “2023-10-26“ } ] }6.2 扩展性考量关系型扩展可以在facts或decisions中添加“related_to“: [“fact_002“ “dec_20231001_001“]字段建立记忆条目之间的关联未来可以构建记忆图谱。审计追踪对于facts和decisions可以添加“history“数组记录每次的修改内容、修改人和修改时间实现完整的变更历史。标签系统为所有条目增加“tags“字段支持多维度的分类和过滤比固定的category更灵活。外部引用“source“字段可以扩展为URL或文件路径指向原始信息来源如会议录音、邮件、文档链接增强记忆的可追溯性。维护建议随着项目发展记忆条目会快速增长。需要定期如每季度进行“记忆归档”将已完结、不再活跃的decisions标记为“archived“。将陈旧的lessons移至一个单独的archived_lessons.json文件。清理daily notes中过于琐碎的记录只保留摘要。 这个过程本身也可以由一个“档案管理员”Agent来自动化或辅助完成。7. 部署、集成与实战避坑指南7.1 安装与环境配置原文档的安装步骤cp -r过于简单实际部署需要考虑更多。依赖管理memory_op.py脚本必然有Python依赖如jsonosdatetime 可能还有openai用于向量嵌入。需要在技能目录下提供requirements.txt文件。# 在技能目录下 pip install -r requirements.txt可能的依赖openainumpysentence-transformers用于本地向量模型python-dateutil。路径配置化绝对路径如/home/openclaw/...在团队协作或不同服务器上会失效。最佳实践是使用配置文件或环境变量。创建一个config.yaml或config.json文件workspace_root: “/home/openclaw/.openclaw/workspace“ vault_path: “/home/openclaw/livesync-bridge/vault“ council_memory_path: “/home/openclaw/council-room/data/council_memory.json“脚本首先读取这个配置文件或者从环境变量如COUNCIL_MEMORY_PATH获取路径。初始化脚本提供一个init.py或setup.sh脚本用于检查并创建所有必要的目录和空文件如初始化的council_memory.json和MEMORY.md模板。7.2 与Council Room/OpenClaw的集成council-memory作为技能需要被主Agent框架调用。技能注册在Council Room的配置中需要将council-memory注册为一个可用技能。这通常意味着在某个配置文件中添加技能路径和入口点。事件驱动调用理想情况下记忆的读写不应完全依赖手动命令。可以设计事件监听当Agent生成最终答案时自动触发daily操作记录对话摘要。当检测到用户语句中包含“我决定…”或“我们的目标是…”时自动触发write --category decisions。当会话开始时自动触发context操作。API化封装为了更好的集成和解决并发问题可以将memory_op.py的核心逻辑封装成一个简单的HTTP服务使用FastAPI或Flask。这样所有Agent都通过调用本地API来访问记忆由服务统一处理并发和持久化。这比直接操作文件要健壮得多。7.3 常见问题与排查技巧问题执行python3 memory_op.py write后council_memory.json文件内容混乱或为空。可能原因1JSON格式错误。在写入时如果脚本异常退出可能导致JSON文件损坏。排查使用python -m json.tool council_memory.json验证JSON格式。解决实现写操作的原子性。先将数据写入一个临时文件如.council_memory.json.tmp写入成功后再用os.replace()原子性地替换原文件。这样即使崩溃原文件也是完整的。可能原因2权限不足。Agent进程没有对目标文件的写权限。排查检查文件所有权和权限ls -la council_memory.json。解决确保运行Agent的用户对该文件及其目录有读写权限。问题context操作返回的信息不准确或过时。可能原因1缓存问题。脚本可能缓存了旧的记忆数据。解决确保每次read或context操作都从磁盘重新读取文件或者在内存缓存中设置较短的过期时间。可能原因2记忆未及时同步。如果记忆文件被其他进程修改当前脚本可能不知道。解决对于高频读写的场景考虑使用数据库如SQLite而非纯文件利用数据库的事务和锁机制。问题向量搜索速度慢。可能原因记忆向量数量太多每次搜索都进行全量计算。解决索引化使用专业的向量数据库如Chroma Qdrant Weaviate它们内置了高效的近似最近邻ANN搜索索引。过滤先通过类别、标签、日期等元数据过滤出一个小集合再在这个小集合上进行向量相似度计算。定期修剪归档或删除非常旧的、低重要性的记忆。问题Agent变得“固执己见”过于依赖旧记忆而忽略新信息。可能原因上下文注入时旧记忆的权重过高或者新信息没有被及时写入记忆。解决在context生成逻辑中为记忆条目引入“衰减因子”或“新鲜度权重”。越近的记忆权重越高。同时确保Agent有机制将对话中的新发现及时写入记忆系统。记忆系统的构建是一个迭代过程。从最简单的文件读写开始逐步增加向量搜索、冲突解决、自动摘要等高级功能。关键是要让它紧密贴合你的Agent团队的实际工作流真正成为提升协作效率和智能体“智商”的助力而不是一个增加复杂性的负担。