# lx-0/llm-wiki architecture

> Architecture diagram of the GitHub repository lx-0/llm-wiki, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lx-0/llm-wiki
- Repository: https://github.com/lx-0/llm-wiki

## Overview

llm-wiki compiles personal data into a shared, queryable Obsidian wiki. The main workflow captures agent sessions and other substrates, stages or writes them into the vault, compiles them into linked Markdown, then serves human and agent queries. Documented side branches include curiosity scans, wiki health checks, approved suggestions, remote publishing, surfaced commitments, and analytical self-reports. The desktop app is an optional control surface. Several subsystem paths and links below are based on README documentation rather than inspected implementation; these are cited as documented relationships.

Main entry points: [`scripts/compile.py`](https://github.com/lx-0/llm-wiki/blob/main/scripts/compile.py) (Knowledge compiler), [`scripts/core/paths.py`](https://github.com/lx-0/llm-wiki/blob/main/scripts/core/paths.py) (Compiled wiki), [`hooks/session-end.py`](https://github.com/lx-0/llm-wiki/blob/main/hooks/session-end.py) (Session hooks), [`scripts/core/flush_pipeline.py`](https://github.com/lx-0/llm-wiki/blob/main/scripts/core/flush_pipeline.py) (Session staging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture"]
  node_session_hook["Session hooks<br/>[session-end.py]"]
  node_transcript["Transcript extraction<br/>[_transcript.py]"]
  node_flush["Session staging<br/>[flush_pipeline.py]"]
  node_collectors["Substrate collectors"]
  node_html_ingest["HTML ingestion<br/>[html_ingest.py]"]
  node_vault_data[("Vault materials<br/>[paths.py]")]
end

subgraph group_engine["Compilation engine"]
  node_compiler["Knowledge compiler<br/>[compile.py]"]
  node_compile_stages["Compile stages"]
  node_wiki[("Compiled wiki<br/>[paths.py]")]
end

subgraph group_consumption["Wiki consumers"]
  node_query["Wiki query<br/>[query.py]"]
  node_curiosity["Curiosity loop<br/>[producer.py]"]
  node_lint["Wiki health checks<br/>[lint.py]"]
  node_commitments["Commitment surfacing"]
  node_suggestions["Approved suggestions<br/>[producer.py]"]
  node_publish["Remote mirror"]
  node_reports["Self-reports"]
end

subgraph group_desktop["Desktop control"]
  node_desktop_app["Desktop control<br/>[main.ts]"]
  node_wiki_exec["CLI execution seam<br/>[wiki-exec.ts]"]
  node_desktop_query["Desktop query<br/>[query.ts]"]
  node_listeners["Listener lifecycle<br/>[lifecycle.ts]"]
end

subgraph group_foundation["Runtime foundations"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_paths["Vault paths<br/>[paths.py]"]
  node_intent_records["Intent records<br/>[_record.py]"]
end

node_operator(("Operator"))
node_agent(("Agent sessions"))

node_agent -->|"ends session"| node_session_hook
node_session_hook -->|"extracts transcript"| node_transcript
node_session_hook -->|"stages context"| node_flush
node_flush -->|"writes session log"| node_vault_data
node_operator -->|"provides substrates"| node_collectors
node_collectors -->|"writes raw captures"| node_vault_data
node_operator -->|"submits HTML"| node_html_ingest
node_html_ingest -->|"writes articles"| node_vault_data
node_vault_data -->|"feeds materials"| node_compiler
node_compiler -.->|"runs stages"| node_compile_stages
node_compiler -->|"writes articles"| node_wiki
node_operator -->|"asks question"| node_query
node_query -->|"reads index"| node_wiki
node_compiler -->|"queues gap scans"| node_curiosity
node_operator -->|"checks wiki"| node_lint
node_compiler -->|"surfaces commitments"| node_commitments
node_operator -->|"approves actions"| node_suggestions
node_operator -->|"initiates mirror"| node_publish
node_publish -->|"mirrors Markdown"| node_wiki
node_operator -->|"runs study"| node_reports
node_reports -->|"reads substrate"| node_wiki
node_operator -->|"uses controls"| node_desktop_app
node_desktop_app -->|"invokes CLI"| node_wiki_exec
node_desktop_query -->|"runs query"| node_wiki_exec
node_desktop_app -->|"controls listeners"| node_listeners
node_wiki_exec -->|"dispatches wiki command"| node_wiki
node_config -->|"uses paths"| node_paths
node_flush -->|"uses session location"| node_paths
node_intent_records -->|"resolves record paths"| node_paths

click node_session_hook "https://github.com/lx-0/llm-wiki/blob/main/hooks/session-end.py"
click node_transcript "https://github.com/lx-0/llm-wiki/blob/main/hooks/_transcript.py"
click node_flush "https://github.com/lx-0/llm-wiki/blob/main/scripts/core/flush_pipeline.py"
click node_collectors "https://github.com/lx-0/llm-wiki/tree/main/scripts/collectors"
click node_html_ingest "https://github.com/lx-0/llm-wiki/blob/main/scripts/preprocessors/html_ingest.py"
click node_vault_data "https://github.com/lx-0/llm-wiki/blob/main/scripts/core/paths.py"
click node_compiler "https://github.com/lx-0/llm-wiki/blob/main/scripts/compile.py"
click node_compile_stages "https://github.com/lx-0/llm-wiki/tree/main/scripts/compile_stages"
click node_wiki "https://github.com/lx-0/llm-wiki/blob/main/scripts/core/paths.py"
click node_query "https://github.com/lx-0/llm-wiki/blob/main/scripts/query.py"
click node_curiosity "https://github.com/lx-0/llm-wiki/blob/main/scripts/curiosity/producer.py"
click node_lint "https://github.com/lx-0/llm-wiki/blob/main/scripts/lint.py"
click node_commitments "https://github.com/lx-0/llm-wiki/tree/main/scripts/compile_stages"
click node_suggestions "https://github.com/lx-0/llm-wiki/blob/main/scripts/suggestions/producer.py"
click node_publish "https://github.com/lx-0/llm-wiki/tree/main/scripts/publish"
click node_reports "https://github.com/lx-0/llm-wiki/tree/main/scripts/reports/_engine"
click node_desktop_app "https://github.com/lx-0/llm-wiki/blob/main/desktop/src/main.ts"
click node_wiki_exec "https://github.com/lx-0/llm-wiki/blob/main/desktop/src/vault/wiki-exec.ts"
click node_desktop_query "https://github.com/lx-0/llm-wiki/blob/main/desktop/src/vault/query.ts"
click node_listeners "https://github.com/lx-0/llm-wiki/blob/main/desktop/src/listeners/lifecycle.ts"
click node_config "https://github.com/lx-0/llm-wiki/blob/main/scripts/core/config.py"
click node_paths "https://github.com/lx-0/llm-wiki/blob/main/scripts/core/paths.py"
click node_intent_records "https://github.com/lx-0/llm-wiki/blob/main/scripts/intents/_record.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_session_hook,node_transcript,node_flush,node_collectors,node_html_ingest,node_vault_data toneBlue
class node_compiler,node_compile_stages,node_wiki toneAmber
class node_query,node_curiosity,node_lint,node_commitments,node_suggestions,node_publish,node_reports toneMint
class node_desktop_app,node_wiki_exec,node_desktop_query,node_listeners toneRose
class node_config,node_paths,node_intent_records,node_operator,node_agent toneIndigo
```

## Components

### Capture

- [Session hooks](https://github.com/lx-0/llm-wiki/blob/main/hooks/session-end.py): `hooks/session-end.py`
- [Transcript extraction](https://github.com/lx-0/llm-wiki/blob/main/hooks/_transcript.py): `hooks/_transcript.py`
- [Session staging](https://github.com/lx-0/llm-wiki/blob/main/scripts/core/flush_pipeline.py): `scripts/core/flush_pipeline.py`
- [Substrate collectors](https://github.com/lx-0/llm-wiki/tree/main/scripts/collectors): `scripts/collectors`
- [HTML ingestion](https://github.com/lx-0/llm-wiki/blob/main/scripts/preprocessors/html_ingest.py): `scripts/preprocessors/html_ingest.py`
- [Vault materials](https://github.com/lx-0/llm-wiki/blob/main/scripts/core/paths.py): `scripts/core/paths.py`

### Compilation engine

- [Knowledge compiler](https://github.com/lx-0/llm-wiki/blob/main/scripts/compile.py): `scripts/compile.py`
- [Compile stages](https://github.com/lx-0/llm-wiki/tree/main/scripts/compile_stages): `scripts/compile_stages`
- [Compiled wiki](https://github.com/lx-0/llm-wiki/blob/main/scripts/core/paths.py): `scripts/core/paths.py`

### Wiki consumers

- [Wiki query](https://github.com/lx-0/llm-wiki/blob/main/scripts/query.py): `scripts/query.py`
- [Curiosity loop](https://github.com/lx-0/llm-wiki/blob/main/scripts/curiosity/producer.py): `scripts/curiosity/producer.py`
- [Wiki health checks](https://github.com/lx-0/llm-wiki/blob/main/scripts/lint.py): `scripts/lint.py`
- [Commitment surfacing](https://github.com/lx-0/llm-wiki/tree/main/scripts/compile_stages): `scripts/compile_stages`
- [Approved suggestions](https://github.com/lx-0/llm-wiki/blob/main/scripts/suggestions/producer.py): `scripts/suggestions/producer.py`
- [Remote mirror](https://github.com/lx-0/llm-wiki/tree/main/scripts/publish): `scripts/publish`
- [Self-reports](https://github.com/lx-0/llm-wiki/tree/main/scripts/reports/_engine): `scripts/reports/_engine`

### Desktop control

- [Desktop control](https://github.com/lx-0/llm-wiki/blob/main/desktop/src/main.ts): `desktop/src/main.ts`
- [CLI execution seam](https://github.com/lx-0/llm-wiki/blob/main/desktop/src/vault/wiki-exec.ts): `desktop/src/vault/wiki-exec.ts`
- [Desktop query](https://github.com/lx-0/llm-wiki/blob/main/desktop/src/vault/query.ts): `desktop/src/vault/query.ts`
- [Listener lifecycle](https://github.com/lx-0/llm-wiki/blob/main/desktop/src/listeners/lifecycle.ts): `desktop/src/listeners/lifecycle.ts`

### Runtime foundations

- [Runtime configuration](https://github.com/lx-0/llm-wiki/blob/main/scripts/core/config.py): `scripts/core/config.py`
- [Vault paths](https://github.com/lx-0/llm-wiki/blob/main/scripts/core/paths.py): `scripts/core/paths.py`
- [Intent records](https://github.com/lx-0/llm-wiki/blob/main/scripts/intents/_record.py): `scripts/intents/_record.py`

### Other components

- **Operator**
- **Agent sessions**

## Connections

- Agent sessions → Session hooks: ends session (evidence: `README.md`)
- Session hooks → Transcript extraction: extracts transcript (evidence: `hooks/session-end.py`)
- Session hooks → Session staging: stages context (evidence: `hooks/session-end.py`)
- Session staging → Vault materials: writes session log (evidence: `scripts/core/flush_pipeline.py`)
- Operator → Substrate collectors: provides substrates (evidence: `README.md`)
- Substrate collectors → Vault materials: writes raw captures (evidence: `README.md`)
- Operator → HTML ingestion: submits HTML (evidence: `scripts/preprocessors/html_ingest.py`)
- HTML ingestion → Vault materials: writes articles (evidence: `scripts/preprocessors/html_ingest.py`)
- Vault materials → Knowledge compiler: feeds materials (evidence: `README.md`)
- Knowledge compiler → Compile stages: runs stages
- Knowledge compiler → Compiled wiki: writes articles (evidence: `README.md`)
- Operator → Wiki query: asks question (evidence: `scripts/query.py`)
- Wiki query → Compiled wiki: reads index (evidence: `scripts/query.py`)
- Knowledge compiler → Curiosity loop: queues gap scans (evidence: `README.md`)
- Operator → Wiki health checks: checks wiki (evidence: `README.md`)
- Knowledge compiler → Commitment surfacing: surfaces commitments (evidence: `README.md`)
- Operator → Approved suggestions: approves actions (evidence: `README.md`)
- Operator → Remote mirror: initiates mirror (evidence: `README.md`)
- Remote mirror → Compiled wiki: mirrors Markdown (evidence: `README.md`)
- Operator → Self-reports: runs study (evidence: `README.md`)
- Self-reports → Compiled wiki: reads substrate (evidence: `README.md`)
- Operator → Desktop control: uses controls (evidence: `desktop/src/main.ts`)
- Desktop control → CLI execution seam: invokes CLI (evidence: `desktop/src/main.ts`)
- Desktop query → CLI execution seam: runs query (evidence: `desktop/src/vault/query.ts`)
- Desktop control → Listener lifecycle: controls listeners (evidence: `desktop/src/main.ts`)
- CLI execution seam → Compiled wiki: dispatches wiki command (evidence: `desktop/src/vault/wiki-exec.ts`)
- Runtime configuration → Vault paths: uses paths (evidence: `scripts/core/config.py`)
- Session staging → Vault paths: uses session location (evidence: `scripts/core/flush_pipeline.py`)
- Intent records → Vault paths: resolves record paths (evidence: `scripts/intents/_record.py`)
