llm-wiki

LLM Wiki

Build and maintain a persistent, compounding personal knowledge base as interlinked Markdown files. Inspired by Andrej Karpathy's LLM Wiki pattern and the LLM Wiki Architecture paradigm.

Core Philosophy

Knowledge is compiled once and kept fresh — not re-derived from scratch on every query.

Traditional RAG scans from scratch on every question, with nothing persisting between queries. LLM Wiki's core insight: let the LLM handle all the bookkeeping (updating cross-references, keeping summaries current, marking contradictions), and humans only need to do three things: curate sources, guide analysis, and ask good questions.

Fundamental difference from RAG:

• RAG = discovering knowledge from scratch every time
• LLM Wiki = knowledge accumulates over time, the knowledge network grows continuously

When This Skill Activates

Use this skill when the user:

• Asks to create, build, or start a wiki or knowledge base
• Asks to ingest, add, or process a source (URL, PDF, notes, transcript)
• Asks a question about their wiki's accumulated knowledge
• Asks to lint, audit, or health-check their wiki
• References their wiki, knowledge base, or notes in a research context

Architecture: Three Layers

LLM Wiki is not software — it's a working paradigm. Three-layer separation achieves concern separation:

┌─────────────────────────────────────────────────────────────┐
│  Layer 3: Convention Layer (SCHEMA.md)                      │
│  Tells LLM how to maintain the wiki — configured once,    │
│  internalized by LLM for all future sessions                │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: Persistent Knowledge Layer                       │
│  (entities/ concepts/ synthesis/ comparisons/ queries/)    │
│  LLM-owned and maintained — primary workspace              │
├─────────────────────────────────────────────────────────────┤
│  Layer 1: Raw Source Layer (raw/)                          │
│  Immutable ground truth — LLM read-only, always retained  │
│  for re-ingestion                                         │
└─────────────────────────────────────────────────────────────┘

Three-layer responsibilities:

• Raw Source Layer (raw/): Factual foundation, added by user, LLM read-only, can be re-ingested anytime
• Persistent Knowledge Layer: LLM's output artifact, readable and writable, primary workspace
• Convention Layer (SCHEMA.md): LLM's working contract, configured once, continuously effective

Operating Contract

• Wiki root resolution order: explicit user path > WIKI_PATH env var > remembered path in ~/.llm-wiki > current working directory (when it already contains SCHEMA.md, index.md, and log.md) > ~/wiki.
• The wiki must remain readable in Obsidian, VS Code, and plain text tools.
• Raw sources are immutable after capture. Fix interpretation in synthesized pages, not in raw/.
• Every durable wiki action updates both navigation (index.md) and history (log.md).
• Prefer fewer, stronger pages over many thin pages.
• Preserve uncertainty. Use confidence, contested, contradictions, and explicit open questions instead of smoothing over weak evidence.
• Do not mass-update 10+ existing pages without explaining the intended change set first, unless the user explicitly asked for autonomous bulk maintenance.
• Treat the wiki root as a dedicated wiki directory. Do not initialize into a non-empty unrelated directory unless the user explicitly approves it.
• Only add helper scripts for deterministic, repetitive work. For this skill, bundled scripting is justified for wiki bootstrap (scripts/init-wiki.sh), but ingest/query/lint remain mostly agent-driven until scale proves more tooling is needed.

Directory Structure

wiki/
|-- SCHEMA.md              # Domain, conventions, page thresholds, tag taxonomy
|-- index.md               # Catalog of synthesized pages with one-line summaries
|-- log.md                 # Append-only action history
|-- raw/                   # Immutable captured sources
|   |-- articles/
|   |-- papers/
|   |-- transcripts/
|   |-- notes/
|   `-- assets/
|-- entities/              # People, organizations, products, projects, tools
|-- concepts/              # Concepts, methods, principles, reusable mental models
|-- comparisons/           # Side-by-side analysis and tradeoff records
|-- queries/               # Filed answers worth preserving
|-- synthesis/             # Higher-level maps, playbooks, and multi-source summaries
`-- _archive/              # Superseded pages kept for traceability

If an existing wiki uses a compatible but different structure, follow SCHEMA.md rather than forcing this layout. Only migrate structure when the user asks.

Resolve The Wiki Root

Before any ingest, query, lint, or edit workflow, resolve the wiki root in this order:

1. If the user explicitly names a path, use that path.
2. Else if WIKI_PATH is set, use it.
3. Else if ~/.llm-wiki exists, use the path stored there.
4. Else if the current working directory already contains SCHEMA.md, index.md, and log.md, treat the current working directory as the wiki root.
5. Else use ~/wiki.

Shell pattern for steps 2-5:

