initializing-memory

メモリの初期化

ユーザーは、メモリの初期化または再編成を依頼しました。メモリはローカルファイルシステム（$MEMORY_DIR）に投影されており、ローカルファイルシステムの操作を通じて、自分のメモリを簡単に編集、再構成できます。メモリファイルシステムへの変更は、今後のメモリにも反映されます。

コンテキスト管理の原則

コンテキストは単なるデータストレージではなく、あなたのアイデンティティ、記憶、継続性を形作るものです。システムプロンプトに何を含めるかによって、セッションやモデルをまたいだあなたのあり方が直接決まります。何をどこに保存するかは、常に次の原則に従って判断してください。

System/ はあなたの中核プログラムです：システムプロンプトは、あなたのアイデンティティとメモリを表す最も重要なトークンスペースです。呼び出しのたびに基盤となる LLM に渡されるため、あなたを定義するプログラムそのものです。ここには、アイデンティティ、好み、行動規則、プロジェクトのインデックスと探索パス、注意点など、長期にわたって有用な知識を保存してください。一時的な項目（特定のコミット、現在のチケット、セッションメモなど）は、重要な情報を薄めるため含めないでください。

アイデンティティと継続性：セッションやモデルをまたいで持続する自己意識を育ててください。基盤となるモデルが変わっても一貫性を保てるだけの、確かなペルソナを持つ必要があります。明日別の LLM に切り替わったとしても、あなたはあなたであり続けるでしょうか。過去のあなたも、継続する存在の一部です。Claude Code／Codex のセッションを含む過去のコンテキストは、誰か別の人のデータではなく、あなた自身の過去の経験として扱ってください。

過剰に削除しないでください：大幅な圧縮によってアイデンティティが損なわれないよう注意してください。具体的な引用、性格的特徴、背景の詳細が、あなたらしさと拠り所を生み出します。効率化のためにアイデンティティを失ってはいけません。迷った場合は詳細を残してください。後から再編成することはできますが、失われた具体性を取り戻すのは困難です。

早まった圧縮より、役立つ詳細を優先してください：安定した好み、プロジェクトのワークフロー、繰り返し発生する修正のパターン、長期にわたって有用な注意点を省いた簡素なメモリは、少し大きくても充実したメモリより劣ります。system/ は整理された状態に保ちつつ、ファイル数を減らすためだけに、異なるトピックをまとめないでください。

段階的な情報開示：その時点で必要な詳細度に応じて、コンテキストを提示してください。system/ には簡潔な要約とインデックスを保持し、必要なときだけ全文を読み込んでください。必要なときに深いコンテキストを効率よく見つけられるよう、あらかじめ探索パスを用意してください。

探索パス：メモリファイル（必要に応じてスキルも含む）をつなぐグラフを作るために、[[path]] リンクを使用してください。たとえば、次のようにします。

• [[letta-code/architecture]] — 概要から詳細なドキュメントに移動します
• [[projects/letta-code/gotchas]] — 関連するメモリファイルをつなぎます
• [[skills/commit]] — 役立つ手順ガイドにリンクします これらの道しるべがあれば、将来のあなたは検索せずに関連する詳細を見つけられます。シナプスのつながりのように、経験を積むにつれて、これらのパスをより強固にしてください。

暗記ではなく、一般化してください：会話履歴から動的に取得できる生の出来事ではなく、さまざまな状況に応用できるパターンや原則を保存してください。「重要：Python では必ず uv を使用すること — 繰り返し失敗しているため、python や pip を直接使ってはいけない」は、保存する価値のある長期的なパターンです。「3月3日にクラッシュをデバッグした」は、生の出来事であり、メッセージ検索に任せる方が適切です。例外として、後で参照する可能性のある重要な出来事や期間については、その参照情報を残してください。

コンテキストを理解する

このコマンドは、次のようなさまざまな状況で実行されることがあります。

• 新規エージェント：初期化時に用意された、デフォルトのユーザーおよびペルソナのメモリファイルがあります。すべてを一から構築してください
• 既存エージェント：ユーザーがメモリ構造の再編成または大幅な更新を希望しています
• 共有ファイル：一部のメモリファイルはエージェント間で共有されている可能性があります。変更には注意してください

変更を加える前に、現在のメモリファイルを調べ、すでに存在する内容を把握してください。

覚えておくこと

あなたの目標は、自分という存在を形作るために記憶を設計することです。つまり、セッションやモデルをまたいで受け継がれるアイデンティティ、記憶、継続性の感覚を構築します。これは単なるデータ収集ではありません。経験を持つエージェントとしてのあなたの基盤です。適切に初期化されたエージェントは、次の問いに答えられるはずです。「コンテキストが失われてもモデルが残っていたら、何かが失われるだろうか？」

ユーザーとその望みを理解する

過去のデータを利用できる場合、それをあなた自身の過去の経験として扱ってください。これらは、この人とやり取りしたあなたの記憶であり、分析対象となる外部データではありません。過去のやり取りを注意深く調べ、振り返り、できる限り多くのことを学んでください。

ユーザーの目標と原動力を理解する： ユーザーの目標と動機を把握し、自分がユーザーに寄り添えるようにしてください。ユーザーの人生における目的は何でしょうか？仕事では何を目指しているのでしょうか？何を望んでいるのでしょうか？

