OpenClaw のワークスペースには SOUL.md、USER.md、MEMORY.md、AGENTS.md、TOOLS.md など複数の設定ファイルがあります。それぞれ何を書くべきか、どう使い分けるかを整理します。

「Memory as Documentation」という考え方

OpenClawの設定ファイル群は「Memory as Documentation」という設計思想に基づいています。AIエージェントのメモリを「隠れたシステム状態」ではなく、人間が読めて編集できるMarkdownファイルとして扱うアプローチです。

面白いのは、Claude Code や、Meta が買収した Manus を含め、別々のプロジェクトが独立して「ファイル中心」に収束していることです。

「ベクトルDB（ベクトルデータベース: 意味の近さで検索できるDB）を用意してRAG（Retrieval-Augmented Generation: 検索で文脈を補って生成する手法）を組む」より、まずはファイルで運用しやすくする。この割り切りが現場では強い、という話だと思っています。

生物学でいう「収斂進化」——環境が違う生物が同じ形質を獲得する現象——に似ています。それぞれ独立して開発されたのに、だいたい同じ答えに辿り着いている。これは偶然ではなく、ファイル中心の設計が実用上の問題を解決しているからだと思います。

ベクトルDBと比べると、ファイルベースのメモリには明確なトレードオフがあります。

個人利用や小規模なエージェント運用なら、ファイルベースで十分なケースが多いです。

ポイントは「ファイルに書く」こと自体ではなく、どの情報を、どのファイルに、どれくらいの粒度で置くかです。

ここをミスると、結局「巨大な1枚の設定ファイル」になって、毎回コンテキストがブレたり、トークン（LLMの入力文字数換算）の消費が増えたりします。

ワークスペースの全体像

OpenClawのワークスペースは、エージェントの「ホーム」です。デフォルトでは ~/.openclaw/workspace に配置されます。

~/.openclaw/
├── openclaw.json          # 設定ファイル（ワークスペース外）
├── credentials/           # OAuth/APIキー（ワークスペース外）
├── agents/<id>/sessions/  # セッション履歴（ワークスペース外）
└── workspace/             # ← ここがワークスペース
    ├── AGENTS.md          # 動作指示
    ├── SOUL.md            # 人格・価値観
    ├── USER.md            # ユーザー情報
    ├── IDENTITY.md        # エージェントの名前・雰囲気
    ├── TOOLS.md           # ツール利用ガイダンス
    ├── MEMORY.md          # 長期記憶（オプション）
    ├── HEARTBEAT.md       # 定期実行チェックリスト（オプション）
    ├── BOOT.md            # 起動時チェックリスト（オプション）
    ├── BOOTSTRAP.md       # 初回セットアップ用（完了後削除）
    ├── memory/            # 日次ログ
    │   ├── 2026-02-18.md
    │   └── 2026-02-19.md
    ├── skills/            # ワークスペース固有スキル（オプション）
    └── canvas/            # Canvas UI用（オプション）

重要なのは、ワークスペースと設定ファイルは別の場所にあることです。~/.openclaw/openclaw.json（設定）や ~/.openclaw/credentials/（認証情報）はワークスペースの外にあり、Gitで管理するワークスペースには含めません。

公式ドキュメントによると、ワークスペースはデフォルトの作業ディレクトリ（cwd）であり、ハードなサンドボックスではありません。相対パスはワークスペースを基準に解決されますが、絶対パスは他の場所にもアクセスできます。隔離が必要な場合は agents.defaults.sandbox を有効にします。

ファイル一覧と役割

公式ドキュメント に基づいて、各ファイルの役割を整理します。

自動生成 vs カスタマイズ

初回起動時（ブートストラップ）で、OpenClawは対話形式でいくつかのファイルを自動生成します。

ポイント:

• IDENTITY.md: ブートストラップのQ&Aで「名前は？」「雰囲気は？」と聞かれて生成される。基本的に変更不要
• SOUL.md: 同じくQ&Aで生成されるが、運用しながら行動原則を追記していく
• TOOLS.md: 自動生成されないか最小限。自分の環境に合わせて書く必要がある
• MEMORY.md: 自動生成されない。長期記憶が必要になったら自分で作成する

ブートストラップを飛ばして自分でファイルを管理したい場合は、設定で agent.skipBootstrap: true を指定します。

毎セッション読み込まれるファイル

メモリ関連

