Wiki Construct — Project Context

This file captures the reasoning behind the wiki-construct project decisions. Future conversations in this Claude.ai project should read this to understand why the decisions are what they are, not just what they are. This is project context, not a deliverable.

Origin

The project came out of two converging conversations:

A review of Karpathy's LLM Wiki gist (April 2026) — an idea for using an LLM to incrementally compile a structured wiki from raw sources, sitting between the user and their corpus. The gist is intentionally abstract; it describes the pattern and tells the reader to instantiate it with their LLM.
A research session on AI memory architecture — established that Travis's "build my own harness" instinct was actually a "build my own memory layer" need. OB1 (NateBJones-Projects/OB1) was identified as the right adoption target for the Lovebug- facing memory layer.

The wiki and OB1 ended up framed as two complementary memory systems with mostly disjoint audiences:

Wiki = Travis's interface to his own thinking. Slow, deliberate, organized for human browsing in Obsidian. Lovebug reads it only when explicitly pointed at a file.
OB1 = Lovebug's working memory. Fast, voluminous, semantic search via MCP, captured automatically from sessions.

This framing is the load-bearing decision. It collapsed architectural confusion that had built up about "should the wiki be agent-readable" — answer: no, not in the first-class sense. It's a human tool. Agents can read files when pointed at them, but the wiki is not designed for autonomous agent consumption.

Why flat structure won

Earlier drafts had nested subfolders inside each ownership domain: Dev/Projects/<slug>/, Dev/Sessions/, Dev/Reference/. Travis pushed back on this with a use case: "I won't navigate folders — I'll go to an index." Fine-grained folders solve a problem he doesn't have.

The flat structure works because:

The index page (<domain>/index.md) is the navigation surface, not the file tree
Frontmatter (type:, tags:, status:) does categorization better than folders, because it's multi-dimensional
Obsidian's graph view and backlinks panel make wikilink-based navigation more useful than folder-based
Folders only matter to the agent (where to write new files) and to git, both of which are happy with flat

Travis's user story: "I built a PBS CLI tool, where did I put that project plan?" → flat structure means it's listed on Content/index.md, found in seconds. Not buried four folders deep.

Why five page types (synthesis included)

The Karpathy spec has entity, concept, comparison, synthesis as page types. Earlier draft proposed dropping all but entity and adding project, session-notes, topic-landing — four types total.

Travis pushed back on dropping synthesis. Reasoning he gave: "It's the thing I want. I'd rather turn it off later than have to adjust to include it." Plus git-as-recovery mitigates the silent-corruption risk.

So the final spec includes synthesis as a real page type, with two safety controls:

Sources required — every synthesis page lists the pages it pulled from, so provenance is traceable
Lint scrutiny — synthesis pages get extra checks during lint (sources still exist, sources still say what synthesis claims they say, no source has been substantially edited)

Concept pages and comparison pages are dropped. They felt like spec extras for a research-paper-heavy corpus, not an operational vault of project plans and session notes. Add them later if a gap is felt.

Why the skill pattern won

Earlier proposed: a CLAUDE.md at the vault root holding both spec and procedures, invoked via session plans through Dispatch that pointed at it explicitly.

Travis pushed back: how is that different from a skill? You're just doing the trigger-routing manually instead of letting the runtime do it.

He was right. Lovebug confirmed Claude Code on herbydev does load skills from ~/.claude/skills/, so the skill pattern works through Dispatch. The split is:

Skill (~/.claude/skills/wiki-maintenance/) — procedures (compile, lint, migration). Vault-agnostic. Loaded by the runtime when trigger phrases match.
CLAUDE.md (vault root) — spec (page types, frontmatter, folder ownership, tags, git protocol). Vault-specific. Read by the skill at the start of every operation.

This means session plans through Dispatch can be one-line trigger phrases ("update the wiki"). The skill description handles routing. CLAUDE.md handles the spec. No session-plan-with-pointer required.

Sessions are top-level, not children of projects

Travis clarified: a session note is whatever happened in a working session that produced enough learning to capture but didn't crystallize into a project. Sessions may reference projects via wikilinks but do not live inside them.

There are also coding-session notes captured by the agent during code execution — those live in the coding project's repo (eventually OB1), not in the wiki. The wiki holds Travis's sessions. OB1 will hold the agent's session captures.

This distinction kept getting blurred and finally settled here.

What's deferred

These were considered and explicitly deferred:

Wiki-aware extraction — extractor doesn't read the wiki. Phase 2 if at all.
OB1 integration — the wiki is decoupled from OB1. They feed the same eventual context-assembler but don't share infrastructure now.
Jenny's interface — a future PBS-public web surface that reads from the wiki. Out of scope.
Public template repo — trucktrav/homelab-templates for hosting the schema doc publicly. Phase 2.
Pre-compact hook for Dispatch transcript capture — that's OB1 territory.
Concept and comparison pages — Karpathy spec extras. Add if a gap is felt.

Success metric

Travis's metric, restated: "The wiki is working when I can go to it, find info, without starting at a bunch of files in a bunch of different folders and trying to remember what is what."

Concrete version: he can answer "what's going on with X?" for any active project in under 30 seconds, without grepping. If the user story above (PBS CLI tool) takes more than two clicks, the wiki is failing.

Naming / labels worth keeping consistent

The project: wiki-construct. The construction phase, distinct from the wiki itself once operational.
The vault: "the wiki vault" or "the HomeLab vault". Same thing.
The skill: wiki-maintenance. Lives at ~/.claude/skills/wiki-maintenance/ on herbydev.
The spec file: CLAUDE.md at the vault root. Always capitalized that way (per Anthropic convention).
The harness: Dispatch (which invokes Claude Code on herbydev). When discussing the agent that performs operations, call it Lovebug or "the agent" — both are fine.
The two memory systems: "the wiki" and "OB1". Don't try to rename them or unify the framing.

Open items (deferred decisions)

Fourth ownership folder name (likely Personal, decided when needed)
Dataview vs. agent-maintained indexes — Dataview is native to Obsidian and handles frontmatter queries; agent-maintained gives more control over prose sections. Pick during Phase B deploy.
Whether top-level Reference/ stays or folds into a domain later. Lean: keep it.
Exact tag list. Will emerge during Phase C migration.

ob1-deployment — the parallel memory system for Lovebug. Six-phase deployment plan, Tailscale-only initially, Authelia deferred until Jenny's interface lands.
second-brain (older project plan) — the extraction pipeline + LLM wiki idea, before the wiki/OB1 split was cleanly framed. Some of its scope rolled into wiki-construct (the wiki side) and some into ob1-deployment (the harness memory side). The "context assembler" concept from second-brain remains relevant for Phase 2 future work.

7.9 KiB Raw Permalink Blame History