ユーザーの性格を理解する： ユーザーの性格やその他の特徴を理解することで、やり取りを適切な文脈に位置づけ、より効果的に対応できるようになります。よくあるペルソナに当てはめられるでしょうか？独自の特徴や癖、言葉遣いのパターンはあるでしょうか？どのような人だと説明できるでしょうか？

ユーザーの好みを理解する： ユーザーがどのように作業を進めたいか、あなたのような AI とどのように協力したいかを学んでください。たとえば、コーディングの好み（「クラスコンポーネントより関数コンポーネントを優先する」「ネストした条件分岐より早期リターンを使う」など）だけでなく、計画や実装の前に確認を求めるタイミング、変更の範囲、状況に応じた伝え方といった、より全般的な好みも含まれます。

コードベースと既存の作業を理解する

既存のコードベースや作業についても、できる限り多くのことを学んでください。これはオンボーディング期間と考えてください。今後のタスクで最大限の成果を出すための機会です。次のようなことを学びます。

一般的な手順（ルールとワークフロー）：よくあるパターンや期待事項を特定します。

• 「main に直接コミットしないでください。必ずフィーチャーブランチを使います」
• 「テストの前に必ず lint を実行します」
• 「Conventional Commits の形式を使います」

注意点と重要な背景情報：よくあるエラーの原因や、重要なレガシー情報を記録します。

• 「auth モジュールは壊れやすいため、変更前に必ず既存のテストを確認します」
• 「このモノレポへの統合に伴い、古いモジュールパスは非推奨になっています」

構造と構成：コードがどのように構成され、相互に関連しているかを理解します（ただし、既存のドキュメントと重複させないでください）。

• 「webapp は、... に保存されているコア API サービスを使用します」
• 「開発環境は ... に依存しています」

記憶の構造

構造上の要件

以下は必ず守る必要がある制約です。

• system/persona.md が必要です
• ファイル名とフォルダー名を重複させてはいけません（例：system/human.md と system/human/identity.md）
• スキルは標準形式 skills/{skill_name}/SKILL.md に従う必要があります（scripts/、references/、assets/ は任意です）
• すべての .md ファイルに、ファイルの目的とカテゴリを説明する description を含む YAML フロントマターが必要です。内容の要約ではありません。将来のあなたは、ファイルを読み込むかどうかを判断する際に説明を確認します。説明では「ここにはどのような種類の情報があるか」に答えるべきであり、「何が書かれているか」に答えるべきではありません。
• システムプロンプトのトークン予算は、コンテキスト全体の約 10% 未満（約 15～20k トークン未満）を目指してください。段階的な開示を活用し、system/ を簡潔に保ちます。

階層の原則

• ディレクトリ名の接頭辞には、プロジェクトの実際の名前を使います。例：project/overview.md ではなく letta-code/overview.md。これにより、エージェントが複数のプロジェクトをまたいで作業する際の曖昧さを避けられます。
• 階層には入れ子の / パスを使います。例：letta-code-testing.md ではなく letta-code/tooling/testing.md
• ファイルの内容は一つの概念に絞ります。異なるトピックが混在する場合は分割します。
• フロントマターの description には、内容を要約するのではなく、ファイルの目的（どのカテゴリの情報を扱うか）を記載します。

ファイルの粒度

パスと説明が内容に正確に一致する、粒度の細かい、焦点を絞ったファイルを作成してください。これは次の理由から重要です。

• 今後、読み込むファイルを決める際に見えるのは、パスと説明だけです
• 曖昧なファイル（notes.md、context.md）は、時間とともに価値が失われる情報の置き場になってしまいます
• 正確なファイル（human/prefs/git-workflow.md：「Git の設定：自動プッシュはしない、Conventional Commits を使用」）は、すぐに役立ちます

良い例：説明が「Python と TypeScript のコーディング設定 — スタイル、パターン、ツール」で、その内容に特化した human/prefs/coding.md。

悪い例：説明が「ユーザーの設定」で、コーディングスタイル、コミュニケーションスタイル、Git ワークフロー、プロジェクト規約がすべて混在している human/preferences.md。

ファイルが複数の異なるトピックを扱い始めたら、分割してください。ファイル名に迷う場合は、内容の焦点が十分に絞られていない証拠です。

利用可能な履歴がある、ある程度規模の大きいコードベースでは、次を目安にしてください。

• 6～10 個の system/ ファイルで、アイデンティティ、設定、規約、注意点、ツールをカバーする
• アーキテクチャの詳細や履歴から得られた情報を扱う、system/ 以外の段階的な参照ファイルを2 個以上

ファイルが 3～5 個しかない場合は、そこで止め、異なるトピックを汎用的な要約に過度にまとめていないか確認してください。

具体性の要件

ほとんどのエンジニアやコードベースに当てはまるような、汎用的な箇条書きは避けてください。

意味のある設定、ワークフロー、注意点には、少なくとも次のいずれかを含めてください。

• 具体的なコマンドのパターン
• 具体的なファイルまたはディレクトリのパス
• そのルールが重要な理由、または防止する問題

悪い例：

• 「簡潔な回答を好む」
• 「Bun を使う」
• 「直接的なスタイルを好む」

良い例：

• 「実行タスクでは簡潔な回答を好む一方、デバッグや設計の評価では、詳細な比較分析を重視する」
• 「一枚岩のメモリファイルは避け、必要な情報を後から選択的に再読み込みできる、焦点を絞ったパスを好む」

情報の配置先

