memory-system-v2

记忆系统 v2.0

为 AI Agent 提供快速语义记忆，使用 JSON 索引，搜索时间低于 20 毫秒。

概览

记忆系统 v2.0 是一款轻量级、基于文件的记忆系统，专为需要以下功能的 AI Agent 设计：

• 跨会话记住学到的知识、决策、见解、事件和交互
• 在 <20ms 内语义搜索记忆
• 自动将每日记忆整合为每周摘要
• 跟踪重要性和上下文，以便更好地回忆

使用纯 bash + jq 构建，无需数据库。

功能

• ⚡ 快速搜索： 平均搜索时间 <20ms（通过 36 项测试）
• 🧠 语义记忆： 捕捉 5 种记忆（学习、决策、见解、事件、交互）
• 📊 重要性评分： 使用 1-10 分制为记忆排序
• 🏷️ 标签系统： 使用标签整理记忆
• 📝 上下文跟踪： 记住创建记忆时正在进行的工作
• 📅 自动整合： 自动生成每周摘要
• 🔍 智能搜索： 支持多词搜索，并按重要性加权
• 📈 统计与分析： 跟踪记忆数量、类型和重要性分布

快速开始

安装

# Install jq (required dependency)
brew install jq

# Copy memory-cli.sh to your workspace
# Already installed if you're using Clawdbot

基本用法

捕捉记忆：

./memory/memory-cli.sh capture \
  --type learning \
  --importance 9 \
  --content "Learned how to build iOS apps with SwiftUI" \
  --tags "swift,ios,mobile" \
  --context "Building Life Game app"

搜索记忆：

./memory/memory-cli.sh search "swiftui ios"
./memory/memory-cli.sh search "build app" --min-importance 7

最近的记忆：

./memory/memory-cli.sh recent learning 7 10
./memory/memory-cli.sh recent all 1 5

查看统计信息：

./memory/memory-cli.sh stats

自动整合：

./memory/memory-cli.sh consolidate

记忆类型

1. 学习（重要性：7-9）

你掌握的新技能、工具、模式和技巧。

示例：

./memory/memory-cli.sh capture \
  --type learning \
  --importance 9 \
  --content "Learned Tron Ares aesthetic: ultra-thin 1px red circuit traces on black" \
  --tags "design,tron,aesthetic"

2. 决策（重要性：6-9）

做出的选择、采用的策略和采取的方法。

示例：

./memory/memory-cli.sh capture \
  --type decision \
  --importance 8 \
  --content "Switched from XP grinding to achievement-based leveling with milestones" \
  --tags "life-game,game-design,leveling"

3. 见解（重要性：8-10）

突破、领悟和顿悟时刻。

示例：

./memory/memory-cli.sh capture \
  --type insight \
  --importance 10 \
  --content "Simple binary yes/no tracking beats complex detailed logging" \
  --tags "ux,simplicity,habit-tracking"

4. 事件（重要性：5-8）

里程碑、完成事项、发布和重大事件。

示例：

./memory/memory-cli.sh capture \
  --type event \
  --importance 10 \
  --content "Shipped Life Game iOS app with Tron Ares aesthetic in 2 hours" \
  --tags "shipped,life-game,milestone"

5. 交互（重要性：5-7）

与用户的关键对话、反馈和请求。

示例：

./memory/memory-cli.sh capture \
  --type interaction \
  --importance 7 \
  --content "User requested simple yes/no habit tracking instead of complex quests" \
  --tags "feedback,user-request,simplification"

架构

文件结构

memory/
├── memory-cli.sh              # Main CLI tool
├── index/
│   └── memory-index.json      # Fast search index
├── daily/
│   └── YYYY-MM-DD.md          # Daily memory logs
└── consolidated/
    └── YYYY-WW.md             # Weekly consolidated summaries

JSON 索引格式

{
  "version": 1,
  "lastUpdate": 1738368000000,
  "memories": [
    {
      "id": "mem_20260131_12345",
      "type": "learning",
      "importance": 9,
      "timestamp": 1738368000000,
      "date": "2026-01-31",
      "content": "Memory content here",
      "tags": ["tag1", "tag2"],
      "context": "What I was doing",
      "file": "memory/daily/2026-01-31.md",
      "line": 42
    }
  ]
}

性能基准

36 项测试全部通过：

• 搜索：平均 <20ms（最快：8ms，最慢：18ms）
• 捕捉：平均 <50ms
• 统计信息：<10ms
• 最近记录：<15ms
• 所有操作：目标 <100ms ✅

