llm-wiki

Files (48)

• .gitignore
• CHANGELOG.md
• CLAUDE.md
• LICENSE
• README.md
• SKILL.md
• CLAUDE.md · examples/
• README.md · examples/
• SKILL.md · examples/
• 2026-06-04-attention-talk-prep.md · examples/local/prep/
• 2017-06-12-attention-is-all-you-need.md · examples/raw/machine-learning/
• 2022-05-27-flashattention.md · examples/raw/machine-learning/
• README.md · examples/wiki/
• gaps.md · examples/wiki/
• index.md · examples/wiki/
• log.md · examples/wiki/
• attention-cost.md · examples/wiki/machine-learning/
• attention-efficiency.md · examples/wiki/machine-learning/
• transformer-architectures.md · examples/wiki/machine-learning/
• why-transformers-scale.md · examples/wiki/machine-learning/
• archive.md · references/
• audit.md · references/
• bulk-ingest.md · references/
• codebase-wiki.md · references/
• concept-map.md · references/
• critical-analysis.md · references/
• distilled-ingest.md · references/
• gaps.md · references/
• graphify.md · references/
• high-fidelity-ingest.md · references/
• ingest.md · references/
• init.md · references/
• lint.md · references/
• local-content.md · references/
• multiple-wikis.md · references/
• okf.md · references/
• rich-format-ingest.md · references/
• scoping.md · references/
• archive-template.md · references/templates/
• article-template.md · references/templates/
• index-template.md · references/templates/
• raw-template.md · references/templates/
• wiki-claude-md-template.md · references/templates/
• wiki-gitignore-template.md · references/templates/
• wiki-readme-template.md · references/templates/
• wiki-skill-template.md · references/templates/
• lint_mermaid.py · scripts/
• lint_wiki.py · scripts/

SKILL.md (first lines)

# LLM Wiki

A knowledge basein plain markdown. Sources land in `raw/` (immutable); you compile them into `wiki/` articles you own. Local markdown with YAML frontmatter, readable on GitHub, openable as an Obsidian vault. No servers, no databases, no embeddings.

Core idea (Karpathy): the LLM writes and maintains the wiki; the human chooses sources and asks questions. Knowledge is compiled once at ingest.

## Invocation

**Query is the default.** Ingest, Lint, Audit and Critique are the four deliberate operations, each opted into by its verb or by a request that plainly calls for it. Anything else is a Query against the wiki: a bare question, "what do I know about X", "summarise everything on Y". No `query` keyword needed.

A leading mode argument routes straight to that operation:

- `ingest` (alias `add`) - trailing text is the source: a URL, a path, or pasted content.
- `lint` - health checks; no further input.
- `audit` - trailing text names the article or topic to verify.
- `critique` (alias `scrutinise`) - trailing text names the article, topic, or pasted content to examine.
- `query` (alias `ask`) - forces query handling when a question could look like another operation.

Otherwise route natural language to Ingest, Lint, Audit or Critique only when it clearly calls for one; answer everything else as a Query.

### Always required, and scenario-gated

Every operation, always:

- Act only on the user's request; never background-write.
- Compile any write from a source already in `raw/`, never straight from a live URL or an external path.
- Update `wiki/index.md` and append `wiki/log.md` on any write.
- Bump an article's `updated` whenever its content changes.
- Replace outdated knowledge by superseding it, never by deleting or editing in place.

Everything else is scenario-gated. Match your task against a branch below and read that file before acting - a pointer is an instruction to open the file, not a citation. When unsure, read it: cheaper than corrupting the wiki by guessing.

- Ingesting any source -> `references/ingest.md`
- No `wiki/` yet, so this ingest initialises one -> `references/init.md`
- Settling what a new wiki is for, or whether an llm-wiki suits the job at all -> `references/scoping.md`
- Source is a PDF, Word file, slides, images, or a spreadsheet -> `references/rich-format-ingest.md`
- User wants the high-signal content rather than the whole source -> `references/distilled-ingest.md`
- Source is a transcript, chat log, interview notes, or a long noisy article -> `references/high-fidelity-ingest.md`
- Many sources at once, or one pass would exhaust context -> `references/bulk-ingest.md`
- The wiki's subject is a codebase -> `references/codebase-wiki.md`
- Drawing or maintaining a mermaid concept map -> `references/concept-map.md`
- Recording or closing a knowledge gap -> `references/gaps.md`
- Personal, uncommitted content under `local/` -> `references/local-content.md`
- Working directory holds several wikis side by side -> `references/multiple-wikis.md`
- Saving an answer into the wiki as an archive page -> `references/archive.md`
- Old-format wiki, or a question about `type`, index form, or log form -> `references/okf.md`
- Running graphify over the wiki as a read-only lens -> `references/graphify.md`

Lint, Audit and Critique each gate their own reference from their section below.

## Design philosophy

