Archive Agent

🚀 アーカイブエージェント

自然言語でファイルを検索し、質問を投げかけましょう。

AI検索（RAGエンジン）、自動OCR、MCPインターフェースを備えたスマートなファイルインデクサーです。

🚀 クイックスタート

https://github.com/user-attachments/assets/1cd8211e-6e5b-4e61-8ccc-74c140697abc

このツールを使えば、自然言語でファイルを検索し、質問を投げかけることができます。以下の手順で始めましょう。

✨ 主な機能

• 平文、ドキュメント、PDF、画像をインデックス化します。
• 自動OCRとエンティティ抽出を使用して画像を処理します。
• AI（OpenAI、Ollama、LM Studio）を使ってファイルを検索し、クエリを実行します。
• MCPサーバーを搭載しており、IDEやAI拡張機能を通じた自動化が可能です。

📦 インストール

必要条件

以下の要件をインストールしてください。

• 🐳 Docker （Qdrantサーバーを実行するため）
• 🐍 Python >= 3.10 （コアランタイム） （通常はすでにインストールされています）

Ubuntu / Linux Mint

このインストール方法は、Ubuntuを派生元とするすべてのLinuxディストリビューション（例：Linux Mint）で動作するはずです。

任意のディレクトリで、以下のコマンドを一度実行して Archive Agent をインストールします。

git clone https://github.com/shredEngineer/Archive-Agent
cd Archive-Agent
chmod +x install.sh
./install.sh

install.sh スクリプトは以下の手順を順番に実行します。

• uv をダウンロードしてインストールします（Python環境管理に使用）。
• カスタムPython環境をインストールします。
• spaCy トークナイザーモデルをインストールします（チャンク分割に使用）。
• pandoc をインストールします（ドキュメント解析に使用）。
• 永続的なストレージと自動再起動機能を持つQdrant Dockerイメージをダウンロードしてインストールします。
• 現在のユーザーにグローバルな archive-agent コマンドをインストールします。

🚀 Archive Agentのインストールが完了しました！

👉 次に、AIプロバイダーのセットアップを完了してください。
（その後、Archive Agentの実行ができるようになります！）

💻 使用例

基本的な使用法

以下のコマンドを実行することで、ドキュメントと画像を追跡します。

archive-agent include "~/Documents/**" "~/Images/**"
archive-agent update

GUIを起動するには、以下のコマンドを実行します。

archive-agent 

または、コマンドラインから質問を投げかけるには、以下のコマンドを実行します。

archive-agent query "Which files mention donuts?"

高度な使用法

ここでは、より高度なシナリオでの使用方法を説明します。例えば、特定のパターンを除外したり、詳細な情報を表示したりすることができます。

# 除外パターンを追加
archive-agent exclude "~/Documents/*.txt"

# 詳細情報を表示しながら更新
archive-agent update --verbose

📚 ドキュメント

AIプロバイダーのセットアップ

Archive Agent では、異なるAIプロバイダーを選択することができます。

OpenAIプロバイダーのセットアップ

OpenAIプロバイダーを選択した場合、Archive Agent はOpenAI APIキーが必要です。

OpenAI APIキーをエクスポートするには、sk-... を実際のキーに置き換えて、以下のコマンドを一度実行します。

echo "export OPENAI_API_KEY='sk-...'" >> ~/.bashrc && source ~/.bashrc

これにより、現在のユーザーに対してエクスポートが永続的に保存されます。

💡 知っておくと良いこと: OpenAIはあなたのデータをトレーニングに使用しません。

Ollamaプロバイダーのセットアップ

Ollamaプロバイダーを選択した場合、Archive Agent は http://localhost:11434 で実行されているOllamaが必要です。

• Ollamaのインストール方法

デフォルトのArchive Agent設定では、以下のOllamaモデルがインストールされていることが想定されています。

ollama pull llama3.1:8b             # for chunk/rerank/query
ollama pull llava:7b-v1.6           # for vision
ollama pull nomic-embed-text:v1.5   # for embed

