trellis-session-insight

Trellis セッションインサイト

このスキルでは、AI に**trellis mem の呼び出し方**（プロジェクトのセッション横断型メモリの供給元）と、いつ使うべきかを教えます。

これは意図的に、ワークフローではなく機能を教えるスキルとして設計されています。固定の出力ファイルも、必須の書き戻し手順も、「作業完了後には必ず実行する」というルールもありません。mem が返した内容をどう扱うかは、会話のその場で判断します。このスキルの目的は、AI がこの機能を使えることを把握し、使うかどうかを判断できるようにすることです。

trellis mem とは

ユーザーの過去の Claude Code、Codex、Devin CLI、Grok、OpenCode、Pi Agent、ZCode の会話ログをインデックス化し、それらの一覧表示、検索、Trellis タスクの境界による絞り込み、整理済みの対話内容の出力を行うローカル CLI です。Claude と Codex は ~/.claude/projects/ と ~/.codex/sessions/ を使用します。Devin CLI（Cognition のターミナルエージェント。trellis init --devin の Desktop ではありません）は ~/.local/share/devin/cli/sessions.db を使用します。Grok は ~/.grok/sessions/ を使用します。OpenCode は ~/.local/share/opencode/opencode.db を使用します（依存関係のない SQLite リーダー）。Pi は既定のセッションルート、または環境変数で設定されたセッションルート、グローバル設定の ~/.pi/agent/settings.json、スコープが限定されたプロジェクトの .pi/settings.json を使用します。相対パスの sessionDir 値は、設定ファイルのディレクトリを基準に解決されます。プロジェクトローカルの Pi 設定を使うには、現在の cwd または --cwd を指定して、プロジェクトスコープで検索する必要があります。ZCode は ~/.zcode/cli/db/db.sqlite を使用します。

mem のデータがアップロードされることはありません。読み取りはすべてローカルで行われます。

使うべき場面

判断の目安は、「先輩のチームメイトが『それ、前にも話しませんでしたか？』と尋ねそうかどうか」です。具体的には、次のような場面です。

• ブレインストーミングのやり直しを防ぐ。 ユーザーが以前取り組んだことのある領域に関わる新しいタスクを始める際、ユーザーに再度尋ねる前に、すでに決定済みの内容がないか確認したいとき。
• 以前と似たバグのデバッグ。 現在のバグのパターンが、ユーザーが以前報告または修正したものに似ていると感じるとき。関連する過去のセッションを取得すれば、デバッグを最初からやり直さずに済むことがあります。
• セッションをまたいだ作業の継続。 ユーザーが間を空けて作業を再開し、具体的な説明なしに「どこまで進めていましたっけ」／「前回の続き」と尋ねるとき。
• 決定事項の検索。 ユーザーが「X について決めたこと」に言及しているものの、その決定が prd.md や spec/ ではなく、過去のブレインストーミングに記録されているとき。
• 作業完了時の振り返り。 すべての作業完了時に必ず行うのではなく、このタスクで決めたこと、困ったこと、意外だったことのまとめをユーザーが明示的に求めたとき。
• 過去の作業からパターンを見つける。 ユーザーが「X で同じミスを繰り返していませんか」／「毎回同じ落とし穴にはまっていますか」と尋ねたとき。セッションを横断して検索すれば答えられます。

どれにも当てはまらない場合は、mem を呼び出さないでください。これはツールであり、儀式ではありません。

使うべきでない場面

• 関連するコンテキストが現在のターン、prd.md、design.md、最近の git log、または開いているファイルにすでにある場合。mem は、すぐに参照できる範囲から外れてしまった情報を探すためのものです。
• ユーザーが過去の会話の内容ではなく、コード内の事実について尋ねている場合。git log -p、grep、ファイルの直接確認のほうが速く、信頼性も高いです。
• サブエージェント（trellis-implement／trellis-check）で、そのディスパッチプロンプトにすでに厳選済みの implement.jsonl／check.jsonl コンテキストが含まれている場合。さらに mem を使うと、たいてい情報が増えて煩雑になります。
• ユーザーが「履歴を調べず、聞いたことだけに答えて」と明示している場合。

mem の戻り値の活用方法

出力は成果物ではなく、素材として扱ってください。取得したら、現在の会話に応じて判断します。

• 過去の特定のやり取りがユーザーの現在の質問への答えになる場合は、返信にそのまま引用し、ユーザーが確認できるように session-id / phase を示します。
• mem によって、文書化されているべきだった重要な決定が見つかった場合は、<task>/prd.md または <task>/design.md を更新します。まず、提案する編集内容をユーザーに提示します。
• 現在のタスクの記録に残すべき内容で、PRD には適さない場合は、タスク専用のメモファイル（例：<task>/notes.md、または既存のメモへの追記）に追加します。
• プロジェクト全体に関わる規約や注意点で、今後のタスクにも役立つ場合は、.trellis/spec/ を更新します。その際は trellis-update-spec スキルを実行します。session-insight が担当するのは発見までです。
• 今後数回のやり取りに活かして、何も書き込まずに回答の質を高めるだけにします。単発の情報を思い出す場合は、これが適切なこともよくあります。

Trellis は、情報の保存先を一つに定めていません。すべての検索結果を決まったファイルに押し込むと、そのファイルは雑多な情報で膨らんでしまいます。状況に応じて判断してください。

呼び出し方法

CLI の全リファレンスは references/cli-quick-reference.md にあります。大半のケースでは、次のいずれかを使用します。

# Find sessions whose contents mention a keyword (project-scope is default;
# add --global to search every project on this machine).
trellis mem search "<keyword>"

# Dump dialogue from one session, optionally filtered by phase or keyword.
trellis mem extract <session-id> --phase brainstorm
trellis mem extract <session-id> --grep "<keyword>"

# Drill into a session: top-N hit turns + surrounding context.
trellis mem context <session-id> --turns 3 --around 2

# When you do not know the session id yet, start with list + filter.
trellis mem list --cwd <project-path>
trellis mem projects   # → list active project cwds, then narrow

フェーズを絞り込む（--phase brainstorm|implement|all）と、task.py create と task.py start の境界でセッションを分割します。現在のタスクの完了時レビューでは、--phase brainstorm で計画時の議論を取得し、--phase implement で実行のやり取りを取得します。デフォルトは all です。

トリガーパターン

references/triggering-patterns.md には、「mem を使おう」と考えるきっかけとなる、ユーザーのより直接的な言い回し（英語＋中国語）が記載されています。直感を養う際に参照できるよう、手元に置いておいてください。

対象外

• mem はコードを編集したり、ファイルを更新したりしません。書き戻すかどうかは、その場で判断してください。
• mem はプラットフォームの JSONL ストアに対して読み取り専用です。リモートへのプッシュや同期は行いません。
• このスキルは trellis-update-spec（発見した内容をプロジェクト全体のガイダンスに反映するための適切なツール）や、プラットフォームネイティブのタスク／仕様ワークフローに取って代わるものではありません。