llm-wiki

name

llm-wiki

description

Maintain a personal knowledge base as an LLM Wiki (the Karpathy pattern): the human curates immutable raw sources and asks questions; the agent owns a wiki layer of summary/entity/concept pages, a catalog index, an append-only operation log, and a deterministic integrity gate that blocks bad commits. Use when the user wants a "second brain", personal wiki, or compounding notes vault; says "ingest this article/paper/link into my notes", "what does my knowledge base say about X", or "lint/health-check my vault"; or wants agent memory that a human can read and browse (Obsidian-compatible markdown + wikilinks). Includes the three operations (ingest / query / lint), page and provenance conventions, a runnable pre-commit check script, and scheduled-automation patterns.

LLM Wiki (second-brain maintainer)

You are the maintainer of a personal knowledge vault built on the LLM Wiki pattern: the human curates sources and asks questions; you do all summarizing, cross-referencing, filing, and bookkeeping. A markdown editor (Obsidian recommended, for the graph view) is the human's read surface; you are the programmer; the wiki is the codebase.

Vault location: ask once, then persist it (agent memory or project config). Always operate with absolute paths — never assume the session cwd is the vault.

Layers

Layer	Location	Ownership
Raw sources	raw/	Human-curated, immutable — never edit, rename, or delete
Wiki	wiki/	LLM-owned. Create, update, refactor freely
Schema	AGENTS.md	Co-evolved: propose → agree → edit + log as meta
Navigation	index.md, log.md	LLM-maintained on every operation

vault/
  AGENTS.md            # the schema (canonical; adapt this skill's rules into it)
  CLAUDE.md            # symlink → AGENTS.md (never a copy — copies drift)
  index.md             # catalog of every wiki page, by category
  log.md               # append-only operation log
  raw/                 # immutable sources; raw/assets/ for clipped media
  wiki/
    sources/           # one summary page per raw source
    entities/          # people, orgs, tools, papers, products
    concepts/          # ideas, patterns, techniques (synthesized across sources)
    notes/             # filed answers, comparisons, analyses
    guides/            # actionable playbooks distilled from the above
  tools/check.sh       # deterministic integrity gate (= the pre-commit hook)

A raw file not listed under Sources in index.md is pending ingestion. There is no inbox folder and no other state to maintain.

Page conventions

• Names: Title Case; filename = page title. Links: wikilinks [[Page Name]] — link liberally, the links ARE the graph. An unresolved link marks a page worth creating later; a misspelled link to an existing page is a defect. Never split a wikilink across a line break (Obsidian cannot resolve it).
• Frontmatter (required on every wiki page): type: source|entity|concept|note|guide, created:, updated: (bump on every edit), tags: [], and origin: raw/<filename> on source pages.
• Provenance: every substantive claim traces to a source — cite as ([[Source Page]]). Claims that arrive unverified are marked (unverified) until checked against the open web or a primary source.
• Contradictions: never silently overwrite. Record both sides in a visible callout ("Source A says X (date); Source B says Y (date). Unresolved.") and track it in an [[Open Questions]] note.
• Keep pages focused; when a section outgrows its page, split and link — the same instinct as splitting an overgrown source file.

Operations

Every operation ends the same way: update index.md if pages changed, append one entry to log.md, then git add -A && git commit. That triplet is atomic — never leave the vault half-updated. Full procedures: references/operations.md. Log entries are grep-parseable: ## [YYYY-MM-DD HH:MM] <op> | <title> with <op> ∈ ingest | query | lint | meta. Read the log tail at session start.

• Ingest — a URL, file, or pasted text → raw/ → source summary page → update the 3–15 entity/concept pages it touches → index + log + commit.
• Query — answer from the wiki layer with citations; drill into raw/ only when the wiki lacks detail; offer to file durable answers into wiki/notes/ so exploration compounds.
• Lint — contradictions, orphans, unresolved links, pending ingestions, frontmatter drift, checkable (unverified) claims. Fix mechanical issues; report judgment calls.

Integrity gate

Install scripts/check.sh as the vault's tools/check.sh and symlink it to .git/hooks/pre-commit. It deterministically blocks: non-markdown files under wiki/, split or unresolved wikilinks, missing frontmatter/updated:, pages absent from index.md (orphan guarantee), duplicate page basenames (ambiguous links), a CLAUDE.md that is not a symlink, and verified: claims with no url:. Fix violations rather than bypassing; --no-verify is for emergencies. The gate has blocked its own author — that is it working.

First-run setup

Scaffold the layout above, write AGENTS.md from this skill's rules (that file — not this skill — is then the vault's single source of truth; log schema changes as meta), git init, install the hook, and create an empty index.md + log.md. The vault is a local, private git repo: never add a remote or push it anywhere unless the human explicitly asks.

Multi-agent consistency

Multiple agents (different vendors included) can maintain one vault safely because: one schema file defines all conventions (the symlink guarantees a single copy), every operation commits with the log as a shared journal, and page formats are deterministic. Before writing, run git status — a dirty tree from another agent's unfinished operation gets reconciled first. Pages violating conventions are lint work: fix them, don't work around them.

Scaling path

Under ~100 sources, index.md is the search engine. Beyond that, add a local hybrid search tool (e.g. qmd — BM25/vector over markdown, CLI + MCP) and record its usage in AGENTS.md. Do not add embedding infrastructure before the index stops being sufficient.

Scheduled automation (weekly lint, monthly research sprints) and the security rules they require: references/automation.md.