LLM Wiki

LLM Wiki

Build and maintain a persistent Markdown knowledge network instead of rediscovering the same project facts from raw documents in every session. Follow the pattern described by Karpathy's LLM Wiki, while letting each repository define its own schema and privacy boundary.

Preserve the knowledge boundary

• Treat raw sources as immutable. Add a new source or correction record instead of rewriting history.
• Treat the Wiki as synthesized project knowledge, not as a dump of chats, logs, task todos, or copied documents.
• Treat the Wiki-local agent instruction file (AGENTS.md for Codex, CLAUDE.md for Claude Code) as its schema: topology, naming, required metadata, and maintenance rules.
• Keep active task state in the task Spec. Promote only verified, reusable, repository-appropriate knowledge.
• Keep credentials, private messages, user preferences, system memory, production payloads, and personal paths out of shared project knowledge.
• Persist only repository-relative paths, sanitized logical aliases, or content hashes in Wiki pages and maintenance logs. Keep machine-local absolute paths in the uncommitted task baseline only.
• Confirm the target repository accepts Wiki writes before modifying it. A useful finding does not by itself authorize a commit.

Read wiki-contract.md whenever deciding where information belongs or how pages must be structured.

Select one operation

Do not combine a broad restructure with unrelated content ingestion unless the user explicitly requests both.

Run the control loop

1. Read the repository instructions, the Wiki-local agent instruction file, root index.md, and the smallest relevant section indexes.
2. State the requested operation, target root, source root, read or write scope, privacy boundary, and completion evidence.
3. For a write operation, record the repository baseline, dirty and untracked state, expected files, and initial hashes. Stop on overlapping user changes.
4. Inspect current pages before adding content. Reuse or update existing concepts instead of creating near-duplicates.
5. Preserve raw material and source attribution.
6. Make the smallest coherent set of edits. Re-read a shared index, map, or log immediately before writing it and stop on baseline drift.
7. Validate pages, links, metadata, provenance, privacy, and the exact diff before appending a completed maintenance log entry.
8. Report what changed, which sources support it, what remains uncertain, and whether any knowledge candidate was intentionally not synced.

Read the Write baseline gate in maintenance-guide.md before any operation that changes Wiki or inbox files.

Initialize

Confirm the Wiki root and immutable source root, then read init-guide.md. Create only sections justified by the current project; avoid empty taxonomies copied from examples.

Minimum initialization evidence:

• The Wiki-local agent instruction file defines the three layers and maintenance rules.
• README.md, index.md, log.md, and inbox/ exist.
• Each initial section has an index.md.
• Links resolve and content pages satisfy the metadata contract.

Stage inbox material

Add a recognizable source note to inbox/ without rewriting it into project truth. Attach the required intake fields for capture time, origin, owner, intent, target, and status. Do not update indexes or claim ingestion until the full ingest operation completes.

Read the Inbox section of maintenance-guide.md before moving or deleting staged material.

Ingest

Compile source material into the smallest set of existing or new pages that preserves meaning and provenance. Reconcile contradictions explicitly; do not silently replace an older conclusion.

An ingest is complete only when pages, section indexes, the global index, cross-links, optional provenance maps, and log.md agree. Read maintenance-guide.md for the full quality gate.

Query

Start from index.md, follow only relevant pages and their links, and cite concrete repository paths in the answer. Name the date or freshness limit for time-sensitive facts. If the Wiki does not cover the question, say so instead of filling the gap from assumption.

Propose new synthesis as an ingest candidate. Do not mutate the Wiki during a read-only query unless the request also authorizes maintenance.

Lint, repair, or restructure

Treat lint as report-only by default. Read maintenance-guide.md, run the checks that fit the repository, and finish as clean, completed-with-findings, or blocked. Do not repair files or append log.md unless the user or repository also authorizes maintenance writes.

For lint-fix or restructure, apply the write baseline gate, change only the authorized files, validate first, and append a completed log entry last. Preserve redirects or update all inbound links when moving pages. Unresolved findings may remain after a completed audit; they block a repair operation only when its Done Contract requires them to be fixed.

Stop conditions

Stop and report the exact gap when:

• the Wiki root, source root, schema, or write authority is unclear;
• source material contains secrets, private identities, production data, or content unsuitable for the target repository;
• a proposed page conflicts with verified knowledge and the contradiction cannot be resolved from available sources;
• an expected write target already contains overlapping dirty changes or changes after its baseline hash was recorded;
• moving or deleting an inbox or raw-source file could lose the only copy;
• a restructure would break inbound links that cannot be enumerated;
• validation cannot distinguish the new Wiki state from stale or unrelated content.

Reference map

• wiki-contract.md: knowledge layers, information boundaries, topology, naming, metadata, links, and provenance.
• init-guide.md: initialization sequence, minimum directory shape, and schema template.
• maintenance-guide.md: inbox, ingest, query, lint, validation commands, and common failure modes.