For anything the sections below do not cover.

- **Filter at ingest, not in retention.** Decide what is worth keeping, and strip secrets, when a source arrives.
- **Supersession, not decay.** Knowledge does not expire on a timer. When new information replaces old, mark the old article stale, point it at the replacement, and keep it: a superseded decision still explains the current state.
- **Evidence, not confidence scores.** Never attach a number like `0.85` to a claim. State which sources confirm it, which contradict it, when it was last confirmed.
- **Git is the audit trail.** History and rollback come from version control, not bespoke versioning fields. Recommend a git repo.
- **Invocation-driven, human in the loop.** You act when the user asks; no background automation writes to the wiki unsupervised. The user curates; you do the bookkeeping.
- **Text-only and self-contained.** Plain markdown, relative links, YAML frontmatter. Ordinary tools (grep, git, the agent's file and web tools) are fine. External servers, vector stores, embedding pipelines, knowledge-graph databases, and multi-agent sync or governance layers are not - index plus grep covers a personal wiki's scale.

## Architecture

Under the user's project root:

**raw/** - Source material, the source of truth. Immutable means never edited after capture, not that it must be the unfiltered original: a `raw/` file is either a verbatim copy or a reviewed distilled extract of a verbose source (`fidelity: distilled`, `references/distilled-ingest.md`) (preferred). Once written, either is read, never modified. Topic subdirectories, e.g. `raw/machine-learning/`.

**wiki/** - Compiled articles you own. One level of topic subdirectories only: `wiki/<topic>/<article>.md`. Four special files:
- `wiki/README.md` - orientation for anyone opening the wiki without this skill. Mostly static; created at init.
- `wiki/index.md` - global catalogue in OKF index form: per-topic sections of `* [Title](path) - summary`, no Updated column. The entry point for queries.
- `wiki/log.md` - append-only operation log with a greppable prefix.
- `wiki/gaps.md` - register of known unknowns: concepts referenced but unwritten, questions the wiki cannot answer.

**local/** (optional) - Personal markdown kept out of git: drafts, working notes, private sources. A sibling of `raw/` and `wiki/`, excluded by the wiki `.gitignore`. Exempt from the index, log, gaps, cascade and audit. One rule: `local/` may link into `wiki/` and `raw/`, but no committed file may ever link into `local/` (broken for other clones; it leaks the path into git). Full rules and promotion path: `references/local-content.md`.

**SKILL.md** (this file) - the schema layer. Templates live in `references/`.

### File format

Every article and raw file starts with YAML frontmatter, then standard markdown. Frontmatter is machine-readable (Obsidian Properties, Dataview queries); body links render on GitHub and in Obsidian's graph and backlinks.

Article frontmatter:

```yaml
---
title: Transformer Architectures
type: concept          # concept | entity | archive
topic: machine-learning
resource:              # optional canonical URI of the asset an entity describes
created: 2026-04-03
updated: 2026-04-03
status: current        # current | stale
superseded_by:         # relative path to replacement, set only when status: stale
tags: [transformers, attention]
aliases: []
---
```

- `updated` is the canonical "knowledge last changed" date; lint reads it. It changes when content changes, not when the file is touched. The index does not carry it (OKF keeps freshness in frontmatter).
- `type: archive` marks crystallised query answers (`references/archive.md`); archives are point-in-time and never cascade-updated.
- `resource` is the canonical URI of the asset an `entity` article describes (table, service, API, repo), distinct from the body Sources/Raw provenance lines. Optional, absent for abstract `concept` articles. Mirrors the OKF `resource` field (`references/okf.md`).
- `status` and `superseded_by` drive supersession (see Ingest > Conflicts and supersession). Leave `superseded_by` empty for current articles.
- `tags` and `aliases` are optional, for Obsidian and Dataview.

The wiki is a superset of an Open Knowledge Format (OKF) v0.1 bundle, so OKF tooling reads it with no export. **On meeting an older-format wiki mid-Lint or mid-Ingest, on creating or migrating `type` fields, or on any question about index or log form, you MUST read `references/okf.md` and follow it.**

### Links and paths

Inside `wiki/` files, all links are relative to the current file:
- Same topic: `[Other Article](other-article.md)`
- Different topic: `[Other Article](../other-topic/other-article.md)`
- Raw file: `[Source](../../raw/topic/file.md)` (two levels up to project root)

In conversation output, use project-root-relative paths, e.g. `wiki/topic/article.md`. `superseded_by` uses the same file-relative form as body links.

### Special files

`wiki/README.md` covers the raw/wiki split, frontmatter fields, supersession-not-deletion, and what index.md, log.md and gaps.md are, for a reader without this skill. Keep it high-level and static; point at this file's procedures rather than copying them. Template: `references/templates/wiki-readme-template.md`.

From sammcj/agentic-coding, Apache-2.0.

More from sammcj/agentic-coding