档案代理

Just getting started?

• 👉 Install Archive Agent on Linux
• 👉 Run Archive Agent
• 👉 MCP Tools
• 👉 Update Archive Agent

---

Install Archive Agent

Please install these requirements before proceeding:

• Docker (for running Qdrant server)
• Python >= 3.10 (core runtime) (usually already installed)

AI provider setup

Archive Agent lets you choose between different AI providers:

• Remote APIs (higher performance and cost, less privacy):
• OpenAI: Requires an OpenAI API key.
• OpenRouter: Requires an OpenRouter API key. Access to 400+ models.

• Local APIs (lower performance and cost, best privacy):
• Ollama: Requires Ollama running locally.
• LM Studio: Requires LM Studio running locally.

💡 Good to know: You will be prompted to choose an AI provider at startup; see: Run Archive Agent.

📌 Note: You can customize the specific models used by the AI provider in the Archive Agent settings. However, you cannot change the AI provider of an existing profile, as the embeddings will be incompatible; to choose a different AI provider, create a new profile instead.

OpenAI provider setup

If the OpenAI provider is selected, Archive Agent requires the OpenAI API key.

To export your OpenAI API key, replace sk-... with your actual key and run this once:

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

This will persist the export for the current user.

💡 Good to know: OpenAI won't use your data for training.

OpenRouter provider setup

If the OpenRouter provider is selected, Archive Agent requires an OpenRouter API key.

OpenRouter provides a unified API to access 400+ models from many providers (OpenAI, Google, Anthropic, Meta, and more) through a single endpoint.

To export your OpenRouter API key, replace sk-or-... with your actual key and run this once:

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

This will persist the export for the current user.

With the default Archive Agent Settings, these OpenRouter models are used:

💡 Good to know: You can customize the models in the Archive Agent settings. OpenRouter supports structured outputs, embeddings, and vision across many models. Browse all available models at openrouter.ai/models.

Ollama provider setup

If the Ollama provider is selected, Archive Agent requires Ollama running at http://localhost:11434.

• How to install Ollama.

With the default Archive Agent Settings, these Ollama models are expected to be installed:

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

💡 Good to know: Ollama also works without a GPU. At least 32 GiB RAM is recommended for smooth performance.

LM Studio provider setup

If the LM Studio provider is selected, Archive Agent requires LM Studio running at http://localhost:1234.

• How to install LM Studio.

With the default Archive Agent Settings, these LM Studio models are expected to be installed:

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

💡 Good to know: LM Studio also works without a GPU. At least 32 GiB RAM is recommended for smooth performance.

---

Quickstart on the command line (CLI)

For example, to track your documents and images, run this:

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

To start the GUI, run this:

archive-agent 

Or, to ask questions from the command line:

archive-agent query "Which files mention donuts?"

---

Developer's guide

Archive Agent was written from scratch for educational purposes (on either end of the software).

💡 Good to know: Tracking the test_data/ gets you started with some kind of test data.

Open current profile config in nano

To open the current profile's config (JSON) in the nano editor, run this:

archive-agent config

See Archive Agent settings for details.

Archive Agent settings

Archive Agent settings are organized as profile folders in ~/.archive-agent-settings/.

E.g., the default profile is located in ~/.archive-agent-settings/default/.

The currently used profile is stored in ~/.archive-agent-settings/profile.json.

📌 Note: To delete a profile, simply delete the profile folder. This will not delete the Qdrant collection (see Qdrant database).

Profile configuration

The profile configuration is contained in the profile folder as config.json.

💡 Good to know: Use the config CLI command to open the current profile's config (JSON) in the nano editor (see Open current profile config in nano).

💡 Good to know: Use the switch CLI command to switch to a new or existing profile (see Create or switch profile).

📌 Note: When using GPT-5 (default as of Archive Agent v14.0.0), ai_temperature_query is ignored. GPT-5 reasoning effort and verbosity are currently not available in the configuration, but may be customized directly inside OpenAiProvider.py.

📌 Note: Since max_workers_vision and max_workers_embed requests are processed in parallel per file, and max_workers_ingest files are processed in parallel, the total number of requests multiplies quickly. Adjust according to your system resources and in alignment with your AI provider's rate limits.

How chunk references work

To ensure that every chunk can be traced back to its origin, Archive Agent maps the text contents of each chunk to the corresponding line numbers or page numbers of the source file.

• Line-based files (e.g., .txt) use the range of line numbers as reference.
• Page-based files (e.g., .pdf) use the range of page numbers as reference.

📌 Note: References are only approximate due to paragraph/sentence splitting/joining in the chunking process.

---

CLI command reference

Important modules

To get started, check out these epic modules:

• Files are processed in archive_agent/data/FileData.py
• The app context is initialized in archive_agent/core/ContextManager.py
• The default config is defined in archive_agent/config/ConfigManager.py
• The CLI commands are defined in archive_agent/__main__.py
• The commit logic is implemented in archive_agent/core/CommitManager.py
• The CLI verbosity is handled in archive_agent/core/CliManager.py
• The GUI is implemented in archive_agent/core/GuiManager.py
• The AI API prompts for chunking, embedding, vision, and querying are defined in archive_agent/ai/AiManager.py
• The AI provider registry is located in archive_agent/ai_provider/ai_provider_registry.py

If you miss something or spot bad patterns, feel free to contribute and refactor!