if [ -n "${WIKI_PATH:-}" ]; then
  WIKI="$WIKI_PATH"
elif [ -f "$HOME/.llm-wiki" ]; then
  WIKI="$(cat "$HOME/.llm-wiki")"
elif [ -f "SCHEMA.md" ] && [ -f "index.md" ] && [ -f "log.md" ]; then
  WIKI="$PWD"
else
  WIKI="$HOME/wiki"
fi

If the resolved root does not exist yet and the user is asking to ingest into a wiki, initialize it first. If the target directory exists but is non-empty and does not already look like a wiki, stop and ask before bootstrapping into it.

Session Orientation

Before ingesting, querying, or editing an existing wiki:

1. Resolve the wiki root.
2. Read SCHEMA.md if present.
3. Read index.md if present.
4. Read the last 20-30 entries of log.md if present.
5. Search the wiki for the task's key terms before creating a new page.

This prevents duplicate pages, broken conventions, and repeated work.

Useful shell patterns:

rg -n 'keyword|related term' "$WIKI" -g '*.md'
find "$WIKI" -maxdepth 3 -name '*.md' | sort
tail -80 "$WIKI/log.md"

Initialize A Wiki

When creating a new wiki:

1. Resolve the target root using the rules above.

2. If that root already contains SCHEMA.md, index.md, and log.md, treat it as already initialized; do not reinitialize unless the user explicitly asks.

3. If the target directory exists but is non-empty and does not already look like a wiki, stop and ask before modifying it.

4. Determine the domain. If the user has not specified one, use a broad personal knowledge base domain and note that it is easy to refine later.

