# エージェント向けメモリ機構の外部事例

調査日: 2026-04-21。本ドキュメントはユーザー依頼の3ソース（OpenAI Codex Chronicle / Shann³ の "AI Knowledge Layer" スレッド / Nous Research Hermes Agent）を中心に、直近で公開されたメモリ機構をまとめ、insomnia に入れる際の比較材料とすることを目的とする。2026年前半は各所からメモリ実装が同時多発的に登場しているので、「どの事例がどのレイヤを担っているか」を見失わないよう、各節で**何を記憶するか／いつ書くか／どう引き出すか／何に保存するか**を揃えて整理する。

数値・URLは一次ソースで再確認すること。挙動は研究プレビュー段階のものが多く、変わる前提で読む。

---

## 1. OpenAI Codex — Memories & Chronicle

Codex CLI に 2026-03 頃から追加された "Memories" 機能と、2026-04-15 頃に macOS 向け研究プレビューとして乗った "Chronicle"。スクリーン内容まで観測対象に広げた点が目新しいが、**コアは素朴な extract / consolidation の 2 段パイプライン**で、実装の示唆が多い。

### データフロー（memories 本体）

セッション開始時に走る 2-step パイプライン。`codex-rs/core/src/memories/` を直接読み確認した挙動:

- **extract — Extraction**（`extraction implementation`）: 対象 rollout ごとにモデル呼び出しで **JSON schema 強制**の `StageOneOutput { raw_memory, rollout_summary, rollout_slug }` を返させる（`#[serde(deny_unknown_fields)]`）。`CONCURRENCY_LIMIT = 8` で並列実行、結果は SQLite の `stage1_outputs` テーブルに格納。`StateRuntime` の job leasing で duplicate work 防止
  - モデル: `gpt-5.4-mini` / Low reasoning（`memories.extract_model` で override 可）
  - テンプレ: `codex-rs/core/templates/memories/stage_one_system.md` + `stage_one_input.md`
- **consolidation — Consolidation**（`consolidation implementation`）: **singleton** として走る（`jobs` テーブルで `kind = 'memory_consolidate_global'`, `job_key = 'global'` を `wx` 相当に claim）。`ConsolidationInputSelection` で前回 baseline との **added / retained / removed** 差分を計算し、その差分を prompt に埋めて sub-agent に投入
  - 出力は **自由形式 Markdown**（JSON schema なし）。sub-agent が memory_root を cwd に持ち、`MEMORY.md` / `memory_summary.md` / `skills/<name>/` を直接書き換える
  - モデル: `gpt-5.4` / Medium reasoning（`memories.consolidation_model` で override 可）
  - Heartbeat 90s / lease 3600s、失敗時 `retry_remaining` デフォルト 3
  - テンプレ: `codex-rs/core/templates/memories/consolidation.md`（836 行の詳細 instructions）
- 生成タイミングは「スレッドが十分アイドルになってから」（age + idle window で判定）
- `memory_summary.md` が **5,000 tokens cap** で system prompt に注入される（`MEMORY_TOOL_DEVELOPER_INSTRUCTIONS_SUMMARY_TOKEN_LIMIT`）

**非対称の肝**: 抽出 (extract) は structured output で分類を強制、統合 (consolidation) は sub-agent に自由書き込みさせる。分類ブレを extract で封じ、統合の柔軟性は consolidation の agentic 判断に委ねる、という役割分担。insomnia の extract / consolidation 設計の直接の元ネタ。

### 保存場所 / 形式

- `$CODEX_HOME/memories/`（既定 `~/.codex/memories/`）配下に Markdown。
- `memory_summary.md` を中心に「summaries / durable entries / recent inputs / supporting evidence」の Markdown を束ねる構成。
- Chronicle 派生メモリは `$CODEX_HOME/memories_extensions/chronicle/` に分離。
- スクリーンキャプチャ中間物は `$TMPDIR/chronicle/screen_recording/` に置かれ、running 中 6h で自動削除。サーバー側には保存しない（法的義務時を除く）。
- **Extension resource retention は決定論的 7 日 hard-coded**（`EXTENSION_RESOURCE_RETENTION_DAYS = 7`, `memories/extensions.rs:11`）。filename embedded timestamp (`%Y-%m-%dT%H-%M-%S`) が cutoff より古い `.md` リソースを consolidation 直前に物理削除し、削除リストを `removed_extension_resources` として consolidation prompt に渡す（agent はそれを見て派生メモリを抹消）。

### 設定

- `memories.generate_memories` / `memories.use_memories`: 生成 / 注入の on-off。
- `memories.extract_model`: extract に使う軽量モデル。
- `memories.consolidation_model`: consolidation のマージ側モデル（既定で reasoning 系）。
- セッション内 `/memories` コマンドでスレッド単位に無効化可能。
- シークレットは生成時に自動 redaction。

### Chronicle 固有

- 画面スクリーンショット + OCR テキスト + タイミング + ローカルファイルパスを入力に、**サンドボックス化した Codex セッション**をバックグラウンドで回して Markdown メモリを吐く。
- 「Chronicle は rate limit を激しく消費する」「画面由来の prompt injection リスクが増える」「ローカル unencrypted」が公式に注意書きされている。Pro / macOS / 非EU+UK+CH 限定。
- 可搬性の観点では、生成物が単なる Markdown ファイルでユーザーが手編集できる点が重要。

### 設計上の示唆

- **圧縮は reasoning モデルで非同期に走らせる**: 会話ループの応答性を落とさず、コストも分離する。
- **中間テーブル（SQLite）と最終出力（Markdown）の 2 段構成**: 解析容易性と人間編集性を両立。
- **5k tokens 固定注入**: 動的 retrieval ではなく "常駐 summary" として使う素朴さ。
- **拡張はサブディレクトリで**: `memories_extensions/<name>/` というパターンで観測チャンネルを増やす構造。

一次ソース:
- https://developers.openai.com/codex/memories
- https://developers.openai.com/codex/memories/chronicle
- https://deepwiki.com/openai/codex/3.7-memory-system
- https://9to5mac.com/2026/04/20/codex-for-mac-gains-chronicle-for-enhancing-context-using-recent-screen-content/

