> ## Documentation Index
> Fetch the complete documentation index at: https://openclawdoc.org/llms.txt
> Use this file to discover all available pages before exploring further.

# ワークスペース記憶の研究

> 対象: Clawd スタイルのワークスペース (agents.defaults.workspace, デフォルトは ~/.openclaw/workspace)。

対象: Clawd スタイルのワークスペース (`agents.defaults.workspace`, デフォルトは `~/.openclaw/workspace`)。ここでは「記憶」は 1 日 1 つの Markdown ファイル (`memory/YYYY-MM-DD.md`) と、少数の安定したファイル (例: `memory.md`, `SOUL.md`) として保存されています。

本ドキュメントでは、Markdown を「真実のソース（正）」として人間がレビュー可能な状態で維持しつつ、派生インデックスを介して **構造化された想起** (検索、実体（エンティティ）サマリー、確信度の更新) を追加する、**オフライン優先** の記憶アーキテクチャを提案します。

## なぜ変更するのか？

現在の仕組み (1 日 1 ファイル) は以下の点に優れています:

* 「追記専用」のジャーナリング（日記）形式
* 人間による直接編集が可能
* Git による耐久性と監査性
* 低摩擦なキャプチャ（「ただ書き留めるだけ」で済む）

一方で、以下の点が弱みです:

* 高精度な検索（「X について何を決めたか？」「最後に Y を試したのはいつか？」）
* 実体（エンティティ）中心の回答（Alice, The Castle, warelay について多くのファイルを読み返さずに答えること）
* 意見や好みの安定性（および、それが変化した際の根拠の把握）
* 時間的な制約（「2025 年 11 月時点で何が事実だったか？」）や、矛盾の解消

## 設計目標

* **オフライン**: ネットワークなしで動作。ラップトップや Castle 上で実行可能。クラウド依存なし。
* **説明可能**: 想起された項目は、ソース（ファイルと位置）が特定可能であり、推論プロセスと分離されていること。
* **簡素**: 日次のログ記録は Markdown のままとし、複雑なスキーマ設計を強いない。
* **段階的**: v1 は全文検索（FTS）のみで有用。セマンティック/ベクトル検索やグラフ構造はオプションのアップグレードとする。
* **エージェント親和性**: トークン枠内での想起を容易にする（事実の小さな塊（Bundle）を返す）。

## 北極星モデル (Hindsight × Letta)

以下の 2 つの要素を組み合わせます:

1. **Letta/MemGPT スタイルの制御ループ**
   * 小さな「コア記憶」を常にコンテキスト内に保持（ペルソナ + ユーザーに関する重要事実）。
   * それ以外はコンテキスト外（Out-of-context）とし、ツールを介して想起。
   * 記憶への書き込みは明示的なツール呼び出し（追記/置換/挿入）とし、永続化された後、次のターンで再注入される。

2. **Hindsight スタイルの記憶基盤**
   * 観察されたこと（Observed） vs 信じていること（Believed） vs 要約されたこと（Summarized）を分離。
   * Retain（保持）/ Recall（想起）/ Reflect（内省）をサポート。
   * 根拠に基づいて進化する、確信度（Confidence）を伴う意見。
   * 実体（エンティティ）を認識した想起 + 時間的なクエリ（完全なナレッジグラフがなくても実現可能）。

## 提案するアーキテクチャ (Markdown ＋ 派生インデックス)

### 正統ストア (Git 親和性)

`~/.openclaw/workspace` を、人間が読める正統な記憶として維持します。

推奨されるワークスペースのレイアウト:

```
~/.openclaw/workspace/
  memory.md                    # 小規模: 恒久的な事実 + 好み (コアに近い記憶)
  memory/
    YYYY-MM-DD.md              # 日次ログ (追記型、物語形式)
  bank/                        # 「型定義された」記憶ページ (安定、レビュー可能)
    world.md                   # 世界に関する客観的な事実
    experience.md              # エージェントが何をしたか (一人称視点)
    opinions.md                # 主観的な好み/判断 + 確信度 + 根拠へのポインタ
    entities/
      Peter.md
      The-Castle.md
      warelay.md
      ...
```