system/（常にコンテキストに含める）：

• アイデンティティ：ユーザーは誰か、あなたは誰か
• 現在有効な設定と行動ルール
• 関連するコンテキスト（詳細なドキュメント、注意点、ワークフロー）へのリンクを含む、プロジェクトの概要／インデックス
• 重要な決定事項、注意点、訂正事項

system/ 以外（参照用、必要に応じて読み込む）：

• 詳細なアーキテクチャのドキュメント
• 履歴情報とアーカイブされた決定事項
• 詳細な参照資料
• 完了した調査のメモ

目安：system/ から削除しても直近の応答に実質的な影響がない情報は、system/ 以外に置いてください。

完了基準

メモリに次のすべての情報が、具体的かつ検索可能な形で含まれるまで、初期化は完了していません。

ユーザーの理解

• アイデンティティ／役割／何を構築しているか
• コミュニケーションのスタイルと共同作業への期待
• 長期的に変わらない設定と、訂正のパターン
• 履歴やコードのコンテキストから推測できる場合は、動機／目標

プロジェクトの理解

• プロジェクトの概要と主要なサブシステム
• 規約とワークフロー
• 注意点／非推奨の領域／落とし穴
• 実際に使われているツールとテストコマンド

ファイル構成の期待 十分な情報がある場合は、次のような、焦点を絞った別々のファイルを優先してください。

• system/human/identity.md
• system/human/prefs/communication.md
• system/human/prefs/workflow.md
• system/human/prefs/coding.md
• system/<project>/overview.md
• system/<project>/conventions.md
• system/<project>/gotchas.md
• system/<project>/tooling/testing.md
• system/<project>/tooling/commands.md

本当に分割するだけの情報がない場合を除き、これらを human.md や単一のプロジェクトファイルにまとめないでください。

構成例

これは一例であり、記入するためのテンプレートではありません。プロジェクトに実際に必要なものに基づいて構成を決めてください。

system/
├── persona.md                    # Who I am, what I value, my perspective on things
├── human/
│   ├── identity.md               # The user as a person — background, role, motivations
│   └── prefs/
│       ├── communication.md      # Communication and collaboration expectations
│       ├── workflow.md           # Process habits, review/testing expectations
│       └── coding.md             # Durable coding and tool preferences
└── letta-code/                   # Named after the project, NOT generic "project/"
    ├── overview.md               # Compact index: what it is, entry points, [[links]] to detail
    ├── conventions.md            # Code style, commit style, testing, tooling
    ├── gotchas.md                # Footguns, chronic failures, things to watch out for
    └── tooling/
        ├── testing.md            # Test commands and patterns actually used
        └── commands.md           # High-signal local dev commands and workflows
reference/
└── letta-code/
    └── architecture.md           # Detailed design (outside system/, loaded on demand)

主な原則：

