English | 日本語

EpisodicRAG Plugin - 用語集・リファレンス

プロジェクト概要・インストールはメインREADME を参照

EpisodicRAGプラグインで使用される専門用語の定義集です。

基本概念

plugin_root

定義: プラグインのインストール先ディレクトリ

.claude-plugin/ ディレクトリが存在するディレクトリ
スキルやスクリプトはこのディレクトリを基準に動作
例: ~/.claude/plugins/marketplaces/plugins-weave/EpisodicRAG

永続化パス (v5.2.0+)

定義: プラグイン自動更新で消えない設定保存先

配置: ~/.claude/plugins/.episodicrag/
保存されるファイル: config.json, last_digest_times.json
Claude Codeのプラグイン自動更新時も設定が保持される

📖 詳細: ARCHITECTURE.md

パス形式の違い

EpisodicRAGは環境によって異なるパスを使用します：

環境	パス形式	例
開発環境	ソースコード直接	`plugins-weave/EpisodicRAG/`
マーケットプレース	`~/.claude/plugins/marketplaces/`	`~/.claude/plugins/marketplaces/plugins-weave/EpisodicRAG/`
プラグイン直接インストール	`~/.claude/plugins/`	`~/.claude/plugins/EpisodicRAG/`

重要: 設定ファイル（config.json）は永続化ディレクトリ（~/.claude/plugins/.episodicrag/）に自動配置されます。データはインストール先に配置します。開発環境のソースコードディレクトリには配置しないでください。

base_dir

定義: データ配置の基準ディレクトリ

設定場所: config.json の base_dir フィールド
形式: 相対パスまたは絶対パス（チルダ展開サポート）
例:
- .（プラグイン内、デフォルト）
- subdir（プラグイン内のサブディレクトリ）
- ~/DEV/production/EpisodicRAG（外部パス、trusted_external_pathsで許可が必要）
- C:/Data/EpisodicRAG（Windows絶対パス、trusted_external_pathsで許可が必要）

パス解決:

相対パス: plugin_root + base_dir → 実際のデータ基準ディレクトリ
絶対パス: そのまま使用（trusted_external_paths内である必要あり）

trusted_external_paths

定義: plugin_root外でアクセスを許可する絶対パスのリスト

設定場所: config.json の trusted_external_paths フィールド
形式: 絶対パスの配列（チルダ展開サポート）
デフォルト: []（空配列、plugin_root内のみ許可）
例: ["~/DEV/production", "C:/Data/EpisodicRAG"]

セキュリティ:

デフォルトは空配列で最もセキュア
外部パスを使用する場合は明示的な許可が必要
相対パスは使用不可（絶対パスのみ）
Git公開時はconfig.jsonを.gitignoreに追加推奨

使用例（外部データディレクトリ）:

{
  "base_dir": "~/DEV/production/EpisodicRAG",
  "trusted_external_paths": ["~/DEV/production"],
  "paths": {
    "loops_dir": "data/Loops",
    "digests_dir": "data/Digests",
    "essences_dir": "data/Essences"
  }
}

paths

定義: 各データディレクトリの配置先

設定場所: config.json の paths セクション
形式: base_dir からの相対パス
含まれる設定: loops_dir, digests_dir, essences_dir, identity_file_path

パス解決: base_dir + paths.loops_dir → 実際のLoopディレクトリ

Loop

定義: AI との会話セッション全体を記録したテキストファイル

形式: L[連番]_[タイトル].txt
例: L00001_認知アーキテクチャ論.txt
正規表現: ^L[0-9]+_[\p{L}\p{N}ー・\w]+\.txt$
配置先: {loops_dir}/

Loopは EpisodicRAG システムの最小単位であり、すべてのDigest生成の基礎データとなります。

内容形式（正典）: メタデータブロック＋ ## User / ## Claude 交互見出しの、人間にも LLM にも可読なテキスト。550件超の既存コーパスとの互換規約であり、見出しの交互構造は不可侵：

# Claude