---

## 2. Shann³ "AI Knowledge Layer"

https://x.com/shannholmberg/status/2044111115878326444 で提唱している、**エージェントより先に読ませる知識層**という枠組み。エンジニア向けというよりマーケター / コンテンツ運用者向けだが、構造はかなり insomnia に転用しやすい。

### 2 層構造

- **Knowledge Base Layer (KBL) — 動的**
  - 生素材（tweet / 記事 / ブックマーク / PDF / ノート / ボイスメモ）を raw フォルダへ投げ込む。
  - 別エージェントが読んで種類別に分類、相互参照つきの構造化 wiki ページ化、マスターインデックスを維持。
  - 毎日少しずつ賢くなる前提。

- **Brand Foundation (BF) — 静的**
  - 声のルール / 視覚スタイル / ポジショニング / オーディエンス定義 / 禁則語などを**ユーザーだけが編集**。
  - エージェントは生成前に必ず BF を読む。書き換えはしない。
  - 別ソースの続編 ("Ronin runs 10 social accounts ... 17 markdown files") でも同じパターン。KBL + BF + エージェント 1 本で 10 アカウント運用している。

### ルーツ: Karpathy の llm-wiki

Shann³ の構成は Karpathy が 2026-04 に公開した `llm-wiki` gist をそのまま応用したもの。構造は 3 層：

- `raw/` — 人間のみ書き込む生ソース。
- `wiki/` — LLM 所有、page / index / glossary / log を自動維持。1 ソース取り込みで 10-15 ページが同時更新される。
- `CLAUDE.md`（または `AGENTS.md` / `GEMINI.md`）— ページ種別・ワークフロー・フォーマット・健全性チェックルールを定義するスキーマ。

運用は3種:

- **ingest**: 新規ソース投入 → 要約ページ作成 → index 更新 → entity/concept 更新 → `log.md` 追記。
- **query**: wiki を検索し citation 付きで答える。意義ある合成は `syntheses/` として保存。
- **lint**: 矛盾・stale claim・孤立ページ・参照抜け・データ欠落の定期点検。

`SamurAIGPT/llm-wiki-agent` がこのパターンを具体化しており、ディレクトリ構造が示唆的（なお `/wiki-lint` のプロダクション実装としては OpenClaw `memory-wiki` extension があり、§4 / §9 で触れる）：

```
wiki/
├── index.md          (全ページのカタログ)
├── log.md            (append-only 作業記録)
├── overview.md       (生きた合成ビュー)
├── sources/          (原文1つ = 1サマリ)
├── entities/         (人・会社・プロジェクト)
├── concepts/         (考え方・フレーム・手法)
└── syntheses/        (query 回答をページ化)
graph/
├── graph.json        (SHA256 キャッシュ付きノード/エッジ)
└── graph.html        (vis.js で可視化)
```

スラッシュコマンド例:
```
/wiki-ingest raw/papers/my-paper.md
/wiki-query "what are the main themes?"
/wiki-lint
/wiki-graph
```

### LLM Wiki vs RAG という論点

MindStudio の比較記事が要点をまとめている。

- **LLM Wiki が有利**: 文書 100 本未満、構造化コンテンツ、精度・監査性重視、速度（Git で versioning できる）。
- **RAG が必要**: 1,000 本以上、非構造テキスト、open-ended な質問、未知のドメイン。
- 決定論的 wikilink retrieval と、SHA256 キャッシュで差分のみ再処理。

### 設計上の示唆

- **可変 KBL と不変 BF の分離**が強い。insomnia なら前者が Chronicle 的な自動メモリ、後者が `AGENTS.md` / 人間のガイド。
- **retrieval を埋め込みではなく決定論的 wikilink でやる**アプローチは、少量ドメインで意外と強い。
- エージェントに書かせる `log.md` と `index.md` の append-only 運用は、後で diff / git で検証しやすい。

一次ソース:
- https://x.com/shannholmberg/status/2044111115878326444
- https://x.com/shannholmberg/status/2043307903822844087 (Ronin / 17 markdown files)
- https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
- https://github.com/SamurAIGPT/llm-wiki-agent
- https://www.mindstudio.ai/blog/llm-wiki-vs-rag-knowledge-base

---

## 3. Nous Research Hermes Agent

Self-improving agent を名乗るフレーム。メモリ周りは **3 層 + クローズドな学習ループ**。

### 3 層メモリ

- **Persistent Memory**: `MEMORY.md` / `USER.md` の Markdown + SQLite + FTS5 による過去セッション全文検索。char limit が hard-coded で **`MEMORY.md` 2,200 chars / `USER.md` 1,375 chars**（合計 ≒ 1,300 tokens）、system prompt 起動時スナップショット
- **Skill Library**: 複雑タスクの帰結として skill 化。`agentskills.io` 標準準拠（§5）、`~/.hermes/skills/<name>/SKILL.md` に保存。`skill_manage` tool (action: create/patch/edit/delete/write_file/remove_file) 経由で agent が自ら CRUD する
- **User Model (Honcho)**: "dialectic user modeling" でセッションを跨いでユーザー像を蓄積（外部 Honcho サービス連携）

### 学習ループ（`run_agent.py` 実装より）

既存 ref の「5 + tool call で自律生成」「15 tool call ごと reflection」は誤り。実装を読むと:

- `_skill_nudge_interval = 10`（デフォルト、設定可）で **skill review**、`_iters_since_skill` がツール呼び出しのたび increment
- memory nudge は別に **10 turns** で発火
- 閾値超過で **background thread に別 AIAgent を fork**（max_iterations = 8）、review prompt を与える
- レビュー本体は **1 LLM call** の自由形式、続いて agent が必要なら `skill_manage` / `memory` tool を呼んで書き戻す
- review prompt 原文（`_SKILL_REVIEW_PROMPT`, `run_agent.py:2738-2746`）:
  > Review the conversation above and consider saving or updating a skill if appropriate.
  > Focus on: was a non-trivial approach used to complete a task that required trial and error...
  > **If nothing is worth saving, just say 'Nothing to save.' and stop.**