💡 知っておくと良いこと: OllamaはGPUなしでも動作します。 スムーズなパフォーマンスを得るには、少なくとも32GiBのRAMが推奨されます。

LM Studioプロバイダーのセットアップ

LM Studioプロバイダーを選択した場合、Archive Agent は http://localhost:1234 で実行されているLM Studioが必要です。

• LM Studioのインストール方法

デフォルトのArchive Agent設定では、以下のLM Studioモデルがインストールされていることが想定されています。

meta-llama-3.1-8b-instruct              # for chunk/rerank/query
llava-v1.5-7b                           # for vision
text-embedding-nomic-embed-text-v1.5    # for embed

💡 知っておくと良いこと: LM StudioはGPUなしでも動作します。 スムーズなパフォーマンスを得るには、少なくとも32GiBのRAMが推奨されます。

Archive Agentの仕組み

処理対象のファイル

Archive Agent は現在、以下のファイルタイプをサポートしています。

• テキスト:
  • 平文: .txt, .md
  • ドキュメント:
    • ASCIIドキュメント: .html, .htm
    • バイナリドキュメント: .odt, .docx （画像を含む）
  • PDFドキュメント: .pdf （画像を含む、OCR戦略を参照）
• 画像: .jpg, .jpeg, .png, .gif, .webp, .bmp

ファイルの処理方法

最終的に、Archive Agent はすべてのファイルをテキストにデコードします。

• 平文ファイルはUTF-8にデコードされます。
• ドキュメントは平文に変換され、画像が抽出されます。
• PDFドキュメントはOCR戦略に従ってデコードされます。
• 画像はAIビジョンを使用してテキストにデコードされます。
  • ビジョンモデルは判読不能な画像を拒否します。

ドキュメントには Pandoc、PDFには PyMuPDF4LLM、画像には Pillow を使用しています。

📌 注意: サポートされていないファイルは追跡されますが、処理されません。

OCR戦略

PDFドキュメントには、Archive Agent がサポートする異なるOCR戦略があります。

• strict OCR戦略:

  • PDFのOCRテキストレイヤーは 無視されます。
  • PDFページは画像として扱われます。
  • コストが高く、処理が遅いですが、より正確です。

• relaxed OCR戦略:

  • PDFのOCRテキストレイヤーが抽出されます。
  • PDFの前景画像はデコードされますが、背景画像は 無視されます。
  • コストが安く、処理が速いですが、正確性は低くなります。

• auto OCR戦略:

  • PDFのOCRテキストレイヤーから抽出される文字数に基づいて、各ページに最適なOCR戦略を選択します。
  • ocr_auto_threshold（auto OCR戦略が relaxed ではなく strict に解決するための最小文字数）に基づいて決定します。
  • コスト、速度、正確性のトレードオフです。

Archive Agent設定を参照してください: ocr_strategy, ocr_auto_threshold

📌 注意: 最良の結果を得るためには、strict OCR戦略をお勧めします。 PDFドキュメントには、ページのスタイルやレイアウトに関連する小さな画像が含まれていることが多く、これらはオーバーヘッドを引き起こし、情報をほとんど提供せず、結果を混乱させることさえあります。

💡 知っておくと良いこと: 起動時にOCR戦略を選択するように促されます（Archive Agentの実行を参照）。

スマートチャンク分割の仕組み

Archive Agent はデコードされたテキストを以下のように処理します。

• デコードされたテキストはクレンジングされ、文に分割されます。
• 文は適切なサイズのブロックにグループ化されます。
• 各ブロックはAIモデルを使用して小さなチャンクに分割されます。
  • ブロックの境界は適切に処理されます（最後のチャンクは引き継がれます）。
• 各チャンクには コンテキストヘッダー が付加されます（検索が向上します）。
• 各チャンクはAI埋め込みを使用してベクトルに変換されます。
• 各ベクトルはファイルメタデータを持つ ポイント に変換されます。
• 各 ポイント はQdrantデータベースに保存されます。

