obsidianrockofthestars/llm-wiki-vault

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.