hierarchical-agent-memory

階層型エージェントメモリ（HAM）

AI コーディングエージェントがプロンプトのたびにプロジェクト全体を読み直す代わりに、ディレクトリごとのチートシートを提供するスコープ付きメモリシステムです。ルートの CLAUDE.md にグローバルコンテキスト（約 200 トークン）、サブディレクトリの CLAUDE.md ファイルにスコープ付きコンテキスト（各約 250 トークン）を保存し、.memory/ レイヤーには決定事項、パターン、未確認の推論を格納するインボックスを保存します。

このスキルを使う場面

• Claude Code のセッション間で入力トークンのコストを削減したい場合
• プロジェクトに 3 つ以上のディレクトリがあり、エージェントが同じファイルを何度も読み直している場合
• 1 つの巨大な CLAUDE.md ではなく、ディレクトリごとにスコープを限定したコンテキストを使いたい場合
• トークン削減量、セッション履歴、コンテキストの健全性を可視化するダッシュボードを使いたい場合
• 新しいプロジェクトを立ち上げる際に、初日から構造化されたエージェントメモリを用意したい場合

利用可能性と根拠

このツリーに含まれるのはガイドのみです。HAM CLI、ダッシュボード、トークナイザーは同梱されていません。go ham と ham ... は上流のワークフローに関する慣習です。実行したり、ファイル、ダッシュボード、削減効果が存在すると主張したりする前に、実際にインストールされている、レビュー済みの実装を確認してください。コンテキストを追加する際は既存のプロジェクト指示を保持し、推論した項目は未確認のままにしてください。また、非公開のセッション履歴を読む前に、対象範囲の許可を得てください。測定されたトークン使用量は、モデル上の削減量、コスト、炭素排出量の例とは分けて報告してください。異なるタスク同士を、改善が実証された比較として扱わないでください。

仕組み

ステップ 1：セットアップ（「go ham」）

プロジェクトのプラットフォームと成熟度を自動検出し、メモリ構造を生成します。

project/
├── CLAUDE.md              # Root context (~200 tokens)
├── .memory/
│   ├── decisions.md       # Architecture Decision Records
│   ├── patterns.md        # Reusable patterns
│   ├── inbox.md           # Inferred items awaiting confirmation
│   └── audit-log.md       # Audit history
└── src/
    ├── api/CLAUDE.md      # Scoped context for api/
    ├── components/CLAUDE.md
    └── lib/CLAUDE.md

ステップ 2：コンテキストのルーティング

ルートの CLAUDE.md には、エージェントにどのサブコンテキストを読み込むべきかを正確に伝えるルーティングセクションが含まれます。

## Context Routing

→ api: src/api/CLAUDE.md
→ components: src/components/CLAUDE.md
→ lib: src/lib/CLAUDE.md

エージェントはルートを読み込んだ後、推測せずに、関連するサブディレクトリのコンテキストをすぐに読み込みます。

ステップ 3：ダッシュボード（「ham dashboard」）

localhost:7777 でウェブダッシュボードを起動し、次の情報を可視化します。

• トークン削減量（HAM を使用したセッションと使用しないセッション）
• 日ごとのトークン数とコストの推移
• ディレクトリごとのセッション内訳
• コンテキストファイルの健全性（CLAUDE.md の網羅状況：欠落、古さ、継承）
• ルーティング遵守状況（エージェントがルーティングマップに従う頻度）
• 炭素排出量／エネルギーの推定値

コマンド

トリガー	動作
go ham	HAM をセットアップします。プラットフォームを自動検出し、CLAUDE.md ファイルを生成します
ham savings	トークンとコストの削減レポートを表示します
ham dashboard	インタラクティブなウェブダッシュボードを起動します
ham audit	メモリファイルの健全性を確認します
ham insights	セッションデータから実行可能なインサイトを生成します
ham route	ルートの CLAUDE.md にコンテキストルーティングセクションを追加／更新します
ham carbon	エネルギー効率と炭素効率のデータを表示します

例

例 1：初回セットアップ

User: go ham

Agent: HAM setup complete. Created 8 files.
  - CLAUDE.md (root)
  - .memory/decisions.md
  - .memory/patterns.md
  - .memory/inbox.md
  - src/api/CLAUDE.md
  - src/components/CLAUDE.md
  - src/lib/CLAUDE.md
  - src/utils/CLAUDE.md

Baseline captured in .memory/baseline.json
Run "HAM savings" to see your token and cost savings.

例 2：削減量の確認

User: ham savings

Agent:
  Before HAM: ~7,500 tokens/prompt
  After HAM:    ~450 tokens/prompt
  Savings:    7,050 tokens (94%)

  Monthly projection (1,500 prompts):
    Sonnet: ~$31.73 saved
    Opus:   ~$158.63 saved

ベストプラクティス

• ルートの CLAUDE.md は 60 行／250 トークン未満にします
• サブディレクトリの CLAUDE.md ファイルは、それぞれ 75 行未満にします
• 古いコンテキストファイルや欠落したファイルを見つけるため、2 週間ごとに ham audit を実行します
• 新しいディレクトリを追加した後は ham route を使い、ルーティングを最新の状態に保ちます
• .memory/inbox.md を定期的に確認し、推論された項目を承認または却下します

制限事項

• トークン数の推定には、実際のトークナイザーではなく、約 4 文字を 1 トークンとする近似値を使用します
• ベースラインとの削減量の比較は、一般的なエージェントの動作に基づく推定値です
• ダッシュボードには Node.js 18+ が必要で、~/.claude/projects/ からセッションデータを読み取ります
• コンテキストルーティングの検出は、セッションの JSONL ファイルに記録された CLAUDE.md の読み込み順序に依存します
• サブディレクトリの CLAUDE.md の内容は自動更新されません。手動で更新するか、ham audit を使って管理します
• 炭素排出量の推定には地域ごとの電力網の平均値を使用し、リアルタイムのエネルギーデータは使用しません

関連スキル

• agent-memory-systems — エージェントメモリのアーキテクチャに関する一般的なパターン
• agent-memory-mcp — MCP ベースのメモリ統合