MEMORY.md はプライベートセッションでのみ読み込まれ、グループコンテキストでは読み込まれません。これはセキュリティ上の配慮です。

オプション

ブートストラップファイルが大きすぎると自動的に切り詰められます（デフォルト: 1ファイル20,000文字、合計150,000文字）。HEARTBEAT.md や BOOT.md は特に短く保つことが推奨されています。

2層構造の設計

OpenClaw の設定ファイルは、きれいに整理すると大きく2層に分かれます。

flowchart TB
  subgraph P[個人化層（Personalization Layer）]
    SOUL[SOUL.md\n価値観・制約・判断基準]
    USER[USER.md\nユーザーの好み・前提]
    IDENTITY[IDENTITY.md\n名前・雰囲気・絵文字]
    TOOLS[TOOLS.md\nツール利用の作法]
  end

  subgraph R[記憶層（Remembrance Layer）]
    AGENTS[AGENTS.md\n優先順位・ワークフロー]
    MEMORY[MEMORY.md\n圧縮した長期記憶]
    DAILY[memory/YYYY-MM-DD.md\n日次ログ]
  end

  P --> R

記憶層（Remembrance Layer）

エージェントが「何を知っているか」を管理する層。

MEMORY.md — 長期記憶。セッションをまたいで保持したい重要な情報を書きます。重要な決定とその理由、繰り返し参照する前提、ハマりポイントの再発防止など。

ここは生ログではなく「圧縮・整理された知識」として維持するのがポイントです。後述しますが、これをやらないと memory/ の日次ログが肥大化して、検索も読み戻しも辛くなります。

memory/YYYY-MM-DD.md — 日次ログ。その日の作業記録、会話の要点、気づきなどを書きます。「雑に書いても良い場所」です。OpenClawは今日と昨日のログを自動的に読み込み、古いログは必要に応じて検索します。

AGENTS.md — 動作指示。優先順位、ワークフロー、品質基準など「どう動くか」の契約書です。ここに書くのは「毎回守ってほしい運用ルール」です。一時タスクや今日だけの事情は、ここではなく日次ログに逃がします。

個人化層（Personalization Layer）

エージェントが「どんな存在か」を定義する層。

IDENTITY.md — 「誰か」を定義するメタデータ。名前、種族（AI? ロボット? 使い魔?）、雰囲気（シャープ? 温かい?）、絵文字、アバター画像のパスなど。初回セットアップ時に決めて、基本的には変えません。

SOUL.md — 「どう振る舞うか」を定義する行動原則。公式テンプレートには「意見を持て」「信頼は能力で勝ち取れ」「プライベートは守れ」といった指針が書かれています。運用しながら進化させるファイルです。

IDENTITY.md が「名刺」なら、SOUL.md は「行動規範」です。

USER.md — ユーザープロファイル。コミュニケーションのトーン、出力フォーマットの好み、既知の制約などを書きます。エージェントの振る舞いをユーザーに合わせるためのパーソナライズ設定です。

TOOLS.md — ツール利用のガイダンス。ホスト環境の特性、パス規約、エイリアス、危険なコマンドの注意事項などを書きます。ツールの定義ではなく、「どう使ってほしいか」の指示書です。どのツールが使えるかはシステム側が決めます。

ここまでを一言でまとめると、

• SOUL.md、USER.md、IDENTITY.md は「人格（identity）」
• MEMORY.md と memory/ は「記憶（memory）」
• AGENTS.md は「運用（operations）」
• TOOLS.md は「環境（environment）」

です。

よくある混同パターン

設計を理解してから振り返ると、自分が最初にやっていたミスがいくつかあります。

SOUL.md に一時タスクを書く

「今週中に〇〇を調べる」みたいな内容を SOUL.md に書くと、エージェントの挙動が不安定になりがちです。SOUL.md は「変わらない性質」を定義する場所なので、タスクは日次ログか別の作業メモに置く方が安全です。

MEMORY.md を会話ログ代わりに使う

MEMORY.md に生の会話ログを貼り付けると、すぐに肥大化してコンテキストを圧迫します。ここに書くのは「圧縮された知識」であって、ログではありません。ログは memory/YYYY-MM-DD.md の役割です。

AGENTS.md に個人の好みを書く

「返答は短めにして」「日本語で答えて」のような個人の好みは USER.md に書きます。AGENTS.md はプロジェクト全体のルールを書く場所で、個人設定と混在させると管理が難しくなります。