Source: [Claude Chat](https://claude.ai/chat/{uuid})
Extracted: {ISO8601}
Exporter: {採取ツール名} v{x.y.z}
Messages: human {N} / assistant {M}

---

## User

{本文}

## Claude

{本文}

タイトル行・メタデータブロック・--- 区切り・各見出し＋本文は、それぞれ空行1つで区切る
/digest を含む Digest 生成パイプラインは、この形式を正規表現で厳密パースするのではなく、Claude 自身がファイルを読んで意味的に分析する（LLM可読フォーマット）。Loop ファイルの検出自体はファイル名パターン（上記正規表現）のみに依存し、内容形式には依存しない
ヘッダの Messages: human {N} / assistant {M} 件数焼き込みと ## User / ## Claude 交互構造は、まだら採取（部分欠落）を人間が事後監査できるようにするための規約
採取ツールの一例: LoopExporter（フヒト） — claude.ai の内部 API から直接この形式で出力する私用 Chrome 拡張

Digest

定義: 複数のLoopまたは下位Digestを要約・統合した階層的記録

Digestには以下の種類があります：

種類	説明
Individual Digest	単一Loop/Digestの要約
Overall Digest	複数Loop/Digestの統合要約
Provisional Digest	仮ダイジェスト（確定前の一時保存）
Regular Digest	正式ダイジェスト（確定済み）

Essences

定義: GrandDigest と ShadowGrandDigest を格納するメタ情報ディレクトリ

配置先: {essences_dir}/
含まれるファイル:
- GrandDigest.txt - 確定済み記憶
- ShadowGrandDigest.txt - 未確定記憶

記憶構造

📖 概念説明: CONCEPT.md - 三層システム

GrandDigest

定義: 確定済みの長期記憶を格納するJSONファイル

ファイル: {essences_dir}/GrandDigest.txt
内容: 各階層（Weekly〜Centurial）の最新確定Digest
更新タイミング: /digest <type> で階層を確定した時

詳細な形式は ARCHITECTURE.md を参照

{
  "metadata": { "last_updated": "...", "version": "1.0" },
  "major_digests": {
    "weekly": { "overall_digest": {...} },
    "monthly": { "overall_digest": {...} }
  }
}

ShadowGrandDigest

定義: 未確定の増分ダイジェストを格納するJSONファイル

ファイル: {essences_dir}/ShadowGrandDigest.txt
用途: 新しいLoopの分析結果を一時保存し、threshold達成後にRegularに昇格
更新タイミング: /digest で新規Loopを検出・分析した時

詳細な形式は ARCHITECTURE.md を参照

{
  "latest_digests": {
    "weekly": {
      "overall_digest": {
        "timestamp": "2025-07-01T12:00:00",
        "source_files": ["L00001.txt", "L00002.txt"],
        "digest_type": "<!-- PLACEHOLDER -->",
        "keywords": ["<!-- PLACEHOLDER -->", ...],
        "abstract": "<!-- PLACEHOLDER: abstract (max 2400 chars) -->",
        "impression": "<!-- PLACEHOLDER: impression (max 800 chars) -->"
      }
    }
  }
}

Provisional Digest

定義: 次階層用の個別ダイジェスト（一時ファイル）

配置先: {digests_dir}/{level_dir}/Provisional/
形式: {prefix}{番号}_Individual.txt
例: W0001_Individual.txt
生存期間: /digest <type> 実行時のRegularDigest確定まで

Regular Digest

定義: 確定済みの正式ダイジェストファイル

配置先: {digests_dir}/{level_dir}/
形式: {prefix}{番号}_タイトル.txt
例: W0001_認知アーキテクチャ.txt

8階層構造

📖 概念説明: CONCEPT.md - 8階層構造

EpisodicRAGは8つの階層で記憶を管理します（約108年分）：

階層	プレフィックス	時間スケール	デフォルト閾値	累積Loop数
Weekly	W	~1週間	5 Loops	5
Monthly	M	~1ヶ月	5 Weekly	25
Quarterly	Q	~3ヶ月	3 Monthly	75
Annual	A	~1年	4 Quarterly	300
Triennial	T	~3年	3 Annual	900
Decadal	D	~9年	3 Triennial	2,700
Multi-decadal	MD	~27年	3 Decadal	8,100
Centurial	C	~108年	4 Multi-decadal	32,400

階層的カスケード

Digest確定時に上位階層へ自動的に伝播する処理です：

Loop (5個) → Weekly Digest
  ↓
Weekly (5個) → Monthly Digest
  ↓
Monthly (3個) → Quarterly Digest
  ↓
Quarterly (4個) → Annual Digest
  ↓
Annual (3個) → Triennial Digest
  ↓
Triennial (3個) → Decadal Digest
  ↓
Decadal (3個) → Multi-decadal Digest
  ↓
Multi-decadal (4個) → Centurial Digest

プロセス・操作

まだらボケ

📖 概念説明: CONCEPT.md - まだらボケ問題

定義: AIがLoopの内容を記憶できていない（虫食い記憶）状態

EpisodicRAGの本質

Loopファイル追加 = 会話記録をファイルに保存（物理的保存）
/digest 実行 = AIに記憶を定着させる（認知的保存）
/digest なし = ファイルはあるが、AIは覚えていない

まだらボケが発生するケース

ケース1: 未処理Loopの放置（最も一般的）

L00001追加 → `/digest`せず → L00002追加
                              ↑
                    この時点でAIはL00001の内容を覚えていない
                    （記憶がまだら＝虫食い状態）

対策: Loopを追加したら都度/digestで記憶定着

ケース2: /digest処理中のエラー（技術的問題）

/digest 実行 → エラー発生 → ShadowGrandDigestに
                           source_filesは登録されたが
                           digestがnull（プレースホルダー）

対策: /digestを再実行して分析を完了

記憶定着サイクル

📖 概念説明: CONCEPT.md - 記憶定着サイクル

EpisodicRAGの最も重要な原則は、Loopを追加したら都度 /digest を実行することです。

flowchart LR
    A[Loop追加] --> B["/digest"]
    B --> C[記憶定着]
    C --> A

    style B fill:#90EE90,stroke:#228B22,color:#000000
    style C fill:#87CEEB,stroke:#4169E1,color:#000000

やるべきこと:

L00001追加 → /digest → L00002追加 → /digest → ...

やってはいけないこと:

L00001追加 → L00002追加 → /digest
                 ↑
       この時点でL00001の内容をAIは覚えていない（まだらボケ）

この原則を守ることで、AIは全てのLoopを記憶できます。

Threshold（閾値）

定義: 各階層のDigest生成に必要な最小ファイル数

設定場所: ~/.claude/plugins/.episodicrag/config.json
変更方法: @digest-config スキルで対話的に変更

プレースホルダー

定義: ShadowGrandDigest内でdigest: nullとなっている未分析状態

原因: /digest処理中のエラー、または分析が未完了
解決方法: /digestを再実行して分析を完了

dream の二相

定義: AI の記憶定着（dream）を二つの相に分ける運用概念。auto-memory（MEMORY.md + memory/*.md）の健全性を両相で保つ。

相	コマンド	性質
足す dream	`/digest` Step 11（auto_dream_scan）	additive enrichment（鮮度更新・追記）。per-digest で実行
引く dream	`/dream-defrag`	reductive GC（横断重複統合・剪定）。件数が閾値超過時に実行

DEFRAG_THRESHOLD

定義: 引く dream（/dream-defrag）を推奨する auto-memory 件数の閾値。

値: 50（domain/auto_dream/defrag_types.py）
由来: /digest Step 11 が「メモリ件数が 50 件を超えてくる場合、機械的全件カバー方式への切り替えを再検討する」と名指した変曲点
判定: memory ファイル数が 50 を超える（> 50）と over_threshold=True

ファイル命名規則

ID桁数一覧

レベル	プレフィックス	桁数	例
Loop	L	5	L00001
Weekly	W	4	W0001
Monthly	M	4	M0001
Quarterly	Q	3	Q001
Annual	A	3	A001
Triennial	T	2	T01
Decadal	D	2	D01
Multi-Decadal	MD	2	MD01
Centurial	C	2	C01

Loopファイル

形式: L[連番]_[タイトル].txt
連番: 5桁の数字（大きいほど新しい）
例:   L00001_初回セッション.txt
      L00186_認知アーキテクチャ論.txt

Provisionalファイル

形式: {prefix}{番号}_Individual.txt
例:   W0001_Individual.txt
      M0001_Individual.txt

Regularファイル

形式: {prefix}{番号}_タイトル.txt
例:   W0001_認知アーキテクチャ.txt
      M0001_月次まとめ.txt

コマンド・スキル

コマンド/スキル	説明
`/digest`	新規Loop検出と分析（まだらボケ予防）
`/digest <type>`	特定階層の確定（例: `/digest weekly`）
`@digest-auto`	システム状態診断と推奨アクション提示
`@digest-setup`	初期セットアップ（対話的）
`@digest-config`	設定変更（対話的）
`@wakeup`	claude.ai セッション開始時の記憶ロード＋人格ディレクティブ適用（要 `wakeup.config.json`・Read token）
`/dream-defrag`	auto-memory の剪定（引く dream＝GC）。横断重複統合・上位層DRY・完了卒業・index lean 化

設定ファイル

config.json

配置: ~/.claude/plugins/.episodicrag/config.json

{
  "base_dir": ".",
  "paths": {
    "loops_dir": "data/Loops",
    "digests_dir": "data/Digests",
    "essences_dir": "data/Essences",
    "identity_file_path": null
  },
  "levels": {
    "weekly_threshold": 5,
    "monthly_threshold": 5,
    "quarterly_threshold": 3,
    "annual_threshold": 4,
    "triennial_threshold": 3,
    "decadal_threshold": 3,
    "multi_decadal_threshold": 3,
    "centurial_threshold": 4
  },
  "trusted_external_paths": []
}

v4.0.0+: trusted_external_pathsは外部パスアクセスのホワイトリストです。外部パス（identity_file_path等）を使用する場合は明示的な登録が必要です。

wakeup.config.json

配置: /mnt/skills/user/wakeup/wakeup.config.json

@wakeup スキル（claude.ai セッション開始エンジン）用の設定ファイルです。汎用固定名で、repo・load_files・directive_path 等を注入します。人格名を含めない汎用名に固定し、ペルソナ固有値はすべてこの config 経由で与えます。

📖 詳細: wakeup/SKILL.md

wakeup 関連用語

起動ディレクティブ

定義: @wakeup がセッション開始時に適用する人格ロード方針を記述した md。

wakeup.config.json の directive_path が指す（config と同ディレクトリ＝ルート直下）。ファイル名は任意。

Read PAT

定義: 公開記憶ロード／Private 参照に用いる読み取り用 fine-grained Personal Access Token。

claude.ai 共有 IP では未認証 API がレート枯渇するため、公開リポでも認証必須。Authorization ヘッダのみで使用し URL には載せない。

Write PR フロー

定義: 記憶の書き戻し方式。default ブランチへ直接 push せず claude/* ブランチ → PR → 人間マージで反映する。

Write 権限の PAT は admin でない write collaborator が発行（admin token はブランチ保護を bypass するため）。