openclaw-memory-graph

Openclaw プロバイダー向けの Neo4j バックアップ グラフメモリ。

フラットファイルの memory/ システムをプロパティグラフに置き換え、型付きメモリノード、セマンティックエッジ、ベクトル類似度リコール、および既存のフラットファイルメモリの自動マイグレーションをサポートします。

---

前提条件

1. Neo4j の起動または検出

オプション A — Docker Compose（ローカル開発）:

docker compose up -d

bolt://localhost:7687 で Neo4j 5.x を起動し、認証情報は neo4j / openclaw-dev です。

オプション B — Neo4j AuraDB（ホステッド）: 無料インスタンスを作成し、接続 URI と認証情報をメモします。

オプション C — 既存の Neo4j インスタンス: 既存のインスタンスを使用し、接続 URI と認証情報を設定します。

2. 環境変数を設定

変数	必須	デフォルト	説明
NEO4J_URI	はい	—	例: bolt://localhost:7687
NEO4J_USER	はい	—	Neo4j ユーザー名
NEO4J_PASSWORD	はい	—	Neo4j パスワード
OPENCLAW_EMBEDDING_PROVIDER	いいえ	sentence-transformers	openai、ollama、または sentence-transformers
OPENCLAW_EMBEDDING_MODEL	いいえ	all-MiniLM-L6-v2	モデル名またはローカルパス
OPENAI_API_KEY	OpenAI 使用時	—	OpenAI API キー
OLLAMA_BASE_URL	Ollama 使用時	http://localhost:11434	ローカル Ollama URL

3. 依存関係をインストール

pip install -r requirements.txt

Sentence Transformers プロバイダー（オプション — ローカル、API キー不要）:

pip install -r requirements-sentence-transformers.txt

その後、以下を設定します：

OPENCLAW_EMBEDDING_PROVIDER=sentence-transformers
# OPENCLAW_EMBEDDING_MODEL のデフォルトは all-MiniLM-L6-v2
# HuggingFace のモデル名またはファイン調整済みモデルへのローカルパスも受け入れられます。

注記: 初回実行時は、モデルをダウンロード（all-MiniLM-L6-v2 の場合は約 90 MB）し、~/.cache/huggingface/hub/ にキャッシュします。

警告: メモリが既に保存されている後で埋め込みプロバイダーまたはモデルを変更した場合は、再埋め込みが必要です。既存の埋め込みは異なるベクトル空間で生成されており、誤った類似度結果が返されます。再埋め込みするには、すべてのメモリノードの embedding プロパティをクリアし、バッチ埋め込みを再実行します。embeddings.py の batch_embed_memories() を参照してください。

カスタムモデルのファイン調整

ドメイン固有のコンテンツでリコール精度を向上させるには、Sentence Transformer をラベル付きデータセットで ファイン調整できます：

python -m openclaw_memory_graph fine-tune \
    --dataset path/to/data.csv \
    --output ./fine-tuned-model \
    --base-model all-MiniLM-L6-v2

データセット形式（sentence1、sentence2、score 列を持つ CSV または JSONL）:

sentence1,sentence2,score
"The user prefers dark mode","Enable dark theme",0.95
"Bug in login flow","Authentication error",0.88

ファイン調整後、保存されたモデルをポイントします：

OPENCLAW_EMBEDDING_PROVIDER=sentence-transformers
OPENCLAW_EMBEDDING_MODEL=./fine-tuned-model

4. スキルを初期化

from skills.openclaw_memory_graph import MemorySkill

skill = MemorySkill(agent_id="my-project")

新しい agent_id の初回実行時に、スキルが自動的に以下を実行します：

