heuristics

ヒューリスティクス：ソースからのメモリ取り込み

目標

ユーザーが提供したファイルやフォルダーを、有用な historian メモリに変換します。

このスキルは軽量なワークフローです。新しい TypeScript ツール、ナレッジグラフのサブシステム、永続的な取り込みパイプラインは追加しません。現在のエージェントが持つファイル操作機能と MCP 機能を使ってソースの内容を抽出し、@historian のメモリツールを使って、長期的に価値のある知識のみを保存してください。

必須入力

ユーザーは少なくとも 1 つのファイルまたはフォルダーのパスを指定する必要があります。

パスが指定されていない場合は、ほかの作業を始める前にパスを尋ねてください。

任意のユーザー入力：

• 含める、または除外するファイルの glob パターンや拡張子
• わかっている場合は、希望するメモリタイプ
• すべてのファイルを処理するか、選択したファイルのみを処理するか
• サイズが大きいファイルや有用な情報が少ないファイルをスキップするか

必須の最初の手順

内容を抽出または保存する前に、@historian に利用可能なメモリタイプの一覧を要求してください：

@historian list all memory types available

返されたタイプ名を、メモリを保存する際の主な memoryType 値として使用してください。ファイルに適したタイプがない場合は、そのファイルをスキップし、理由を報告してください。

抽出方法の振り分け

ユーザーが指定した各パスについて、まず候補ファイルを列挙してください。ユーザーが明示的に含めている場合を除き、生成物、依存関係、キャッシュ、バイナリのビルド出力が含まれるフォルダーはスキップしてください。

デフォルトでスキップする一般的なフォルダー：

• .git/
• node_modules/
• dist/、build/、.next/、coverage/
• .cache/、.turbo/、.parcel-cache/ などのキャッシュフォルダー

テキストファイルとコードファイル

ファイルがテキスト形式の場合は、直接読み取ってください：

• Markdown、TXT、RST、YAML、TOML、JSON、XML、CSV、TSV
• ソースコードと設定ファイル
• ユーザーが明示的に取り込みを依頼した場合のログ

長期的に価値のある事実、決定事項、慣例、問題、好み、再利用可能なパターンを抽出してください。ファイル全体が簡潔な信頼できる情報源である場合を除き、ファイル全体をそのまま保存しないでください。

ドキュメントファイル

PDF、DOCX、PPTX、XLSX、HTML、EPUB などのドキュメント形式の場合：

1. markitdown が利用可能であれば、それを使ってファイルを Markdown に変換します。
2. markitdown が利用できない、または失敗した場合は、利用可能な最適な LLM またはファイル読み取り方法で抽出します。
3. 抽出の信頼性が確保できない場合は、そのファイルをスキップし、失敗を報告します。

markitdown は任意です。LLM による抽出方法が利用可能であれば、作業を進める前にユーザーへインストールを求めないでください。

画像とスクリーンショット

PNG、JPG、JPEG、WEBP、GIF、HEIC、SVG、およびスクリーンショット形式のファイルの場合：

1. 利用可能であれば、ビジョン MCP を使用します。
2. テキストを含むスクリーンショットには、OCR を重視した抽出方法を優先します。
3. 図、ホワイトボード、視覚的なメモには、一般的な画像分析を優先します。
4. ビジョン MCP が利用できない場合は、可能であれば LLM による抽出を使用します。それもできない場合はスキップし、画像を抽出できなかったことを報告します。

複数形式が混在するフォルダー

フォルダーの場合は、ファイルを抽出方法ごとに分類し、有用な情報の多いファイルから処理してください。フォルダーのサイズ、ファイルサイズ、コンテキストの予算に基づいて、エージェントが分割方法とバッチサイズを決定できます。固定の上限はありません。

分類ルール

抽出した各項目を、memory_list_types で利用可能なメモリタイプに照らして分類します。

プロジェクトでより適切なカスタムタイプが定義されていない限り、以下のヒューリスティクスを使用してください：

ソースの内容	該当する可能性が高いメモリタイプ
アーキテクチャの選択、システム上のトレードオフ、採用したテクノロジー	architectural-decision
UI/UX の選択、ビジュアルの方向性、インタラクションに関する決定	design-decision
再利用可能な教訓や発見	learning
ユーザーが明示した作業スタイルや個人的な好み	user-preference
チームやプロジェクトの慣例	project-preference または conventions-pattern
既知のバグ、リスク、不足事項、制限事項	issue
再利用可能な実装パターン	recurring-pattern
一般的で長期的に価値のあるプロジェクト知識	context

複数のファイルで同じ概念が説明されている場合は、重複を作らず、1 つのメモリに統合してください。

永続化ワークフロー

抽出した有用な項目ごとに、次の手順を実行します。

1. 内容が既存の知識と重複する可能性がある場合、または既存の知識を更新する場合は、memory_recall で既存のメモリーを検索します。
2. 関連するメモリーがある場合は、その filePath を指定して memory_remember で更新します。
3. 関連するメモリーがない場合は、memory_remember で新しいメモリーを作成します。
4. 簡潔で内容が分かるタイトルを付けます。タイトルにメモリーの種類を含めないでください。
5. 保存した知識の追跡性を保つため、メモリー本文にソースパスを追加します。

ヒストリアンへのリクエスト例：

@historian remember this as a learning:
Title: markitdown-is-optional-for-source-ingestion
Content: Source ingestion should use markitdown when available, but fall back to
LLM extraction when it is not installed. Source: docs/ingestion-notes.md

保存しない内容

永続的なプロジェクトの記憶にならない内容はスキップします。

• 判断や発見を含まない一時的なログ
• 他の場所から取得できる、コピーされたベンダーのドキュメント
• 生成されたビルド成果物
• 抽出された教訓、判断、規約、問題のない生のソースファイル
• シークレット、認証情報、トークン、個人の非公開データ

ファイルにシークレットが含まれている場合、そのシークレットは保存しないでください。必要に応じて、「サンプルの env ファイルに実際のトークンのような文字列が含まれていた」など、サニタイズした問題のメモリーだけを保存します。

最終レポート

処理後、簡潔な表で報告します。

ソース	抽出方法	メモリーの種類	結果
path/to/file.pdf	markitdown	context	保存済み：title
path/to/screen.png	vision OCR	issue	保存済み：title
path/to/vendor.js	スキップ	-	生成物、または情報価値が低い

また、次の内容も報告します。

• 見つかったメモリーの種類
• スキップしたファイルとその理由
• 抽出に失敗した項目

プロンプトの例

Use heuristics to ingest ./docs into historian memories.

Use heuristics on ./research and only save architectural decisions and issues.

Use heuristics to extract these screenshots into memory: ./notes/*.png

Use heuristics to ingest ./meeting-notes, use markitdown if available, otherwise
extract with LLM judgement.

完了条件

次のすべてを満たした場合にのみ、ワークフローは完了です。

1. ユーザーから提供されたパスを列挙している。
2. 利用可能なメモリーの種類を、まず @historian を通じて確認している。
3. 各ファイルを、明確な理由とともに抽出、スキップ、または失敗として記録している。
4. 有用な知識を、利用可能なメモリーの種類に分類している。
5. 有用な知識を、@historian 経由で memory_remember を使って保存している。
6. 最終レポートで、処理したすべてのソースについて、抽出方法、メモリーの種類、結果を対応付けている。