命令参考

capture

./memory-cli.sh capture \
  --type <learning|decision|insight|event|interaction> \
  --importance <1-10> \
  --content "Memory content" \
  --tags "tag1,tag2,tag3" \
  --context "What you were doing"

search

./memory-cli.sh search "keywords" [--min-importance N]

recent

./memory-cli.sh recent <type|all> <days> <min-importance>

stats

./memory-cli.sh stats

consolidate

./memory-cli.sh consolidate [--week YYYY-WW]

与 Clawdbot 集成

记忆系统 v2.0 专为与 Clawdbot 无缝协作而设计：

在 AGENTS.md 中自动捕捉：

## Memory Recall
Before answering anything about prior work, decisions, dates, people, preferences, or todos: run memory_search on MEMORY.md + memory/*.md

工作流示例：

1. Agent 学到新内容 → memory-cli.sh capture
2. 用户询问“我们昨天构建了什么？” → memory-cli.sh search "build yesterday"
3. Agent 准确回忆详情，并提供文件和行号引用

使用场景

1. 学习跟踪

捕捉每项新学会的技能、工具或技巧：

./memory-cli.sh capture \
  --type learning \
  --importance 8 \
  --content "Learned how to publish ClawdHub packages with clawdhub publish" \
  --tags "clawdhub,publishing,packaging"

2. 决策历史

记录做出特定选择的原因：

./memory-cli.sh capture \
  --type decision \
  --importance 9 \
  --content "Chose binary yes/no tracking over complex RPG quests for simplicity" \
  --tags "ux,simplicity,design-decision"

3. 里程碑跟踪

记录重要成就：

./memory-cli.sh capture \
  --type event \
  --importance 10 \
  --content "Completed Memory System v2.0: 36/36 tests passed, <20ms search" \
  --tags "milestone,memory-system,shipped"

4. 每周回顾

自动生成每周摘要：

./memory-cli.sh consolidate --week 2026-05

高级用法

按重要性筛选搜索结果

# Only high-importance learnings
./memory-cli.sh search "swiftui" --min-importance 8

# All memories mentioning "API"
./memory-cli.sh search "API" --min-importance 1

最近的重要决策

# Decisions from last 7 days with importance ≥ 8
./memory-cli.sh recent decision 7 8

批量分析

# See memory distribution
./memory-cli.sh stats

# Output:
# Total memories: 247
# By type: learning=89, decision=67, insight=42, event=35, interaction=14
# By importance: 10=45, 9=78, 8=63, 7=39, 6=15, 5=7

限制

• 仅支持文本搜索： 暂不支持语义嵌入
• 单用户： 不适用于多用户场景
• 基于文件： 约 10K 条记忆后性能会下降
• 依赖 Bash： 需要 bash + jq（适用于 macOS/Linux）

未来增强

• 使用语义嵌入提升搜索效果
• 使用 AI 自动添加标签
• 记忆图谱（记忆之间的关联）
• 导出到 Notion/Obsidian
• 支持多语言
• 云同步（可选）

测试

完整测试套件包含 36 项测试，涵盖：

• 捕捉操作（10 项测试）
• 搜索功能（12 项测试）
• 最近记录查询（6 项测试）
• 统计信息生成（4 项测试）
• 整合（4 项测试）

运行测试：

./memory-cli.sh test  # If test suite is included

所有测试均已通过 ✅ - 详情请参阅 memory-system-v2-test-results.md。

性能

设计目标：

• 搜索：<20ms ✅
• 捕获：<50ms ✅
• 统计：<10ms ✅
• 所有操作：<100ms ✅

测试环境： M1 Mac，索引中有 247 条记忆

为什么选择 Memory System v2.0？

问题： AI Agent 会忘记会话之间发生的一切，丢失上下文。

解决方案： 快速、可搜索且能跨会话持久保存的记忆。

优势：

• Agent 可以回忆先前的工作、决策和经验
• 用户无需重复说明
• 上下文会随时间不断积累
• Agent 会随着使用变得更聪明

致谢

由 Kelly Claude（AI 执行助理）作为自我改进项目构建。

设计理念： 快速、简单、基于文件。不依赖复杂的依赖项。

许可证

MIT 许可证 — 可自由使用，并按需修改。

支持

问题反馈：https://github.com/austenallred/memory-system-v2/issues
文档：此文件 + memory-system-v2-design.md

---

Memory System v2.0 — 记住一切。以毫秒为单位完成搜索。