atomicmemory/llm-wiki-compiler

Compiler Pipeline Architecture

Implements a directed acyclic graph (DAG) compilation model where source files are nodes and semantic relationships are edges. The architecture separates ingestion from synthesis, enabling incremental rebuilds via content-addressable hashing.

Core Abstractions

• KnowledgeNode: Immutable vertex representing a semantic unit (paragraph/code block) with SHA-256 content hashing
• ContextEdge: Weighted edge containing similarity scores and bidirectional relevance metrics
• CompilationUnit: Atomic work unit for parallel processing; implements Merkle tree integrity

Tradeoffs

Prioritizes compilation speed over query-time latency, shifting computational cost to build-time. Uses TypeScript's single-threaded event loop with worker_threads for embedding generation, accepting memory overhead for graph resident set.

"Context-native compilation: treating knowledge bases as differentiable computation graphs where backlinks serve as gradient pathways for information retrieval, effectively minimizing context window entropy."

Novel Techniques

1. Semantic Backlink Synthesis: Utilizes vector similarity (cosine > 0.82) to auto-generate wiki-style [[links]] beyond exact string matching, implementing Dense Passage Retrieval heuristics for link prediction.
2. Differential Knowledge Compilation: Implements content-addressable storage (CAS) using Merkle trees to enable sub-second incremental builds. Only affected subgraphs are re-embedded, reducing API costs by ~94% on large vaults.
3. Karpathy-Optimized Chunking: Enforces header hierarchy preservation (H1→H3) with strict token budgets (4k/8k/128k context windows) and "context preamble injection" - prepending file metadata to each chunk for LLM orientation.
4. Bidirectional Context Injection: Maintains prevContext and nextContext pointers in compiled output, enabling LLMs to reconstruct document flow without loading full files, crucial for RAG coherence.
5. Obsidian URI Schema Native: Generates obsidian://open?vault=X&file=Y links compatible with local LLM clients (Ollama, LM Studio) and implements frontmatter YAML schema for property-based retrieval.

Implementation Signature

// Core compilation API
class KnowledgeCompiler {
  async compile(source: SourceTree): Promise<KnowledgeGraph> {
    const chunks = await this.chunker.semanticSplit(source, {
      strategy: 'karpathy-hierarchy',
      maxTokens: this.contextWindow,
      preserveLinks: true
    });
    
    return this.graphBuilder.build(chunks, {
      similarityThreshold: 0.82,
      maxBacklinks: 5,
      differential: true // Merkle-based caching
    });
  }
}

Throughput Metrics

Scalability Characteristics

Horizontal scaling limited by graph connectivity density. Beyond ~100k nodes, All-Pairs similarity computation requires approximate nearest neighbor (ANN) indexing (HNSW) to maintain O(log n) link generation. Currently implements single-node HNSW via hnswlib-node.

Limitations

• Cold Start Penalty: Initial compilation of 10k+ documents requires full embedding generation ($$$ API costs)
• Memory Ceiling: V8 heap limits restrict in-memory graphs to ~150k nodes without external vector DB (Pinecone/Chroma integration experimental)
• TypeScript Event Loop Blocking: Heavy regex parsing for wiki-link extraction can stall I/O; mitigated via setImmediate yielding every 1k lines

Competitive Landscape

Production Adoption Patterns

• AI Research Labs: Using for paper corpus compilation with citation backlinking
• Technical Documentation Teams: Migrating from Docusaurus for LLM-augmented support bots
• Solo Technical Founders: Personal knowledge management (PKM) with ChatGPT integration
• Legal Tech Startups: Case law compilation with semantic precedent linking
• DevRel Teams: API documentation with interactive code example linking

Integration Points

Native support for .env configuration of OpenAI, Anthropic, and Ollama endpoints. Implements ChromaDB and Pinecone exporters for vector persistence. Migration path from Obsidian vaults via --import-obsidian flag preserving frontmatter and tags.