- 末尾の "Nothing to save." 指示が肝。頻繁発火でも中身ゼロの場合は NOP で抜ける設計。insomnia extract の「空配列許容」の直接ソース

### 書き込み機構

- `skill_manage` tool: OpenAI function-calling schema。frontmatter YAML 検証、security scan、atomic write (temp + `os.replace()`)
- `memory` tool: target = `memory | user`、action = `add | replace | remove`。fcntl/msvcrt で file lock、entry-based rewrite
- **char limit 超過時は `add` を hard reject**（`memory_tool.py:248-259`）。エラーメッセージに `Memory at {current}/{limit} chars. Adding this entry would exceed the limit. Replace or remove existing entries first.` と明記し、LLM 側に「自分で削減してから再追加」を強制する。GC は完全に LLM agentic（決定論的 eviction は無い）、人間 offer や scoring も無い、非常にシンプルな設計
- FTS5: `messages_fts` virtual table + INSERT/DELETE/UPDATE trigger で auto-sync、CJK は LIKE フォールバック

### 実装観点

- 主要ディレクトリ: `agent/` `skills/` `tools/` `gateway/` `hermes_cli/` `tui_gateway/` `cron/` `plugins/` `optional-skills/` など
- バックエンド抽象: local / Docker / SSH / Daytona / Singularity / Modal。Daytona / Modal ではアイドル時 hibernation で永続化コストを削る
- OpenClaw からの移行: `hermes claw migrate`

### 設計上の示唆

- **"skill"＝ procedural memory として episodic / semantic から分離する**のは insomnia にとっても綺麗。Claude Code の skill と接続できる余地がある。
- **FTS5 + LLM 要約ハイブリッド**で、ベクタを入れずにそこそこ回せる事例として参考価値が高い（少量ドメインなら LLM Wiki 論と同じ示唆）。
- **Honcho 的 user model** を semantic profile として固定注入する運用は、Codex の memory summary と形式的に同じ。

一次ソース:
- https://github.com/NousResearch/hermes-agent
- https://github.com/NousResearch/hermes-agent/blob/main/README.md
- https://hermes-agent.nousresearch.com/docs/
- https://hermes-agent.nousresearch.com/

---

## 4. 周辺事例（比較のため）

### Letta / MemGPT

- 4 区画: **Message Buffer**（直近）、**Core Memory**（in-context の編集可能 block: user prefs / persona）、**Recall Memory**（全履歴の検索）、**Archival Memory**（ベクトル or グラフ DB に外部化された宣言的知識）。
- OS メタファ: context window = RAM、外部ストア = Disk。エージェントが function call で階層間を移動させる。
- memory block = `{label, description, value, char_limit}`。
- **sleep-time agent** が idle 中に非同期で block を書き換える。主要 agent と **別 process で並列**に走り、`core_memory_replace` / `core_memory_append` / archival tool 群を呼んで **直接 memory block を書き換える**。主 agent のターン処理をブロックしないため、「mid-session で memory 品質を上げる」のが特徴。
- context 限界近くで要約による eviction → 再帰要約で古いメッセージを累進圧縮。**eviction 判断は context window fill の決定論的しきい値**で発火するが、要約の内容生成は LLM。evicted message は recursive summary として memory block に残り、古いほど重みが相対的に下がる。

### Cloudflare Agent Memory (2026-04 Agents Week)

- 分類: **Fact / Event / Instruction / Task**（Task のみベクトル索引除外）。
- 基盤: Durable Objects（プロファイル毎の SQLite、FTS・supersession chain・tx write を担う）、Vectorize（セマンティック）、Workers AI（Llama 4 Scout: 構造化、Nemotron 3: 自然文合成）。
- **Supersession chain は決定論的**（公式 blog 再確認）: Fact / Instruction は classification pipeline で **normalized topic key** が振られ、同 key の新 memory が来ると旧 memory を **supersede（物理削除せず forward pointer で版チェーン化）**。LLM 判断は入らない。superseded 側の vector は並行して削除され、新 vector が upsert される。SHA-256 content-addressed ID で `INSERT OR IGNORE` による冪等 dedupe も併用。
- API:
  ```javascript
  const profile = await env.MEMORY.getProfile("my-project");
  await profile.ingest([messages], { sessionId });
  await profile.remember({ content, sessionId });
  const results = await profile.recall("query");
  ```
- Ingest は 10k 文字チャンク + 2 メッセージ重複、並行 4 チャンク。Verification が 8 種類（entity / temporal / factual 支援）。
- Retrieval は 5 経路並行（FTS Porter stemming / exact fact-key / raw message / ベクトル直 / HyDE）を Reciprocal Rank Fusion でマージ。fact-key 優先、recency タイブレーク。時制クエリは regex + 算術で決定論的処理。
- SHA-256 content-addressed ID で冪等。
- 「メモリはあなたのもの」エクスポート前提。

### LinkedIn Cognitive Memory Agent (CMA)

- 3 層: **Episodic**（対話履歴）/ **Semantic**（構造化事実）/ **Procedural**（学習済みワークフロー）。
- 共有メモリ基盤として planner / reasoner / executor 複数エージェントが同じ層を参照。
- Recent context retrieval + semantic search + summarization compaction で階層管理。
- 高 stake 用途は human validation フローを挟む。

### OpenClaw

Peter Steinberger が 2025-11 に出したメッセージングファースト agent。2026-02 に本人は OpenAI 入社、プロジェクトは foundation へ移譲。Hermes Agent の `hermes claw migrate` はここからの移行導線。設計は **Markdown ファイルのみに全状態を持つ**という極端な透明性志向で、insomnia の「ファイル + git」方針との親和性が最も高い。

Agent Workspace（`~/.openclaw/workspace/`）構成:

| ファイル | 役割 |
|----------|------|
| `AGENTS.md` | 運用指示とメモリ使用ガイドライン |
| `SOUL.md` | ペルソナ・口調・境界 |
| `USER.md` | ユーザー識別と呼称の好み |
| `IDENTITY.md` | エージェント名・絵文字 |
| `TOOLS.md` | ローカルツールのメモ |
| `MEMORY.md` | 長期記憶（durable facts / preferences / decisions）。DM セッション起動時に常駐ロード |
| `memory/YYYY-MM-DD.md` | 日次ノート。**当日 + 前日のみ**自動ロード |
| `DREAMS.md` | dreaming sweep の人間レビュー用サマリ（任意） |
| `skills/` | workspace 固有 skill override（最高優先） |

エージェントが触るツール:

- `memory_search`: 文言違いでも引ける semantic search
- `memory_get`: ファイル or 行範囲の読み取り

メモリ更新のタイミング（`extensions/memory-core/src/` 実装より）:

- **Compaction 前の silent turn**: `before_agent_reply` フックで `DREAMING_SYSTEM_EVENT_TEXT` を検出、`runShortTermDreamingPromotionIfTriggered` が発火。エージェントへの write-back 指示ではなく、**後述の dreaming pass をインラインで走らせる**仕組み
- **Dreaming pass (optional)**: 実体は **3 passes** (Light + Deep + REM)、cron default `"0 3 * * *"` UTC
  - **Light**: 最近の recall / daily / session signals を short-term store に ingest + narrative 生成（**subagent LLM call 1 回**、`NARRATIVE_SYSTEM_PROMPT` で poetic な dream diary）
  - **Deep**: `applyShortTermPromotions()` が promotion を決定。**LLM call ゼロ**、以下の 6 重みスコアと 3 ゲートで機械判断
    - 重み: frequency (0.24) / relevance (0.30) / diversity (0.15) / recency (0.15) / consolidation (0.10) / conceptual (0.06) + pass boost
    - ゲート: `minScore 0.8` / `minRecallCount 3` / `minUniqueQueries 3`
  - **REM**: テーマ反映 + narrative LLM call 1 回
  - promotion 通過項目のみ `MEMORY.md` に append、`DREAMS.md` に人間レビュー用 diary
- **書き込み制約**: `MEMORY.md` は hardcoded path、`memory/YYYY-MM-DD.md` のみ許可（regex `SHORT_TERM_PATH_RE`）。エージェントへ expose されているのは `memory_search` / `memory_get` の **read-only**。書き込みは系統内部のみ
- **Lock**: `memory/.dreams/short-term-promotion.lock` を `wx` フラグで exclusive create、60s stale 検出 + 10s wait timeout、in-process の Map も併用
- **モデルが "覚えている" のはディスクに書かれた内容だけ**、という明示ポリシー。隠れた state 無し

**insomnia にとって重要**: consolidation を LLM 依存から切り離せる見本。narrative は subagent が生成するが、promotion の判断は純機械（scoring）。insomnia の plan では Scope 外（consolidation は当面 agent 委任）だが、成熟したカテゴリから決定論的 promotion に差し替える upgrade path の参考になる。

**GC 観点の追加詳細**（`extensions/memory-core/src/short-term-promotion.ts:1518-1652` 実装より）:

- `applyShortTermPromotions()` は **append 専用**。gate 通過候補の snippet を `MEMORY.md` 末尾に `<!-- openclaw-memory-promotion:<hash> --> ` marker 付きで追記するだけで、既存 `MEMORY.md` ブロックの書き換えや削除は一切行わない
- **重複回避**: marker set を先読みし、既に書かれた key はスキップ
- **汚染検出**: `isContaminatedDreamingSnippet()` で dreaming narrative prompt が snippet に混入している候補を promotion 前に弾く（再帰汚染防止）
- **日次ノートの decay は物理削除ではなく search score 減衰のみ**（`memory/temporal-decay.ts`）。`halfLifeDays = 30` で `exp(-ln2/HL * age)` を score に乗じる。対象は `memory/YYYY-MM-DD.md` 形式のファイル限定で、`MEMORY.md` や topic ファイルは evergreen 扱い（減衰しない）
- **自己参照汚染の退避**: `dreaming-repair.ts` は dreaming narrative が session corpus や `DREAMS.md` に逆流した場合を検出し、該当ファイルを `.openclaw-repair/dreaming/<timestamp>/` に **rename で退避**（削除ではない）。lint と同じく audit-first の GC スタイル
- `MEMORY.md` 側の GC（重複 block の統合、stale record の drop 等）は **この extension には存在しない**。書き込みは promotion の append のみで、ユーザーが手で消すか `memory-wiki` lint のレポート経由で扱う

OpenClaw は「**削除は人間、script は append と退避まで**」という強い原則が貫かれている。

設計上の示唆:

- Workspace = git リポジトリ 1 本で完結、配置もフラット。insomnia の pod workspace 概念にそのまま借用できる。
- 秘密は workspace **外**の `~/.openclaw/` 側（auth / credentials / session transcripts / managed skills）に退避する分離設計は、pod sandbox 境界を越えない運用の手本になる。
- `memory/YYYY-MM-DD.md` の日次切り分け + 「当日+前日のみ load」は、時系列の自然減衰を Markdown で素直に表現できる良い pattern。

### LangChain Agent Builder memory（参考）

- 記事は 301 redirect のため未取得。`https://www.langchain.com/blog/how-we-built-agent-builders-memory-system` に原文あり。semantic / episodic / procedural 三分類は共通。

一次ソース:
- https://www.letta.com/blog/agent-memory
- https://blog.cloudflare.com/introducing-agent-memory/
- https://www.infoq.com/news/2026/04/linkedin-cognitive-memory-agent/
- https://github.com/openclaw/openclaw/blob/main/docs/concepts/memory.md
- https://docs.openclaw.ai/concepts/agent-workspace
- https://en.wikipedia.org/wiki/OpenClaw

---

## 5. Agent Skills 標準（procedural memory の実装単位）

Hermes / OpenClaw / Claude Code / OpenAI Codex / Cursor / GitHub Copilot 等が揃って採用している **`agentskills.io` オープン標準**。Anthropic が 2025-12 に発表し、2026-03 時点で事実上の共通フォーマットになっている。memory 設計の「手続き的記憶 (procedural memory)」のほぼ全てがこの単位で流通するので、insomnia でも独自フォーマットを避けて素直にこれに乗るのが合理的。