• Neo4j で (:Agent) ルートノードを作成
• memory/*.md をスキャンしてフラットファイルメモリをグラフにマイグレーション
• 非同期で埋め込みを生成

マイグレーションはべき等です — 再実行してもノードが重複することはありません。

---

メモリタイプ

タイプ	Neo4j ラベル	用途
short-term	ShortTerm	セッションスコープのコンテキスト；TTL 有効期限をサポート
long-term	LongTerm	永続的な事実、設定、ユーザープロファイル
working	WorkingMemory	タスク中のアクティブなスクラッチパッド

リレーションシップタイプ

タイプ	意味
RELATED_TO	一般的なセマンティック関連付け
PRECEDES	時間的順序付け（A は B の前に発生）
SUPPORTS	A が B の証拠またはコンテキストを提供
CONTRADICTS	A が B と矛盾

---

オペレーション

save — 新しいメモリを保存

memory_id = skill.save(
    name="User role",
    content="The user is a senior backend engineer with Go expertise.",
    memory_type="long-term",          # 必須: 'short-term'、'long-term'、または 'working'
    description="User background",    # オプション：ワンライン要約
    ttl=3600,                          # オプション：TTL（秒）（short-term のみ）
)
# 戻り値: UUID 文字列（新しいメモリの id）

埋め込み生成は保存後に非同期で実行されます。埋め込みプロバイダーが設定されていない場合、リコールはテキストマッチにフォールバックします。

---

recall — 関連するメモリを取得

result = skill.recall(
    query="Go programming background",
    top_k=5,               # オプション、デフォルト 5
    type_filter="long-term",  # オプション：1 つのメモリタイプに限定
)
# 戻り値:
# {
#   "results": [ { "id": ..., "name": ..., "content": ..., "score": ... }, ... ],
#   "method": "vector"   # または埋め込みが利用できない場合は "text"
# }

埋め込みが利用できない場合、スキルは name と content に対する大文字小文字を区別しない部分文字列マッチにフォールバックし、レスポンスに "warning" キーを含めます。

---

update — 既存のメモリを修正

updated = skill.update(
    memory_id,
    content="Updated content here.",
    name="New name",          # 書き込み可能なフィールド
    description="Updated description",
)
# 戻り値: 更新されたメモリノードプロパティ辞書
# 発生例外: memory_id がこのエージェント下に存在しない場合の NotFoundError

content が変更された場合、埋め込み再生成が自動的にトリガーされます。

---

forget — メモリを永続的に削除

result = skill.forget(memory_id)
# 戻り値: {"deleted": True, "message": "Memory '<id>' deleted."}
# または:  {"deleted": False, "message": "Memory '<id>' not found."}

ノードとすべてのリレーションシップを削除します。これは不可逆的です。

---

connect — 2 つのメモリ間にエッジを作成

result = skill.connect(
    from_id=memory_id_a,
    to_id=memory_id_b,
    relationship="SUPPORTS",   # RELATED_TO | PRECEDES | SUPPORTS | CONTRADICTS
)
# 戻り値: {"connected": True, "from": ..., "to": ..., "relationship": "SUPPORTS"}
# 発生例外: 未知のリレーションシップタイプの ValidationError

---

traverse — 開始ノードからグラフを巡回

subgraph = skill.traverse(
    start_id=memory_id,
    depth=2,                            # オプション、デフォルト 1
    relationship_types=["SUPPORTS"],    # オプション フィルター
)
# 戻り値: {"nodes": [...], "edges": [...]}

---

list — このエージェントのすべてのメモリを返す

memories = skill.list(type_filter="long-term")  # type_filter はオプション
# 戻り値: メモリノード辞書のリスト、updated_at DESC でソート

---

prune_expired — TTL 期限切れの短期メモリを削除

deleted_count = skill.prune_expired()
# 戻り値: int — 削除されたノード数

定期的に呼び出す（例：セッション開始時）と、古い ShortTerm ノードを削除します。

---

完全な例

from skills.openclaw_memory_graph import MemorySkill

skill = MemorySkill(agent_id="my-project")

# 長期的な事実を保存
user_mid = skill.save(
    name="User role",
    content="The user is a senior backend engineer with Go expertise.",
    memory_type="long-term",
)
ctx_mid = skill.save(
    name="Frontend context",
    content="User is new to React — frame explanations in Go analogues.",
    memory_type="long-term",
)

# 関連するメモリをリンク
skill.connect(user_mid, ctx_mid, "RELATED_TO")

# セッションスコープのコンテキストを保存（1 時間で有効期限切れ）
skill.save(
    name="Current task",
    content="Reviewing the auth middleware PR.",
    memory_type="short-term",
    ttl=3600,
)

# 応答する前に関連するメモリをリコール
result = skill.recall("user's programming background", top_k=3)
for mem in result["results"]:
    print(mem["name"], "—", mem["content"])

# 接続されたコンテキストを探索
subgraph = skill.traverse(user_mid, depth=2)

# 有効期限切れの短期メモリをクリーンアップ
skill.prune_expired()

---

エラーハンドリング

例外	発生条件
ConfigurationError	NEO4J_URI、NEO4J_USER、または NEO4J_PASSWORD が不足している
AuthorizationError	Neo4j 認証情報が拒否された
NotFoundError	update が存在しない id で呼び出された
ValidationError	無効な memory_type または relationship 値

すべての例外は skills.openclaw_memory_graph.exceptions からインポート可能です。

---

グラフ構造リファレンス

(:Agent {id}) -[:HAS_MEMORY]-> (:Memory:ShortTerm | :LongTerm | :WorkingMemory)
(:Memory) -[:RELATED_TO | :PRECEDES | :SUPPORTS | :CONTRADICTS]-> (:Memory)

メモリノードは、Neo4j ベクトルインデックスを介したコサイン類似度リコール用の embedding ベクトルを保持します（Neo4j 5.0+ が必要）。