# obsidianrockofthestars/llm-wiki-vault architecture

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

- Interactive diagram: https://gitdiagram.com/obsidianrockofthestars/llm-wiki-vault
- Repository: https://github.com/obsidianrockofthestars/llm-wiki-vault

## Overview

#### Purpose and Operating Model
This is a file-based “LLM wiki vault”: immutable captured notes are synthesized by an AI agent into a navigable Markdown wiki. The wiki is derived state; `Raw/` remains the source of truth. The repository is intended for agentic CLI/editor tools and human reading in Markdown/Obsidian-compatible clients.

#### Primary Entry Points
- Agent operating instructions: `CLAUDE.md`
- Required session gate/context loader: `_vault-guard/session_start.py`
- Human-facing setup and operating guidance: `README.md`, `docs/LESSONS.md`
- Wiki navigation and compact current-state context: `wiki/index.md`, `wiki/digest.md`

#### Source-of-Truth Capture Layer
`Raw/` is append-only and must not be edited by the agent. It separates durable inputs by intent:
- Identity, priorities, decision context: `Raw/00 - Core/riley-profile.md`
- Active-project records: `Raw/01 - Projects/flour-hour.md`, `Raw/01 - Projects/moonpatch.md`
- Preference/judgment calibration and chronological agent-work deltas: `Raw/02 - Calibration/2026-01-15 - reward timing qa.md`, `Raw/03 - Session Logs/2026-01-20-0930 - First wiki build from three sources.md`

Templates standardize new source records at `Raw/Templates/project-note.md` and `Raw/Templates/session-log.md`.

#### Synthesis and Knowledge Graph Layer
The agent reads Raw material, discusses or validates implications with the user, then creates/updates cross-linked wiki pages. Key derived artifacts are:
- Global navigation: `wiki/index.md`
- Cheapest complete operational view: `wiki/digest.md`
- Append-only history of wiki changes: `wiki/log.md`
- Topic/project pages: `wiki/flour-hour.md`, `wiki/moonpatch.md`, `wiki/onboarding-philosophy.md`

Wiki pages use `[[wiki-links]]`; linking concepts across domains is an explicit semantic requirement. `templates/wiki-page.md` defines the page shape.

#### Session Control Flow
1. Start with `python _vault-guard/session_start.py`.
2. The gate checks vault health and loads high-value context (digest, index excerpt, recent session logs).
3. Agent consumes new immutable Raw notes, updates the derived wiki, and records the operation in `wiki/log.md`.
4. On close, the agent writes a new immutable session log under `Raw/03 - Session Logs/`; then `python _vault-guard/snapshot.py` preserves recoverable state.
5. Those logs become later synthesis inputs, forming the closed feedback loop.

#### Integrity and Recovery Boundary
`_vault-guard/` is the enforcement boundary between agent behavior and vault safety:
- `_vault-guard/integrity_check.py` performs sentinel, structure, and format validation; critical failures return non-zero.
- `_vault-guard/session_start.py` blocks normal work if integrity fails.
- `_vault-guard/snapshot.py` creates timestamped compressed backups and retains a bounded history.

Failure handling prioritizes restoring from the newest snapshot before further modifications. This makes mechanical checks—not instruction compliance—the safety mechanism.

#### Runtime and External Dependencies
The operational runtime is Python for guard scripts plus any file-capable LLM agent (for example Claude Code, Cursor, or Gemini CLI). No application server, database, or cloud service is implied. Obsidian is an optional reader for the Markdown wiki-link graph. The design’s persistent interfaces are the filesystem, Markdown documents, Python exit codes, and tar.gz snapshots.