補足:

* **日次ログは日次ログのまま維持**。JSON に変換する必要はありません。
* `bank/` 内のファイルは、内省（Reflection）ジョブによって生成・**整理**されますが、手動での編集も可能です。
* `memory.md` は「小規模かつコア」な状態を保ち、Clawd がすべてのセッションで目にする情報となります。

### 派生ストア (機械的な想起用)

ワークスペース配下に、派生インデックス（必ずしも Git 管理しなくてよい）を追加します:

```
~/.openclaw/workspace/.memory/index.sqlite
```

バックエンドの構成:

* 事実、実体（エンティティ）リンク、意見のメタデータのための SQLite スキーマ。
* 語彙検索（Lexical recall）のための SQLite **FTS5** (高速、軽量、オフライン)。
* セマンティック検索のためのオプションの埋め込み（Embeddings）テーブル。

このインデックスは、いつでも **Markdown から再構築可能** です。

## Retain / Recall / Reflect (運用ループ)

### Retain: 日次ログを「事実」として正規化する

Hindsight の重要な知見: 断片的なスニペットではなく、**物語的で自己完結した事実**を保存すること。

`memory/YYYY-MM-DD.md` での実践ルール:

* 1 日の終わり（または途中）に、以下の 2〜5 個の項目を含む `## Retain` セクションを追加する:
  * 物語形式（ターンを跨いだ文脈が保持されている）。
  * 自己完結（後でそれ単体で見ても意味が通じる）。
  * 型（Type）と実体（Entity）のメンションでタグ付けされている。

例:

```
## Retain
- W @Peter: アンディの誕生日のため、現在はマラケシュに滞在（2025年11月27日〜12月1日）。
- B @warelay: try/catch で connection.update ハンドラーをラップすることで、Baileys の WS クラッシュを修正（詳細は memory/2025-11-27.md を参照）。
- O(c=0.95) @Peter: WhatsApp では簡潔な返信（1500文字未満）を好む。長い内容はファイルに書き出すこと。
```

最小限のパース（解析）ルール:

* 型プレフィックス: `W` (世界), `B` (経験/伝記), `O` (意見), `S` (観察/要約; 通常は自動生成)
* 実体（エンティティ）: `@Peter`, `@warelay` など（スラッグは `bank/entities/*.md` にマップ）
* 意見の確信度: `O(c=0.0..1.0)` (オプション)

作者（ユーザー）にこれを意識させたくない場合: 内省ジョブがログの残りの部分からこれらの項目を推論することも可能ですが、明示的な `## Retain` セクションを設けることが、最も簡単な「品質向上レバー」となります。

### Recall: 派生インデックスに対するクエリ

以下の想起方法をサポートすべきです:

* **語彙検索**: 「特定の単語、名前、コマンドを探す」 (FTS5)
* **実体検索**: 「X について教えて」 (実体ページ + 実体にリンクされた事実)
* **時間検索**: 「11月27日あたりに何が起きたか」「先週以降の出来事」
* **意見検索**: 「ピーターの好みは？」 (確信度 + 根拠付き)

返信形式はエージェントが扱いやすい形式とし、出典を引用します:

* `kind` (`world|experience|opinion|observation`)
* `timestamp` (元の年月日、または抽出された期間)
* `entities` (`["Peter","warelay"]`)
* `content` (物語的な事実)
* `source` (`memory/2025-11-27.md#L12` など)

### Reflect: 安定したページの生成と信念の更新

内省は、定期的に（日次またはハートビート時の `ultrathink` として）実行されるジョブです:

* 最近の事実から `bank/entities/*.md` を更新（実体サマリー）。
* 補強・矛盾する情報に基づき、`bank/opinions.md` の確信度を更新。
* オプションで、`memory.md`（コアとなる恒久的事実）への編集を提案。

