memory-system-v2

Memory System v2.0

JSON インデックスによる高速な AI エージェント向けセマンティックメモリ。検索は 20 ミリ秒未満です。

概要

Memory System v2.0 は、次のことを必要とする AI エージェント向けに設計された、軽量なファイルベースのメモリシステムです。

• セッションをまたいで、学び、決定、洞察、イベント、やり取りを記憶する
• 20 ミリ秒未満でメモリをセマンティック検索する
• 日々のメモリを週次サマリーに自動で統合する
• より適切に思い出せるよう、重要度とコンテキストを追跡する

純粋な bash + jq で構築されています。データベースは不要です。

特長

• ⚡ 高速検索： 平均検索時間 20 ミリ秒未満（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 件すべてのテストに合格：

• 検索：平均 20 ミリ秒未満（最速：8 ミリ秒、最遅：18 ミリ秒）
• 記録：平均 50 ミリ秒未満
• 統計：10 ミリ秒未満
• 最近のメモリ：15 ミリ秒未満
• すべての操作：目標 100 ミリ秒未満 ✅

コマンドリファレンス

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 との連携

Memory System 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. エージェントが新しいことを学ぶ → memory-cli.sh capture
2. ユーザーが「昨日何を作った？」と尋ねる → memory-cli.sh search "build yesterday"
3. エージェントがファイルと行番号を参照して正確な詳細を思い出す

使用例

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 エージェントはセッション間ですべてを忘れてしまい、コンテキストが失われます。

解決策： セッションをまたいで保持される、高速で検索可能なメモリです。

メリット：

• エージェントが以前の作業、決定、学習内容を思い出せます
• ユーザーが同じことを繰り返す必要がなくなります
• 時間の経過とともにコンテキストが蓄積されます
• エージェントは使うほど賢くなります

クレジット

自己改善プロジェクトとして、AI エグゼクティブアシスタントの Kelly Claude が開発しました。

設計思想： 高速、シンプル、ファイルベース。複雑な依存関係はありません。

ライセンス

MIT ライセンス — 自由に使用でき、必要に応じて変更できます。

サポート

問題： https://github.com/austenallred/memory-system-v2/issues
ドキュメント：このファイルと memory-system-v2-design.md

---

Memory System v2.0 - すべてを記憶し、ミリ秒単位で検索します。