Introduction to Archivum
Relevant source files
The following files were used as context for generating this wiki page:
Archivum is a self-hosted, AI-powered knowledge base designed to run entirely on a home server via Docker. Unlike traditional Personal Knowledge Management (PKM) tools that require manual upkeep, Archivum utilizes an AI agent to incrementally build and maintain a persistent wiki. It ingests diverse file formats and URLs, extracts structured notes via Large Language Models (LLMs), and organizes them into a knowledge graph and vector store for semantic search.
The system is architected as a local-first, multi-service stack. It provides a web-based Markdown editor (using CodeMirror 6), a REST API for programmatic access, and a built-in Model Context Protocol (MCP) server. The primary goal is to ensure that knowledge compounds over time with every source added and every question asked, serving as a "wiki that writes itself."
Sources: archivum-prd-v1.0.md:12-24, README.md:3-9, Progress.md:7-14
System Architecture
Archivum is deployed as a single Docker Compose stack consisting of several interconnected services. The architecture prioritizes data durability and local-first storage.
Core Components
| Service | Technology | Role |
|---|---|---|
| Web UI | React + Vite | Three-panel interface for editing, graph visualization, and querying. |
| REST API | FastAPI (Python 3.12) | Core logic for ingestion, search, wiki CRUD, and authentication. |
| MCP Server | Python MCP SDK | Universal interface for AI agents (Claude Desktop, Cursor, etc.). |
| Wiki Agent | Python (Internal) | LLM-driven processing for entity extraction and page generation. |
| Qdrant | Qdrant | Vector database for high-speed semantic search. |
| Neo4j/Kuzu | Neo4j 5 or Kuzu | Graph database for managing entity and page relationships. |
| Caddy | Caddy | Reverse proxy providing TLS termination and auto-HTTPS. |
Sources: archivum-prd-v1.0.md:417-427, README.md:213-228, scripts/install.py:32-60
Infrastructure Diagram
The following diagram illustrates the relationship between the user interfaces, the API backend, and the specialized data stores.
Data Ingestion Pipeline
The ingestion process is the primary mechanism for expanding the knowledge base. It follows a strictly defined sequential pipeline to transform raw files into structured wiki content.
- Raw Input: Files are dropped into the UI or URLs are submitted via the API.
- Parsing: Specific parsers (e.g., PyMuPDF for PDFs, BeautifulSoup for HTML, AST-aware parsers for code) extract text and metadata.
- LLM Extraction: The
WikiAgentsends extracted text to an LLM to identify topics, entities, and relationships. - Wiki Generation: The agent generates Markdown pages with YAML frontmatter.
- Indexing: Content is stored as Markdown (canonical truth), indexed in Qdrant for search, and synced to the graph database for relationship mapping.
Sources: archivum-prd-v1.0.md:129-155, apps/backend/archivum/ingest/agent.py:27-65
Extraction Logic
The WikiAgent uses a specialized system prompt to ensure consistency. It extracts data into a structured JSON format containing pages, entities (person, concept, org, etc.), and relationships (related_to, mentions, etc.).
# From apps/backend/archivum/ingest/agent.py:27-65
WIKI_SYSTEM_PROMPT = """...
Return ONLY valid JSON in this exact structure:
{
"pages": [
{
"slug": "kebab-case-slug",
"title": "Page Title",
"content": "---...# Page Title...",
"tags": ["tag1", "tag2"]
}
],
"entities": [{"name": "Entity Name", "type": "person|concept|org|place|tech"}],
"relationships": [{"from": "entity_name", "to": "entity_name", "type": "related_to|..."}]
}"""
Sources: apps/backend/archivum/ingest/agent.py:27-65
Model Context Protocol (MCP) Server
A critical feature of Archivum is its built-in MCP server, which exposes the knowledge base to external AI agents. It supports both stdio (for local desktop clients) and HTTP/SSE (for remote/web clients) transports.
Available MCP Tools
| Tool | Description |
|---|---|
ingest_source | Processes a file path or URL into the wiki. |
search_wiki | Performs semantic search; returns top-k results with excerpts. |
get_page | Retrieves full Markdown content and metadata by slug. |
list_pages | Returns a list of all pages in the wiki. |
write_page | Creates or updates a page and triggers re-indexing. |
query | Natural language question answering with cited sources. |
graph_neighbors | Returns graph neighbors for a specific entity or page. |
lint_wiki | Runs health checks for broken links or contradictions. |
Sources: archivum-prd-v1.0.md:386-407, apps/backend/archivum/mcp/server.py:46-218
MCP Interaction Flow
Security and Privacy
Archivum is designed to keep data within the home network. Remote access is managed through layers rather than direct port exposure.
- Remote Access: Recommended via Tailscale for full authenticated access or Cloudflare Tunnels for read-only share links.
- Authentication: Password-based login for the owner, with short-lived JWT session tokens and refresh tokens stored in
httpOnlycookies. - Markdown Sanitization: All content is sanitized using
DOMPurify(client-side) andbleach(server-side) to prevent XSS. - Storage Isolation: The
/rawvolume is mounted as read-only to services except for the ingestion pipeline to prevent accidental overwrites.
Sources: archivum-prd-v1.0.md:546-590, README.md:144-180, apps/backend/archivum/api/pages.py:246-270
Configuration and Setup
The system is configured primarily through environment variables defined in a .env file. The install.py script provides a guided wizard to set these values.
| Variable | Description | Default |
|---|---|---|
ANTHROPIC_API_KEY | Key for Claude extraction and synthesis. | — |
LLM_EXTRACTION_PROVIDER | Provider for extraction (anthropic, ollama, etc.). | anthropic |
EMBED_PROVIDER | Provider for embeddings (local, ollama, etc.). | local |
OWNER_PASSWORD | Password for the initial admin account. | changeme |
MCP_API_KEY | Bearer token for MCP server authorization. | — |
Sources: README.md:95-125, scripts/install.py:32-60
Conclusion
Archivum represents a shift from static knowledge repositories to active, agent-maintained systems. By combining canonical Markdown storage with modern AI retrieval and graph technology, it ensures that personal or team knowledge remains evergreen and programmatically accessible. The integration of the Model Context Protocol further positions Archivum as a foundational tool for the emerging ecosystem of AI coding assistants and autonomous agents.
Sources: archivum-prd-v1.0.md:12-24, Progress.md:7-14