memory-graph-builder

Memory Graph Builder

機能

OpenClaw は、エージェントのメモリをフラットな MEMORY.md ファイルに保存します。1 行に 1 つの事実が記録されるだけで、構造や関連性はありません。エージェントのメモリが 200 件を超え、その半分が重複し、3 件が互いに矛盾し、セッションごとにファイル全体で 4,000 トークンを消費するようになるまでは、これで問題ありません。

Memory Graph Builder は、MEMORY.md を生データソースとして扱い、その上に構造化されたナレッジグラフを構築します。各メモリは、型付きの関係で他のノードとつながるノードになります。このグラフにより、次のことが可能になります。

• 重複の検出 — 「ユーザーはダークモードを好む」と「ユーザーは暗いテーマが好き」は同じ事実です
• 矛盾の検出 — 「ユーザーは Python 3.8 を使う」対「ユーザーは Python 3.12 を使う」
• 古さの検出 — 設定可能なしきい値より古く、参照されていない事実を検出します
• メモリダイジェスト — 生の MEMORY.md をシステムプロンプト内で置き換える、関連性を考慮した圧縮サマリーです。トークンを 30～60％節約できます

OpenLobster の Neo4j ベースのグラフメモリシステムに着想を得て、データベースを必要とせず、既存の OpenClaw の MEMORY.md 上で動作するように調整されています。

実行するタイミング

• 毎晩午後 10 時に自動実行（cron）
• メモリを一括追加した後（例：project-onboarding の後）
• エージェントのコンテキスト初期化が遅く感じられるとき（メモリの肥大化）
• メモリの品質を監査するために手動で実行

グラフ構造

各メモリ行はノードになります。

nodes:
  - id: "mem_001"
    text: "User prefers Python for backend work"
    category: preference    # preference | fact | project | person | tool | config
    entities: ["user", "python", "backend"]
    added_at: "2026-03-01"
    last_referenced: "2026-03-15"
    confidence: 0.9
edges:
  - from: "mem_001"
    to: "mem_014"
    relation: related_to    # related_to | contradicts | supersedes | depends_on

使用方法

python3 graph.py --build                    # Parse MEMORY.md, build graph
python3 graph.py --duplicates               # Show duplicate clusters
python3 graph.py --contradictions           # Show contradicting pairs
python3 graph.py --stale --days 30          # Show memories not referenced in 30 days
python3 graph.py --digest                   # Generate compressed memory digest
python3 graph.py --digest --max-tokens 1500 # Digest with token budget
python3 graph.py --prune --dry-run          # Show what would be removed
python3 graph.py --prune                    # Remove duplicates + stale entries
python3 graph.py --stats                    # Graph statistics
python3 graph.py --status                   # Last build summary
python3 graph.py --format json

Cron による起動時の動作

毎晩午後 10 時に、次の処理を行います。

1. MEMORY.md を読み取ります
2. グラフを再構築します（増分処理 — 新規または変更された行のみを再処理します）
3. 重複と矛盾を検出します
4. 古いエントリにフラグを付けます（デフォルトでは、30 日を超えて参照されていないもの）
5. 新しいメモリダイジェストを生成します
6. ダイジェストを ~/.openclaw/workspace/memory-digest.md に書き込みます
7. サマリーを state に記録します

メモリダイジェスト

ダイジェストは、LLM での利用に最適化された、ナレッジグラフの圧縮表現です。すべての生の行をそのまま出力するのではなく、次の処理を行います。

• 関連するメモリをカテゴリ別にまとめます
• 重複する事実を 1 つのエントリに統合します
• エージェントが解決できるよう、矛盾に [CONFLICT] を付けます
• 信頼度のしきい値を下回る古いエントリを除外します
• 設定可能な最大トークン数の上限を守ります

ダイジェスト出力の例：

## Preferences
- Prefers Python for backend, TypeScript for frontend
- Dark mode everywhere; compact UI layouts
- Commit messages: imperative mood, max 72 chars

## Active Projects
- openclaw-superpowers: skill library, 40 skills, MIT license
- personal-site: Next.js 14, deployed on Vercel

## People
- Alice (teammate): works on auth, prefers Go

## Conflicts (needs resolution)
- [CONFLICT] Python version: "3.8" vs "3.12" — ask user to clarify

手順

ステップ 1 — グラフを構築する

python3 graph.py --build

ステップ 2 — 重複と矛盾を確認する

python3 graph.py --duplicates
python3 graph.py --contradictions

矛盾を解消するには、MEMORY.md を直接編集するか、エージェントに確認を求めてください。

ステップ 3 — 古いエントリを整理する

python3 graph.py --prune --dry-run
python3 graph.py --prune

ステップ 4 — ダイジェストを生成して使用する

python3 graph.py --digest --max-tokens 1500

OpenClaw のメモリ注入先を、生の MEMORY.md ではなく ~/.openclaw/workspace/memory-digest.md に指定してください。

状態

グラフ構造、ダイジェストキャッシュ、監査履歴は ~/.openclaw/skill-state/memory-graph-builder/state.yaml に保存されます。

フィールド：last_build_at、node_count、edge_count、duplicate_count、contradiction_count、stale_count、digest_tokens、build_history。