Graph Database (Kuzu)
Relevant source files
The following files were used as context for generating this wiki page:
Archivum utilizes Kuzu, an embedded graph database, to store and manage complex relationships between wiki pages and extracted entities. As a lightweight alternative to Neo4j, Kuzu provides the infrastructure for multi-hop queries, backlink detection, and knowledge graph visualizations without requiring a separate database container. It serves as a derived index, meaning the graph can be entirely rebuilt from the project's canonical Markdown files.
The graph system enables the AI agent to incrementally build a persistent knowledge base where information compounds. By syncing relationships such as page references, entity mentions, and conceptual relations, Archivum allows users and AI agents to navigate knowledge via a force-directed graph view or natural language queries that leverage multi-hop relationship data.
Sources: archivum-prd-v1.0.md:16, apps/backend/archivum/db/graph.py:1, README.md:213-222
Data Architecture and Schema
The Kuzu implementation follows a structured schema consisting of node tables and relationship tables. The database is initialized at startup, creating these tables if they do not already exist.
Node and Relationship Tables
The schema defines two primary types of nodes and three distinct relationship types to capture the structure of the knowledge base.
| Table Type | Table Name | Fields | Description |
|---|---|---|---|
| Node | Page | slug (PK), title, wiki_id | Represents a Markdown wiki page. |
| Node | Entity | name (PK), type, wiki_id | Represents extracted people, concepts, organizations, etc. |
| Relationship | REFERENCES | FROM Page TO Page | Captured when one page links to another via wikilinks. |
| Relationship | MENTIONS | FROM Page TO Entity | Captured when a page mentions a specific named entity. |
| Relationship | RELATED_TO | FROM Entity TO Entity | Captured for conceptual relationships between entities. |
Sources: apps/backend/archivum/db/graph.py:38-54, archivum-prd-v1.0.md:6 Epic 3
Entity Relationship Diagram
The following diagram illustrates the relationships stored within the Kuzu graph:
The graph supports several entity types, including person, concept, org, place, and tech.
Sources: apps/backend/archivum/db/graph.py:38-54, apps/backend/archivum/ingest/agent.py:46
Integration and Data Flow
The graph database is integrated into the ingestion pipeline and the Model Context Protocol (MCP) server.
Ingestion Pipeline Integration
When the WikiAgent processes a document, it extracts not only the text content but also entities and relationships. These are then upserted into Kuzu using the upsert_page, upsert_entity, and various relationship-adding functions. The agent uses claude-haiku to identify these structured links.
Asynchronous Execution Wrapper
Kuzu calls in the Python backend are synchronous by default. To prevent blocking the main event loop, all graph operations are wrapped in an asyncio.run_in_executor call.
async def _run(fn, *args, **kwargs):
loop = asyncio.get_running_loop()
return await loop.run_in_executor(None, lambda: fn(*args, **kwargs))
Sources: apps/backend/archivum/db/graph.py:61-64
Core Graph Operations
The archivum.db.graph module provides a public API for interacting with the Kuzu instance.
Neighborhood Discovery
The get_neighbors function is critical for the UI and MCP tools. It retrieves all nodes and edges exactly one hop away from a specified node ID (either a Page slug or an Entity name), including both outgoing references and incoming backlinks.
Sources: apps/backend/archivum/db/graph.py:126-179
Index Rebuilding and Maintenance
Because Kuzu is a derived index, Archivum provides a mechanism to rebuild the entire graph. If the index becomes corrupted, it can be regenerated from the source-of-truth Markdown files. Additionally, the cleanup_abandoned_nodes function removes Entity nodes that no longer have incoming MENTIONS edges from any Page (e.g., after a page deletion).
Sources: apps/backend/archivum/db/graph.py:246-279, README.md:218-222
MCP Tools and External Access
The archivum-mcp server exposes graph functionality to external AI clients (like Claude Desktop or Cursor) through specific tools.
| MCP Tool | Description | Implementation |
|---|---|---|
graph_neighbors | Returns Kuzu neighbors of a page/entity. | Calls graph.get_neighbors |
export_graph_demo | Generates a mock graph export for testing. | Uses graph_export.py fixtures |
query | Synthesizes an answer using semantic search + graph context. | Combines Qdrant + Kuzu lookups |
Sources: apps/backend/archivum/mcp/server.py:136-153, archivum-prd-v1.0.md:9 MCP Tools
Visualization and Export
Archivum includes a dedicated script for exporting the graph into inspectable formats. The graph_export.py script can export the live Kuzu database into:
- JSON: A
graph.jsonfile containing all nodes and edges. - HTML: A self-contained, offline-capable visualization using SVG and a circle layout, titled "Archivum graph export".
The export manifest tracks the generation time, output files, and whether the data came from the live DB or a mock demo fallback.
Sources: apps/backend/archivum/scripts/graph_export.py:75-200
Conclusion
The Kuzu-backed graph database is the core of Archivum's relational knowledge management. By mapping connections between wiki pages and entities, it allows the system to move beyond simple keyword search into structured, associative exploration. Its embedded nature ensures that the system remains lightweight for home server deployment while maintaining the ability to reconstruct the entire knowledge structure from flat Markdown files.
Sources: archivum-prd-v1.0.md:1-4, apps/backend/archivum/db/graph.py:1-10