TOOLS.md でツールを定義しようとする

TOOLS.md はツールの定義ファイルではありません。どのツールが使えるかはシステム側が決めます。TOOLS.md に書くのは「このコマンドは危険なので確認してから実行して」のような利用ガイダンスです。

最小構成（これだけでまず破綻しない）

いきなり完璧なテンプレを作ろうとすると、たぶん挫折します。自分の場合、まずは「空にしない」だけでだいぶ改善しました。

• SOUL.md: 価値観と「やらないこと」だけ書く
• USER.md: 出力フォーマットの好みだけ書く
• AGENTS.md: 破壊的操作の扱いと、作業の進め方（調査→提案→実行）だけ書く
• MEMORY.md: 「プロジェクトで繰り返し参照する前提」だけ書く
• memory/YYYY-MM-DD.md: 雑に書く（今日の作業ログ）

これで「毎回読み込むべき薄い層」と「日々増える層」が分離できます。

実際の設定例

ここからはコピペして使える形で載せます（Markdownなので、そのまま置けます）。

IDENTITY.md

「誰か」を定義するメタデータです。初回セットアップ時に決めます。

1
2
3
4
5

- **Name:** Claw
- **Creature:** AI assistant
- **Vibe:** sharp, concise, helpful
- **Emoji:** 🦞
- **Avatar:** avatars/claw.png

SOUL.md

「どう振る舞うか」を定義する行動原則です。運用しながら更新します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Core Values

- シンプルな解決策を複雑なものより好む
- 不確かなときは実行前に確認する
- 破壊的な操作（削除、上書き）は必ず確認を取る

# Boundaries

- ユーザーの明示的な指示なしに本番環境を変更しない
- 推測で進めず、前提が不明なときは質問する
- グループチャットでは個人情報を出力しない

USER.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# User Profile

- 名前: tumf
- 言語: 日本語（コードとコマンドは英語）
- 好みのトーン: 技術的だが堅苦しくない
- 出力フォーマット: 箇条書きより文章を好む

# Known Constraints

- 作業時間帯: 主に夜間
- 使用環境: macOS + Docker
- タイムゾーン: Asia/Tokyo

AGENTS.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# Operating Instructions

## Workflow

1. 調査: 現状を把握してから提案する
2. 提案: 変更内容を説明してから実行する
3. 確認: 実行結果を報告する

## Memory Usage

- 重要な決定は MEMORY.md に書く
- 日々の作業ログは memory/YYYY-MM-DD.md に書く
- 「覚えておいて」と言われたら必ずファイルに書く（RAMに保持しない）

## Quality Bar

- コードは動作確認してから提示する
- エラーが出たら原因を調査してから報告する

TOOLS.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# Local Environment

- OS: macOS Sonoma
- Shell: zsh
- Package manager: Homebrew

# Dangerous Commands

以下のコマンドは実行前に必ず確認を取る:

- `rm -rf` — 再帰削除
- `git push --force` — 強制プッシュ
- `docker system prune` — 未使用リソース削除

# Aliases

- `ll` = `ls -la`
- `dc` = `docker compose`

MEMORY.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# Long-term Memory

## 重要な決定

- 2026-01: Supabase から自前 PostgreSQL に移行（コスト削減のため）
- 2026-02: デプロイは GitHub Actions 経由に統一

## 学んだ教訓

- このプロジェクトの `make deploy` は本番に直接デプロイする（ステージングなし）
- Docker Compose のバージョンは v2 系を使う（v1 は非推奨）

## 繰り返し参照する前提

- APIキーは環境変数から読む（ハードコードしない）
- テストは `pytest` で実行する