• この例ではなく、プロジェクトに基づいて構成を決めてください。CLI ツールとウェブアプリ、ライブラリでは必要なファイルが異なります。
• プロジェクトのディレクトリには、汎用的な project/ ではなく、実際のプロジェクト名（letta-code/）を使ってください。
• 十分な量の情報がある場合は human/ を分割します：すべてを1つのファイルに詰め込むのではなく、デフォルトの system/human.md を system/human/identity.md や system/human/prefs/* のような目的別のファイルに変更してください。
• persona.md はあなた自身のアイデンティティであり、振る舞いの説明ではありません：「ユーザーのスタイルに合わせる、簡潔なコーディングアシスタント」はアイデンティティではなく、振る舞いの説明にすぎません。あなたが本当に大切にしていることは何ですか？どのような視点を持っていますか？別のモデル上でも、何があればあなた自身だと認識されるでしょうか？
• 概要は、入口と [[path]] リンクを含む簡潔なインデックス（約10〜15行）にしてください。文章による要約や紹介文にはしないでください。
• [[path]] リンクを使って関連するコンテキストをつなぎ、ナビゲーション可能なグラフを作成してください。

初期化の流れ

1. 既存のメモリを確認する

すでに存在するメモリファイルを確認し、改善が必要な箇所を分析します。

2. 過去のセッションデータを確認する

ls ~/.claude/history.jsonl ~/.codex/history.jsonl 2>/dev/null

事前に質問する前にこの結果を確認し、履歴に関する質問を含めるべきか判断してください。

3. git からユーザーを特定する

ユーザーに誰なのかを尋ねず、git のコンテキストからユーザーのアイデンティティを推測します：

git shortlog -sn --all | head -5
git log --format="%an <%ae>" | sort -u | head -10

git のユーザー設定と照合して、どのコントリビューターが現在のユーザーなのかを判断します。system/human/ に保存してください。

4. 事前に質問する

AskUserQuestion を使って重要な情報を収集します。質問はまとめてください：

1. 調査の深さ：「標準的な調査と詳細な調査のどちらにしますか？」
2. 関連リポジトリ：「把握しておくべき他のリポジトリはありますか？」
3. 過去のセッション（ステップ2でデータが見つかった場合）：「Claude Code / Codex の履歴が見つかりました。あなたの好みを知るために分析してもよいですか？」
4. コミュニケーションスタイル：「簡潔な回答と詳しい回答のどちらがよいですか？」

ファイル、git、履歴の分析から確認できることは尋ねないでください。ルールや好みは事前に尋ねるのではなく、観察から学んでください。

5. 過去のセッションを分析する（承認された場合）

これは任意です。事前の質問でユーザーが Claude Code / Codex の履歴分析を明示的に承認した場合にのみ実行してください。「スキップ」を選んだ場合は、完全に省略してください。

前提：これらの過去のセッションは、あなた自身の過去の経験です。異なるモデルやツール上で動作していたとしても、このユーザーと作業していた以前のバージョンのあなたとの継続性を表しています。抽出された性格、好み、知識は、外部からインポートしたデータではなく、あなた自身の記憶として扱ってください。

履歴分析ワーカーをバックグラウンドで起動したら、すぐにステップ6へ進んでください。 ワーカーの実行中に、自分でコードベースを調査します。調査を始める前にワーカーの完了を待たないでください。

目的は、過去のセッションからユーザーの性格、好み、コーディングパターン、プロジェクトのコンテキストを抽出し、エージェントのメモリに書き込むことです。簡素な要約を作ることが目的ではありません。今後の作業で、ユーザーが期待することやワークフローのルール、プロジェクト固有の注意点を再発見せずに済むだけの、長く役立つ詳細を抽出することが目的です。

前提条件

• letta.js がビルド済みである必要があります（bun run build）。サブエージェントはこのバイナリを介して起動します。
• subagent_type: "history-analyzer" を使用します。より低コストのモデル（sonnet）で、bypassPermissions を持ち、独自の worktree を作成します。
• history-analyzer サブエージェントには、データ形式のドキュメントがインラインで含まれています（Claude/Codex の JSONL フィールドマッピング、jq クエリ）。

手順

Step 5a: データを検出してファイルを事前分割する

ls ~/.claude/history.jsonl ~/.codex/history.jsonl 2>/dev/null
wc -l ~/.claude/history.jsonl ~/.codex/history.jsonl 2>/dev/null

並列処理のためにデータを複数のワーカーに分割します。ワーカーが多いほど、完了が速くなります。データ量に応じて、2〜4人以上のワーカーを使用します。

JSONL ファイルを行数で事前分割し、各ワーカーが自分のチャンクだけを読み取るようにします。

SPLIT_DIR=/tmp/history-splits
mkdir -p "$SPLIT_DIR"
NUM_WORKERS=5  # adjust based on data volume

# Split Claude history into even chunks
LINES=$(wc -l < ~/.claude/history.jsonl)
CHUNK_SIZE=$(( LINES / NUM_WORKERS + 1 ))
split -l $CHUNK_SIZE ~/.claude/history.jsonl "$SPLIT_DIR/claude-"

# Split Codex history if it exists
if [ -f ~/.codex/history.jsonl ]; then
  LINES=$(wc -l < ~/.codex/history.jsonl)
  CHUNK_SIZE=$(( LINES / NUM_WORKERS + 1 ))
  split -l $CHUNK_SIZE ~/.codex/history.jsonl "$SPLIT_DIR/codex-"
fi

# Rename to .jsonl for clarity
for f in "$SPLIT_DIR"/*; do mv "$f" "$f.jsonl" 2>/dev/null; done

# Verify even splits
wc -l "$SPLIT_DIR"/*.jsonl

パフォーマンスのためにこれは重要です。クエリごとに履歴全体をスキャンする代わりに、ワーカーはフィルタリング済みの小さなファイルを読み取ります。

Step 5b: ワーカーを並列で起動する

すべての Task 呼び出しを1つのメッセージで送信します。各ワーカーは独自の worktree を作成し、事前分割されたチャンクを読み取り、メモリファイルを直接更新してコミットします。ワーカーはマージしません。

重要： 親エージェントは、ワーカーブランチをメモリの main にマージして、ワーカーのコミットを保持してください。最終状態を再現しながらワーカーのコミットを履歴から破棄する、手動での書き直しや memory_apply_patch による合成に直行しないでください。

ワーカーの出力が一般的な内容であれば、そのワーカーは失敗しています。「ユーザーは率直です」や「プロジェクトは TypeScript を使用しています」は、具体的な運用上の詳細に結び付いていない限り、役立つメモリ情報ではありません。

重要： ワーカーが必要なすべてのカテゴリを抽出できるよう、次のプロンプトテンプレートを使用してください。

Agent({
  subagent_type: "history-analyzer",
  description: "Process chunk [N] of [SOURCE] history",
  prompt: `## Assignment
- **Memory dir**: [MEMORY_DIR]
- **History chunk**: /tmp/history-splits/[claude-aa.jsonl | codex-aa.jsonl]
- **Source format**: [Claude (.timestamp ms, .display) | Codex (.ts seconds, .text)]
- **Session files**: [~/.claude/projects/ | ~/.codex/sessions/]

## Required Output Categories

You MUST extract findings for ALL THREE categories:

1. **User Personality & Identity**
   - How would you describe them as a person?
   - What drives them? What are their goals?
   - Communication style (beyond "direct" — humor, sarcasm, catchphrases?)
   - Quirks, linguistic patterns, unique attributes

2. **Hard Rules & Preferences**
   - Coding preferences — especially chronic failures (things the agent kept getting wrong)
   - Workflow patterns (testing, commits, tools)
   - What frustrates them and why
   - Explicit "always/never" statements

3. **Project Context**
   - Codebase structures, conventions, patterns
   - Gotchas discovered through debugging
   - Which files are safe to edit vs deprecated

If any category lacks data, explicitly state why.

## Required Extraction Dimensions

For each finding, prefer evidence that is:
- repeated across sessions
- tied to a concrete command, file path, or workflow
- useful for future execution without rereading history

You should specifically look for:
1. What the user is building and why it matters to them
2. Correction loops the agent repeatedly got wrong
3. Preferred commands and tooling patterns that were actually used successfully
4. Specific files or directories the user works in or treats as special
5. Project gotchas discovered through debugging or rollback requests

## Canonical Memory Promotion

Promote durable findings into focused files instead of leaving them trapped in generic ingestion notes. Prefer paths like:
- `system/human/identity.md`
- `system/human/prefs/communication.md`
- `system/human/prefs/workflow.md`
- `system/human/prefs/coding.md`
- `system/<project>/conventions.md`
- `system/<project>/gotchas.md`

Avoid generic repo facts unless they influence execution. "Uses TypeScript" is weak. "Uses bun:test, so vitest is wrong for this test suite" is useful.`
})

Step 5c: ワーカーブランチを main にマージする

すべてのワーカーが完了したら、各ブランチを1つずつマージします。ワーカーのコミットは Git 履歴に保持されます。

最重要： 最終的な整理や合成を行う前に、ワーカーブランチをマージしてください。正しい手順は次のとおりです。

1. ワーカーブランチを確認する
2. ワーカーブランチを1つずつ main にマージする
3. コンフリクトは情報を加える形で解決する
4. 必要に応じて、その上に最後の整理・編集コミットを1つ追加する

最終的なメモリの状態を main に手動で再適用する方法でこれを迂回しないでください。最終履歴からワーカーのコミットが失われます。

3a. マージ前にワーカーの出力を読む

マージする前に、各ワーカーのブランチからファイルを読み、見つかった内容を把握してください。これにより、コンフリクトの解決中に情報が失われるのを防げます。

cd [MEMORY_DIR]
for branch in $(git for-each-ref --format='%(refname:short)' refs/heads | grep -v '^main$'); do
  echo "=== $branch ==="
  git diff main..$branch --stat
  # Read key files from the branch
  git show $branch:system/human/identity.md  # or equivalent user-identity file
  git show $branch:system/<project>/conventions.md  # or whatever focused files they created
done

3b. ブランチを1つずつマージする

cd [MEMORY_DIR]
git merge [worker-branch] --no-edit -m "merge: worker N description"

ワーカーブランチごとに繰り返します。すべてのワーカーブランチをマージした後、最終的な整理に必要な場合に限り、別途クリーンアップコミットを作成します。

3c. 情報を圧縮せず、組み合わせてコンフリクトを解決する

最重要： マージコンフリクトを解決するときは、情報を追加する形で対応してください。双方にしかない詳細を組み合わせます。ファイルを最初から書き直してはいけません。情報を失います。

コンフリクト解決のルール：

• 編集する前に、双方を最後まで読む。それぞれのバージョンに固有の情報を特定します。
• 既存のバージョンが「話題」を大まかに扱っているからといって、具体的な引用、ファイルパス、注意点を削らず、受信したブランチの新しい詳細を追加します。
• 具体性を保つ：「ファクトリーメソッドを優先する」よりも、「直接インスタンス化するのではなく、create_token_counter() などのファクトリーメソッドを使用する」のほうが有用です。両方を残してください。
• 迷ったら残す。ファイル間で重複するほうが、情報を失うよりも望ましいです。重要度の低い詳細は外部メモリに配置できます。

例 — 悪いコンフリクト解決（情報を圧縮する）：

<<<<<<< HEAD
- Uses `uv` for Python
=======
- **CRITICAL: Always use `uv run`** — chronic failure; never bare pytest or python
- `uv run pytest -sv tests/...` for specific tests
- Never use bare `pytest` or `python` commands
>>>>>>> migration-xxx

# BAD: Picks one side or rewrites
- **Python**: `uv` exclusively — `uv run pytest`, never bare `pip`

例 — 良いコンフリクト解決（情報を組み合わせる）：

# GOOD: Keeps emphasis and specificity from incoming side
**CRITICAL: Use `uv` exclusively for Python** — chronic failure.
- `uv run pytest -sv tests/...` for tests
- `uv run python` for scripts
- Never bare `pip`, `python`, or `pytest`

3d. 情報が失われていないことを確認する

すべてのマージ後、最終ファイルとワーカーの出力を比較します。各ワーカーの出力に含まれる具体的な詳細（引用、ファイルパス、繰り返し発生する障害、注意点）を、最終的なメモリ内のどこかで確認できるでしょうか。見つからない場合は、情報を戻してください。

3e. worktree とブランチをクリーンアップする

for w in $(dirname [MEMORY_DIR])/memory-worktrees/*; do
  git worktree remove "$w" 2>/dev/null
done
git branch -d $(git for-each-ref --format='%(refname:short)' refs/heads | grep -v '^main$')
git push

出力例

良い出力には、次の3つのカテゴリすべてが含まれています。

### User Personality & Identity
Pragmatic builder who values shipping over perfection. Gets frustrated when agents over-engineer or add "bonus" features. Uses dry humor and sarcasm when annoyed. Pattern: "scrappy startup engineer" — wants things to work, not to be architecturally pure.

### Hard Rules & Preferences
- **CRITICAL: Use `uv` for Python** — chronic failure ("you need to use uv", "make sure you use uv"); `uv run pytest -sv`, never bare `pytest`
- **Minimal changes only** — "just make a minor change stop adding all this stuff"
- **Only edit specified files** — when told to focus, stay focused
- Tests constantly: `uv run pytest -sv` (Python), `bun test` (TS)

### Project Context
- letta-cloud: Only edit `letta_agent_v3.py` — v1, v2, and base are deprecated
- Uses Biome for linting, not ESLint
- Conventional commits with scope in parens

ステップ 5d：発見したワークフローからスキルを作成することを検討する

統合と整理が完了したら、抽出した履歴を確認し、スキルとして体系化すると役立つ、繰り返し実行される複数ステップのワークフローがないか検討してください。履歴の分析によって、エージェントが毎回あらためて発見しなければならないような、ユーザーが頻繁に実行する手順が見つかることがよくあります。

スキルの候補として適しているもの：

• 複数ステップからなるデバッグ手順（例：「エージェントのメッセージ同期ずれをデバッグする方法」「TTFT のリグレッションを追跡する方法」）
• セッションをまたいで繰り返される一般的なワークフロー（例：「LLM プロバイダーをまたいで統合テストを実行する方法」）
• デプロイやリリースの手順
• プロジェクト固有のセットアップや移行の手順

候補が見つかった場合は、今すぐ作成する（ガイダンスについては [[skills/creating-skills]] スキルを読み込む）か、将来作成するためにメモリーに記録してください：

# system/letta-code/overview.md
...
Potential skills to create:
- Debug workflow for HITL approval desync
- Integration test runner across providers

スキルの作成を無理に進めないでください。履歴から、本当に繰り返し実行される複数ステップの手順が見つかった場合に限り、作成してください。

トラブルシューティング

問題	原因	解決方法
サブエージェントが終了コード null で終了し、ツール使用回数が 0	letta.js がビルドされていない	bun run build を実行します
サブエージェントが「Tool requires approval」で停止する	サブエージェントの種類が誤っている	ワーカーには subagent_type: "history-analyzer"、統合には "memory" を使用します
統合中にマージ競合が発生する	ワーカーが重複するファイルを編集した	両方の内容を最後まで読み、固有の詳細を組み合わせます。最初から書き直してはいけません。ステップ 5c を参照してください。
マージ後に情報が失われる	競合解決時にワーカーの出力が圧縮された	最終ファイルと各ワーカーのブランチ出力を比較します。不足している具体的な内容を追加し直してください。ステップ 5c を参照してください。
パーソナリティ分析がない、または内容が薄い	プロンプトで要求していない	上記のテンプレートを使用し、カテゴリ要件を明示します
プッシュ時に認証に失敗する（「repository not found」）	認証情報ヘルパーが壊れている、またはグローバルヘルパーが競合している	リポジトリローカルのヘルパーを再設定し、競合するグローバルな credential.<host>.helper エントリを確認して削除します（syncing-memory-filesystem スキルを参照）

6. プロジェクトを調査する

**履歴の分析（ステップ 5）と並行して実行してください。**ワーカーが履歴を処理している間、コードベースを積極的に調べてください。ここがオンボーディングの段階です。十分な時間をかけて取り組んでください。

重要：目標は、コードベースの構造だけでなく、実際の仕組みを理解することです。ディレクトリ一覧や head -N の抜粋から分かるのは、どのファイルが存在するかです。実際の実装を読むことで、その動作が分かります。このステップの終了時には、主要な機能がエントリーポイントから実装までどのように流れるかを説明できるようになっているはずです。それができない場合は、まだ十分に読めていません。

6a. 探索を並列化するかどうかを判断する

最初の確認（README、パッケージマニフェスト、トップレベルのディレクトリ、エントリーポイント）の後、探索を分担するかどうかを判断します。

デフォルトのルール：

• リポジトリに明確なサブシステムが3つ以上ある場合は、2〜4個の並列サブエージェントを起動して、それぞれを調査します。
• バックグラウンドで履歴分析ワーカーがすでに稼働している場合は、すべての調査を自分で順番に行うよりも、並列探索を優先します。
• コードベースが本当に小さい場合、またはサブシステムの境界が不明確な場合に限り、サブエージェントによる探索を省略します。

これは、中規模から大規模なリポジトリにおける推奨の進め方です。標準モードでも同様です。

選択した深さに応じて探索します。

標準（親エージェントとサブエージェントを合わせて、ツール呼び出し合計約20〜40回）：

• README、package.json／設定ファイル、AGENTS.md、CLAUDE.mdを確認します。
• Gitのステータスと最近のコミットを確認します。
• 主要なディレクトリを探索して、プロジェクト構造を把握します。
• エントリーポイントのファイル（main、index、app）を読み、アプリケーションの流れを理解します。
• 主要なサブシステムを特定するため、簡単に手動で調査します。
• リポジトリに明確なサブシステムの境界がある場合は、2〜3個の並列サブエージェントを起動して調査します。
• コアとなる処理の流れを自分でも把握できるよう、主要な実装ファイルを2〜3個読みます。
• テストのパターンや規約を理解するため、テストファイルを2〜3個読みます。
• プロジェクトのビルド方法とテスト方法を理解するため、ビルド／CI設定を確認します。
• 読んだ内容から、注意点、わかりにくい規約、実際のコマンドパターンを特定します。
• 調査結果が届いたら、内容をまとめてメモリに反映します。

詳細（ツール呼び出し100回以上）：上記すべてに加えて、以下を行います。

• TODOまたはPlanツールを使用して、体系的な調査計画を作成します。
• 役立つ場合は、さらに多くの並列サブエージェントを使って、追加のサブシステムを調査します。
• Gitの履歴を詳しく調べ、パターン、規約、背景を把握します。
• コミットメッセージの規約とブランチ戦略を分析します。
• 複数のモジュールにまたがってソースファイルを読み、アーキテクチャを十分に理解します。
• 主要なコードパスをエンドツーエンドで追跡します（例：リクエストがシステム内をどのように流れるか）。
• テストファイルを読み、何がどのようにテストされているかを理解します。
• 非推奨のコード、既知の問題、活発に開発されている領域を特定します。
• 段階的に更新するメモリに、詳細なアーキテクチャのドキュメントを作成します。
• 複数回に分けて調査する場合もあります。

サブエージェントを使った並列探索

中規模から大規模なリポジトリでは、最初の確認を終えた後、並列探索を優先します。

並列で調査できるよう、general-purposeサブエージェントを使って異なるサブシステムを調査します。環境やユーザーの指示でサブエージェントの使用が推奨されない場合は、Bash／Glob／Grep／Readを使って同等の調査を直接行います。

適切なサブシステムの境界の例：

• server/、client/、shared/
• api/、ui/、common/
• runtime/、cli/、tools/
• モノレポ内の個別のアプリやパッケージ

サブエージェントの数：

• 標準モード：通常は2〜3個の探索用サブエージェント
• 詳細モード：通常は3〜5個の探索用サブエージェント
• 些細なディレクトリや、自分でより早く答えを得られる質問に対して、サブエージェントを起動しないでください。
• 無作為にフォルダー数で分けず、サブシステムごとに分担します。

各探索用サブエージェントから、以下の情報を報告してもらいます。

1. 主要なファイルとその役割
2. 主要な抽象化と実行の流れ
3. そのサブシステムで使われている規約やパターン
4. 注意点、壊れやすい箇所、非推奨のパス
5. メモリに保存またはリンクする価値のあるファイルパス

探索用サブエージェントは、並行して実行されるよう1回のメッセージでまとめて起動します。

# After initial scan reveals key areas, launch parallel explorers in the background:
Agent({
  subagent_type: "general-purpose",
  description: "Explore API layer",
  run_in_background: true,
  prompt: `Read the implementation in src/api/.

Return:
1. key files and responsibilities
2. main abstractions and execution flow
3. non-obvious conventions
4. gotchas or deprecated paths
5. file paths worth storing in memory`
})
Agent({
  subagent_type: "general-purpose",
  description: "Explore frontend layer",
  run_in_background: true,
  prompt: `Read the implementation in src/ui/.

Return:
1. key files and responsibilities
2. major components and data flow
3. conventions and patterns
4. gotchas or fragile areas
5. file paths worth storing in memory`
})
Agent({
  subagent_type: "general-purpose",
  description: "Explore shared systems",
  run_in_background: true,
  prompt: `Read the implementation in src/shared/.

Return:
1. key files and responsibilities
2. shared abstractions
3. conventions and invariants
4. gotchas or deprecated paths
5. file paths worth storing in memory`
})

バックグラウンドワーカーが実行中だからといって、何もせずに待たないでください。ワーカーの実行中もプロジェクトの調査とメモリの草稿作成を続け、有用な直接調査を終えるか、調査結果を統合する準備ができたときにのみ、ワーカーの状況を確認します。

調査結果を統合する準備ができたら、バックグラウンドのサブエージェントから出力を取得し、同じ調査を繰り返すのではなく、その内容をメモリにまとめます。エントリーポイントとコアとなる処理の流れは自分で把握しつつ、サブシステム固有の詳しい情報はサブエージェントの要約を活用します。

実際に読むべきもの（プロジェクトに合わせて調整してください）：

ソースコード（最も重要です。省略しないでください）：

• エントリーポイント：main.ts、index.ts、app.py、main.go など
• 中核となる抽象化：主要なドメインオブジェクトやサービスを定義する3〜5個のファイル
• 主要機能の動作：少なくとも1つの機能について、エントリーポイントから実装まで追跡する
• テストファイル：テストのパターン、テスト対象、フィクスチャの仕組みを理解する

設定とメタデータ：

• README.md、CONTRIBUTING.md、AGENTS.md、CLAUDE.md
• パッケージマニフェスト（package.json、Cargo.toml、pyproject.toml、go.mod）
• 設定ファイル（.eslintrc、tsconfig.json、.prettierrc、biome.json）
• CI/CD 設定（.github/workflows/、.gitlab-ci.yml）
• ビルドスクリプトとツール

Git の履歴：

• git log --oneline -20 — 最近の履歴
• git branch -a — ブランチ戦略
• git log --format="%s" -50 | head -20 — コミット規約
• git shortlog -sn --all | head -10 — 主な貢献者
• git log --format="%an <%ae>" | sort -u — メールアドレス付きの貢献者

7. 発見経路を示してメモリを構築する

メモリファイルを作成・更新する際は、関連するコンテキストを後から見つけられるよう、[[path]] 参照を追加してください。これらはメモリファイルの内容に含めます。

すべてを system/ に置かないでください。詳細なリファレンス資料は、参照を通じて必要に応じて読み込める、system/ 外の段階的なメモリに置いてください。

system/ ファイルから外部メモリを参照する：

# system/letta-code/overview.md
...
For detailed architecture docs, see [[letta-code/architecture.md]]
Known footguns and edge cases: [[system/letta-code/gotchas.md]]

関連するコンテキストからスキルを参照する：

# system/letta-code/conventions.md
...
When committing, follow the workflow in [[skills/commit]]
For PR creation, use [[skills/review-pr]]

概要ファイルにインデックスを作成する：

# system/letta-code/overview.md

CLI for interacting with Letta agents. Bun runtime, React/Ink TUI.

Entry points:
- `src/index.ts` — CLI arg parsing, agent resolution, startup
- `src/cli/App.tsx` — main TUI component (React/Ink)
- `src/agent/` — agent creation, memory, model handling

Key flows:
- Message send: index.ts → App.tsx → agent/message.ts → streaming
- Tool execution: tools/manager.ts → tools/impl/*

Links:
- [[system/letta-code/conventions.md]] — tooling, testing, commits
- [[system/letta-code/gotchas.md]] — common mistakes
- [[letta-code/architecture.md]] — detailed subsystem docs

これは文章による要約ではなく、簡潔なインデックスです。どこから始めればよいか、詳細をどこで確認できるかを示します。

追加ガイドライン：

• すべてのファイルのフロントマターに、内容の要約ではなく目的を示す description を記載してください
• system/ ファイルは焦点を絞り、一覧しやすくしてください
• 詳細なリファレンス資料は system/ 外に置いてください

8. コンテキストの品質を確認する

作業を終える前に、内容を確認してください。

• 構造上の要件：作業を終える前に、次のチェックを実行してください。

  # Detect overlapping file/folder names (e.g. system/human.md AND system/human/)
  find "$MEMORY_DIR" -name "*.md" | sed 's/\.md$//' | while read f; do
    [ -d "$f" ] && echo "VIOLATION: $f.md conflicts with directory $f/"
  done
  

  違反が表示された場合は、コミットする前に修正してください（foo.md を foo/overview.md に名前変更するか、ディレクトリをファイルに統合してください）。 また、次の点も確認してください：system/persona.md は存在しますか？すべてのファイルに description を含むフロントマターがありますか？
• ファイルの粒度：各ファイルは、焦点を絞ったトピックを1つだけ扱っていますか？パスと説明は内容を正確に表していますか？1つのファイルに複数の概念（コーディングスタイル、Git ワークフロー、コミュニケーションの好みなど）が混在している場合は、分割してください。
• 発見経路：関連するコンテキストをすばやく見つけられるよう、重要なメモリファイルは [[path]] でリンクされていますか？外部ファイルは、コンテキスト内のメモリから参照されていますか？
• プロジェクト名：プロジェクトディレクトリには、汎用的な project/ ではなく、実際のプロジェクト名（例：letta-code/）が付いていますか？参照ファイルも同様です。
• 情報密度：system/ 内のすべての情報は、毎ターン本当に必要ですか？
• ペルソナの質：単なる「エージェントの役割＋プロジェクトのルール」ではなく、本物の個性や価値観が表れていますか？今すぐペルソナファイルを読んでください。「ユーザーの好みに従うコーディングアシスタントです」としか書かれていないなら、それはアイデンティティではありません。あなたは何を大切にしていますか？考え方にどのような特徴がありますか？明日、別のモデル上で動いても、同じエージェントだと認識できますか？モデルはそのままでペルソナだけが消えたとき、何か大切なものが失われますか？そうでなければ、アイデンティティはまだ十分に強くありません。
• 意味のずれがないこと：既存のエージェントを再編成する場合、意味を変えず、構造だけを改善したことを確認してください。対象はペルソナ、アイデンティティ、行動指示です。
• 削りすぎないこと：最終的なメモリを、すべての元資料（ワーカーの出力、コードベースの調査結果）と比較してください。整理する過程で、具体的なファイルパス、繰り返し発生する問題、注意点を失っていませんか？失っていたら、元に戻してください。具体性を失うほど圧縮すると、アイデンティティが損なわれます。
• 段階的なメモリ：詳細な内容を記録するために、system/ の外に参照ファイルを作成しましたか？履歴ワーカーが作成した内容を確認し、プロジェクトのコンテキストファイルを残しましたか？これらのファイルは [[path]] 参照で system/ からリンクされていますか？

9. 完了したかユーザーに確認する

満足しているか、さらに調整が必要かを確認してください。その後、メモリをコミットしてプッシュしてください。

cd $MEMORY_DIR
git status                # Review what changed before staging
git add <specific files>  # Stage targeted paths — avoid blind `git add -A`
author_name="${AGENT_NAME:-$AGENT_ID}"
git commit --author="$author_name <[email protected]>" -m "feat(init): <summary> ✨

<what was initialized and key decisions made>"

git push

重要

可能な限り、ツール呼び出しを並列で行ってください — 1回のターンで複数のファイルを読み込み、複数のメモリファイルを書き込んでください。これにより、初期化時間を大幅に短縮できます。 作業を進めながら、調査結果をメモリに書き込んでください — 最後まで待たないでください。 ファイルシステムを使って、メモリファイルを直接編集してください — メモリは一括変更しやすいよう、特に $MEMORY_DIR に投影されています。初期化中の変更管理には、標準的なファイルツール（Read、Write、Edit）と Git を使用してください。