Archive Agent設定を参照してください: chunk_lines_block

💡 知っておくと良いこと: この スマートチャンク分割 は、検索の精度と効果を向上させます。

チャンク参照の仕組み

すべてのチャンクがその元のファイルに追跡可能であることを確保するために、Archive Agent は各チャンクのテキスト内容をソースファイルの対応する行番号またはページ番号にマッピングします。

• 行ベースのファイル（例：.txt）は行番号の範囲を参照として使用します。
• ページベースのファイル（例：.pdf）はページ番号の範囲を参照として使用します。

📌 注意: 参照は、チャンク分割プロセスでの段落/文の分割/結合により、概算 です。

チャンクの取得方法

Archive Agent は、あなたの質問に関連するチャンクを以下のように取得します。

• 質問はAI埋め込みを使用してベクトルに変換されます。
• 類似したベクトルを持つポイントがQdrantデータベースから取得されます。
• 十分なスコアを持つポイントのチャンクのみが保持されます。

Archive Agent設定を参照してください: retrieve_score_min, retrieve_chunks_max

チャンクの再ランキングと拡張方法

Archive Agent は取得されたチャンクをフィルタリングします。

• 取得されたチャンクは、あなたの質問に対する関連性で再ランキングされます。
• 最も関連性の高いチャンクのみが保持され（他のチャンクは破棄されます）。
• 選択された各チャンクは、関連するドキュメントからより大きなコンテキストを取得するために拡張されます。

Archive Agent設定を参照してください: rerank_chunks_max, expand_chunks_radius

回答の生成方法

Archive Agent は再ランキングされ拡張されたチャンクを使用して、あなたの質問に以下のように回答します。

• LLMは質問に対するコンテキストとしてチャンクを受け取ります。
• LLMの回答は構造化された出力として返され、整形されます。

💡 知っておくと良いこと: Archive Agent は普遍的に役立つことを目的とした回答テンプレートを使用しています。

追跡対象のファイルの選択方法

Archive Agent は パターン を使用してファイルを選択します。

• パターンは実際のファイルパスであることができます。

• パターンはワイルドカードを含むパスであり、実際のファイルパスに解決されることができます。

