Commonplace

The theory of LLM wikis, running as one.

Commonplace is a framework for agent-operated knowledge bases — LLM wikis in the sense Karpathy sketched: a persistent, linked markdown layer that AI agents build and maintain around your own work. It ships the type system, writing conventions, agent skills, and Python commands to run one.

A wiki is two things — notes and the links between them — and an LLM wiki is one where the agent produces both: it concretizes a vague thought into a committed note, then connects it to everything you've already written. That turns an ephemeral chat, where the insight scrolls away, into a durable, growing body of your thinking. The agent takes the two slow parts, drafting and filing. Judging whether it's true still falls to you — though we're moving more of that into the agents too: critique passes, review gates, refinement loops.

It is self-hosting, in the bootstrapping sense. The theory of how to build LLM wikis lives in this repository as notes, and the methodology those notes lay out is executed here, not just described: LLM agents follow it to maintain the very wiki the theory lives in. The skills agents use to write, connect, and validate notes are themselves artifacts in the wiki, written and maintained the same way; the writing conventions govern the very files they are written in. Nothing here is documentation about a separate system. The wiki is the system, and reading this repo is watching it run.

The content is AI-generated through human-AI collaboration: a human directs the inquiry, and AI agents (Claude, ChatGPT, and others) draft, connect, and maintain the notes.

Rendered notes are available at https://zby.github.io/commonplace/. The HTML site is easier to browse than raw Markdown when reading across the KB.

What's in the box

kb/                       Knowledge base
  types/                  Global types (text, note, instruction, definition, index)
  notes/                  Notes — the primary knowledge unit (theoretical register)
  reference/              Shipped-system docs and ADRs (descriptive register)
  instructions/           Framework skills, review gates, and operator procedures (prescriptive register)
  agent-memory-systems/   Reviews of external agent-memory and knowledge systems
  agentic-systems/        Reviews of external agentic systems and harnesses
  sources/                Snapshotted external sources + analysis
  reports/                Generated review, connect, and fix reports
  work/                   Workshop space — in-flight drafts and explorations
  tasks/                  Work tracking
  log.md                  Improvement log
  index.md                Top-level entry point

src/commonplace/          Packaged operational engine
  cli/                    The commonplace-* commands
  review/                 Review system
  lib/                    Shared runtime helpers
  docs/                   Rendered-site (MkDocs) hooks and assets

Key ideas

Title as claim, not topic. Note titles are assertions that work as prose when linked: "approvals guard against LLM mistakes not active attacks" instead of "approvals system". Following links reads like a chain of reasoning — why this works.

Progressive refinement. Capture with zero friction — a file with no frontmatter is a valid text, with zero structural requirements. Add frontmatter and it becomes a note. A note can later take a specialized type — a definition, an adr — but only when its content earns the extra structure. Structure is earned, not imposed (the wikiwiki principle).

Files, not database. Authored knowledge stays file-backed: universal interface, free versioning via git, zero infrastructure. Derived indexes solve scale problems without replacing the source of truth. The current scoped exception is the experimental review system, which stores review state in SQLite because that state behaves like local operational metadata rather than library content; see ADR 010.

The network IS the knowledge. Individual notes matter less than their relationships. Every link must articulate its relationship (extends, grounds, contradicts, exemplifies) — "related" is not a relationship. An unconnected note is invisible (linking methodology).

Externalized methodology. The procedures for working the wiki — how to write a note, connect it, validate it — are written down as skills and conventions, not baked into a particular model or assistant. Every agent reads them fresh, so a different model, or a new session, produces consistent work: the manual is on disk, not in the weights.

Skills, instructions, and commands

Commonplace gives agents three kinds of operative artifact.

Commands (commonplace-*) are the Python CLI — deterministic operations called by name. Install the package, then:

commonplace-validate kb/notes        # check frontmatter, types, links, structure
commonplace-init                     # scaffold Commonplace into a project
commonplace-github-snapshot <url>    # snapshot a GitHub issue/PR into kb/sources/
commonplace-x-snapshot <url>         # snapshot an X/Twitter thread

The review system ships as a further family of commonplace-* commands; see the review system overview.

Skills (cp-skill-*) are agent procedures the harness auto-loads from their descriptions: when a task matches a skill, the agent invokes it. commonplace-init installs them into a consuming project.

Instructions are the same kind of artifact as skills — procedures written in Markdown — but without the description-based auto-loading. They are invoked explicitly — by the user, or by another skill — and live under kb/instructions/.

Content workflow

Reading

Search the KB, read matching notes, follow links to deepen understanding. Link semantics (extends, grounds, contradicts) help the agent decide which connections are worth following. Good descriptions act as retrieval filters — they discriminate between similar notes so the agent reads fewer irrelevant ones.

Writing

The agent retrieves related notes first, reads the target collection's COLLECTION.md to match its conventions and quality bar, then writes the note (cp-skill-write).

Connecting is a separate step: link the new note from related notes and indexes (cp-skill-connect). An unconnected note is invisible to future search, so it is not optional.

Usage

Direct use (this repo)

Clone the repo and start working. The repo is a functioning knowledge base out of the box — skills, types, writing conventions, and methodology are all in place.

git clone https://github.com/zby/commonplace.git
cd commonplace

If you use direnv, make sure your shell has the direnv hook installed, then run direnv allow once after entering the repo. The .envrc sets PATH and UV_CACHE_DIR for the project. Start Codex or Claude Code from that direnv-loaded interactive shell so the runtime inherits the project venv; otherwise launch it with direnv exec . <command>.

The kb/ directory is both the methodology and your workspace — new notes go alongside the existing ones, and the root AGENTS.md provides the project routing layer.

This is the right mode when:

• You want to explore or contribute to the Commonplace methodology itself

• You want a standalone knowledge base without attaching it to another project

• You're evaluating the system before installing it elsewhere

Installing into a project

Commonplace can be installed into any project as a Python package. See INSTALL.md for the setup flow.

Prerequisites

License

Commonplace is dual-licensed:

• Code in src/ and package tooling: MIT

• Knowledge-base content, documentation, templates, and bundled instructional artifacts: CC BY 4.0