Memory System V2

核心用法

Memory System v2.0 是一款纯 Bash 实现的文件型语义记忆系统，专为 AI Agent 跨会话记忆需求设计。通过 memory-cli.sh 命令行工具，用户可以捕获五种记忆类型（learning/decision/insight/event/interaction），每条记忆包含 1-10 重要性评分、标签和上下文信息。数据以 Markdown 日志形式存储，JSON 索引实现亚 20 毫秒级搜索。

典型工作流：
1. 捕获记忆：capture --type learning --importance 9 --content "..." --tags "swift,ios"
2. 语义搜索：search "swiftui" --min-importance 8
3. 周期回顾：consolidate 自动生成周汇总

显著优点

• 极致性能：36 项测试验证，搜索平均 <20ms（最快 8ms），捕获 <50ms
• 零依赖架构：仅需 bash + jq，无需数据库或网络服务
• 结构化分类：五类记忆类型 + 重要性权重 + 标签系统，召回精准度高
• 自动聚合：日常记忆自动合并为周度摘要，降低信息过载
• Clawdbot 原生集成：设计为 AI Agent 的持久记忆层，开箱即用

潜在局限

• 纯文本搜索：无向量嵌入，依赖关键词匹配，语义理解有限
• 单用户设计：无多租户隔离，协作场景需额外封装
• 扩展瓶颈：官方标称 ~10K 条记忆后性能下降，大数据量需归档策略
• 平台依赖：Bash/jq 绑定，Windows 原生支持受限

适合人群

• AI Agent 开发者需为 Agent 构建持久记忆能力
• 个人知识管理用户偏好本地化、低维护方案
• 快速原型团队需要轻量级决策追踪与复盘工具

常规风险

• 数据丢失：文件型存储无内置备份机制，需用户自行版本控制
• 并发冲突：多进程同时写入可能导致索引损坏
• 隐私暴露：上下文字段可能意外记录敏感信息，需定期审计
• 锁定效应：长期积累后迁移至其他系统成本较高

核心用法

Memory System v2 是一款轻量级、纯文件架构的语义记忆系统，专为 AI 代理设计。基于 bash + jq 实现，零外部依赖，无需数据库即可在本地构建可搜索的知识库。

主要功能模块：

1. 记忆捕获 (capture)：支持5种记忆类型——学习(learning)、决策(decision)、洞见(insight)、事件(event)、交互(interaction)，按1-10重要性评分，可附加标签与上下文

2. 智能检索 (search)：多关键词联合搜索，支持重要性阈值过滤，平均响应<20ms

3. 时间维度查询 (recent)：按类型、天数、最小重要性筛选近期记忆

4. 自动整合 (consolidate)：按周自动生成摘要，实现记忆层级压缩

5. 统计分析 (stats)：展示记忆分布、类型占比、重要性分布等维度数据

文件架构：

~/clawd/memory/
├── memory-cli.sh      # 主程序
├── index/memory-index.json  # JSON索引（快速检索）
├── daily/YYYY-MM-DD.md      # 每日原始日志
└── consolidated/YYYY-WW.md  # 周度整合摘要

性能实测（247条记忆/M1 Mac）：

• 搜索：8-18ms（平均<20ms ✅）
• 捕获：<50ms
• 统计：<10ms

---

显著优点

1. 极致速度：JSON索引 + 本地文件，避免数据库开销，搜索性能远超基于文本grep的方案

2. 零运维成本：纯bash/jq实现，无服务依赖，无需配置数据库或Docker

3. 语义分类科学：5种记忆类型覆盖知识管理全场景，重要性评分实现信息分层

4. AI原生设计：专为AI代理跨会话记忆设计，上下文字段记录"当时正在做什么"，召回时还原场景

5. 完全离线：数据仅本地存储，符合隐私敏感场景需求

6. 测试完备：36项测试覆盖全部核心功能，质量可信

---

潜在缺点与局限性

1. 无语义嵌入：当前为关键词匹配，不支持向量相似度搜索，同义词召回能力有限

2. 单机单用户：无多用户隔离机制，团队协作场景不适用

3. 规模天花板：作者建议~10K条记忆前性能稳定，超量后需考虑迁移或分片

4. 输入验证薄弱：捕获命令对用户输入长度、特殊字符缺乏限制，极端输入可能影响数据完整性

5. JSON构造方式：使用heredoc字符串插值构造JSON，存在理论注入风险（虽实际影响有限）

6. 无自动备份：依赖用户自行管理~/clawd/memory目录的备份策略

---

适合人群

• AI代理开发者：为LLM工具链添加跨会话记忆能力
• 个人知识管理用户：追踪学习路径、决策理由、项目里程碑
• 隐私优先用户：拒绝云服务，要求数据完全本地可控
• 轻量工具爱好者：厌倦重型Notion/Obsidian复杂功能，追求Unix哲学极简方案

不适合：

• 需要团队协作的多人场景
• 超大规模数据（>10万条记忆）
• 需要向量语义搜索的复杂召回需求

---

常规风险

| 风险类别 | 具体描述 | 缓解措施 |

|---------|---------|---------|

| 数据丢失 | 纯本地文件，无自动云同步 | 定期备份`~/clawd/memory`目录 |

| 注入风险 | JSON构造使用字符串插值 | 避免在content/tags中输入未转义引号 |

| 文件膨胀 | 日志文件无限增长 | 手动清理或实现日志轮转 |

| jq兼容性 | 依赖jq版本未明确 | 建议jq 1.6+，安装后验证功能 |

| 权限误设 | 目录权限问题导致读写失败 | 确保运行用户对`~/clawd`有写权限 |

总体评估：低风险、高实用性的本地工具，安全认证等级S，适合生产环境个人使用。