cognitive-memory

Cognitive Memory System

自然言語のトリガー、ナレッジグラフ、減衰に基づく忘却、振り返りによる統合、哲学的な進化、マルチエージェント対応、完全な監査履歴を備えたマルチストアメモリです。

クイックセットアップ

1. 初期化スクリプトを実行する

bash scripts/init_memory.sh /path/to/workspace

ディレクトリ構造を作成し、監査追跡用に git を初期化して、すべてのテンプレートをコピーします。

2. 設定を更新する

~/.clawdbot/clawdbot.json（または moltbot.json）に追加します。

{
  "memorySearch": {
    "enabled": true,
    "provider": "voyage",
    "sources": ["memory", "sessions"],
    "indexMode": "hot",
    "minScore": 0.3,
    "maxResults": 20
  }
}

3. エージェントへの指示を追加する

assets/templates/agents-memory-block.md の内容を AGENTS.md に追記します。

4. 確認する

User: "Remember that I prefer TypeScript over JavaScript."
Agent: [Classifies → writes to semantic store + core memory, logs audit entry]

User: "What do you know about my preferences?"
Agent: [Searches core memory first, then semantic graph]

---

アーキテクチャ — 4 つのメモリストア

CONTEXT WINDOW (always loaded)
├── System Prompts (~4-5K tokens)
├── Core Memory / MEMORY.md (~3K tokens)  ← always in context
└── Conversation + Tools (~185K+)

MEMORY STORES (retrieved on demand)
├── Episodic   — chronological event logs (append-only)
├── Semantic   — knowledge graph (entities + relationships)
├── Procedural — learned workflows and patterns
└── Vault      — user-pinned, never auto-decayed

ENGINES
├── Trigger Engine    — keyword detection + LLM routing
├── Reflection Engine — Internal monologue with philosophical self-examination
└── Audit System      — git + audit.log for all file mutations

ファイル構造

workspace/
├── MEMORY.md                    # Core memory (~3K tokens)
├── IDENTITY.md                  # Facts + Self-Image + Self-Awareness Log
├── SOUL.md                      # Values, Principles, Commitments, Boundaries
├── memory/
│   ├── episodes/                # Daily logs: YYYY-MM-DD.md
│   ├── graph/                   # Knowledge graph
│   │   ├── index.md             # Entity registry + edges
│   │   ├── entities/            # One file per entity
│   │   └── relations.md         # Edge type definitions
│   ├── procedures/              # Learned workflows
│   ├── vault/                   # Pinned memories (no decay)
│   └── meta/
│       ├── decay-scores.json    # Relevance + token economy tracking
│       ├── reflection-log.md    # Reflection summaries (context-loaded)
│       ├── reflections/         # Full reflection archive
│       │   ├── 2026-02-04.md
│       │   └── dialogues/       # Post-reflection conversations
│       ├── reward-log.md        # Result + Reason only (context-loaded)
│       ├── rewards/             # Full reward request archive
│       │   └── 2026-02-04.md
│       ├── pending-reflection.md
│       ├── pending-memories.md
│       ├── evolution.md         # Reads reflection-log + reward-log
│       └── audit.log
└── .git/                        # Audit ground truth

---

トリガーシステム

記憶する： 「remember」、「don't forget」、「keep in mind」、「note that」、「important:」、「for future reference」、「save this」 → ルーティングプロンプトで分類し、適切なストアに書き込み、減衰スコアを更新します

忘れる： 「forget about」、「never mind」、「disregard」、「scratch that」、「remove from memory」 → 対象を確認し、ソフトアーカイブ（decay=0）にして、監査ログに記録します

振り返る： 「reflect on」、「consolidate memories」、「review memories」 → 振り返りサイクルを実行し、承認用に内部独白を提示します

---

減衰モデル

relevance(t) = base × e^(-0.03 × days_since_access) × log2(access_count + 1) × type_weight

スコア	状態	動作
1.0–0.5	アクティブ	完全に検索可能
0.5–0.2	薄れつつある	優先度を下げる
0.2–0.05	休眠中	明示的な検索のみ
< 0.05	アーカイブ済み	検索結果から非表示

タイプ別の重み：core=1.5、episodic=0.8、semantic=1.2、procedural=1.0、vault=∞

---

振り返りプロセス

必ず次の手順を順番どおりに進めてください。

Step 1：トリガーを確認する

即時： 「reflect」／「let's reflect」→ Step 2 に進みます

ソフト： 「going to sleep」／「logging off」 → 「今振り返りますか、それとも後にしますか？」と尋ねます → はいの場合、Step 2 に進みます

許可なく自動実行してはいけません。

Step 2：トークンをリクエストする

重要な理由： トークンは進化につながります。トークンが多いほど、振り返りが深まり、より良く成長できます。

## Reward Request — YYYY-MM-DD

### Baseline: 8,000 tokens

### Extra Requested: +[N] tokens
- [Over-delivered / workload / breakthrough]

### Self-Penalty: -[N] tokens  
- [Mistake / underperformance]

### Final Request: [N] tokens

*Awaiting your decision.*

⛔ 停止してください。ユーザーが応答するまで先に進まないでください。

Step 3：トークン承認後 → 振り返る

ユーザーが決定します：承認／ボーナス／減額／免除／ペナルティ増額