### SKILL.md の最小仕様

```
skill-name/
├── SKILL.md          # 必須: frontmatter + Markdown 本文
├── scripts/          # 任意: 実行可能コード
├── references/       # 任意: 詳細ドキュメント
└── assets/           # 任意: テンプレ・画像・lookup など
```

```markdown
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---
```

frontmatter 仕様:

| Field | 必須 | 制約 |
|-------|------|------|
| `name` | ○ | 64 字以下、小文字英数とハイフンのみ、親ディレクトリ名と一致 |
| `description` | ○ | 1024 字以下。**何をするか + いつ使うか**の両方を含める |
| `license` | ― | 任意 |
| `compatibility` | ― | 500 字以下。env 依存（特定 CLI / Python 3.14+ 等）がある場合 |
| `metadata` | ― | 任意 key/value |
| `allowed-tools` | ― | 実験的。space-separated `Bash(git:*) Read` 等 |

### Progressive disclosure（これが核）

Skill は 3 段でロードされる:

1. **Metadata (~100 tokens)**: `name` + `description` のみ、全 skill が起動時に常駐
2. **Instructions (<5k tokens 推奨)**: skill が発動した時に本文がロード
3. **Resources**: `scripts/` `references/` `assets/` は必要時のみ個別に読まれる

→ **常駐コストは「名前 + 一行説明」だけ**で、本体は遅延ロード。これがメモリ設計における宣言的知識 (LLM Wiki の `index.md` 常駐) と完全に同型で、**知識 / skill を同じ「目次のみ常駐・本体リンクで遅延」モデルに統一できる**。

### Claude Code の拡張

標準 + α として Claude Code が独自に足している項目:

- `disable-model-invocation: true`: ユーザーしか起動できない（deploy / commit 等の副作用ありタスクに使う）
- `user-invocable: false`: エージェントしか起動しない（背景知識用。`/` メニューから隠れる）
- `paths: ["src/**/*.ts"]`: **ファイル glob マッチ時のみ自動発動**。関心スコープを暗黙に絞る
- `context: fork` + `agent: Explore`: サブエージェントの fork context で実行（isolated context）
- `allowed-tools`: skill 有効時だけ事前承認されたツール
- `hooks`: skill ライフサイクルにフックを紐付け
- `$ARGUMENTS` / `${CLAUDE_SESSION_ID}` / `${CLAUDE_SKILL_DIR}` による文字列置換
- `` !`<cmd>` `` でプリプロセッサとしてシェルを走らせ、結果を本文に差し込む

Claude Code の skill 格納階層（上から優先）:

```
enterprise (managed) > personal (~/.claude/skills/) > project (.claude/skills/) > plugin (<plugin>/skills/)
```

プラグイン skill のみ `plugin-name:skill-name` の namespace を持つ。Live change detection（ディレクトリ監視）と monorepo 対応のネストディレクトリ自動検出もある。

Skill content のライフサイクルは重要で、**一度発動すると rendered 内容が会話に単一メッセージとして入り、以後再読み込みされない**。auto-compaction 時は各 skill の直近 invocation だけが冒頭 5,000 tokens 維持され、全 skill 合算 25,000 tokens の予算内で新しい順に残す。つまり「skill の本体は session 中ずっと context に居座る」前提で書く必要がある。

### insomnia への示唆

- **procedural memory は SKILL.md で表現**する。`.claude/skills/` に人間手入れの skill を置き、エージェントが自動生成する手続きは別ディレクトリ（例: `memory/skills/`）で分離、混ざらないようにする。BF/KBL 分離の原則に一致。
- **`paths:` によるスコープ絞り**は、前回議論した「Pod の所属スコープ = ディレクトリ階層」と自然に噛む。`paths: ["crates/protocol/**"]` の skill は protocol スコープの pod でだけ発動、という運用が素直にできる。
- **progressive disclosure の 3 段構造**をメモリ本体にも適用する。知識ファイル先頭に 1 行 description を YAML で持たせ、`index.md` に description だけ集約、本体は wikilink で遅延ロード、という揃え方が可能。
- 独自フォーマットを作らない。Hermes / OpenClaw / Claude Code のエコシステム skill をそのまま引き込める。

一次ソース:
- https://agentskills.io/specification
- https://code.claude.com/docs/en/skills
- https://github.com/anthropics/skills
- https://developers.openai.com/codex/skills

---

## 6. プロンプト・スキルの継続的チューニング (external author empirical-prompt-tuning)

メモリや skill の**中身を腐らせない**側の話。external author が 2025-07 頃に公開し、その後 Claude Code の SKILL として整備したメソッドで、「暗黙知の排除」を自動化する。insomnia のように skill を蓄積する設計では、**書いた直後に客観的に試す**仕組みが無いと品質が崩れていく。ここへの素直な当てはめ材料として記録。

### 基本思想

> Agent 向けテキスト指示（skill / slash command / task プロンプト / CLAUDE.md 節 / コード生成プロンプト）を、**バイアスを排した別の実行者**に動かしてもらい、**両面（実行者の自己申告 + 指示側メトリクス）**で評価して反復改善する。

書き手が自分で評価すると "こういう意図だったから" のバイアスで通ってしまう。だから毎反復ごとに **新規サブエージェント** に dispatch して、結果を構造化報告させる。

### 7 ステップ

1. description と body の整合性チェック（description 1024 字制約もここで効く）
2. baseline: 要件チェックリスト + シナリオ（典型 1 + edge 1-2）を固定
3. 新規 subagent で実行
4. 両面評価
5. 最小 patch で 1 箇所だけ直す
6. 新規 subagent で再実行
7. 収束判定

### 実行 AI に出させるレポート形式

- 成果物
- 要件達成（[critical] は最低ライン明記）
- **不明瞭だった点**
- **裁量で補完した箇所**
- 再試行回数

### 指示側メトリクス（機械抽出）

Claude Code の Task tool 戻り値から:
- `tool_uses` 数
- `duration_ms`
- 要件チェックリスト達成率（critical / non-critical 別）

