🧠 Archive Agent

---

Archive Agent

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

Archive Agent は RAG をコマンドラインで利用できるようにし、MCP を通じてツールに接続します。チャットボットではありません。

---

自然言語で必要な情報を見つける

• セマンティック AI 検索とクエリでドキュメントの可能性を引き出します
• ファイルはコンテキストヘッダー付きのセマンティックチャンク分割を使用して分割され、ローカルデータベースに保存されます。
• RAG エンジン¹は、取得したチャンクの再ランキングと拡張を使用します。

¹ 検索拡張生成とは、あらかじめ用意した情報の断片をクエリに照合する手法です。

---

デバイス上でドキュメントをネイティブにインデックス化

• ローカル AI ファイルシステムインデクサーを搭載
• PDF、画像、Markdown、プレーンテキストなどをネイティブに取り込みます。
• ~/Documents/*.pdf のようなパターンを使用してファイルを選択し、追跡します。
• 自動 OCR（実験的）とエンティティ抽出を使用して画像を文字起こしします。
• 変更はローカルの Qdrant ベクトルデータベースに自動的に同期されます。

---

AI はお好みのものを

• 多くの AI プロバイダーと MCP に対応
• 最高のパフォーマンスを実現する OpenAI または互換 API ¹
• すべてのプロバイダーの 400 以上のモデルにアクセスできる OpenRouter
• プライバシーを最優先する場合に適した Ollama と LM Studio（ローカル LLM）
• 組み込みの MCP サーバーを通じてワークフローと統合します。

¹ xAI / Grok と Claude の OpenAI 互換 API が含まれます。 URL の設定を調整し、OPENAI_API_KEY を上書きするだけです。

---

スケーラブルなパフォーマンス

• 中断後も再開可能な並列処理
• 最適化されたマルチスレッドを使用して、複数のファイルを同時に処理します。
• すべてのネットワークリクエストで、AI キャッシュと余裕を持たせた再試行ロジックを使用します。
• 高品質なプロンプトとスキーマを用いて、AI の構造化出力を活用します。

---

アーキテクチャ

(以下の図が表示されない場合は、Mermaid.live でご覧ください)

graph LR

  %% Ingestion Pipeline
  subgraph Ingestion
    A[<b>Track and Commit Files</b><br>Supports Profiles] --> B[<b>Ingest Files</b><br>Automatic OCR Strategy<br>Image Entity Extraction]
    B --> C[<b>Semantic Chunking</b><br>with Context Headers<br>Lines per Block: 100<br>Words per Chunk: 200]
    C --> D[<b>Embed Chunks</b><br>Model: text-embedding-3-large<br>Vector Size: 3072]
    D --> E[<b>Store Chunks</b><br>Local Qdrant database]
  end

  %% Query Pipeline
  subgraph Query
    F[<b>Ask Question</b>] --> G[<b>Embed Question</b><br>Model: text-embedding-3-large]
    G --> H[<b>Retrieve Nearest Chunks</b><br>Score Min: 0.1<br>Chunks Max: 30]
    E --> H
    H --> I[<b>Rerank by Relevance</b><br>Chunks Max: 8]
    I --> J[<b>Expand Context</b><br>Chunks Radius: 1]
    J --> K[<b>Generate Answer</b>]
    K --> L[<b>Get Answer</b><br>in CLI, GUI, MCP]
  end

---

まずはここから

• 👉 Linux に Archive Agent をインストールする
• 👉 Archive Agent を実行する
• 👉 MCP ツール
• 👉 Archive Agent を更新する

---

ドキュメント

• Archive Agent
  • 自然な言葉で必要な情報を見つける
  • ドキュメントをデバイス上でネイティブにインデックス化
  • AI は自分で選ぶ
  • スケーラブルなパフォーマンス
  • アーキテクチャ
  • 始めたばかりですか？
  • ドキュメント
  • 対応 OS
  • Archive Agent のインストール
    • Ubuntu / Linux Mint
  • AI プロバイダーのセットアップ
    • OpenAI プロバイダーのセットアップ
    • OpenRouter プロバイダーのセットアップ
    • Ollama プロバイダーのセットアップ
    • LM Studio プロバイダーのセットアップ
  • 処理対象のファイル
  • ファイルの処理方法
  • OCR 戦略
  • スマートなチャンク分割の仕組み
  • チャンク参照の仕組み
  • チャンクの取得方法
  • チャンクの再ランキングと拡張の仕組み
  • 回答の生成方法
  • 追跡対象のファイルを選択する方法
  • Archive Agent の実行
  • コマンドライン（CLI）クイックスタート
  • CLI コマンドリファレンス
    • コマンド一覧を見る
    • プロファイルを作成または切り替える
    • 現在のプロファイル設定を nano で開く
    • 対象パターンを追加する
    • 除外パターンを追加する
    • 対象／除外パターンを削除する
    • 対象／除外パターンを一覧表示する
    • パターンを解決してファイルを追跡する
    • 追跡中のファイルを一覧表示する
    • 変更されたファイルを一覧表示する
    • 変更されたファイルをデータベースにコミットする
    • 追跡とコミットをまとめて実行する
    • ファイルを検索する
    • ファイルにクエリを実行する
    • Archive Agent GUI を起動する
    • MCP サーバーを起動する
  • MCP ツール
  • Archive Agent の更新
    • Archive Agent の設定
      • プロファイル設定
    • ウォッチリスト
    • AI キャッシュ
  • Qdrant データベース
  • 開発者ガイド
    • 重要なモジュール
    • ネットワークとリトライの処理
    • コードのテストと分析
    • インメモリストレージで Qdrant を実行する
  • ツール
    • チャンクメタデータ内のファイルパスを変更する
    • コンテキストヘッダーからファイルパスを削除する
  • 既知の問題
  • GNU GPL v3.0 ライセンス
  • コラボレーターを歓迎します

---

対応 OS

Archive Agent は、以下の構成でテスト済みです。

• Ubuntu 24.04（PC x64）
• Ubuntu 22.04（PC x64）

異なる環境で Archive Agent のインストールとテストに成功した場合は、ぜひお知らせください。ここに追加します！

---

Archive Agent のインストール

続行する前に、以下の要件をインストールしてください。

• Docker (Qdrant サーバーの実行に使用)
• Python >= 3.10 (コアランタイム)（通常はすでにインストールされています）

Ubuntu / Linux Mint

このインストール方法は、Ubuntu から派生したあらゆる Linux ディストリビューション（例：Linux Mint）で動作します。

📌 注： GUI、MCP サーバー、Qdrant サーバーは、環境変数 LOCAL_AUTH_PASSWORD から読み込まれる1つのパスワードで保護されています。 Archive Agent をインストールまたは実行する前に、エクスポートしてください（例：シェルのプロファイルに設定します）。 設定されていない場合、archive-agent gui、archive-agent mcp、manage-qdrant.sh は起動を拒否します。

export LOCAL_AUTH_PASSWORD='your-password'

任意の現在のディレクトリに 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 をインストールします（ドキュメントの解析に使用）
• 永続ストレージ、自動再起動、API キーとしての LOCAL_AUTH_PASSWORD を設定して、Qdrant の Docker イメージをダウンロードしてインストールします
• 現在のユーザー向けにグローバルな archive-agent コマンドをインストールします

Archive Agent がインストールされました！

👉 次に、AI プロバイダーのセットアップを完了してください。
（その後、Archive Agent の実行に進めます！）

---

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

Archive Agent では、複数の AI プロバイダーから選択できます。

• リモート API (高性能・高コスト、プライバシー保護は低め)：

  • OpenAI：OpenAI API キーが必要です。
  • OpenRouter：OpenRouter API キーが必要です。400以上のモデルを利用できます。

• ローカル API (低性能・低コスト、プライバシー保護は最も高い)：

  • Ollama：Ollama をローカルで実行する必要があります。
  • LM Studio：LM Studio をローカルで実行する必要があります。

💡 参考情報： 起動時に AI プロバイダーを選択するよう求められます。Archive Agent の実行をご覧ください。

📌 注： Archive Agent の設定で、AI プロバイダーが使用するモデルをカスタマイズできます。ただし、埋め込みに互換性がなくなるため、既存のプロファイルの AI プロバイダーは変更できません。別の AI プロバイダーを選択するには、新しいプロファイルを作成してください。

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

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

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

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

これにより、現在のユーザー向けにエクスポート設定が保持されます。

💡 参考情報： OpenAI はお客様のデータをトレーニングに使用しません。

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

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

OpenRouter は、単一のエンドポイントを通じて複数のプロバイダー（OpenAI、Google、Anthropic、Meta など）の 400 種類以上のモデルにアクセスできる統合 API を提供しています。

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

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

これにより、現在のユーザーの環境にエクスポート設定が保存されます。

デフォルトの Archive Agent Settings では、次の OpenRouter モデルが使用されます。

タスク	デフォルトのモデル	入力／出力コスト
チャンク分割	google/gemini-2.5-flash-lite	トークン 100 万個あたり $0.10 / $0.40
再ランク付け	google/gemini-2.5-flash-lite	トークン 100 万個あたり $0.10 / $0.40
クエリ	google/gemini-2.5-flash	トークン 100 万個あたり $0.30 / $2.50
ビジョン	google/gemini-2.5-flash	トークン 100 万個あたり $0.30 / $2.50
埋め込み	openai/text-embedding-3-large	トークン 100 万個あたり $0.13

💡 補足： Archive Agent settings でモデルをカスタマイズできます。OpenRouter は多くのモデルで、構造化出力、埋め込み、ビジョンをサポートしています。利用可能なすべてのモデルは、openrouter.ai/models で確認できます。

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

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

• Ollama のインストール方法。

デフォルトの Archive Agent Settings では、次の 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 がなくても動作します。 快適に動作させるには、少なくとも 32 GiB の RAM を推奨します。

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

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

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

デフォルトの Archive Agent Settings では、次の 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 がなくても動作します。 快適に動作させるには、少なくとも 32 GiB の RAM を推奨します。

---

処理対象のファイル

Archive Agent は現在、次のファイル形式をサポートしています。

• テキスト：
  • プレーンテキスト：.txt、.md、.markdown
  • ドキュメント：
    • ASCII ドキュメント：.html、.htm（画像はサポートされていません）
    • バイナリドキュメント：.odt、.docx（画像を含む）
  • PDF ドキュメント：.pdf（画像を含む。OCR 戦略を参照）
• 画像：.jpg、.jpeg、.png、.gif、.webp、.bmp

📌 注： HTML ドキュメント内の画像は現在サポートされていません。

📌 注： 旧形式の .doc ファイルは現在サポートされていません。

📌 注： サポート対象外のファイルは記録されますが、処理されません。

---

ファイルの処理方法

最終的に、Archive Agentはすべてを次のようにテキストにデコードします。

• プレーンテキストファイルはUTF-8にデコードされます。
• ドキュメントはプレーンテキストに変換され、画像は抽出されます。
• PDFドキュメントはOCR戦略に従ってデコードされます。
• 画像はAIビジョンを使用してテキストにデコードされます。
  • OCR、エンティティ抽出、または両方の組み合わせ（デフォルト）を使用します。
  • ビジョンモデルは、判読できない画像を拒否します。
  • エンティティ抽出では、画像から構造化情報を抽出します。
  • 構造化情報は画像の説明として書式設定されます。

Archive Agentの設定を参照してください：image_ocr、image_entity_extract

Archive Agentは、最適化されたパフォーマンスでファイルを処理します。

• 外科的同期：
  • PDFの解析フェーズは直列化されます（PyMuPDFのスレッド処理の制限によるものです）。
  • その他すべてのフェーズ（ビジョン、チャンク分割、埋め込み）は、パフォーマンスを最大化するために並列で実行されます。
• ビジョン処理は、ファイル間およびファイル内の画像とページを対象に並列化されます。
• 埋め込み処理は、テキストチャンクとファイルを対象に並列化されます。
• スマートチャンク分割では、引き継ぎの仕組みに依存するため、逐次処理が使用されます。

Archive Agentの設定を参照してください：max_workers_ingest、max_workers_vision、max_workers_embed

---

OCR戦略

PDFドキュメントでは、Archive AgentがサポートするOCR戦略がいくつかあります。

• strict OCR戦略（推奨）：

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

• relaxed OCR戦略：

  • PDFのOCRテキストレイヤーが抽出されます。
  • PDFの前景画像はOCRでデコードされますが、背景画像は無視されます。
  • 低コストで高速な一方、精度は低くなります。

• auto OCR戦略：

  • PDFのOCRテキストレイヤーから抽出された文字数に基づいて、ページごとに最適なOCR戦略の選択を試みます。
  • ocr_auto_threshold（auto OCR戦略がstrictではなくrelaxedを選択するために必要な最小文字数）に基づいて判断します。
  • コスト、速度、精度のバランスを取ります。

⚠️ 警告： auto OCR戦略はまだ実験段階です。 PDFドキュメントには、ページのスタイルやレイアウトに関係する小さな画像や散在する画像が含まれていることが多く、情報への貢献がほとんどない、あるいは結果を煩雑にする場合でも、処理のオーバーヘッドが発生します。

💡 補足： 起動時にOCR戦略を選択するよう求められます（Archive Agentの実行を参照してください）。

---

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

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

• デコードされたテキストをサニタイズし、文に分割します。
• 文を適切なサイズのブロックにまとめます。
• AIモデルを使用して、各ブロックをより小さなチャンクに分割します。
  • ブロック境界は適切に処理されます（最後のチャンクが次のブロックに引き継がれます）。
• 各チャンクの先頭にコンテキストヘッダーを付けます（検索精度が向上します）。
• AI埋め込みを使用して、各チャンクをベクトルに変換します。
• 各ベクトルをファイルのメタデータを含むポイントに変換します。
• 各ポイントをQdrantデータベースに保存します。

Archive Agentの設定を参照してください：chunk_lines_block、chunk_words_target

💡 補足： このスマートチャンク分割により、検索の精度と有効性が向上します。

📌 注： チャンクが埋め込みモデルのトークン上限（通常8192トークン）を超えた場合、まれにArchive Agentは最終手段として、チャンクが収まるまで段階的に10％ずつ（最大10回）切り詰めます。

📌 注： 非常に大きなドキュメントでは、文への分割に時間がかかることがあります。 現在、この手順の進行状況を表示する方法はありません。

---

チャンク参照の仕組み

各チャンクを元の場所まで追跡できるように、Archive Agent は各チャンクのテキスト内容を、ソースファイルの対応する行番号またはページ番号に対応付けます。

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

📌 注： チャンク化の過程で段落や文が分割・結合されるため、参照はあくまで 概算 です。

---

チャンクの取得方法

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

• 質問は AI 埋め込みを使ってベクトルに変換されます。
• 類似したベクトルを持つポイントが Qdrant データベースから取得されます。
• 十分なスコアを持つポイントのチャンクのみが残されます。
• retrieve_knee_enable が有効な場合、スコアが明確に低下する箇所で適応型しきい値が低関連度のチャンクを除外します。

Archive Agent の設定を参照してください：retrieve_score_min、retrieve_chunks_max、retrieve_knee_enable、retrieve_knee_sensitivity、retrieve_knee_min_chunks

📌 注： 適応型しきい値には、並べ替えた類似度スコアに対して Kneedle アルゴリズムを使用します。しきい値をより保守的にするには、retrieve_knee_sensitivity を高く設定し、最低数を確保するには retrieve_knee_min_chunks を使用してください。

💡 調整のヒント：

• 取得される内容が少なすぎる、または文脈が不足している場合は、retrieve_knee_min_chunks を増やす（例：3～5）か、retrieve_knee_sensitivity を高くしてください。
• 取得される内容が多すぎる、またはノイズが多い場合は、retrieve_knee_sensitivity を少し下げる（例：0.8～1.0）か、retrieve_knee_min_chunks を減らしてください。
• 適応型しきい値を完全に無効にする場合は、retrieve_knee_enable を false に設定してください。

---

チャンクの再ランク付けと拡張の仕組み

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

• 取得したチャンクは、質問との関連性に基づいて再ランク付けされます。
• 関連性の高い上位のチャンクのみが残されます（その他のチャンクは破棄されます）。
• 選択された各チャンクは拡張され、関連するドキュメントからより広い文脈が取得されます。

Archive Agent の設定を参照してください：rerank_chunks_max、expand_chunks_radius

---

回答の生成方法

Archive Agent は、再ランク付けされ拡張されたチャンクを使って、次のように質問に回答します。

• LLM は質問のコンテキストとしてチャンクを受け取ります。
• LLM の回答は構造化された出力として返され、フォーマットされます。

💡 補足： Archive Agent は、幅広い状況で役立つことを目指した回答テンプレートを使用します。

---

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

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

• パターンには実際のファイルパスを指定できます。

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

• 💡 パターンは、/home/user/Documents/*.txt（または ~/Documents/*.txt）のような 絶対 パスで指定するか、絶対パスに解決される必要があります。

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

• 💡 ワイルドカード ** を使うと、任意のファイル、および 0 個以上のディレクトリ、サブディレクトリ、ディレクトリへのシンボリックリンクに一致します。

パターンには、含めるパターンと除外するパターンがあります。

• 解決された除外対象ファイルの集合は、解決された包含対象ファイルの集合から取り除かれます。
• 残ったファイル（包含対象で、除外されていないファイル）のみが Archive Agent によって追跡されます。
• 隠しファイルは常に無視されます！

この方法により、追跡する特定のファイルやファイルの種類を細かく制御できます。

---

Archive Agent の実行

💡 補足： 起動時に、次の項目を選択するよう求められます。

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

コマンドラインインターフェース（CLI）のスクリーンショット：

---

コマンドライン（CLI）でクイックスタート

たとえば、ドキュメントや画像を追跡するには、次を実行します。

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

GUI を起動するには、次を実行します。

archive-agent 

または、コマンドラインから質問するには、次を実行します。

archive-agent query "Which files mention donuts?"

---

CLI コマンドリファレンス

コマンド一覧を表示する

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

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 オプションを指定します。

追跡されていないファイルをデータベースから削除する際に自動で確認するには、--confirm-delete オプションを指定します。

💡 補足： 次の場合に変更が検出されます。

• ファイルが追加された
• ファイルが削除された
• ファイルが変更された：
  • ファイルサイズが異なる
  • 更新日時が異なる

すべてのファイルの取り込みが完了した後、Qdrant データベースが更新されます。

📌 注： 最初にファイルを track することを忘れないでください。

追跡とコミットをまとめて実行する

track してから commit までを一度に実行するには、次を実行します。

archive-agent update

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

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

追跡されていないファイルをデータベースから削除する際に自動で確認するには、--confirm-delete オプションを指定します。

ファイルを検索する

archive-agent search "Which files mention donuts?"

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

📌 注： 質問の引数には必ず引用符を使用してください。または、引数を省略すると対話型プロンプトが表示されます。

追加情報（埋め込み、検索、再ランキング）を表示するには、--verbose オプションを指定します。

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

ファイルにクエリを実行する

archive-agent query "Which files mention donuts?"

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

📌 注記： 質問の引数には必ず引用符を使用してください。または、引数を省略して対話型プロンプトを表示します。

追加情報（埋め込み、検索、再ランキング、クエリ実行）を表示するには、--verbose オプションを渡します。

このクエリで AI キャッシュ（埋め込み、再ランキング）を使用しないようにするには、--nocache オプションを渡します。

クエリ結果を JSON ファイルに保存するには、次のいずれかを実行します。

• 特定のファイル名を指定して --to-json を実行します。

  archive-agent query "Which files mention donuts?" --to-json answer.json
  

• --to-json-auto [DIR] を実行すると、質問からわかりやすいファイル名を自動生成し、 ディレクトリ DIR を指定した場合はそこに書き込みます （最大 160 文字。必要に応じて [...] で切り詰めます。デフォルトは現在のディレクトリ . で、パス内に存在しないディレクトリは作成されます）。

  archive-agent query "Which files mention donuts?" --to-json-auto Output/
  # Creates: Output/Which_files_mention_donuts_.json
  

📌 注記： Archive Agent v12.2.0 以降、--to-json または --to-json-auto オプションを使用すると、回答を含む対応する Markdown ファイル（.md）も作成されます。（現在、これを無効にする方法はありません。）

Archive Agent GUI を起動する

ブラウザーで Archive Agent GUI を起動するには、次を実行します。

archive-agent gui

追加情報（埋め込み、検索、再ランキング、クエリ実行）を表示するには、--verbose オプションを渡します。

このクエリで AI キャッシュ（埋め込み、再ランキング）を使用しないようにするには、--nocache オプションを渡します。

クエリ結果を JSON ファイルに保存するには、次を実行します。

• --to-json-auto [DIR] を実行すると、質問からわかりやすいファイル名を自動生成し、 ディレクトリ DIR を指定した場合はそこに書き込みます （最大 160 文字。必要に応じて [...] で切り詰めます。デフォルトは現在のディレクトリ . で、パス内に存在しないディレクトリは作成されます）。

  archive-agent gui --to-json-auto Output/
  

📌 注記： Archive Agent v12.2.0 以降、--to-json-auto オプションを使用すると、回答を含む対応する Markdown ファイル（.md）も作成されます。（現在、これを無効にする方法はありません。）

📌 注記： コンソールで CTRL+C を押すと、GUI サーバーが終了します。

📌 注記： GUI はすべての IPv4 インターフェース（ポート 8501）で待ち受け、表示やクエリの実行前に LOCAL_AUTH_PASSWORD の入力を求めます。

MCP サーバーを起動する

Archive Agent MCP サーバーを起動するには、次を実行します。

archive-agent mcp

追加情報（埋め込み、検索、再ランキング、クエリ実行）を表示するには、--verbose オプションを渡します。

このクエリで AI キャッシュ（埋め込み、再ランキング）を使用しないようにするには、--nocache オプションを渡します。

クエリ結果を JSON ファイルに保存するには、次を実行します。

• --to-json-auto [DIR] を実行すると、質問からわかりやすいファイル名を自動生成し、 ディレクトリ DIR を指定した場合はそこに書き込みます （最大 160 文字。必要に応じて [...] で切り詰めます。デフォルトは現在のディレクトリ . で、パス内に存在しないディレクトリは作成されます）。

  archive-agent mcp --to-json-auto Output/
  

📌 注記： Archive Agent v12.2.0 以降、--to-json-auto オプションを使用すると、回答を含む対応する Markdown ファイル（.md）も作成されます。（現在、これを無効にする方法はありません。）

📌 注記： コンソールで CTRL+C を押すと、MCP サーバーが終了します。

📌 注記： MCP サーバーへのすべてのリクエスト（/sse ストリームと /messages/）には LOCAL_AUTH_PASSWORD が必要です。 Authorization: Bearer <password>（MCP クライアント、スクリプト）または任意のユーザー名を使った HTTP Basic 認証（ブラウザー、curl -u x:<password>）で渡してください。 それ以外の場合は 401 が返されます。

スタンドアロンの STRICT OCR

STRICT 戦略で PDF ファイルを OCR 処理し、Markdown ファイルを出力するには、次のコマンドを実行します。

archive-agent standalone-ocr-strict "~/Documents/scan.pdf"

各ページはページ全体の画像としてレンダリングされ、AI ビジョン OCR で処理されます。 結果は PDF と同じ場所に .md ファイルとして書き込まれます（例：scan.md）。

レンダリング解像度をカスタマイズするには、--dpi オプションを指定します（デフォルト：150）。

詳細情報を表示するには、--verbose オプションを指定します。

この操作で AI キャッシュ を使用しないようにするには、--nocache オプションを指定します。

📌 注： このコマンドの実行に、稼働中の Qdrant データベースは必要ありません。

💡 補足： 次の MCP 設定を使用すると、IDE や AI 拡張機能から Archive Agent を自動化できます。

• .vscode/mcp.json は GitHub Copilot agent mode（VS Code） 用です：
• .roo/mcp.json は Roo Code（VS Code 拡張機能） 用です

---

MCP ツール

Archive Agent は、MCP 経由で次のツールを公開します。

MCP ツール	相当する CLI コマンド	引数	実装	説明
get_patterns	patterns	なし	同期処理	対象／除外パターンの一覧を取得します。
get_files_tracked	track の後に list	なし	同期処理	追跡対象ファイルの一覧を取得します。
get_files_changed	track の後に diff	なし	同期処理	変更されたファイルの一覧を取得します。
get_collections	なし	なし	同期処理	利用可能な Qdrant コレクションの一覧を取得します。
get_chunk_headers	なし	file_path [, collection]	非同期処理	ファイルのチャンク見出しの一覧を取得します。
get_search_result	search	question [, collection]	非同期処理	質問に関連するファイルの一覧を取得します。
get_answer_rag	query	question [, collection]	非同期処理	RAG を使用して質問への回答を取得します。

📌 注： これらのコマンドは読み取り専用で、AI が Qdrant データベースを変更できないようにします。

💡 補足： オプションの collection パラメーターを使用すると、名前を指定して任意の Qdrant コレクションをクエリできます。省略した場合は、アクティブなプロファイルのコレクションが使用されます。利用可能なコレクションを確認するには、#get_collections を使用します。

💡 補足： IDE や AI 拡張機能で #get_answer_rag などと入力するだけで、ツールを直接呼び出せます。

💡 補足： #get_answer_rag の出力は、AiQuery.py で定義されている QuerySchema 形式に従います。

💡 補足： #get_chunk_headers ツールは、指定したファイルのすべてのチャンク見出し（意味要約）を返すことで、ドキュメントの構成をすばやく把握できるようにします。全文を取得せずにドキュメントの内容を理解するのに役立ちます。

---

Archive Agent の更新

Archive Agent をインストールしたばかりの場合、この手順はすぐには必要ありません。 ただし、最新機能を利用するには、定期的にインストールを更新してください。

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

./update.sh

📌 注： 更新できない場合は、インストールディレクトリを削除してから、再度 Archive Agent のインストール をお試しください。 設定とデータは別の場所に安全に保存されています。 詳細については、Archive Agent の設定 と Qdrant データベース をご覧ください。

💡 補足： Qdrant の Docker イメージも更新するには、次のコマンドを実行します。

sudo --preserve-env=LOCAL_AUTH_PASSWORD ./manage-qdrant.sh update

📌 注： sudo は環境変数を引き継がないため、--preserve-env=LOCAL_AUTH_PASSWORD を指定します。manage-qdrant.sh は、この環境変数がない状態ではコンテナの作成を拒否します。

---

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 コマンドを使うと、新しいプロファイルまたは既存のプロファイルに切り替えられます（プロファイルの作成または切り替え を参照）。

キー	説明
config_version	設定のバージョン
mcp_server_host	MCP サーバーのホスト（デフォルトは http://127.0.0.1。LAN 内に公開するには http://0.0.0.0 を設定します）
mcp_server_port	MCP サーバーのポート（デフォルトは 8008）
ocr_strategy	DecoderSettings.py での OCR 戦略
ocr_auto_threshold	auto OCR 戦略が strict ではなく relaxed に切り替わる最小文字数
image_ocr	画像の処理：true で OCR を有効にし、false で無効にします。
image_entity_extract	画像の処理：true でエンティティ抽出を有効にし、false で無効にします。
chunk_lines_block	チャンク分割におけるブロックあたりの行数
chunk_words_target	チャンクあたりの目標単語数
qdrant_server_url	Qdrant サーバーの URL
qdrant_collection	Qdrant コレクションの名前
retrieve_score_min	取得したチャンクの最小類似度スコア（0...1）
retrieve_chunks_max	取得するチャンクの最大数
retrieve_knee_enable	取得の適応型カットオフ（true でニーに基づくカットオフを有効にし、false で無効にします）
retrieve_knee_sensitivity	ニー検出の感度（Kneedle の S パラメーター。値が高いほど保守的になります）
retrieve_knee_min_chunks	適応型カットオフ適用時に保持するチャンクの最小数
rerank_chunks_max	再ランク付け後に保持する上位チャンクの数
expand_chunks_radius	再ランク付けされた各チャンクの前後に追加するチャンクの数
max_workers_ingest	並列処理するファイルの最大数。ファイルごとに 1 つのスレッドを作成します
max_workers_vision	ファイルごとに並列処理するビジョンリクエストの最大数。リクエストごとに 1 つのスレッドを作成します
max_workers_embed	ファイルごとに並列処理する埋め込みリクエストの最大数。リクエストごとに 1 つのスレッドを作成します
ai_provider	ai_provider_registry.py での AI プロバイダー
ai_server_url	AI サーバーの URL
ai_model_chunk	チャンク分割に使用する AI モデル
ai_model_embed	埋め込みに使用する AI モデル
ai_model_rerank	再ランク付けに使用する AI モデル
ai_model_query	クエリに使用する AI モデル
ai_model_vision	ビジョンに使用する AI モデル（"" でビジョンを無効にします）
ai_vector_size	埋め込みのベクトルサイズ（Qdrant コレクションで使用）
ai_temperature_query	クエリモデルの温度（GPT-5 では無視されます）
📌 注記： Archive Agent v14.0.0 以降のデフォルトである GPT-5 を使用する場合、ai_temperature_query は無視されます。
GPT-5 の推論の労力と回答の詳細度は、現在設定から指定できませんが、
OpenAiProvider.py 内で直接カスタマイズできます。

📌 注記： max_workers_vision と max_workers_embed のリクエストはファイルごとに並列処理され、 max_workers_ingest 個のファイルも並列処理されるため、リクエストの総数は急速に増加します。 システムリソースと AI プロバイダーのレート制限に合わせて調整してください。

ウォッチリスト

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

ウォッチリストを管理するコマンドは、次のものに限られます。

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

AI キャッシュ

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

AI キャッシュにより、各プロファイルで次の処理が保証されます。

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

これにより、コミットが中断された場合でも、Archive Agent は中断した箇所からすぐに再開できます。

1 回のコミットで AI キャッシュを回避するには、commit または update コマンドに --nocache オプションを渡します （変更したファイルをデータベースにコミットするおよび追跡とコミットをまとめて実行するを参照）。

💡 補足： クエリはキャッシュされないため、常に最新の回答を得られます。

📌 注記： AI キャッシュ全体を消去するには、プロファイルのキャッシュフォルダーを削除してください。

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

---

Qdrant データベース

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

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

Qdrant サーバーは 127.0.0.1:6333 のみでリッスンし、API キーとして LOCAL_AUTH_PASSWORD を必要とします （manage-qdrant.sh によって QDRANT__SERVICE__API_KEY としてコンテナーに渡されます）。Archive Agent はこれを自動的に送信します。

💡 補足： Qdrant ダッシュボードにアクセスして、コレクションやスナップショットを管理できます。 ダッシュボードでは API キー（LOCAL_AUTH_PASSWORD）の入力が求められます。REST を直接呼び出す場合は、api-key ヘッダーが必要です。

curl -H "api-key: $LOCAL_AUTH_PASSWORD" http://127.0.0.1:6333/collections

📌 注記： API キーなし（または古い API キー）で作成された Qdrant コンテナーは、1 回再作成する必要があります。 manage-qdrant.sh start は、API キーのないコンテナーの起動を拒否します。ストレージは保持されます。

sudo --preserve-env=LOCAL_AUTH_PASSWORD ./manage-qdrant.sh recreate

---

開発者向けガイド

Archive Agent は、ソフトウェアのどちら側にとっても教育目的で一から作成されました。

💡 補足： test_data/ を追跡すると、何らかのテストデータを使って作業を始められます。

重要なモジュール

まずは、次の主要なモジュールをご確認ください。

• ファイルの処理は archive_agent/data/FileData.py で行います
• アプリのコンテキストは archive_agent/core/ContextManager.py で初期化されます
• デフォルト設定は archive_agent/config/ConfigManager.py で定義されています
• CLI コマンドは archive_agent/__main__.py で定義されています
• コミット処理は archive_agent/core/CommitManager.py で実装されています
• CLI の詳細度は archive_agent/core/CliManager.py で処理されます
• GUI は archive_agent/core/GuiManager.py で実装されています
• チャンク化、埋め込み、ビジョン、クエリ用の AI API プロンプトは archive_agent/ai/AiManager.py で定義されています
• AI プロバイダーのレジストリは archive_agent/ai_provider/ai_provider_registry.py にあります

見落としや好ましくないパターンに気づいた場合は、ぜひ貢献してリファクタリングしてください！

ネットワークとリトライ処理

Archive Agent は、指数バックオフとインテリジェントな失敗検出による包括的なリトライロジックを実装しています。

• AI プロバイダーの操作：ネットワークタイムアウトや API エラーに対して、指数バックオフで最大 60 秒の遅延を設け、10 回リトライします
• データベース操作：Qdrant の接続問題に対して、指数バックオフで最大 10 秒の遅延を設け、10 回リトライします
• スキーマ検証：AI 応答の解析に失敗した場合、キャッシュを無効化しながら 10 回リトライします
• MAX_TOKENS の検出：モデルがトークン上限に達した場合は即座にスキップします（確実に切り捨てられる状況で無駄なリトライを行いません）
• ブロック単位の回復性：チャンク化に失敗したブロックは CRITICAL ログを出してスキップし、ファイルの処理を続行します
• 二層の戦略：ネットワークレベルのリトライでインフラストラクチャの障害に対処し、スキーマレベルのリトライで AI 応答の品質に対処します

すべての並列プロセッサ（チャンク化、ビジョン、埋め込み）は、破損したデータを抱えたまま黙って処理を続けるのではなく、致命的なエラーを適切に伝播します。

コードのテストと解析

ユニットテスト、型チェック、スタイルチェックを実行するには、次のコマンドを実行してください。

./audit.sh

インメモリストレージで Qdrant を実行する

インメモリストレージで Qdrant を実行する場合（Docker を利用できない OpenAI Codex 環境など）は、install.sh と archive-agent を実行する前に、次の環境変数を設定してください。

export ARCHIVE_AGENT_QDRANT_IN_MEMORY=1

• install.sh はこの環境変数を確認し、manage-qdrant.sh の実行をスキップします。
• QdrantManager.py はこの環境変数を確認し、サーバー URL と API キーを無視して、代わりにインメモリストレージを使用します。

📌 注： Qdrant のインメモリストレージは揮発性であり、ディスクには保存されません。

---

ツール

チャンクメタデータ内のファイルパスを変更する

現在アクティブな Qdrant コレクション内のチャンクメタデータにあるファイルパスを一括変更するには、次のコマンドを実行してください。

cd tools/

./qdrant-rename-paths-in-chunk-metadata.py
# OR
uv run python qdrant-rename-paths-in-chunk-metadata.py

ファイルの移動やフォルダー名の変更後に、update コマンドを再度実行したくない場合に便利です。

📌 注：

• このツールは Qdrant データベースを直接変更します。重要なデータを扱う場合は、必ずバックアップを作成してください。
• このツールは追跡対象ファイルを更新しません。手動で検索および置換を行い、ウォッチリストを更新する必要があります（Archive Agent の設定を参照）。

コンテキストヘッダーからファイルパスを削除する

Archive Agent < v11.0.0 では、チャンクのコンテキストヘッダーにファイルパスが含まれていました。これは検索結果に偏りをもたらす、好ましくない設計上の判断でした。

現在アクティブな Qdrant コレクション内のコンテキストヘッダーから、すべてのファイルパスを一括削除するには、次のコマンドを実行してください。

cd tools/

./qdrant-remove-paths-from-chunk-headers.py
# OR
uv run python qdrant-remove-paths-from-chunk-headers.py

📌 注：

• このツールは Qdrant データベースを直接変更します。重要なデータを扱う場合は、必ずバックアップを作成してください。

---

既知の問題

• track は最初にファイルを 追加済み と報告しますが、その後の track 呼び出しでは 変更済み と報告します。

• 追跡フェーズで追跡対象のファイルを削除して復元しても、現在は適切に処理されません。

  • 追跡対象のファイルを削除すると、{size=0, mtime=0, diff=removed} が設定されます。
  • 追跡対象のファイルを復元すると、{size=X, mtime=Y, diff=added} が設定されます。
  • size と mtime が消去されているため、復元されたファイルを検出するための情報が失われます。

• 処理できないファイルはウォッチリストに記録されます（追跡を解除すると、Qdrant データベースからの削除が試みられます）。

• 処理できないファイルが、最終統計では「Qdrant データベースで更新済み」と表示されます。

• 空の画像も AI ビジョンで処理されますが、ローカルで簡単に検出してスキップできます。

• テストが不足しているため、PDF のベクター画像が期待どおりに変換されない場合があります。（当面は strict OCR 戦略を使用すると、確実に役立ちます。）

• バイナリ文書のページ番号（例：.docx）はまだサポートされていません。Microsoft Word 文書のサポートは実験的です。

• チャンク分割処理で段落や文を分割・結合するため、参照はあくまで おおよそのもの です。

• AI キャッシュでは、まだ AiResult スキーマの移行に対応していません。（エラーが発生した場合は、当面 --nocache フラグを渡すか、AI キャッシュフォルダーをすべて削除すると確実に役立ちます。）

• strict OCR モードで、PDF ページの画像が拒否された場合（例：OpenAI のコンテンツフィルターポリシー違反）、PDF の OCR レイヤーから抽出したテキスト（存在する場合）に切り替えるのではなく、現在は空のままになります。

• 文の分割に使用される spaCy モデル en_core_web_md は、英語のソーステキストにのみ適しています。現時点では多言語サポートがありません。

• HTML 文書の画像はサポートされていません。

• 処理できないファイルの扱いは、まだカスタマイズできません。ユーザーに確認するべきでしょうか。ファイル全体を拒否するべきでしょうか。処理できない画像は現在、そのまま許容され、[Unprocessable image] に置き換えられます。

• GPT-5 の推論レベルと詳細度は、現在設定で指定できません。

• GUI は最初のボタンクリックに反応せず、2 回目のクリックが必要になることがあります。（Streamlit ではなく NiceGUI を使用するよう移行するべきです。）

• テストカバレッジに不足があります（コアの検索パス）：archive_agent/db/QdrantManager.py は約 54％、archive_agent/ai/query/AiQuery.py は約 57％、archive_agent/core/CliManager.py は約 37％のカバレッジです。不足している領域には、参照修復パス、CLI の書式設定分岐、検索処理のエッジケースが含まれます。

---

GNU GPL v3.0 の下でライセンスされています

Copyright © 2025 Dr.-Ing. Paul Wilhelm <[email protected]>

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 をご覧ください。

---

コラボレーターを歓迎します

このオープンソースプロジェクトへの貢献を歓迎します。お気軽に、いつでもイシューを登録したり、プルリクエストを送信したりしてください。