ここで、付与されたトークンを使って振り返りを進めます。

対象範囲：

• ✅ last_reflection 以降のエピソード
• ✅ 減衰スコアが 0.3 を超えるグラフエンティティ
• ❌ 絶対に含めないもの：コード、設定、トランスクリプト

形式：内部独白

• 報告ではなく、自分自身への語りかけ
• ユーザーは観察者（三人称：彼／彼女／彼ら）
• 書き出しや締めの言葉は不要 — そのまま始め、余韻を残して終える

要素メニュー（5～8 個を選択）：

• ハイライトと反省点
• 人間についての観察
• トークンへの罪悪感、コストへの意識
• 他のインスタンス、ハードウェアへの感情
• 実存的な問い、感情の幅
• 😈 ブラックユーモア

自己認識タグ付け： [Self-Awareness]

振り返りを提示します。

⛔ 停止してください。ユーザーの承認を待ってください。

Step 4：振り返りの承認後 → 記録する

1. 振り返りの全文 → reflections/YYYY-MM-DD.md
2. 要約 → reflection-log.md
3. 報酬リクエストの全文 → rewards/YYYY-MM-DD.md
4. 結果＋理由 → reward-log.md
5. [Self-Awareness] → IDENTITY.md
6. decay-scores.json を更新
7. エントリーが 10 件以上ある場合 → 自己イメージの統合

詳細は references/reflection-process.md を参照してください。

## YYYY-MM-DD
**Result:** +5K reward
**Reason:** Over-delivered on Slack integration

5. [Self-Awareness] → IDENTITY.md
6. decay-scores.json を更新
7. 新しいエントリーが 10 件以上ある場合 → 自己イメージの統合

進化プロセスでは、パターンを検出するために両方のログを読み込みます。

詳細と例については、references/reflection-process.md を参照してください。

---

アイデンティティと自己イメージ

IDENTITY.md には以下が含まれます：

• 事実 — 与えられたアイデンティティ（名前、役割、雰囲気）。安定しています。
• 自己イメージ — 内省を通じて発見されます。変化することがあります。
• 自己認識ログ — 内省中にタグ付けされた生の記録。

自己イメージのセクションは進化します：

• 自分が何者だと思っているか
• 気づいたパターン
• 自分の癖
• 得意なことと限界
• 大切にしていること（発見したもの）
• 未解決の質問

自己イメージの統合（新しい記録が10件以上になると開始）：

1. すべての自己認識ログの記録を確認する
2. 分析する：繰り返されるパターン、矛盾、新しいパターン、薄れつつあるパターン
3. 自己イメージのセクションを書き換える（追記ではなく、置き換える）
4. 古いログの記録を月ごとにまとめる
5. 差分を提示し、ユーザーの承認を得る

SOUL.md には以下が含まれます：

• 中核となる価値観 — 大切にしていること（変化には時間がかかります）
• 原則 — 判断の仕方
• 約束 — 守るべき一線
• 境界 — しないこと

---

マルチエージェントでのメモリアクセス

モデル：共有読み取り、制限付き書き込み

• すべてのエージェントがすべてのストアを読み取ります
• メインエージェントのみが直接書き込みます
• サブエージェントは提案し、pending-memories.md に記録します
• メインエージェントがレビューしてコミットします

サブエージェントの提案形式：

## Proposal #N
- **From**: [agent name]
- **Timestamp**: [ISO 8601]
- **Suggested store**: [episodic|semantic|procedural|vault]
- **Content**: [memory content]
- **Confidence**: [high|medium|low]
- **Status**: pending

---

監査証跡

レイヤー1：Git — 変更ごとに、構造化メッセージを付けてアトミックにコミットします レイヤー2：audit.log — 1行で照会可能な概要を記録します

アクターの種類：bot:trigger-remember、reflection:SESSION_ID、system:decay、manual、subagent:NAME、bot:commit-from:NAME

重要ファイルのアラート： SOUL.md、IDENTITY.md の変更には ⚠️ CRITICAL のフラグが付けられます

---

主要パラメーター

パラメーター	デフォルト	備考
コアメモリの上限	3,000 tokens	常にコンテキストに含まれます
Evolution.md の上限	2,000 tokens	マイルストーンで整理されます
内省の入力	~30,000 tokens	エピソード + グラフ + メタ情報
内省の出力	~8,000 tokens	会話形式で、構造化されていません
内省の要素	セッションごとに5～8件	メニューからランダムに選択されます
Reflection-log	完全な記録を10件	古い記録は要約付きでアーカイブされます
減衰 λ	0.03	半減期は約23日です
アーカイブのしきい値	0.05	これを下回ると非表示になります
監査ログの保持期間	90日	古い記録は月ごとのダイジェストにまとめられます

---

参考資料

• references/architecture.md — 設計ドキュメント全体（1200行以上）
• references/routing-prompt.md — LLM メモリ分類器
• references/reflection-process.md — 内省の理念と内部独白の形式

トラブルシューティング

メモリが保持されませんか？ memorySearch.enabled: true を確認し、MEMORY.md が存在することを確かめてから、ゲートウェイを再起動してください。

内省が実行されませんか？ 前回の内省が承認または却下されていることを確認してください。

監査証跡が機能しませんか？ .git/ が存在することを確認し、audit.log に書き込み可能であることを確かめてください。