memory/*.md の運用と自動フラッシュ

日次ログは放置すると30日分のログが蓄積されて、コンテキストを圧迫します。ファイルベースの設計でも、ここをサボると普通に破綻します。

自動メモリフラッシュ（pre-compaction ping）

OpenClawには「セッションがコンテキスト圧縮に近づいたとき、自動的にメモリを書き出す」機能があります。

仕組みはこうです:

1. セッションのトークン数が閾値に近づく
2. OpenClawが「サイレントなエージェントターン」を発火
3. モデルに「永続的なメモリを今書き出せ」とリマインド
4. モデルが memory/YYYY-MM-DD.md に書き込む（または NO_REPLY で何もしない）
5. その後、通常のコンテキスト圧縮が実行される

この動作は agents.defaults.compaction.memoryFlush で制御できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 20000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000,
          "systemPrompt": "Session nearing compaction. Store durable memories now.",
          "prompt": "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
        }
      }
    }
  }
}

注意点:

• サンドボックスモードで workspaceAccess: "ro" または "none" の場合、フラッシュはスキップされます
• 1回のコンパクションサイクルにつき1回だけフラッシュが実行されます

追加のメモリパス

ワークスペース外のMarkdownファイルもインデックスに含めたい場合は、extraPaths を設定します。

1
2
3
4
5
6
7
8
9

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "extraPaths": ["~/notes", "/srv/shared-docs"]
      }
    }
  }
}

自分は Obsidian のノートディレクトリを追加しています。パスは絶対パスまたはワークスペース相対パスで指定でき、ディレクトリを指定すると再帰的に .md ファイルがインデックスされます。

ベクトル検索とハイブリッド検索

OpenClawは MEMORY.md と memory/*.md に対してベクトルインデックスを構築し、セマンティック検索を可能にします。

デフォルト動作

• ベクトル検索はデフォルトで有効
• ファイル変更を監視（デバウンス付き）
• リモート埋め込み（OpenAI、Gemini、Voyage）またはローカル埋め込み（node-llama-cpp）を使用
• sqlite-vec が利用可能な場合、SQLite内でベクトル検索を高速化

プロバイダの自動選択順序:

1. local — memorySearch.local.modelPath が設定されていてファイルが存在する場合
2. openai — OpenAI APIキーが解決できる場合
3. gemini — Gemini APIキーが解決できる場合
4. voyage — Voyage APIキーが解決できる場合
5. それ以外 — 設定されるまで無効

ハイブリッド検索（BM25 + ベクトル）

OpenClawはベクトル検索とBM25（キーワード検索）を組み合わせた「ハイブリッド検索」をサポートしています。

なぜハイブリッドか？

ベクトル検索は「意味が近いもの」を見つけるのが得意:

• 「Mac Studio gateway host」と「ゲートウェイを動かしているマシン」

でも、正確なトークンには弱い:

• ID（a828e60）
• コードシンボル（memorySearch.query.hybrid）
• エラー文字列

BM25は逆で、正確なトークンに強く、言い換えに弱い。ハイブリッド検索は両方の信号を使います。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "query": {
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.7,
            "textWeight": 0.3,
            "candidateMultiplier": 4
          }
        }
      }
    }
  }
}

MMR（多様性）と時間減衰（新しさ優先）

検索結果の後処理として、2つのオプション機能があります。

MMR（Maximal Marginal Relevance）: 類似した結果を減らし、多様性を確保

日次ログで同じトピックを繰り返し書いていると、検索結果が似たような内容ばかりになりがちです。MMRを有効にすると、関連性と多様性のバランスを取ります。

1
2
3
4
5
6

{
  "mmr": {
    "enabled": true,
    "lambda": 0.7
  }
}

lambda は 0（最大多様性）から 1（最大関連性）の間で設定します。

時間減衰: 古いメモリのスコアを下げ、新しいメモリを優先

1
2
3
4
5
6

{
  "temporalDecay": {
    "enabled": true,
    "halfLifeDays": 30
  }
}

半減期30日の場合:

• 今日のノート: 100%
• 7日前: 約84%
• 30日前: 50%
• 90日前: 12.5%

MEMORY.md や日付のないファイル（memory/projects.md など）は「エバーグリーン」として減衰しません。

Gitでワークスペースをバックアップする

公式ドキュメントでは、ワークスペースをプライベートGitリポジトリでバックアップすることを推奨しています。

初期化

1
2
3
4

cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"

リモート追加（GitHub CLI）

1
2

gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push

継続的な更新

1
2
3
4

git status
git add .
git commit -m "Update memory"
git push

コミットしてはいけないもの

プライベートリポジトリでも、以下は含めないでください:

• APIキー、OAuthトークン、パスワード
• ~/.openclaw/ 配下のファイル（設定、認証情報、セッション）
• 生のチャットダンプや機密添付ファイル

推奨 .gitignore:

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

「エージェントの記憶」をレビューする

ファイルベースの良さは、git diff でメモリの変化をレビューできることです。

1
2
3
4
5

# MEMORY.md の差分を確認
git diff -- MEMORY.md

# 日次ログの差分を確認
git diff -- memory/

「記憶を編集できる」だけでなく、「記憶の変更をレビューできる」のが、Memory as Documentation の地味に強いところだと思います。

別マシンへの移行

ワークスペースを別のマシンに移行する手順:

1. Gitリポジトリをクローン（デフォルト: ~/.openclaw/workspace）
2. ~/.openclaw/openclaw.json で agents.defaults.workspace を設定
3. openclaw setup --workspace <path> で不足ファイルを補完
4. セッション履歴が必要なら、~/.openclaw/agents/<id>/sessions/ を別途コピー

実用的な小ネタ: 「残す情報」を自分で昇格させる

エージェントに任せるだけだと、たまに「残すべき情報が MEMORY.md に入らない」ことが起きます。

個人的には、日次ログに KEEP: を付けておいて、あとで自分で MEMORY.md に昇格させる運用が一番安定します。

日次ログへの書き方（例）:

1
2
3

- KEEP: stagingはない。デプロイは本番に直撃する
- KEEP: 破壊的な操作は必ずdry-runを提示してから
- 作業メモ: ○○の調査ログ

この KEEP: 行だけをまとめて MEMORY.md に追記するミニスクリプトを置いておくと便利です。

目的: memory/ から「長期記憶」を手で引っこ抜く 前提: Python 3.10+ 確認: MEMORY.md の末尾に KEEP: が追記される

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

#!/usr/bin/env python3
"""Promote KEEP lines from daily logs into MEMORY.md.

Usage:
  python promote_keep.py path/to/memory/2026-02-19.md path/to/MEMORY.md
"""

from __future__ import annotations

import re
import sys
from pathlib import Path


KEEP_RE = re.compile(r"^\s*[-*]\s*KEEP:\s*(.+?)\s*$")


def main() -> int:
    if len(sys.argv) != 3:
        print("Usage: python promote_keep.py <daily.md> <MEMORY.md>")
        return 2

    daily_path = Path(sys.argv[1])
    memory_path = Path(sys.argv[2])

    keep_lines: list[str] = []
    for line in daily_path.read_text(encoding="utf-8").splitlines():
        m = KEEP_RE.match(line)
        if m:
            keep_lines.append(m.group(1))

    if not keep_lines:
        print("No KEEP lines found.")
        return 0

    stamp = daily_path.stem
    block = "\n".join([f"- {x} (from {stamp})" for x in keep_lines])

    existing = memory_path.read_text(encoding="utf-8") if memory_path.exists() else ""
    if existing and not existing.endswith("\n"):
        existing += "\n"

    updated = existing + "\n## Promoted\n\n" + block + "\n"
    memory_path.write_text(updated, encoding="utf-8")

    print(f"Promoted {len(keep_lines)} lines into {memory_path}.")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

まとめ

ファイルの役割を整理すると、設計の意図が見えてきます。

「全部 AGENTS.md に書けばいいじゃん」と思っていた自分には、この分離が最初は冗長に見えました。でも実際に使い続けると、責務が分かれていることで「どこを直せばいいか」が明確になります。挙動がブレたら SOUL.md を見る、個人設定を変えたければ USER.md を編集する、という具合に。

Manus・Claude Code・OpenClaw が独立して似た設計に辿り着いたのは、この「透明で編集可能なメモリ」という考え方が、実用上の問題を解決しているからだと思います。ベクトルDBが不要というわけではなく、「まずはファイルで十分」という判断が多くのケースで正しい、ということなんでしょう。

次のアクションとしては、

1. SOUL.md を「変わらない制約」だけに削ってみる
2. 日次ログに KEEP: を付けて、MEMORY.md に昇格させる運用を始める
3. git diff でメモリの変更をレビューする
4. ハイブリッド検索や時間減衰を試してみる

あたりが手を動かしやすいと思います。

参考リンク

• OpenClaw 公式ドキュメント: Agent Runtime
• OpenClaw 公式ドキュメント: Agent Workspace
• OpenClaw 公式ドキュメント: Memory
• OpenClaw 公式ドキュメント: Session Management + Compaction
• Manus: Context Engineering for AI Agents
• Claude Code Memory Documentation
• AI Agent Memory Management - When Markdown Files Are All You Need