### 収束判定

> 連続 2 回で新規不明瞭点ゼロ、精度の伸び ≤3pt、step 分散 ±10%、実行時間 ±15%

シナリオは hold-out を用意して過適合検出、評価基準の後付け修正は無効化扱い。

### クリティカルな制約

> 毎回**新規** AI を dispatch すること。同じセッション再利用は前回の指摘を学習してしまい、指標が腐る。

### insomnia への示唆

- **skill や lessons を新規追加した直後に、同じ insomnia ハーネス内の別 pod で実行して評価**する自動フロー（"skill doctor" 的な存在）を作れる。これは insomnia が pod factory を持っている点と相性がいい。
- 失敗ログを書いた後、「同じ失敗が再現しないか」を新規 pod で試走する検証ステップが、構造的に**メモリ整備の一部**に組み込める。skill 化しない失敗ログでも有効。
- 評価指標を自前で定義しておくと、後で他人（or 未来の自分）が skill を更新した時に腐敗検知できる。
- 実体は skill 自身として配布されている（`public skill example/dot_claude/skills/empirical-prompt-tuning/SKILL.md`）。insomnia のメンテ用 skill セットのテンプレにそのまま借りられる。

一次ソース:
- https://zenn.dev/external author/articles/empirical-prompt-tuning
- https://github.com/public skill example/blob/main/dot_claude/skills/empirical-prompt-tuning/SKILL.md

---

## 7. パターン抽出

上記を一枚にすると、2026 年現在のメモリ実装はだいたい以下の次元の組み合わせに収まる。

| 次元 | 主な選択肢 |
|------|-----------|
| 分類軸 | 宣言的知識 / エピソード / 手続き(skill) / プロファイル の 2〜4 層 |
| 抽出タイミング | ターン内（write-back）/ セッション終了（rollup）/ 完全非同期（sleep-time agent, bg chronicle） |
| 圧縮方式 | 要約 eviction / recursive summarization / consolidation pass / 差分更新 wiki |
| 保存形式 | Markdown ファイル群 / SQLite (+FTS) / Vector store / Graph DB |
| 取り出し方式 | 常駐注入(summary fixed) / 決定論的 wikilink / FTS / ベクトル / HyDE / RRF 融合 |
| ユーザー編集性 | 不可視 / 読取のみ / 手編集前提 |
| スコープ | per-user / per-project / shared across agents |

insomnia で意思決定すべきポイントはこの対応表：

- **Pod / Agent の「skill」概念を Hermes 風に明示すべきか**。現状の controller.rs には "sub-agent spawn" はあるが、skill を書き出して再利用する仕組みは無い。
- **Codex Chronicle 風の "consolidation モデルを別途設定" 構成**は、insomnia の llm provider policy（Ollama / Codex OAuth / Anthropic）と相性が良い。軽量 extract と重い consolidation を別プロバイダに張れる。
- **LLM Wiki パターンを採用する場合**、既に `docs/` と `tickets/` が Markdown + git で運用されているので、`memory/` ディレクトリを足して Git で可観測にしておくのが自然。RAG やベクトル化より先に、wikilink / index.md / log.md で足りるか見極めるべき。
- **storage 層**: SQLite は既存 crate 構成にもフィット。Cloudflare Agent Memory / Codex の SQLite + 最終 Markdown の 2 段は移植しやすい。
- **prompt injection 対策**: Chronicle が注意書きしている通り、観測チャンネルを増やすと攻撃面が広がる。insomnia では pod の sandbox 境界とメモリ生成を同じ境界で括る必要がある。

---

## 8. GC 機構の横断比較

`docs/plan/memory.md` §GC は「consolidation とは別経路で memory を再評価し、drop / merge / split / `replaced` chain 整理を行う」ことを決めた段階で、判断主体と処理種別の仕様をこれから詰める。本節は他プロジェクトの GC 設計を共通の 6 軸で並べて、insomnia で採るべき型の材料とする。

### 8.1 比較表

対象の行は「その system が実装している GC 機構」単位で、同じプロジェクトが複数機構を持つ場合は複数行にした。