• 💡 パターンは 絶対 パスとして指定する必要があります（または解決される必要があります）。例：/home/user/Documents/*.txt （または ~/Documents/*.txt）。

• 💡 ワイルドカード * を使用して、指定されたディレクトリ内の任意のファイルに一致させます。

• 💡 ワイルドカード ** を使用して、任意のファイルとゼロまたは複数のディレクトリ、サブディレクトリ、およびディレクトリへのシンボリックリンクに一致させます。

含まれるパターン と 除外されるパターン があります。

• 解決された除外ファイルのセットは、解決された含まれるファイルのセットから削除されます。
• 残ったファイルのセット（含まれるが除外されない）のみが Archive Agent によって追跡されます。
• 隠しファイルは常に無視されます！

このアプローチにより、追跡する特定のファイルまたはファイルタイプを最大限に制御することができます。

Archive Agentの実行

💡 知っておくと良いこと: 起動時に、以下を選択するように促されます。

• プロファイル名
• AIプロバイダー （AIプロバイダーのセットアップを参照）
• OCR戦略 （OCR戦略を参照）

クイックスタート

例えば、ドキュメントと画像を追跡するには、以下のコマンドを実行します。

archive-agent include "~/Documents/**" "~/Images/**"
archive-agent update

GUIを起動するには、以下のコマンドを実行します。

archive-agent 

または、コマンドラインから質問を投げかけるには、以下のコマンドを実行します。

archive-agent query "Which files mention donuts?"

コマンド一覧の表示

サポートされているコマンドの一覧を表示するには、以下のコマンドを実行します。

archive-agent

プロファイルの作成または切り替え

新しいまたは既存のプロファイルに切り替えるには、以下のコマンドを実行します。

archive-agent switch "My Other Profile"

📌 注意: プロファイル名引数には常に引用符を使用してください、 または省略するとインタラクティブなプロンプトが表示されます。

💡 知っておくと良いこと: プロファイルは、独立した Qdrantコレクション（Qdrantデータベースを参照）とArchive Agent設定を管理するのに便利です。

現在のプロファイルの設定をnanoで開く

現在のプロファイルの設定（JSON）を nano エディターで開くには、以下のコマンドを実行します。

archive-agent config

詳細については、Archive Agent設定を参照してください。

含まれるパターンの追加

1つまたは複数の含まれるパターンを追加するには、以下のコマンドを実行します。

archive-agent include "~/Documents/*.txt"

📌 注意: パターン引数には常に引用符を使用してください（シェルのワイルドカード展開を防ぐため）、 または省略するとインタラクティブなプロンプトが表示されます。

除外されるパターンの追加

1つまたは複数の除外されるパターンを追加するには、以下のコマンドを実行します。

archive-agent exclude "~/Documents/*.txt"

📌 注意: パターン引数には常に引用符を使用してください（シェルのワイルドカード展開を防ぐため）、 または省略するとインタラクティブなプロンプトが表示されます。

含まれる/除外されるパターンの削除

以前に含まれる/除外される1つまたは複数のパターンを削除するには、以下のコマンドを実行します。

archive-agent remove "~/Documents/*.txt"

📌 注意: パターン引数には常に引用符を使用してください（シェルのワイルドカード展開を防ぐため）、 または省略するとインタラクティブなプロンプトが表示されます。

含まれる/除外されるパターンの一覧表示

含まれる/除外されるパターンの一覧を表示するには、以下のコマンドを実行します。

archive-agent patterns

パターンの解決とファイルの追跡

すべてのパターンを解決し、ファイルの変更を追跡するには、以下のコマンドを実行します。

archive-agent track

追跡されているファイルの一覧表示

追跡されているファイルの一覧を表示するには、以下のコマンドを実行します。

archive-agent list

📌 注意: まず track コマンドを実行してファイルを追跡してください。

変更されたファイルの一覧表示

変更されたファイルの一覧を表示するには、以下のコマンドを実行します。

archive-agent diff

📌 注意: まず track コマンドを実行してファイルを追跡してください。

変更されたファイルをデータベースにコミットする

ファイルの変更をQdrantデータベースと同期するには、以下のコマンドを実行します。

archive-agent commit

チャンク分割と埋め込みに関する追加情報を表示するには、--verbose オプションを指定します。

このコミットでAIキャッシュ（ビジョン、チャンク分割、埋め込み）をバイパスするには、--nocache オプションを指定します。

💡 知っておくと良いこと: 変更は以下の原因でトリガーされます。

• ファイルの追加
• ファイルの削除
• ファイルの変更:
  • 異なるファイルサイズ
  • 異なる変更日時

📌 注意: まず track コマンドを実行してファイルを追跡してください。

追跡とコミットを一度に実行する

track と commit を一度に実行するには、以下のコマンドを実行します。

archive-agent update

チャンク分割と埋め込みに関する追加情報を表示するには、--verbose オプションを指定します。

このコミットでAIキャッシュ（ビジョン、チャンク分割、埋め込み）をバイパスするには、--nocache オプションを指定します。

ファイルの検索

archive-agent search "Which files mention donuts?"

質問に関連するファイルの一覧を表示します。

📌 注意: 質問引数には常に引用符を使用してください、または省略するとインタラクティブなプロンプトが表示されます。

埋め込み、取得、再ランキング、およびクエリに関する追加情報を表示するには、--verbose オプションを指定します。

この検索でAIキャッシュ（埋め込み、再ランキング）をバイパスするには、--nocache オプションを指定します。

ファイルに対するクエリ

archive-agent query "Which files mention donuts?"

RAGを使用して質問に回答します。

📌 注意: 質問引数には常に引用符を使用してください、または省略するとインタラクティブなプロンプトが表示されます。

埋め込み、取得、再ランキング、およびクエリに関する追加情報を表示するには、--verbose オプションを指定します。

このクエリでAIキャッシュ（埋め込み、再ランキング）をバイパスするには、--nocache オプションを指定します。

Archive Agent GUIの起動

ブラウザで Archive Agent GUIを起動するには、以下のコマンドを実行します。

archive-agent gui

📌 注意: コンソールで CTRL+C を押すと、GUIサーバーを閉じることができます。

MCPサーバーの起動

Archive Agent MCPサーバーを起動するには、以下のコマンドを実行します。

archive-agent mcp

📌 注意: コンソールで CTRL+C を押すと、MCPサーバーを閉じることができます。

💡 知っておくと良いこと: これらのMCP設定を使用すると、IDEやAI拡張機能が Archive Agent を自動化することができます。

• for GitHub Copilot agent mode (VS Code):
• for Roo Code (VS Code extension)

MCPツール

Archive Agent はMCPを介して以下のツールを公開しています。

📌 注意: これらのコマンドは 読み取り専用 であり、AIがQdrantデータベースを変更することを防ぎます。

💡 知っておくと良いこと: 例えば、IDEやAI拡張機能で #get_answer_rag と入力するだけで、ツールを直接呼び出すことができます。

Archive Agentの更新

Archive Agentを新たにインストールした場合は、すぐにこの手順を行う必要はありません。ただし、最新の機能を利用するためには、定期的にインストールを更新することをお勧めします。

Archive Agent のインストールを更新するには、インストールディレクトリで以下のコマンドを実行します。

./update.sh

📌 注意: 更新がうまくいかない場合は、インストールディレクトリを削除してから、再度Archive Agentのインストールを行ってみてください。 あなたの設定とデータは別の場所に安全に保存されています。 詳細については、Archive Agent設定とQdrantデータベースを参照してください。

💡 知っておくと良いこと: Qdrant Dockerイメージも更新するには、以下のコマンドを実行します。

sudo ./manage-qdrant.sh update

Archive Agent設定

Archive Agent の設定は、~/.archive-agent-settings/ 内のプロファイルフォルダとして整理されています。

例えば、default プロファイルは ~/.archive-agent-settings/default/ にあります。

現在使用されているプロファイルは、~/.archive-agent-settings/profile.json に保存されています。

📌 注意: プロファイルを削除するには、プロファイルフォルダを削除するだけです。 これにより、Qdrantコレクションは削除されません（Qdrantデータベースを参照）。

プロファイル構成

プロファイル構成は、プロファイルフォルダ内の config.json に含まれています。

💡 知っておくと良いこと: config CLIコマンドを使用して、現在のプロファイルの構成（JSON）を nano エディターで開くことができます（現在のプロファイル構成をnanoで開くを参照）。

💡 知っておくと良いこと: switch CLIコマンドを使用して、新しいまたは既存のプロファイルに切り替えることができます（プロファイルの作成または切り替えを参照）。

ウォッチリスト

プロファイルのウォッチリストは、プロファイルフォルダ内の watchlist.json に含まれています。

ウォッチリストは、以下のコマンドのみで管理されます。

• include / exclude / remove
• track / commit / update

AIキャッシュ

各プロファイルフォルダには、ai_cache フォルダも含まれています。

AIキャッシュにより、特定のプロファイル内で以下のことが保証されます。

• 同じ画像は一度だけOCRされます。
• 同じテキストは一度だけチャンク分割されます。
• 同じテキストは一度だけ埋め込みされます。
• 同じチャンクの組み合わせは一度だけ再ランキングされます。

このようにして、Archive Agent はコミットが中断された場合でも、すぐに中断したところから再開することができます。

単一のコミットでAIキャッシュをバイパスするには、commit または update コマンドに --nocache オプションを指定します （変更されたファイルをデータベースにコミットする および 追跡とコミットを一度に実行する を参照）。

💡 知っておくと良いこと: クエリはキャッシュされないため、常に最新の回答が得られます。

📌 注意: 全体のAIキャッシュをクリアするには、プロファイルのキャッシュフォルダを削除するだけです。

📌 技術的な注意: Archive Agent は、テキスト/画像のバイトと、チャンク分割、埋め込み、再ランキング、およびビジョンのAIモデル名から作成された複合ハッシュを使用してキャッシュをキー付けします。 キャッシュキーは決定的であり、チャンク分割、埋め込み、または ビジョン のAIモデル名を変更するたびに生成されます。 キャッシュエントリは永続的に保持されるため、以前のAIモデル名の組み合わせに戻すと、再び "古い" キーにアクセスされます。

Qdrantデータベース

Qdrant データベースは、~/.archive-agent-qdrant-storage/ に保存されています。

📌 注意: このフォルダは、rootとして実行されるQdrant Dockerイメージによって作成されます。

💡 知っておくと良いこと: Qdrantダッシュボードにアクセスすることで、コレクションとスナップショットを管理することができます。

開発者ガイド

Archive Agent は、教育目的でゼロから作成されました（ソフトウェアの両端で）。

💡 知っておくと良いこと: test_data/ を追跡することで、いくつかの テストデータで始めることができます。

重要なモジュール

始めるには、以下の素晴らしいモジュールをチェックしてください。

• ファイルは で処理されます。
• アプリコンテキストは で初期化されます。
• デフォルトの設定は で定義されています。
• CLIコマンドは で定義されています。
• コミットロジックは で実装されています。
• CLIの詳細表示は で処理されます。
• GUIは で実装されています。
• チャンク分割、埋め込み、ビジョン、およびクエリのAI APIプロンプトは で定義されています。
• AIプロバイダーレジストリは にあります。

何か不足しているものがあったり、悪いパターンを見つけた場合は、自由に貢献してリファクタリングしてください！

コードテストと分析

単体テストを実行し、型をチェックし、スタイルをチェックするには、以下のコマンドを実行します。

./audit.sh

既知の問題

• [ ] track が最初にファイルを 追加済み と報告した後、その後の track 呼び出しでは 変更済み と報告されます。
• [ ] 追跡フェーズで追跡されているファイルを削除して復元することは、現在適切に処理されていません。
  • 追跡されているファイルを削除すると、{size=0, mtime=0, diff=removed} が設定されます。
  • 追跡されているファイルを復元すると、{size=X, mtime=Y, diff=added} が設定されます。
  • size と mtime がクリアされたため、復元されたファイルを検出するための情報が失われました。
• [ ] AIビジョンは空の画像にも適用されますが、これらはローカルで簡単に検出してスキップすることができます。
• [ ] PDFベクター画像は、テストが不足しているため、期待通りに変換されない場合があります。（この間、strict OCR戦略を使用すると確実に役立ちます。）
• [ ] バイナリドキュメントのページ番号（例：.docx）はまだサポートされていません。
• [ ] 参照は、チャンク分割プロセスでの段落/文の分割/結合により、概算 です。
• [ ] AIキャッシュは、AiResult スキーマのマイグレーションをまだ処理していません。（エラーが発生した場合は、--nocache フラグを指定するか、すべてのAIキャッシュフォルダを削除すると、この間確実に役立ちます。）
• [ ] strict OCRモードでPDFページから拒否された画像（例：OpenAIコンテンツフィルタポリシー違反のため）は、現在、PDF OCRレイヤーから抽出されたテキスト（ある場合）に頼るのではなく、空のままになっています。

📄 ライセンス

このプロジェクトはGNU GPL v3.0のライセンスの下で公開されています。

Copyright © 2025 Dr.-Ing. Paul Wilhelm <paul@wilhelm.dev>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

詳細は LICENSE を参照してください。