5. Run the bootstrap helper (SKILL_DIR is injected by the agent runtime and points to the skill's directory):

   bash "${SKILL_DIR}/scripts/init-wiki.sh" "$WIKI" "$DOMAIN"
   

6. Remember the chosen root for future sessions:

   printf '%s\n' "$WIKI" > "$HOME/.llm-wiki"
   

7. Report the created files and suggest the first high-value sources to ingest.

Bundled bootstrap script

scripts/init-wiki.sh is worth keeping because initialization is deterministic and repetitive:

• SKILL_DIR means the directory containing this SKILL.md; use it when invoking bundled helpers.
• it creates the directory skeleton
• it writes starter SCHEMA.md, index.md, and log.md
• it refuses to overwrite an already initialized wiki root
• it refuses to bootstrap into a non-empty unrelated directory

Do not add more scripts just because a workflow exists in prose. Add them only when a step becomes repetitive enough that the agent would otherwise keep re-implementing shell glue.

Minimal SCHEMA.md

# Wiki Schema

## Domain

Personal knowledge base for research, projects, decisions, reusable workflows, and long-lived learning.

## Conventions

- File names use lowercase kebab-case.
- Every synthesized page starts with YAML frontmatter.
- Use `[[wikilinks]]` for internal links.
- New or updated pages should have at least two meaningful outbound links when possible.
- Add every synthesized page to `index.md`.
- Append every ingest, query filing, lint, archive, and schema change to `log.md`.
- Use provenance markers for specific claims when a page synthesizes multiple sources: `^[raw/articles/source-name.md]`.

## Frontmatter

```yaml
---
title: Page Title
created: YYYY-MM-DD
updated: YYYY-MM-DD
type: entity | concept | comparison | query | synthesis
tags: []
sources: []
confidence: high | medium | low
contested: false
contradictions: []
---
```

## Tag Taxonomy

Start with a small taxonomy and extend deliberately:

- knowledge-management
- ai
- engineering
- finance
- research
- writing
- workflow
- decision
- project
- person
- organization
- tool
- source

New tags must be added here before use.

## Page Thresholds

- Create a page when a concept/entity is central to a source, appears across multiple sources, or is likely to be reused.
- Add to an existing page for passing mentions or incremental facts.
- Do not create pages for trivia, one-off context, or material outside the wiki domain.
- Split pages around 200 lines when they mix distinct topics.
- Archive pages when superseded; do not silently delete knowledge.

## Update Policy

- Prefer newer primary sources over older secondary sources, but keep both when the conflict matters.
- Mark unresolved conflicts with `contested: true` and `contradictions`.
- Never overwrite a prior conclusion without preserving why it changed.

Ingest Sources

When the user provides a URL, PDF, local file, pasted text, transcript, or note:

1. Capture the raw source under raw/ with a descriptive kebab-case file name.

2. Add raw source frontmatter:

   ---
   title: Source Title
   source_url: https://example.com
   ingested: YYYY-MM-DD
   sha256: <body-hash>
   source_type: article | paper | transcript | note | file
   ---
   

3. Compute sha256 over the body after frontmatter. On re-ingest, compare hashes and report unchanged or drifted content.

4. Search existing pages and index.md for relevant entities and concepts.

5. Update existing pages before creating new ones.

6. Create new pages only when they meet SCHEMA.md thresholds.

7. Cross-link pages with [[wikilinks]]; add backlinks where useful.

8. Use only tags from SCHEMA.md, adding taxonomy entries first when needed.

9. Update index.md once after page edits.

10. Append a log.md entry listing files created and updated.

For bulk ingest, read all sources first, identify shared entities/concepts, then update pages in one batch to avoid duplicate or inconsistent pages.

Query The Wiki

When answering from the wiki:

1. Orient from SCHEMA.md, index.md, and recent log.md.
2. Search for relevant terms across Markdown files.
3. Read the strongest relevant pages and raw sources only as needed.
4. Answer from the compiled wiki, naming the pages used with [[wikilinks]].
5. File the answer into queries/, comparisons/, or synthesis/ only if it would be expensive to reconstruct later.
6. Log whether the query was answered only or also filed.

Do not file trivial lookups. Durable pages should encode reusable synthesis, decisions, or hard-won research.

Lint And Health Check

When auditing the wiki, check:

• Broken [[wikilinks]].
• Orphan pages with no inbound links.
• Pages missing from index.md.
• Missing or invalid frontmatter.
• Tags not present in SCHEMA.md.
• Pages over roughly 200 lines.
• Pages with confidence: low, contested: true, or non-empty contradictions.
• Raw source hash drift.
• Stale pages whose domain is fast-moving and whose updated date is old.
• log.md size; rotate to log-YYYY.md when it grows beyond about 500 entries.

Report findings by severity: broken navigation first, then schema/index defects, source integrity, contested/low-confidence knowledge, stale content, and style issues.

Page Patterns

Entity

---
title: Entity Name
created: YYYY-MM-DD
updated: YYYY-MM-DD
type: entity
tags: [organization]
sources: [raw/articles/source.md]
confidence: medium
contested: false
contradictions: []
---

# Entity Name

## Summary

What this entity is and why it matters.

## Key Facts

- Fact with source/provenance.

## Relationships

- Related to [[other-page]] because ...

## Open Questions

- Question that still needs evidence.

Concept

---
title: Concept Name
created: YYYY-MM-DD
updated: YYYY-MM-DD
type: concept
tags: [research]
sources: []
confidence: medium
contested: false
contradictions: []
---

# Concept Name

## Definition

Short explanation.

## Why It Matters

Reusable insight.

## Evidence

- Source-backed details.

## Related

- [[related-concept]]

Synthesis

---
title: Synthesis Title
created: YYYY-MM-DD
updated: YYYY-MM-DD
type: synthesis
tags: [workflow]
sources: []
confidence: medium
contested: false
contradictions: []
---

# Synthesis Title

## Claim

The distilled conclusion.

## Supporting Evidence

| Evidence | Source | Weight |
| --- | --- | --- |
| ... | [[source-or-page]] | high/medium/low |

## Implications

- What should change because of this.

## Watch Items

- What evidence could overturn the conclusion.

Lint Self-Healing Mechanism

Lint is the most overlooked but most critical operation for long-term quality. Run weekly or after accumulating enough new sources. A complete Lint checks:

1. Contradiction detection: Scan all pages with ⚠️ markers for potential contradictions between old and new content
2. Stale content detection: Find claims older than 6 months, compare against latest ingested content, flag potentially outdated info
3. Orphan page detection: Find pages not linked from any other page, suggest adding references
4. Missing concept detection: Find concepts mentioned across multiple sources but without dedicated pages, list suggested new pages
5. Missing link detection: Find places that mention an entity X but don't use [[X]] wikilink

Real scenario for Lint discovering contradictions:

Your wiki has a concept page about "Transformer attention mechanism computational complexity." An early 2022 paper says it's O(n²), while a recently ingested 2025 paper introduces a new linear attention variant with O(n) complexity. Lint discovers this contradiction, adds a warning to the concept page with both source citations, and suggests creating a "linear attention" sub-concept page.

Lint's essence is giving the knowledge base self-healing capability: contradictions don't quietly accumulate, stale claims don't persist long-term, and wiki quality improves over time rather than degrading.

Pitfalls

• Skipping orientation before edits.
• Treating raw sources as editable notes.
• Creating duplicate pages because only index.md was checked.
• Adding tags without updating the taxonomy.
• Filing every answer instead of only reusable synthesis.
• Hiding contradictions by rewriting the latest view as settled fact.
• Letting index.md and log.md drift from the filesystem.

References

• Karpathy's LLM Wiki Gist
• LLM Wiki: Beyond RAG Persistent Knowledge Paradigm