Commonplace

Research on knowledge systems, running as one.

Commonplace is a growing body of research on how to build the most powerful agentic systems. The bet is simple: an LLM can consume a theory and act on it, and can even write the code that theory calls for — so an actionable theory of how to build such systems is itself a way of building them. Commonplace aims to be that theory: one closed under its own recommendations, telling an agent when to reason from prose, when to freeze knowledge into durable code, and how to verify what it produces.

The theory's most immediate target is an LLM wiki in the sense Karpathy sketched: a persistent, linked markdown layer that agents build and maintain around your own work, turning ephemeral chats into a durable, growing body of your thinking. This repository ships everything needed to run one — the type system, writing conventions, agent skills, and commonplace-* Python commands.

It is also the first deployment. The research lives here as notes, and LLM agents follow the methodology those notes lay out to maintain the wiki it lives in. The content is AI-generated throughout — a human directs the inquiry; agents (Claude, ChatGPT, and others) draft, connect, and maintain the notes.

This page covers the tool: what's in the repo, how to use it, and how to install it. The research is best read on the rendered site at https://zby.github.io/commonplace/.

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                Rendered-site homepage

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

Five design principles the system is built on. The research claims behind them live in the notes.

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 one scoped exception is review state, which behaves like local operational metadata rather than library content and lives in SQLite (ADR 010, ADR 035).

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

A further family of commands drives the review system — selecting targets, queuing jobs, finalizing output; 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 procedures written in Markdown, like skills, but without the auto-loading: the user or another skill invokes them explicitly. They live under kb/instructions/.

Usage

Two ways to use Commonplace, by what you want from it: install the system to run a knowledge base of your own, or vendor this repo read-only so your agents can consult the research. Python is only needed for the full install — the vendored KB is plain markdown, so it drops into a TypeScript, Rust, or any other project with no programming environment attached.

Installing into a project (full install)

Commonplace can be installed into any project as a Python package. Your agents get the same type system, conventions, and skills, and accumulate knowledge about your domain rather than this one. The package ships the methodology — the research notes, reference docs, instructions, types, skills, and commonplace-* commands — but not the external-system reviews (kb/agent-memory-systems/, kb/agentic-systems/) or the source snapshots in kb/sources/: those are research material specific to this repo, left out to keep the package small. Read them on the rendered site. See INSTALL.md for the setup flow.

Vendored inside your project (reader mode)

To give your agents the full research corpus — external-system reviews and sources included — without running a KB of your own, vendor this repo inside your project — a git submodule, a gitignored clone, or a plain copy — and add one routing paragraph to your project's CLAUDE.md/AGENTS.md (shipped as AGENTS.md.reader-fragment, so appending it is a single command). Placement inside the project root matters: agent harnesses scope file access to the root, so a subdirectory is readable without permission prompts while a sibling directory is not. Reading needs no Python, no venv, and no skills. See INSTALL.md → Reader install for the commands and the paste-ready routing block.

Working in this repo (development)

Clone the repo to explore or contribute to the Commonplace methodology itself, or to evaluate the system before installing it elsewhere — it is a functioning knowledge base out of the box, with skills, types, writing conventions, and methodology all in place. New notes go alongside the existing ones, and the root AGENTS.md provides the project routing layer.

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>.

Prerequisites

Reader mode needs only an agent runtime and ripgrep (rg) — the KB's navigation leans on rg for search, and most agent runtimes bundle it. No Python, no skills: the KB is plain files, so a copy of the repo inside your project works as well as a clone or submodule. The table below applies to the full install:

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