1. 项目概述为你的AI编码助手构建一个“会思考”的本地记忆系统如果你和我一样每天都在和AI编码助手比如Cursor、Claude Code打交道那你肯定遇到过这个烦人的问题每次新开一个会话它都像一张白纸之前讨论过的项目细节、踩过的坑、总结的最佳实践全都得从头再说一遍。这感觉就像每次开会都要重新介绍一遍团队成员效率低下不说还容易出错。我们需要的不是一个只会临时对话的“金鱼”而是一个能积累经验、形成判断、甚至能“反思”的伙伴。这就是Agentic Memory要解决的问题。它不是一个复杂的向量数据库也不是一个你无法掌控的云端黑盒。它的核心哲学极其简单用Markdown文件在本地磁盘上为你的AI助手构建一个结构化的、可读的、可版本控制的记忆系统。想象一下你的助手在~/.agents/memory/目录下有一个私人的“经验笔记本”在每个Git仓库的/memory/文件夹里有一个团队的“项目知识库”。所有重要的信息——验证过的事实、主观的判断、失败的教训、成功的模式——都被分门别类地记录下来。下次会话开始时助手能自动加载相关记忆直接进入状态而不是从零开始。这个系统的设计深受学术论文《Hindsight is 20/20: Building Agent Memory that Retains, Recalls, and Reflects》的启发但它摒弃了复杂的学术架构选择了一条更务实、更“极客”的路径纯文本、本地优先、完全透明。你可以用diff命令查看记忆的变更用git管理记忆的版本用任何文本编辑器阅读和修改。它不追求智能的“模糊匹配”而是强调精准的“保留、回忆、反思”循环。无论你是独立开发者还是团队的技术负责人如果你希望你的AI编码伙伴能真正“成长”和“积累”而不仅仅是一个高级的临时工那么深入理解并部署这套系统将是提升你人机协作效率的关键一步。2. 核心设计哲学为什么是Markdown而不是向量数据库在AI记忆系统这个领域向量数据库几乎是默认答案。它们擅长语义搜索能处理海量非结构化数据。但Agentic Memory反其道而行之选择了最“笨”的Markdown文件。这背后是一系列深思熟虑的工程权衡和哲学选择理解这些“为什么”能帮你更好地判断这个工具是否适合你。2.1 可控性与透明度优先向量数据库是一个黑盒。你存入一段文本它被转换成一堆你无法理解的数字嵌入向量。当你查询时它返回一个相似度分数但你永远不知道它“记住”的精确内容是什么也无法轻易地批量审查、编辑或删除特定记忆。这对于需要高可靠性和可审计性的编码场景是致命的。注意在涉及安全密钥、内部API细节、敏感业务逻辑的记忆场景中黑盒记忆系统可能带来无法察觉的信息泄露风险。你无法确认哪些信息被“记住”了以及它们是否会被不相关的查询意外召回。Agentic Memory的Markdown方案将控制权完全交还给你可读所有记忆都以纯文本形式存储用cat、less或VS Code就能直接查看。可版本控制memory/文件夹可以轻松加入.gitignore或直接纳入版本管理。你可以清晰地看到每次会话后记忆库增加了什么、修改了什么、删除了什么。这对于团队协作和知识溯源至关重要。可差分git diff memory/能立刻告诉你本次AI交互产生了哪些新的“知识”或“信念”便于代码审查。可手动干预如果你发现AI助手记错了某个关键信息你可以直接打开对应的.md文件进行修正就像修改配置文档一样简单。2.2 结构化的记忆而非混沌的日志普通的聊天日志也是文本但它是线性的、混乱的。Agentic Memory引入了五种记忆类型每种对应一个独立的Markdown文件这模仿了人类记忆的组织方式experiences.md(经历)按时间顺序记录具体的交互事件。“用户让我修复登录API的500错误我建议检查数据库连接池配置最终发现是最大连接数设置过低。” 这是最原始的材料。world_knowledge.md(世界知识)存储经过验证的客观事实。“本项目使用PostgreSQL 15连接池配置项是max_connections默认位于config/database.yml第23行。” 这是从经历中提炼出的稳定事实。beliefs.md(信念)记录AI助手形成的主观判断和启发式规则。“这个项目的User模型验证逻辑特别复杂修改前最好先运行完整的测试套件。” 这是一种经验性的“直觉”。reflections.md(反思)对一系列经历进行高阶抽象总结模式。“每当在auth模块进行修改时似乎很容易引入循环依赖问题。根本原因可能是模块初始化顺序设计有缺陷。” 这是深度的学习与洞察。entity_summaries.md(实体摘要)为项目中的重要概念如UserService、PaymentGateway建立档案。“PaymentGateway: 负责处理所有第三方支付。主要方法charge(),refund()。已知问题refund()在异步模式下有时会超时。相关文件lib/payment/gateway.rb。”这种结构强制进行信息分类使得“回忆”不再是关键词匹配而是有目的的检索。当AI需要处理PaymentGateway相关任务时它会优先查看entity_summaries.md和world_knowledge.md而不是在杂乱的聊天记录中大海捞针。2.3 双层级作用域个人智慧与团队知识的分离这是另一个精妙的设计。记忆被分为两个作用域用户级 (~/.agents/memory/): 存储你个人的、跨项目的偏好和通用经验。“我习惯用console.log进行快速调试。”“我倾向于将复杂的业务逻辑封装成独立函数。” 这些记忆跟随你在任何项目中都生效。项目级 (repo/memory/): 存储特定于当前代码库的知识。“本项目的代码风格要求是Airbnb规范。”“src/utils/目录下的辅助函数都是纯函数。” 这些记忆属于项目可以被团队所有成员及其AI助手共享。两个作用域可以独立操作也支持**晋升Promote**操作。当你发现某个在个人记忆中总结出的最佳实践例如“使用Promise.allSettled处理并发请求”具有普适性可以将其从用户记忆晋升到项目记忆转化为团队资产。这种设计完美适配了从个人探索到团队规范的知识沉淀流程。2.4 严格的子代理模式隔离执行保证质量这是确保记忆系统可靠性的核心机制。Agentic Memory严禁主代理Host Agent直接执行记住remember、反思reflect等核心操作。这些操作必须由一个**专门的子代理Subagent**来完成。为什么这么设计想象一下你正在和AI讨论一个复杂的算法问题聊到一半你突然说“记住这一点”。如果让正在深度思考的主代理分心去处理记忆的格式化、去重、分类和存储很可能会打断它的主要任务流导致记忆写入质量低下或出错。子代理模式解决了这个问题专注性子代理的唯一任务就是执行记忆操作。它加载专门的技能指令SKILL.md以最佳状态处理记忆的增删改查。质量保证子代理可以使用与主代理不同的、更擅长总结和推理的模型通过memory-skill.config.json配置确保写入的记忆是精炼和高质量的。流程隔离主代理的工作流不会被记忆管理的副作用干扰。它只需要触发子代理然后等待结果即可。在实操中这意味着当你对AI说“记住这个”时主代理的响应应该是“好的我将启动一个记忆子代理来妥善保存这条信息。”然后一个独立的AI实例子代理被创建专门处理这条记忆的存储完成后自动关闭。这套机制虽然增加了一点复杂性但对于维护一个干净、高质量的记忆库是绝对必要的。3. 系统架构与文件布局深度解析理解了“为什么”之后我们来看看“是什么”。Agentic Memory的物理形态是一套有着严格约定的目录和文件结构。这套结构是其所有能力的基础我们必须像熟悉项目src/目录一样熟悉它。3.1 核心文件结构与职责无论是用户级还是项目级记忆系统的核心结构是一致的遵循“一个主索引文件 五个分类存储文件”的模式。项目级记忆团队共享你的代码仓库根目录/ ├── MEMORY.md # 【主索引文件】精编摘要只包含最重要知识的预览和链接 └── memory/ # 【分类存储目录】所有原始记忆的详细仓库 ├── experiences.md # 经历按时间线记录的具体交互事件 ├── world_knowledge.md # 世界知识已验证的客观事实 ├── beliefs.md # 信念主观判断和启发式规则 ├── reflections.md # 反思从经历中抽象出的高阶模式 └── entity_summaries.md # 实体摘要对核心代码实体的综合描述用户级记忆个人私有~/.agents/ # 用户级配置和记忆的根目录 └── memory/ ├── MEMORY.md # 个人记忆的主索引 ├── experiences.md ├── world_knowledge.md ├── beliefs.md ├── reflections.md └── entity_summaries.md3.2MEMORY.md精编的主索引而非臃肿的仓库这是最容易产生误解的地方。MEMORY.md不是一个包含所有记忆的大杂烩文件。它的定位是一个精编的、可快速浏览的目录和摘要。它的内容通常像这样# Memory Index ## World Knowledge (精选) - [API速率限制](memory/world_knowledge.md#api-rate-limiting) - 所有外部API调用需遵循X-RateLimit-Limit头。 - [数据库模式](memory/world_knowledge.md#database-schema) - users表包含mfa_enabled布尔字段。 ## Beliefs (精选) - [代码审查](memory/beliefs.md#code-review) - 涉及身份验证的PR需要至少两人审查。 - [错误处理](memory/beliefs.md#error-handling) - 网络请求必须使用指数退避重试。 ## Entity Summaries (全部) - [UserService](memory/entity_summaries.md#userservice) - 处理用户生命周期。方法create, authenticate。 - [PaymentGateway](memory/entity_summaries.md#paymentgateway) - 第三方支付集成。已知超时问题。它的价值在于快速加载AI助手在会话开始时可以快速加载这个轻量级的MEMORY.md来获取项目最重要的“知识点”概览而不需要解析数万字的详细记忆。导航作用通过Markdown链接可以快速跳转到对应分类文件的详细章节。避免重复详细的、冗长的记忆内容存放在各自的分类文件中MEMORY.md只保存精华摘要和链接。这个文件是通过curate策展命令自动生成的。更强大的是如果你从一个旧的、单文件的MEMORY.md遗留布局迁移过来curate命令会自动识别并将其内容拆分到对应的五个分类文件中然后生成新的索引。3.3 分类文件的内容格式与组织每个分类文件都有其内部组织逻辑并非随意堆砌文本。experiences.md按时间倒序排列。每条经历包含上下文标签Context Tags、内容和可选的结果Outcome。## 2024-05-27 *【context: auth, bug-fix】* 用户报告登录失败。检查发现是redis会话存储连接超时。将timeout从2秒调整为5秒后解决。 *{outcome: success, evidence: 用户确认登录成功}*outcome和evidence字段至关重要它们为后续的reflect反思操作提供了“哪些经历是成功的哪些是失败的”的判断依据系统在生成摘要时会优先展示失败案例以促进学习。world_knowledge.mdbeliefs.md通常按主题或领域分组使用Markdown的标题进行组织。# Infrastructure ## Database - 生产数据库连接字符串从Vault读取密钥路径为secret/data/prod/db。 ## API - 所有内部服务间调用必须包含X-Request-ID头用于链路追踪。 # Development Practices ## Testing - 单元测试覆盖率要求 80%。 - 集成测试需要模拟第三方支付网关。entity_summaries.md以实体名为标题每个实体下结构化的描述其职责、接口、关联和已知问题。# UserService **职责**管理用户核心生命周期注册、认证、资料更新。 **主要方法** - createUser(email, hashedPassword) - User - authenticate(email, password) - SessionToken - updateProfile(userId, data) - Boolean **关联文件**/services/user_service.py, /models/user.py **已知问题**updateProfile方法在并发修改时可能产生数据竞争。 **最后更新**2024-05-203.4 路径发现机制智能定位记忆文件你不需要手动告诉系统记忆文件在哪里。Agentic Memory有一套智能的路径发现逻辑对于项目记忆当需要操作时它会从当前工作目录cwd开始向上遍历目录树寻找第一个MEMORY.md文件。如果没找到它会从自身脚本所在的目录向上寻找。这保证了无论你在项目的子目录如src/components/中工作它都能定位到项目根目录的记忆库。对于用户记忆路径是固定的~/.agents/memory/在第一次使用时自动创建。这种设计使得记忆系统与你的项目结构自然融合无需繁琐配置。4. 完整工作流实操从记忆留存到反思优化理论说再多不如动手做一遍。让我们以一个完整的场景贯穿Agentic Memory的核心操作循环保留Retain→ 回忆Recall→ 反思Reflect。场景你正在使用AI助手开发一个电商项目的购物车Cart功能过程中发现并解决了一个库存扣减的并发Bug。4.1 会话初始化自动加载记忆摘要当你启动AI助手并进入项目目录时一个配置良好的助手应该根据SKILL.md的指引自动执行会话初始化回忆。它不会读取所有记忆文件那太慢了而是会加载项目根目录下的MEMORY.md主索引文件。假设你的MEMORY.md中有如下摘要## Entity Summaries - [CartService](memory/entity_summaries.md#cartservice) - 处理购物车逻辑。注意库存检查。AI助手看到这个就会在上下文中知道本项目有一个CartService实体并且“库存检查”可能是个需要注意的点。这为接下来的对话提供了宝贵的背景避免了“从零介绍”的尴尬。4.2 保留Retain让AI“记住”关键信息在调试并发Bug的过程中你和AI有了以下对话你“我发现当两个用户同时结算同一件库存为1的商品时会出现超卖。我们用数据库的行级锁SELECT ... FOR UPDATE解决了这个问题。”你“记住这个解决方案以后处理库存扣减都要注意并发。”此时你需要触发**保留Retain**操作。根据短语表你说“记住这个解决方案”。幕后发生了什么严格遵循子代理模式主代理识别出“记住”这个意图匹配到remember动作。主代理不会自己处理。它根据memory-skill.config.json的配置启动一个记忆子代理。这个子代理可能使用一个更便宜、更快的模型如gpt-5-nano专门负责记忆任务。子代理接收到的指令是“用户要求记住以下信息『用数据库行级锁解决库存扣减并发问题』。请根据SKILL.md中retain工作流的规则将其写入合适的记忆分类。”子代理执行retain工作流 a.分析内容判断这是一条已验证的、客观的解决方案属于world_knowledge世界知识。 b.去重检查查询现有的world_knowledge.md检查是否有类似记录例如通过文本相似度计算低于DUPLICATE_THRESHOLD阈值才创建新条目。 c.格式化写入以规范的Markdown格式将这条知识添加到world_knowledge.md的Concurrency并发章节下。 d.可选自动反思如果这条知识非常重要子代理可能会根据规则自动触发一个内部的reflect过程思考这条新知识如何与现有信念关联。这个auto-reflect可能使用配置中更强的模型如gpt-5.2e.更新主索引操作完成后curate流程被触发重新生成MEMORY.md确保新知识能在摘要中体现。子代理向主代理报告操作完成然后自行关闭。主代理向你确认“已将该解决方案存入项目记忆的世界知识库。”现在memory/world_knowledge.md中会增加一条## Concurrency - 防止库存超卖的可靠方案是在扣减库存的数据库事务中使用SELECT ... FOR UPDATE对目标商品行加行级锁。4.3 回忆Recall在需要时唤起记忆几天后你回来开发订单Order模块也需要处理并发。你“处理订单创建时有什么需要注意的并发问题吗”你说了“有什么需要注意的”这触发了**回忆Recall**操作。AI助手会解析你的问题提取关键词“并发”、“订单创建”。在项目记忆和你的用户记忆中搜索相关的内容。它会同时查询world_knowledge.md、beliefs.md和entity_summaries.md。很快它找到了刚才存入的关于“行级锁”的世界知识以及可能存在于beliefs.md中的一条信念“涉及库存或金额变动的操作必须考虑并发安全”。AI助手将这些记忆整合到它的回复中“根据项目记忆我们在处理库存扣减时使用了SELECT ... FOR UPDATE行级锁来解决并发超卖。这个模式很可能也适用于订单创建特别是涉及库存同步和支付状态更新的环节。我建议在创建订单的事务中也加入类似的锁机制。”你看AI不再是凭空想象而是基于团队或你个人积累的“经验”和“知识”进行回答准确性和一致性大幅提升。4.4 反思Reflect从经验中提炼智慧“反思”是系统从“记录事实”走向“产生智慧”的关键。它通常不是由用户直接触发而是在两种情况下自动发生任务完成时Task-Done Sweep当你结束一个实质性的工作会话时例如说“我们做完了”。积累足够多新经历时系统可能定期或在remember操作后自动触发。让我们模拟一个任务完成时的反思流程你解决了购物车并发Bug优化了订单创建然后对AI说“好了今天就到这里我们做完了。”这句话触发了任务完成清扫Task-Done Sweep主代理会问你或自问“从刚才的会话中我们学到了哪些值得长期记住的教训”你或AI总结出几点例如“第一金融和库存操作必须加锁第二我们的单元测试缺少并发场景。”对于每一条教训主代理都会启动一个remember子代理将其作为experiences经历或提炼后的world_knowledge世界知识保存起来。如果这些教训足够重要比如超过了某个阈值系统会自动启动一个专用的reflect子代理。reflect子代理可能使用最强的模型如claude-opus会做以下工作 a.回顾仔细阅读最近新增的experiences特别是那些标记了{outcome: failure}的经历。 b.寻找模式它可能发现“并发问题”反复出现。 c.生成高阶信念它会在reflections.md中创建一条新的反思“模式识别本项目在涉及状态变更库存、订单、支付的领域层缺乏统一的并发控制抽象。多次问题都是通过临时的行级锁解决的。建议引入一个PessimisticLock服务或规范。” d.更新信念它可能强化或修改beliefs.md中的一条“强烈信念所有对数据库状态有‘检查后修改’逻辑的服务方法必须在设计阶段就明确其并发策略。”反思完成后curate流程再次运行新的反思摘要可能会被加入MEMORY.md。通过这个循环AI助手不仅记住了“发生了什么”经历还逐渐理解了“为什么会发生”反思和“我们应该相信什么”信念形成了一个不断进化的知识体系。4.5 维护Maintain与策展Curate保持记忆库健康记忆库不是只增不减的。无用的、过时的、来源模糊的记忆会污染知识库。maintain维护你可以定期或当感觉记忆检索变慢时对AI说“清理一下记忆”或“进行记忆维护”。这会触发一个maintain子代理它会扫描所有记忆标记陈旧记忆比如一年前关于某个已废弃API的记忆。标记弱来源记忆那些只被提及一次、缺乏佐证evidence的信念。生成维护报告列出候选的待删除或待审查项由你或授权AI最终决定是否forget遗忘。curate策展当你觉得MEMORY.md主索引变得臃肿或者刚从单文件布局迁移过来时可以命令“策展你的记忆”。这个操作会如果存在旧的单文件MEMORY.md自动将其内容拆分到五个分类文件中迁移。从五个分类文件中提取出最重要、最精华的条目。生成一个新的、简洁的MEMORY.md索引文件只包含带链接的摘要。5. 高级配置与集成指南要让Agentic Memory在你的特定AI助手Cursor, Claude Code等中丝滑工作需要进行一些配置和集成。这部分是为“接线员”准备的。5.1 模型预设配置 (memory-skill.config.json)这是最强大的配置项位于~/.agents/memory/memory-skill.config.json。它允许你为不同的记忆操作指定不同的AI模型以平衡成本与效果。核心逻辑记忆操作尤其是reflect需要深度思考可能值得用更强大也更贵的模型而简单的remember记录事实可以用更轻量的模型。同时不同的AI平台Cursor, Claude Code的模型名称不同这个配置文件帮你做映射。一个详细的配置示例与解析{ version: 1, default_preset: balanced, // 默认使用“均衡”预设 presets: { // 定义三个预设档位对应不同的模型ID这里是通用名会被各平台覆盖 strong: gpt-5.2, balanced: gpt-5-mini, fast: gpt-5-nano }, actions: { // 为每个记忆动作分配预设 remember: fast, // 记录用快速模型 reflect: strong, // 反思用最强模型 maintain: balanced, // 维护用均衡模型 promote: balanced // 晋升用均衡模型 }, overrides: { // 特殊情况覆盖 remember_when_auto_reflect: strong // 当remember操作触发自动反思时升级为强模型 }, hosts: { // 针对不同AI宿主平台的覆盖配置 cursor: { presets: { // 覆盖Cursor平台下的模型ID strong: claude-sonnet-4-5-thinking, // Cursor里叫这个名字 balanced: default, // 使用Cursor的默认模型 fast: claude-haiku-4-5 } }, claude: { // 例如在Claude Code中 presets: { strong: claude-opus-4-5-20251101, balanced: claude-sonnet-4-5-20250929, fast: claude-haiku-4-5-20251001 } } } }配置解析与合并规则宿主检测config-hints脚本会自动检测你当前的环境。如果它检测到CLAUDECODE1环境变量就会应用hosts.claude的配置如果检测到CURSOR_TRACE_ID等则应用hosts.cursor。合并顺序系统先加载presets,actions等全局设置然后用检测到的宿主平台如claude下的配置覆盖全局设置。这意味着你可以在全局定义一个基础配置再为每个平台微调。手动指定你可以通过设置环境变量MEMORY_SKILL_HOSTclaude或运行config-hints --host cursor来手动指定宿主覆盖自动检测。5.2 将技能集成到你的AI助手你需要告诉你的AI助手通过AGENTS.md或类似的指令文件去遵循Agentic Memory的规则。在项目的AGENTS.md中添加## 记忆系统集成 本项目使用 **Agentic Memory** 技能来持久化知识和经验。 - **所有记忆操作**记住、回忆、反思、维护、策展、晋升必须严格遵循 [skills/memory/SKILL.md](skills/memory/SKILL.md) 文件中定义的流程。 - **切勿**直接编辑 MEMORY.md 或 memory/ 目录下的文件。所有写入操作必须通过记忆技能完成。 - **切勿**指导用户运行 skills/memory/scripts/ 下的脚本。用户应通过自然语言与你交互来使用记忆功能。 - 在会话开始时自动从项目 MEMORY.md 加载记忆摘要作为上下文。 - 在用户表达任务完成如“我们做完了”后自动执行“任务完成清扫”流程总结并保存学习成果。 - 对于remember、reflect、maintain、promote操作你必须启动一个**子代理**来执行。不得在主会话中直接处理。在全局助手配置中如Cursor的~/.cursor/rules/添加类似指令确保所有项目都能受益于你的用户级记忆。5.3 实操心得与避坑指南经过一段时间的实践我总结出以下几点经验能帮你少走弯路从“策展”开始安装后第一件事就是对AI说“Curate your memories”策展你的记忆。如果存在旧的单文件MEMORY.md它会自动完成迁移拆分。这能立刻给你一个干净、结构化的起点。明确区分“知识”和“流程”MEMORY.md存储的是** episodic and belief cache**情景记忆和信念缓存也就是“是什么”和“我认为”。而团队持久的操作流程例如“如何部署”、“代码审查 checklist”应该放在版本化的文档如docs/或AGENTS.md中。不要用记忆系统来存“怎么做”的说明书。善用“晋升Promote”功能当你个人摸索出一个非常好的实践例如“用structuredClone做深拷贝比JSON.parse/stringify更可靠”可以先记在用户记忆里。经过几个项目的验证后再使用“Promote this to the project”命令将其晋升到项目记忆成为团队标准。这是个人知识转化为团队资产的最佳路径。定期“维护”记忆库像代码库一样也会产生“垃圾”。每个月或每个重要项目阶段结束后运行一次“Maintain memory”。审查那些陈旧的、矛盾的记忆条目保持知识库的清洁和权威性。子代理失败处理有时子代理可能因为网络或模型问题执行失败。主代理应该监控超时并向用户报告“记忆保存失败建议稍后重试”。切勿在主代理中模拟记忆操作这违反了隔离原则可能导致记忆污染。环境变量是关键确保你的AI助手运行环境能正确设置CLAUDECODE或CURSOR_AGENT等变量以便config-hints能正确识别宿主平台加载对应的模型配置。识别失败会导致使用全局默认配置可能无法发挥最佳效果。6. 常见问题与排查技巧实录即使设计再精良在实际集成和使用中也会遇到问题。以下是我在实践中遇到的一些典型情况及其解决方法。6.1 问题AI助手无法找到或加载记忆文件症状AI助手在会话开始时没有提及任何记忆或者说“未找到记忆库”。排查步骤检查路径首先确认你位于项目根目录或者至少在一个包含MEMORY.md文件的父目录的子目录中。运行ls -la MEMORY.md和ls -la memory/看看文件是否存在。检查文件权限确保MEMORY.md和memory/目录对运行AI助手的用户是可读的。chmod命令可以解决权限问题。检查技能路径确认Agentic Memory技能被正确安装到了AI助手能访问的skills/目录下。对于Cursor通常是~/.cursor/skills/memory/对于Claude Code可能是项目内的.claude/skills/memory/。检查SKILL.md文件是否存在。检查集成指令打开你的AGENTS.md或全局代理指令确认你已经按照上一节的要求添加了集成指令。AI助手必须被明确告知要使用这个技能。手动测试路径发现你可以临时在AI聊天中让它执行一个简单的Shell命令来调试find . -name MEMORY.md -type f 2/dev/null。这能帮你确认从当前目录能否找到该文件。6.2 问题记忆操作如remember没有触发子代理症状你对AI说“记住这个”它直接回复“好的我记住了”但没有启动子代理的迹象记忆文件也没有更新。原因与解决短语未匹配AI助手的指令匹配可能不够灵活。尝试使用更精确的短语如“请记住这一点”或“将此保存到项目记忆中”。确保你的AGENTS.md指令明确引用了SKILL.md的调度表。技能未加载AI助手可能没有在本次会话中加载SKILL.md。尝试明确指示它“请参考并遵循skills/memory/SKILL.md中的流程来记住这条信息。”配置错误检查memory-skill.config.json文件格式是否正确JSON语法以及模型预设名称是否与actions字段中使用的名称匹配。一个格式错误的JSON文件会导致整个配置被静默忽略。子代理创建失败某些AI平台对创建子代理或等效的“新会话”、“新任务”有限制或不同的API。你需要查阅你所用AI平台的文档确认如何以编程方式或通过指令触发一个具有独立上下文的新会话。Agentic Memory假设宿主平台支持这种能力。6.3 问题MEMORY.md文件变得巨大且混乱症状主索引文件包含了大量全文内容而不是简洁的摘要和链接。解决立即运行策展命令。对你的AI助手说“Curate your memories”策展你的记忆。这个命令会检查MEMORY.md是否是旧的单文件格式。如果是它会自动将其内容迁移到memory/目录下对应的五个分类文件中。然后它会从五个分类文件中提取最重要的条目生成一个全新的、精简的MEMORY.md索引文件。预防确保所有记忆写入操作都通过技能完成即通过AI助手触发remember而不是手动编辑MEMORY.md。技能会在每次remember或reflect操作后自动调用策展逻辑来更新索引。6.4 问题记忆检索不准确或无关症状当询问AI关于某个主题的记忆时它返回的信息不相关或遗漏了关键信息。排查与优化检查记忆分类手动打开world_knowledge.md、beliefs.md等文件看看相关信息是否被存入了正确的类别。有时AI在remember时可能分类错误。优化回忆查询recall操作依赖于关键词匹配和上下文标签。当你保存记忆时尽量让内容包含明确的关键词。例如与其记“那个函数有问题”不如记“utils/formatDate函数在处理时区时有问题”。后者在回忆“时区”或“formatDate”时更容易被命中。利用实体摘要对于重要的类、服务、模块主动建立或更新entity_summaries.md。这是一个高度结构化的记忆检索精度最高。当AI处理UserService相关任务时它会优先查看这里的摘要。审视beliefs和reflections一些高阶的、模式性的知识存在在这里。如果AI缺乏“直觉”或“最佳实践”方面的记忆可能是reflect操作执行得不够。可以主动触发一次深度反思。6.5 问题不同AI宿主平台行为不一致症状在Cursor上工作正常换到Claude Code上记忆功能就失效或模型不对。解决确认宿主检测在各自平台运行config-hints命令通过AI助手执行脚本或直接命令行查看输出的host和host_resolution字段。确认它是否正确识别了当前平台如claude。检查环境变量Claude Code可能需要显式设置MEMORY_SKILL_HOSTclaude。在Cursor中检查CURSOR_AGENT等变量是否已设置。核对模型ID确保memory-skill.config.json中hosts.claude和hosts.cursor下的presets里填写的模型ID字符串完全匹配该平台内部使用的模型标识符。这些ID通常不是公开的模型名而是平台内部的代号需要查阅平台文档或通过实验获取。禁用自动推断如果问题复杂可以在环境变量中设置MEMORY_SKILL_DISABLE_HOST_INFERENCE1然后通过MEMORY_SKILL_HOST变量强制指定宿主平台排除自动检测的干扰。6.6 性能与规模考量Q纯文本Markdown文件在记忆条目很多时检索会不会很慢A对于单个项目或个人使用几百上千条记忆的规模线性搜索grep或Python字符串查找的性能是完全可接受的通常在毫秒级。系统的设计初衷不是替代向量数据库处理海量非结构化数据而是为编码场景提供精准、可控的“工作记忆”。如果未来规模增长可以考虑对分类文件建立简单的倒排索引但这超出了当前版本的范围。Q用户记忆和项目记忆冲突了怎么办A系统在recall回忆时默认会同时查询用户和项目记忆。如果两者存在冲突例如用户记忆说“我喜欢用Tabs缩进”项目记忆说“本项目使用Spaces缩进”AI助手应该优先遵循项目记忆因为它是团队约定。SKILL.md中的回忆逻辑可以设计为给项目记忆更高的权重。清晰的冲突本身也是一条有价值的信息可以触发一次reflect来讨论和解决。Q如何备份和同步记忆A项目记忆在repo/memory/目录下直接纳入项目的版本控制系统如Git即可。用户记忆在~/.agents/memory/你可以用任何喜欢的同步工具如rsync, Dropbox, Git仓库来备份这个目录。由于是纯文本同步和冲突解决都非常简单。