Main entry points: [`_vault-guard/session_start.py`](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/_vault-guard/session_start.py) (Session gate), [`wiki/flour-hour.md`](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/wiki/flour-hour.md) (Topic and project pages), [`wiki/index.md`](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/wiki/index.md) (Wiki navigation), [`Raw/03 - Session Logs/2026-01-20-0930 - First wiki build from three sources.md`](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/Raw/03%20-%20Session%20Logs/2026-01-20-0930%20-%20First%20wiki%20build%20from%20three%20sources.md) (Session logs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_raw["Immutable Raw Capture"]
  node_raw_core["Identity and priorities<br/>immutable Markdown<br/>[riley-profile.md]"]
  node_raw_projects["Project records<br/>immutable Markdown<br/>[flour-hour.md]"]
  node_raw_calibration["Calibration records<br/>immutable Markdown"]
  node_raw_session_logs["Session logs<br/>immutable Markdown"]
  node_raw_templates["Capture templates<br/>Markdown templates<br/>[project-note.md]"]
end

subgraph group_wiki["Derived Wiki"]
  node_wiki_index["Wiki navigation<br/>derived Markdown<br/>[index.md]"]
  node_wiki_digest["Current-state digest<br/>derived Markdown<br/>[digest.md]"]
  node_wiki_topics["Topic and project pages<br/>linked Markdown<br/>[flour-hour.md]"]
  node_wiki_log["Wiki change log<br/>append-only Markdown<br/>[log.md]"]
  node_wiki_template["Wiki page template<br/>Markdown template<br/>[wiki-page.md]"]
end

subgraph group_guard["Vault Guard"]
  node_session_start["Session gate<br/>Python CLI<br/>[session_start.py]"]
  node_integrity_check["Integrity check<br/>Python validator<br/>[integrity_check.py]"]
  node_snapshot["Snapshot recovery<br/>Python backup CLI<br/>[snapshot.py]"]
  node_snapshots[("Recoverable snapshots<br/>tar.gz archive history")]
end

node_agent_instructions["Agent instructions<br/>Markdown<br/>[CLAUDE.md]"]
node_human_guidance["Operating guidance<br/>Markdown docs<br/>[README.md]"]
node_agent_runtime{{"File-capable LLM agent<br/>CLI/editor runtime"}}
node_markdown_reader{{"Markdown / Obsidian reader<br/>optional reader"}}

node_agent_instructions -->|"governs"| node_agent_runtime
node_human_guidance -->|"guides operation"| node_agent_runtime
node_agent_runtime -->|"starts session"| node_session_start
node_session_start -->|"validates first"| node_integrity_check
node_integrity_check -->|"permits work"| node_agent_runtime
node_session_start -->|"loads"| node_wiki_digest
node_session_start -->|"loads excerpt"| node_wiki_index
node_session_start -->|"loads recent"| node_raw_session_logs
node_raw_core -->|"source context"| node_agent_runtime
node_raw_projects -->|"source context"| node_agent_runtime
node_raw_calibration -->|"calibrates judgment"| node_agent_runtime
node_raw_session_logs -->|"synthesis input"| node_agent_runtime
node_raw_templates -.->|"standardizes new records"| node_raw_projects
node_agent_runtime -->|"synthesizes and cross-links"| node_wiki_topics
node_agent_runtime -->|"updates navigation"| node_wiki_index
node_agent_runtime -->|"updates current state"| node_wiki_digest
node_agent_runtime -->|"records operation"| node_wiki_log
node_wiki_template -.->|"defines page shape"| node_wiki_topics
node_wiki_topics -->|"linked from"| node_wiki_index
node_wiki_topics -->|"summarized in"| node_wiki_digest
node_agent_runtime -->|"writes closing log"| node_raw_session_logs
node_agent_runtime -->|"snapshots on close"| node_snapshot
node_snapshot -->|"creates"| node_snapshots
node_snapshots -.->|"restore after failure"| node_integrity_check
node_markdown_reader -->|"navigates"| node_wiki_index
node_markdown_reader -->|"follows wiki-links"| node_wiki_topics

click node_agent_instructions "https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/CLAUDE.md"
click node_human_guidance "https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/README.md"
click node_raw_core "https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/Raw/00%20-%20Core/riley-profile.md"
click node_raw_projects "https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/Raw/01%20-%20Projects/flour-hour.md"
click node_raw_calibration "https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/Raw/02%20-%20Calibration/2026-01-15%20-%20reward%20timing%20qa.md"
click node_raw_session_logs "https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/Raw/03%20-%20Session%20Logs/2026-01-20-0930%20-%20First%20wiki%20build%20from%20three%20sources.md"
click node_raw_templates "https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/Raw/Templates/project-note.md"
click node_wiki_index "https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/wiki/index.md"
click node_wiki_digest "https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/wiki/digest.md"
click node_wiki_topics "https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/wiki/flour-hour.md"
click node_wiki_log "https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/wiki/log.md"
click node_wiki_template "https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/templates/wiki-page.md"
click node_session_start "https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/_vault-guard/session_start.py"
click node_integrity_check "https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/_vault-guard/integrity_check.py"
click node_snapshot "https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/_vault-guard/snapshot.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_raw_core,node_raw_projects,node_raw_calibration,node_raw_session_logs,node_raw_templates toneBlue
class node_wiki_index,node_wiki_digest,node_wiki_topics,node_wiki_log,node_wiki_template toneAmber
class node_session_start,node_integrity_check,node_snapshot,node_snapshots toneMint
class node_agent_instructions,node_human_guidance,node_agent_runtime,node_markdown_reader toneNeutral
```

## Components

### Immutable Raw Capture

Append-only source of truth.

- [Identity and priorities](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/Raw/00%20-%20Core/riley-profile.md): immutable Markdown · `Raw/00 - Core/riley-profile.md`
- [Project records](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/Raw/01%20-%20Projects/flour-hour.md): immutable Markdown · `Raw/01 - Projects/flour-hour.md`
- [Calibration records](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/Raw/02%20-%20Calibration/2026-01-15%20-%20reward%20timing%20qa.md): immutable Markdown · `Raw/02 - Calibration/2026-01-15 - reward timing qa.md`
- [Session logs](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/Raw/03%20-%20Session%20Logs/2026-01-20-0930%20-%20First%20wiki%20build%20from%20three%20sources.md): immutable Markdown · Chronological agent-work deltas and later synthesis input. · `Raw/03 - Session Logs/2026-01-20-0930 - First wiki build from three sources.md`
- [Capture templates](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/Raw/Templates/project-note.md): Markdown templates · Standardizes new project and session source records. · `Raw/Templates/project-note.md`

### Derived Wiki

Navigable Markdown knowledge graph.

- [Wiki navigation](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/wiki/index.md): derived Markdown · `wiki/index.md`
- [Current-state digest](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/wiki/digest.md): derived Markdown · Cheapest complete operational context. · `wiki/digest.md`
- [Topic and project pages](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/wiki/flour-hour.md): linked Markdown · Cross-domain wiki-link graph. · `wiki/flour-hour.md`
- [Wiki change log](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/wiki/log.md): append-only Markdown · `wiki/log.md`
- [Wiki page template](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/templates/wiki-page.md): Markdown template · `templates/wiki-page.md`

### Vault Guard

Safety, session control, and recovery boundary.

- [Session gate](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/_vault-guard/session_start.py): Python CLI · Loads context and blocks normal work on integrity failure. · `_vault-guard/session_start.py`
- [Integrity check](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/_vault-guard/integrity_check.py): Python validator · Sentinel, structure, and format failures return non-zero. · `_vault-guard/integrity_check.py`
- [Snapshot recovery](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/_vault-guard/snapshot.py): Python backup CLI · Creates timestamped tar.gz backups with bounded retention. · `_vault-guard/snapshot.py`
- **Recoverable snapshots**: tar.gz archive history · Newest snapshot is restored before further modifications after failure.

### Other components

- [Agent instructions](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/CLAUDE.md): Markdown · `CLAUDE.md`
- [Operating guidance](https://github.com/obsidianrockofthestars/llm-wiki-vault/blob/main/README.md): Markdown docs · `README.md`
- **File-capable LLM agent**: CLI/editor runtime · Reads sources, validates implications with the user, and synthesizes the wiki.
- **Markdown / Obsidian reader**: optional reader

## Connections

- Agent instructions → File-capable LLM agent: governs
- Operating guidance → File-capable LLM agent: guides operation
- File-capable LLM agent → Session gate: starts session
- Session gate → Integrity check: validates first
- Integrity check → File-capable LLM agent: permits work · Only after a successful check.
- Session gate → Current-state digest: loads
- Session gate → Wiki navigation: loads excerpt
- Session gate → Session logs: loads recent
- Identity and priorities → File-capable LLM agent: source context
- Project records → File-capable LLM agent: source context
- Calibration records → File-capable LLM agent: calibrates judgment
- Session logs → File-capable LLM agent: synthesis input
- Capture templates → Project records: standardizes new records
- File-capable LLM agent → Topic and project pages: synthesizes and cross-links
- File-capable LLM agent → Wiki navigation: updates navigation
- File-capable LLM agent → Current-state digest: updates current state
- File-capable LLM agent → Wiki change log: records operation
- Wiki page template → Topic and project pages: defines page shape
- Topic and project pages → Wiki navigation: linked from
- Topic and project pages → Current-state digest: summarized in
- File-capable LLM agent → Session logs: writes closing log · New logs are immutable after creation.
- File-capable LLM agent → Snapshot recovery: snapshots on close
- Snapshot recovery → Recoverable snapshots: creates
- Recoverable snapshots → Integrity check: restore after failure
- Markdown / Obsidian reader → Wiki navigation: navigates
- Markdown / Obsidian reader → Topic and project pages: follows wiki-links