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 (ProperDocs) 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.

Research threads

The methodology notes live under kb/notes/; the rendered-site homepage is kb/index.md. Start with deploy-time learning. The foundational vocabulary proceeds from actionable methodology, through reflective system, to graded reflective coverage across representational forms, governed adaptation — search, evaluation, and operative retention — and closure under recommendations. Each property can hold without the others; Commonplace as a reflective system applies them to this repository.

On structure: a wiki accretes it, because structure is cheap to add and free to leave. Commonplace hardens only what an inherited constraint forces and leaves the rest collection-local and replaceable, since task-fitted structure costs cross-task reuse.

Skills, instructions, and commands

Commonplace gives agents three kinds of operative artifact.

Commands (commonplace-*) are the Python CLI — deterministic operations called by name. Install them once per OS user, update the durable command path, and restart the consuming shell or agent runtime:

uv tool install --python ">=3.11" llm-commonplace
uv tool update-shell

After restarting the consuming process, invoke the commands by bare name:

commonplace-validate kb/notes        # check frontmatter, types, links, structure
commonplace-init                      # scaffold Commonplace into the current project
commonplace-github-snapshot https://github.com/owner/repo/issues/123

A further family of commands drives the review system — selecting targets, queuing jobs, finalizing output. commonplace-x-snapshot requires the snapshot package extra. See INSTALL.md for optional extras and the review system overview for review commands.

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/. This includes cp-skill-revise-iterative, an iterative note-revision procedure demoted from the promoted-skills list — its cost-to-value ratio didn't hold up, so it's available on explicit invocation only.

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. A Python runtime, which uv can provision, 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 installs as a user-level uv tool, then scaffolds its KB content into any project. 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. The external-system reviews and source ingest analyses remain available on the rendered site. Raw source captures remain in Git but are deliberately not rendered as pages because they duplicate externally hosted material. 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
uv tool install --python ">=3.11" --editable .
uv tool update-shell

Restart the shells, IDEs, and agent runtimes that need the commands, then call every commonplace-* entry point by bare name. The editable tool observes ordinary source changes directly; after dependency, entry-point, build-metadata, or packaged-scaffold changes, rerun it with uv tool install --reinstall --python ">=3.11" --editable .. Run development dependencies through the project environment, for example uv run pytest and uv run ruff check .. This installation is user-level, so the checkout supplies the one active Commonplace command version for that OS user.

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