Memory

核心用法

Memory 技能采用分层索引架构解决 AI 代理记忆持久化难题。核心工作流遵循三步检索：先查 MEMORY.md（热数据，<500 行），再查 INDEX.md 索引定位类别，最后加载具体文件。所有信息按层级组织——workspace/MEMORY.md 为热缓存，memory/INDEX.md 为根索引，下设 projects/、people/、decisions/、lessons/、logs/、archive/ 六大分类，每类独立索引与详情文件。

写入时强制遵循 WAL（Write-Ahead Log）协议：先更新详情文件，再更新索引，最后响应用户，避免记忆丢失。每月汇总 decisions 和 logs 为单文件，3 个月未访问内容自动归档，确保系统长期运行不膨胀。

显著优点

• 无限扩展性：分层索引使检索复杂度为 O(log n)，1000 个项目仅需 3 次文件读取
• 即时响应：索引文件严格限制 <100 行，MEMORY.md <500 行，始终快速加载
• 数据可控：所有文件本地存储，可选 OpenAI 语义搜索需用户显式配置 API key
• 防遗忘设计：WAL 协议强制先写后响应，关键决策和上下文零丢失

潜在局限

• 维护成本：需定期执行索引健康检查（周）、归档汇总（月）、全量审计（季），自动化程度有限
• 迁移复杂：分层结构对新手有学习曲线，扁平化习惯易导致"文件爆炸"陷阱
• 语义搜索依赖外部：高级搜索需 OpenAI API，存在隐私和成本考量
• 无冲突解决：多人协作场景下文件级并发修改未提及处理机制

适合人群

• 长期项目代理需跨周/月保持上下文
• 高频决策场景需可追溯记录
• 多项目并行管理，需快速切换上下文的用户
• 对数据本地化和可审计性有要求的场景

常规风险

• 索引过时：文件已更新但索引未同步，导致检索失败或信息缺失
• 层级过深：过度拆分导致导航繁琐，建议单层索引 <100 条目
• 归档丢失：自动归档后 3 个月内容移至 archive/，高频回溯需求用户需调整策略
• 敏感数据泄露：虽本地存储，但 MEMORY.md 作为热加载文件可能包含高敏感信息，需额外访问控制

核心用法

Memory 是一套面向 AI Agent 的纯文档型持久化记忆框架，通过严格的层级索引架构实现跨会话的上下文管理。其核心工作流程基于 WAL（Write-Ahead Log）协议：在响应用户前，先将关键信息写入结构化文件系统。存储架构采用三级检索机制：

1. HOT 层（MEMORY.md）：始终加载的活跃上下文（<500行）
2. INDEX 层：各类别的索引文件（memory/*/INDEX.md），仅包含名称、摘要、文件指针
3. DETAIL 层：具体的事实文件，按需加载

用户通过文件系统工具操作：Agent 使用 Write/Edit 命令更新记忆，通过层级导航（ROOT INDEX → 分类 INDEX → 具体文件）实现 O(log n) 检索复杂度，而非线性扫描。

显著优点

• 无限扩展性：层级索引设计理论上支持数万条事实，检索性能不随数据量下降。官方示例展示 1000 项目、10 年决策记录仍保持 3 次文件读取即可定位目标
• 零依赖核心功能：纯 Markdown 文档架构，无需数据库、无需运行时，仅需文件系统操作
• Agent 原生设计：专门针对 LLM Agent 的上下文窗口限制优化，通过索引优先策略避免 token 浪费
• 完整的生命周期管理：内置归档策略（3个月未访问自动归档）、月度汇总、索引健康检查等运维机制
• 可选语义增强：通过 OpenAI 嵌入实现语义搜索，但完全可选，禁用不影响核心功能

潜在局限与缺点

• 纯文档的摩擦成本：依赖 Agent 正确执行文件操作，若 Agent 未严格遵循 WAL 协议，可能出现"响应已给出但记忆未更新"的失步问题
• 无内置一致性保障：缺乏事务机制，并发写入或异常中断可能导致索引与详情文件不一致
• 维护 overhead：需要定期执行健康检查、索引拆分、归档清理等操作，长期使用的自动化程度不足
• 语义搜索的隐私权衡：启用 OpenAI 嵌入时，记忆内容需传输至外部 API，虽有 TLS 加密，但存在数据出境考量

适合人群

• 长期项目协作者：需要 Agent 持续跟踪多阶段项目状态、技术决策、人员信息的开发者
• 高频对话用户：期望 Agent 记住偏好、习惯、历史上下文的重度使用者
• 隐私敏感型组织：要求数据完全本地化、可审计、无黑箱存储的企业环境

常规风险

• 数据丢失风险：本地文件系统无自动备份，用户需自行配置版本控制或备份策略
• Agent 行为依赖：记忆质量完全取决于 Agent 是否正确执行写入协议，存在"忘记更新"的人为（或模型）失误风险
• 可选功能的配置陷阱：误配置 OPENAI_API_KEY 可能导致意外数据外流，需明确环境变量管理