Knowledge Graph & Backlinks
Relevant source files
The following files were used as context for generating this wiki page:
Archivum is designed as an AI-powered knowledge base where information compounds over time rather than remaining as isolated notes. Central to this compounding is the Knowledge Graph, a persistent network of relationships between wiki pages and named entities (people, concepts, organizations, etc.). Unlike traditional RAG systems that treat queries as clean slates, Archivum’s graph captures the synthesis of information during ingestion, allowing for multi-hop discovery and structural awareness.
The system utilizes a dual-layered approach to connectivity: explicit Backlinks (identifying which pages reference the current one) and an automated Relationship Extraction pipeline driven by an LLM agent. This ensures that every new source added to the archive is automatically situated within the existing web of knowledge.
Sources: archivum-prd-v1.0.md:14-23, README.md:14-22
Architecture & Data Flow
The Knowledge Graph is a derived index, meaning the canonical source of truth remains the Markdown files within the wiki directory. The graph is built and updated by the WikiAgent during the ingestion process or when pages are manually edited.
Graph Storage Engines
Archivum supports two primary graph databases:
- Neo4j: Used for high-performance, multi-hop queries and large-scale visualizations.
- Kuzu: An embedded graph database used as a lightweight alternative for home server deployments with limited RAM.
Ingestion to Graph Pipeline
When a document is ingested, it undergoes a structured pipeline where entities and their inter-relationships are mapped into the graph.
This diagram shows the flow from raw source data to the structured graph.
Sources: archivum-prd-v1.0.md:374-386, apps/backend/archivum/ingest/agent.py:46-51, README.md:154-165
Entity and Relationship Extraction
The WikiAgent is responsible for extracting structured knowledge from parsed documents. It identifies named entities and establishes relationships between them using specific types.
Entity Types and Attributes
Entities are categorized to improve graph filtering and visualization:
- person: Individual figures.
- concept: Abstract ideas or theories.
- org: Organizations or companies.
- place: Geographic locations.
- tech: Specific technologies or software.
Relationship Schema
Relationships define the edges between nodes in the graph. Standard types include:
related_tomentioned_withcontrastsreferences(Standard wikilink relationship)
Sources: apps/backend/archivum/ingest/agent.py:165-188, apps/backend/archivum/mcp/demo.py:61-71
Backlink System
Backlinks are automatically tracked by the system to show connectivity from the perspective of a single node. The backend provides a specific endpoint to retrieve all pages that link to a targeted slug.
Logic & API Integration
The get_backlinks endpoint validates the target slug and queries the graph database (Kuzu or Neo4j) to find all incoming edges.
| Endpoint | Method | Parameter | Description |
|---|---|---|---|
/api/pages/{slug}/backlinks | GET | slug | Returns a list of pages referencing the target slug. |
graph_neighbors | MCP Tool | node_id | Returns adjacent nodes and edges for a specific node in the graph. |
Sources: apps/backend/archivum/api/pages.py:257-268, apps/backend/archivum/mcp/server.py:165-171
Code Snippet: Backlink Retrieval
# apps/backend/archivum/api/pages.py:257-268
@router.get("/{slug:path}/backlinks", response_model=list[dict])
async def get_backlinks(
slug: str,
current_user: CurrentUser = Depends(get_current_user),
) -> list[dict]:
slug = _validate_slug(slug)
# Verify page exists
existing = await sqlite.get_page(slug, current_user.wiki_id)
if not existing:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail={"detail": f"Page '{slug}' not found", "code": "page_not_found"},
)
return await graph.get_backlinks(slug, current_user.wiki_id)
Graph Visualization and Export
Archivum provides a force-directed graph view within the Web UI and scripts for exporting the graph as portable artifacts.
Visualisation Features
- Node Color-Coding: Nodes are colored by type (e.g., Pages are blue, Entities are orange).
- Interactive Navigation: Clicking a node navigates directly to its corresponding wiki page.
- Offline Export: The system can generate self-contained HTML files with inline SVG rendering for offline viewing.
Export Structure
The graph_export.py script normalizes graph data into a frontend-friendly format:
{
"nodes": [
{"id": "index", "label": "Index", "type": "page"},
{"id": "Archivum", "label": "Archivum", "type": "entity", "entity_type": "wiki"}
],
"edges": [
{"from": "index", "to": "Archivum", "label": "mentions"}
]
}
Sources: apps/backend/archivum/scripts/graph_export.py:18-35, apps/backend/archivum/mcp/demo.py:192-230
MCP Integration
The Knowledge Graph is exposed to AI agents via the Model Context Protocol (MCP) server. This allows external agents (like Claude Desktop or Cursor) to explore the archive's structure programmatically.
MCP Graph Tools
graph_neighbors: Essential for agents to understand the context surrounding a specific topic by viewing connected nodes.export_graph_demo: Generates a mock-safe demo graph for testing visualizations without a live database.query: Uses a combination of semantic search (Qdrant) and graph traversal (multi-hop) to synthesize answers with citations.
This diagram illustrates how an AI agent retrieves graph data through the MCP interface.
Sources: apps/backend/archivum/mcp/server.py:165-188, archivum-prd-v1.0.md:330-340
Summary
The Knowledge Graph and Backlink system in Archivum transforms a simple collection of Markdown files into a dynamic, interconnected brain. By leveraging automated LLM-based extraction and providing robust API/MCP interfaces, the system ensures that information relationships are preserved, discoverable, and accessible to both human users and AI agents. This structure is foundational to the project's goal of creating a "wiki that writes itself."