| # | プロジェクト / 機構 | 対象 | トリガー | 判断主体 | 処理種別 | 人間介入点 | 履歴保持 |
|---|---------------------|------|----------|----------|----------|-----------|---------|
| 1 | Codex consolidation | `MEMORY.md` block / `memory_summary.md` / `skills/*` | session idle + age | **LLM agentic**（sub-agent） | drop / merge / split / rewrite、removed thread id に紐づく block を **部分削除**（block 丸ごとは消さない、thread-local 記述のみ除去） | 無し（`/memories` で thread 単位 opt-out のみ） | git 任意、memory_root は単なる Markdown |
| 2 | Codex extension resource retention | `memories_extensions/<name>/resources/*.md` | consolidation 実行直前に cron 相当 | **決定論** | **物理削除** （filename timestamp cutoff） | 無し | 完全消去、consolidation prompt に removed list を通知 |
| 3 | Codex stage1 pruning | `stage1_outputs` SQLite row | consolidation 後 / 容量超過 | **決定論** | `selected_for_consolidation = 0` の古い row を cutoff + `LIMIT` で DELETE | 無し | SQL 完全削除 |
| 4 | Hermes `memory` tool | `MEMORY.md` / `USER.md` のエントリ | **char limit (2,200 / 1,375) 超過時の add 拒否** | **LLM agentic**（エラー受けて自分で `replace` / `remove` を呼ぶ） | drop / rewrite | 無し（all-agent） | ディスク消去（file lock で tx 化） |
| 5 | Hermes background review | entry / skill | turn / iter カウンタ（10 デフォルト） | **LLM agentic**（fork agent、max_iterations = 8） | add / update / delete をレビュー判断、`Nothing to save.` で no-op | 無し | same as 4 |
| 6 | OpenClaw `applyShortTermPromotions` | promotion candidate → `MEMORY.md` | Deep dreaming phase | **決定論**（6 重み合算 + 3 ゲート、LLM ゼロ） | **append のみ**（`<!-- openclaw-memory-promotion:<hash> -->` marker、既存 block は触らない） | 無し | 追記のみ、削除系統は別 |
| 7 | OpenClaw temporal decay | `memory/YYYY-MM-DD.md` | search 呼び出し毎 | **決定論** | **物理削除せず search score 減衰**（half-life 30d） | 無し | ファイル残置、検索順位だけ沈む |
| 8 | OpenClaw dreaming-repair | `DREAMS.md` / session-corpus / session-ingestion | 手動 + audit CLI | **決定論** | **archive 退避**（`.openclaw-repair/dreaming/<timestamp>/` に rename）、完全削除しない | 退避後は手動判断 | archive ディレクトリに rename で保持 |
| 9 | memory-wiki `/wiki-lint`（OpenClaw extension、SamurAIGPT/llm-wiki-agent と Karpathy llm-wiki の production 実装） | wiki page / claim | `/wiki-lint` 手動 or cron 想定 | **決定論**（issue 検出ロジック） + その後の **human/LLM 任意判断** | **削除ゼロ**、`reports/lint.md` に issue を書き出すのみ。修正は別コマンド / 人間が行う | 全出力点が人間承認 | 原ファイル無変更、report は上書き |
| 10 | Cloudflare Agent Memory supersession | Fact / Instruction row（Durable Object SQLite） | 新 memory ingest 時 | **決定論**（normalized topic key が一致した瞬間） | **supersede**（旧 row を forward pointer で版チェーン化、物理削除せず）、vector は非同期 delete + new upsert | 無し（全自動） | SQLite に旧版残置、version chain で参照可能 |
| 11 | Letta sleep-time agent | in-context memory block | 非同期 idle process | **LLM agentic** | `core_memory_replace` / `core_memory_append` / archival 移動で block 書き換え | 無し | 書き換え後の block が保存、旧 block は失われる |
| 12 | Letta recursive summarization | message buffer | **context window fill の決定論閾値** | 発火は決定論 / 要約内容は LLM | evict + 再帰要約（古いほど重み減） | 無し | 要約に畳み込まれる（原メッセージは消失） |
| 13 | LinkedIn CMA（公開情報レベル） | Episodic / Semantic / Procedural 各層 | 未公開 | 未公開 | **summarization による compaction**（階層別の drop 仕様は非公開、"cache invalidation is one of the hardest problems" と明示） | **高 stake 用途は human validation** を挟む | 非公開 |

### 8.2 軸別の知見

**対象（何が GC されるか）の粒度差**:

- 最小粒度の Hermes（entry）と Cloudflare（row）は、LLM がエントリ単位で `remove` / `replace` する設計に寄る。
- 中粒度の Codex（`MEMORY.md` block）は、block 内を thread id で部分削除しながら必要なら split / rewrite する agentic 寄り。
- 最大粒度の OpenClaw / memory-wiki は **ファイル単位でのみ削除 / 退避** し、file 中身は LLM / 人間に委ねる。`docs/plan/memory.md` の「1 件 1 ファイル」方針とは **OpenClaw の粒度が最も近い**。

**トリガー（いつ GC するか）の 4 パターン**:

1. **容量超過 hard reject**（Hermes）: 追加要求を失敗で返して LLM に自律対処を強制。**決定論的 trigger + agentic 処理**で、設計最小コスト。
2. **session idle + age**（Codex consolidation）: 人間の活動終了を待って非同期、最もユーザー体感を壊しにくい。
3. **cron / scheduled sweep**（OpenClaw dreaming default `0 3 * * *`, Codex extension retention）: 定期的・予測可能。人間 review との組み合わせがしやすい。
4. **ingest 時の即時**（Cloudflare supersession）: 書き込みの tx 内で完結、後続 GC 走査が要らない。topic key 設計が前提。

insomnia の plan は (2) consolidation で rewrite 許可を置きつつ、GC は (3) 方向で別経路という構造。これは Codex / OpenClaw の両方と整合する。

**判断主体の 3 系統**:

- **決定論のみ**: Codex retention / stage1 pruning / OpenClaw temporal decay / Cloudflare supersession / lint 検出。条件がはっきりしているもの（age / key 一致 / 構造的 issue）は決定論が強い。
- **決定論 scoring → 閾値 gate → 機械適用**: OpenClaw Deep promotion。LLM の揺れを除き、コストも LLM コールゼロ。ただし対象が append 側のみで、削除には使われていない。
- **LLM agentic**: Codex consolidation / Hermes review / Letta sleep-time。判断の柔軟性（block 内部分削除、context 依存の merge）を LLM に委ねる。

`docs/plan/memory.md` は consolidation が LLM agentic、GC も暫定的に **LLM agentic + Linter Warn 併用**としている。完全に一致する事例は **Codex consolidation の consolidation prompt**（836 行）で、「removed thread id を `MEMORY.md` から部分削除し、blockに他の thread が残っている場合は split / rewrite して保持」という手続きを自然言語で指示している。**insomnia は Linter 側に警告カテゴリ（類似 slug / `replaced` 滞留 / sources 過多 / stale）を先に定義し、GC 実行の agent プロンプトはそれを入力にする**構造が素直。

**処理種別の選択肢**:

- `drop / merge / split / rewrite` の組み合わせは Codex consolidation が最も自由度高く、Hermes もそれに近い（entry 粒度）。
- `replaced` chain の整理は **Cloudflare だけが自動で版チェーン維持**、他は LLM 任せ。insomnia は decision record に `replaced_by` を入れているので、Cloudflare 方式の forward pointer 概念を **人間可読な `replaced_by:` frontmatter** で既に踏襲している。GC 時に chain をどこまで短く畳むか（長大な `a → b → c → d` を `a → d` に圧縮するか）は未決定論点で、Cloudflare は圧縮せず chain を保持する設計。
- **`split` は Codex だけが明示**。block 内に複数 thread id が混ざった場合に thread id 単位で分ける。insomnia の「1 件 1 ファイル」方針では split = ファイル分割となり、主題の粒度判断は GC agent に委ねる必要がある。

**人間介入点の 3 段**:

