The Architecture: Folders, Files, and Rules

The Folder Structure

The second brain lives in one parent directory — call it knowledge-base/ — with three sub-folders and one important file that lives one level above it:

your-workspace/
  CLAUDE.md                     ← lives here, one level ABOVE knowledge-base/

  knowledge-base/
    raw/                        ← your source dump; never edited
      session-notes/            ← takeaways saved from Claude conversations
      pages/                    ← all wiki content pages live here
    wiki/                       ← navigation and bookkeeping ONLY
      index.md                  ← table of contents, always current
      log.md                    ← append-only history of every operation
      processed.md              ← registry of already-ingested raw files
    outputs/                    ← finished briefings, reports, and answers

The placement of CLAUDE.md outside knowledge-base/ is intentional: it is Claude's operating manual for the entire workspace, not just a file inside the knowledge base.

The Two Hard Rules

Two rules govern the architecture and must never be broken:

• raw/ is immutable. You dump sources in. Claude reads them. Neither of you edits them. If something in raw/ is wrong, the fix goes in a wiki page, not in the raw source. This preserves your source of truth and makes it possible to re-derive or audit any wiki claim at any time.
• wiki/ contains exactly three files: index.md, log.md, and processed.md. Every content page — every topic, synthesis, entity, and source summary — lives in raw/pages/, not in wiki/. This seems counterintuitive (why are content pages in raw/?) but it solves a real problem: it keeps navigation separate from content. The wiki/ folder is pure bookkeeping; the actual knowledge lives in raw/pages/.

Wikilinks like [[page-name]] resolve by filename regardless of folder, so index.md can still link to everything in raw/pages/ and cross-links between pages work normally.

The processed.md Mechanism

The processed.md file is how the system knows what is new. Every time Claude ingests a raw source, it appends the filename to processed.md. On the next ingest pass — whether triggered manually or by the weekly Dream Sequence — Claude compares raw/ against processed.md and only processes files not yet listed.

This prevents re-ingestion of the same source and makes the Dream Sequence safe to run repeatedly. Drop new files into raw/ anytime; they will be picked up automatically on the next pass. Files already in processed.md are skipped.

The log.md Format

Every operation gets a line in log.md using this exact format:

## [YYYY-MM-DD] ingest|query|dream|session - short title

For example:

## [2026-06-25] ingest - Karpathy LLM Wiki gist
## [2026-06-26] query - Comparison of RAG vs wiki approaches
## [2026-06-30] dream - Weekly health check, 3 orphan pages resolved
## [2026-07-01] session - Product strategy discussion notes

The consistent prefix makes the log grep-parseable: grep "^## [" wiki/log.md | tail -5 gives you the last five operations. This is useful for you to review what has been done and for Claude to orient itself at the start of a new session.

What Goes Inside CLAUDE.md

CLAUDE.md is the document that makes Claude a disciplined wiki maintainer. Without it, Claude has no memory of your conventions from session to session. With it, Claude knows exactly what to do when you say "add this" or "run dream sequence."

Your CLAUDE.md must include:

• The purpose and topic focus of this knowledge base (specific, not generic)
• The folder structure with each location's role explained
• All five operations with step-by-step instructions for each one
• The log.md format with an example entry
• The processed.md format
• The two hard rules stated explicitly
• The self-improving rule: every ingest and every valuable query must update a wiki page and append to log.md

CLAUDE.md is not a one-time setup — it is a living document. As you learn what conventions work for your domain, update it. The better CLAUDE.md is, the less you have to correct Claude across sessions.