mduongvandinh/llm-wiki

Layered Automation Stack

The architecture implements a wiki-as-code paradigm where content mutation follows CI/CD patterns rather than traditional editorial workflows. The system decomposes knowledge management into discrete agentic responsibilities:

Core Abstractions

• Atomic Notes: Immutable content units processed through src/processors/atomicify.py, ensuring single-responsibility principle per markdown file
• Semantic Graph: In-memory vector index (likely FAISS or Chroma) maintaining note_id → embedding mappings for similarity-based link suggestions
• Agentic Commits: Claude Code CLI triggered via GitHub Actions .github/workflows/auto-wiki.yml performs automated refactoring passes

Tradeoffs

The HTML-native implementation sacrifices dynamic query capabilities for build-time determinism. By pre-computing all semantic relationships during the static generation phase, the system eliminates runtime LLM dependency—reducing latency to zero at the cost of stale content between rebuilds. This positions it as a read-heavy, write-automated architecture distinct from dynamic RAG systems.

The elimination of the curator bottleneck by delegating taxonomy maintenance and cross-referencing to the LLM itself, effectively treating the knowledge base as a self-organizing codebase.

Novel Technical Approaches

1. Autonomous Bidirectional Linking: Implements AST-aware markdown manipulation where LinkInjector parses the concrete syntax tree to inject [[Backlinks]] sections without breaking existing formatting. Unlike manual Obsidian workflows, this operates via claude-code --agent-mode executing structured refactoring commands.
2. Hierarchical Clustering via LLM Consensus: Employs a multi-pass clustering algorithm where embeddings identify candidate groupings, followed by LLM-based validation of category coherence. References the LLM-as-Judge pattern from Jiang et al. (2023) for taxonomy validation.
3. Content Drift Detection: Monitors embedding cosine-similarity deltas between successive versions of source notes. When drift exceeds threshold=0.15, triggers automatic re-clustering and link graph updates via GitHub Actions webhooks.
4. Static Site Semantic Enrichment: Pre-computes knowledge graph relationships at build time using 11ty or similar SSGs, generating _data/graph.json for client-side graph visualization without exposing API keys to the browser.
5. Claude Code Native Orchestration: Deep integration with claude-code CLI rather than raw API calls, leveraging the tool's built-in file system awareness and multi-step planning capabilities for complex refactoring operations across hundreds of markdown files.

Automation Metrics

Scalability Constraints

The current architecture exhibits O(n²) complexity in link resolution phases—each new note requires similarity comparison against the entire corpus. For repositories exceeding 10,000 notes, the system likely requires:

• Hierarchical Navigable Small World (HNSW) index replacement for brute-force FAISS
• Incremental builds (only processing changed files) via git diff parsing in CI
• Batching Claude Code operations to avoid rate limits during bulk ingestion

Memory footprint scales linearly with embedding dimensionality (1536d for OpenAI text-embedding-3-small), requiring ~6MB per 1000 notes in vector storage.

Competitive Landscape

Integration Points

• Claude Code CLI: Primary orchestration interface via claude-code --permission-level write executed in GitHub Actions runners
• Static Hosts: Optimized for GitHub Pages, Cloudflare Pages, or Vercel through standard html output directories
• Source Formats: Ingests from Apple Notes, Kindle highlights, PDFs via pymupdf or marker preprocessing pipelines

Production Adoption Patterns

1. Indie Researchers: Academic scholars maintaining literature review databases with auto-generated concept maps
2. Technical Writers: Documentation teams using the system to maintain internal architecture decision records (ADRs) with automated cross-referencing
3. Knowledge Workers: Consultants aggregating client notes into searchable, interlinked intelligence repositories
4. Developer Advocates: Curating API documentation and community FAQs with automatic relationship discovery between concepts

Migration Path

Existing Obsidian vaults migrate via src/migrations/obsidian.py, which handles [[WikiLink]] normalization and front-matter schema transformation. The primary friction point involves reconciling manually curated tags with LLM-generated taxonomies—typically resolved through a hybrid confidence thresholding system.