意見の進化（シンプルかつ説明可能なモデル）:

* 各意見は以下を保持:
  * 内容（Statement）
  * 確信度 `c ∈ [0,1]`
  * 最終更新日時
  * 根拠リンク（肯定・否定する事実の ID）
* 新しい事実が届いた際:
  * 実体の重なりと類似性（まずは FTS、後に埋め込みを使用）から候補となる意見を特定。
  * 小さな差分（Delta）で確信度を更新。大きな変動には、強い矛盾や繰り返しの根拠が必要。

## CLI 統合: スタンドアロン vs 深い統合

推奨: **OpenClaw への深い統合**。ただし、コアライブラリは分離可能にしておきます。

### なぜ OpenClaw に統合するのか？

* OpenClaw は既に以下を把握しています:
  * ワークスペースのパス (`agents.defaults.workspace`)
  * セッションモデルとハートビート
  * ロギングとトラブルシューティングのパターン
* エージェント自身にツールを呼び出させたい:
  * `openclaw memory recall "…" --k 25 --since 30d`
  * `openclaw memory reflect --since 7d`

### なぜライブラリを分離するのか？

* ゲートウェイやランタイムなしで記憶ロジックをテスト可能にするため。
* 他のコンテキスト（ローカルスクリプト、将来のデスクトップアプリなど）から再利用するため。

形態:
記憶ツールは、小さな CLI とライブラリのレイヤーとして意図されていますが、これはあくまで探索段階の構想です。

## "S-Collide" / SuCo の利用タイミング (研究)

もし "S-Collide" が **SuCo (Subspace Collision)** を指しているのであれば、それは部分空間内での学習・構造化された衝突を利用し、想起精度と遅延のトレードオフを高度に最適化した ANN（近似最近傍探索）手法です (論文: arXiv 2411.14754, 2024)。

`~/.openclaw/workspace` における現実的な見解:

* **最初は SuCo を使わないこと**。
* まずは SQLite FTS と（オプションの）シンプルな埋め込みから始めてください。UX 上のメリットの多くはこれで得られます。
* SuCo, HNSW, ScaNN クラスのソリューションを検討するのは、以下の条件を満たしてからにしてください:
  * コーパスが巨大になった場合（数十万〜数百万チャンク）。
  * 総当たり（Brute-force）の埋め込み検索が遅すぎる場合。
  * 想起の品質が、語彙検索（Lexical search）によって著しくボトルネックになっている場合。

オフラインに適した代替案（複雑度の低い順）:

* SQLite FTS5 + メタデータフィルタ (機械学習なし)
* 埋め込み + 総当たり検索 (チャンク数が少なければ驚くほど長く使えます)
* HNSW インデックス (一般的で堅牢、ライブラリのバインディングが必要)
* SuCo (研究グレード。埋め込める堅牢な実装があれば魅力的)

未解決の課題:

* あなたのマシン（ラップトップ + デスクトップ）上の「パーソナルアシスタント記憶」に **最適** なオフライン埋め込みモデルは何か？
  * すでに Ollama があるならローカルモデルで埋め込み、そうでなければツールチェーンに軽量なモデルを同梱する。

## 最小限の有用なパイロット

まずは最小限で、かつ有用なバージョンを作るなら:

* 日次ログに `bank/` 実体ページと `## Retain` セクションを追加。
* 出典（パスと行番号）付きの想起に SQLite FTS を使用。
* 想起の品質や規模が求められた場合にのみ、埋め込みを追加。

## 参考文献

* Letta / MemGPT コンセプト: 「コア記憶ブロック」 ＋ 「アーカイブ記憶」 ＋ ツール駆動の自己編集記憶。
* Hindsight テクニカルレポート: 「Retain / Recall / Reflect」、4 ネットワーク記憶、物語的事実の抽出、意見確信度の進化。
* SuCo: arXiv 2411.14754 (2024): "Subspace Collision" 近似最近傍探索。