- 完全無介入: Codex / Cloudflare / Letta / Hermes
- audit-first（issue を surface し、人間が決断）: memory-wiki lint / OpenClaw dreaming-repair
- high-stake 限定 gate: LinkedIn CMA

insomnia の plan は「人間 offer 承認を併用」なので **audit-first に寄る**のが自然。lint 相当の Warn を Linter で出し、LLM consolidation / GC がそれを消費する前に人間が承認 / 拒否できる UI を提供する構造。memory-wiki lint は `reports/lint.md` というシンプルな Markdown 出力なので、そのまま `memory/reports/gc-lint.md` 相当を tick off する実装が参考になる。

**履歴保持の 3 モデル**:

1. **物理削除**: Codex retention / stage1 / Hermes / Letta（要約で畳む分は実質消失）
2. **archive 退避（rename）**: OpenClaw dreaming-repair
3. **forward pointer / tombstone**: Cloudflare supersession

insomnia は **git 管理下に memory を置く**前提なので、物理削除を選んでも git log で復元できるのが強み。`replaced_by:` frontmatter が forward pointer の役割を果たしているので、Cloudflare 型と git を足した「**現物は物理削除、frontmatter pointer で chain を参照、git で history**」が最も設計コストに合う。archive 退避は git を前提にすると冗長。

### 8.3 insomnia の GC 仕様を詰めるときの示唆

1. **GC trigger は 2 系統に割る**。(a) 決定論: Linter Warn 群 + age / count / size 閾値の sweep、(b) LLM 判定: consolidation とは別 prompt で Linter の issue リストを入力に渡す。両方が `memory/reports/gc-*.md` 相当を書き、それを次回の GC run が読む、というフィードバックループが OpenClaw lint / Codex consolidation input selection の両方と整合する。
2. **Linter に「GC 候補検出」カテゴリを足す**。memory-wiki の lint issue code が参考になる: `stale-page`（90d 超）/ `stale-claim` / `low-confidence` / `orphan` / `duplicate-id` / `broken-wikilink` / `contradiction-present` / `open-question`。insomnia 固有の追加候補: `similar-slug`（類似 slug 乱立、既に plan に記載）/ `replaced-chain-long`（`replaced_by` が 3 段以上）/ `sources-overflow`（1 record の sources が閾値超）/ `knowledge-invoke-frequency-low`（`user_invoke` が一定期間ゼロ）。
3. **処理は rewrite 優先、削除は `status: replaced` 経由**（既に plan 方針と一致）。forward pointer は Cloudflare 流、ただし chain 圧縮ルール（例: 「chain が n 段超えたら中間を drop、端のみ残す」）を決めるかは別論点。Cloudflare は圧縮しない、insomnia は git があるので圧縮してよい。
4. **char limit は採用しない方が筋が良い**。Hermes の hard limit + LLM self-rewrite は設計最小だが、insomnia は 1 record 1 file なのでファイル内 size 制約は薄く、file 数による grep コストの方が支配的になる。file 数閾値 → GC trigger の方が insomnia の形に合う。
5. **決定論 scoring を後から差し込む余地を残す**。OpenClaw Deep pass のような「頻度 / 関連度 / 多様性 / 時間減衰 / 整合性 / 概念」の 6 重み + 閾値は、agent LLM の出力が運用で評価可能になった段階で部分的に差し替える upgrade path として最適。初期は consolidation LLM + Linter Warn で十分。
6. **削除は git commit 単位で可逆**という前提を明示する。プロジェクトメモリは git 管理下なので、GC が誤って drop してもユーザーは revert できる。これは Codex が持っていない利点で、GC agent の判断を多少攻めても安全マージンがある。

一次ソース:
- Codex consolidation: `github.com/openai/codex/codex-rs/core/src/memories/consolidation implementation`, `core/templates/memories/consolidation.md`
- Codex retention / stage1 pruning: `github.com/openai/codex/codex-rs/core/src/memories/extensions.rs:11-139`, `codex-rs/state/src/runtime/memories.rs:290-331, 333-464`
- Hermes char limit reject: `github.com/NousResearch/hermes-agent/tools/memory_tool.py:211-266`
- Hermes review spawn: `github.com/NousResearch/hermes-agent/run_agent.py:2727-2830`
- OpenClaw promotion apply: `github.com/openclaw/openclaw/extensions/memory-core/src/short-term-promotion.ts:1518-1652`
- OpenClaw temporal decay: `github.com/openclaw/openclaw/extensions/memory-core/src/memory/temporal-decay.ts`
- OpenClaw dreaming-repair: `github.com/openclaw/openclaw/extensions/memory-core/src/dreaming-repair.ts:70-165`
- memory-wiki lint: `github.com/openclaw/openclaw/extensions/memory-wiki/src/lint.ts`, `claim-health.ts:6-7`（`WIKI_AGING_DAYS = 30`, `WIKI_STALE_DAYS = 90`）
- Cloudflare supersession: https://blog.cloudflare.com/introducing-agent-memory/
- Letta sleep-time: https://docs.letta.com/guides/agents/memory/, https://www.letta.com/blog/sleep-time-compute, arxiv 2504.13171
- Letta recursive summary: https://www.letta.com/blog/agent-memory
- Karpathy llm-wiki lint: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
- SamurAIGPT/llm-wiki-agent `/wiki-lint`: https://github.com/SamurAIGPT/llm-wiki-agent
- LinkedIn CMA: https://www.infoq.com/news/2026/04/linkedin-cognitive-memory-agent/

---

## 9. 未調査 / 次に掘るべき項目

- Letta `memory block` の Rust 実装例・永続化形式。
- `agentskills.io` の CRDT 的バージョニング方針（標準は version metadata を任意 key にしている。実運用でどう衝突解決するかは未整備）。
- Hermes の Honcho 連携の実体（外部サービス API 越しの dialectic user modeling、repo には prompt と API 呼び出しのみ）。
- LinkedIn CMA の層別 GC 仕様（公開情報では compaction-by-summarization までしか開示されていない）。
- Cloudflare supersession chain の圧縮ポリシー（chain 長の上限、vector GC と row GC の tx 境界）。
