Commonplace
August 19, 2026 · View on GitHub
Research on knowledge systems, running as one.
Commonplace studies how agentic systems can change after deployment through inspectable knowledge artifacts. It also puts that idea into practice: human-directed agents use and revise the Markdown, instructions, schemas, validators, tests, and code in this repository. When later work loads or enforces those artifacts, accepted changes can shape behavior without updating model weights. The repository makes both the mechanism and its governance visible.
The theory's most immediate target is an LLM wiki, in the sense AI researcher Andrej Karpathy sketched: a persistent, linked Markdown layer that agents build and maintain around a person's or project's work. This repository ships the framework for operating one — the type system, writing conventions, agent skills, and commonplace-* Python commands.
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 valid note frontmatter, including description and type: kb/types/note.md, 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.
| Skill | Purpose |
|---|---|
cp-skill-write | Write or edit one artifact under its collection and type contracts |
cp-skill-validate | Validate artifacts, collection landings, and site redirects |
cp-skill-connect | Discover connections and write a connect-report |
cp-skill-convert | Convert raw text captures into structured notes |
cp-skill-ingest | Ingest an external source: snapshot → connect → classify → analyse |
cp-skill-snapshot-web | Capture a URL into kb/sources/ |
cp-skill-health-check | Diagnose a broken Commonplace install |
cp-skill-revise-autoreason | Revise a note with AutoReason-style incumbent/revision/synthesis judging |
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:
| Tool | Required | Purpose |
|---|---|---|
| Agent runtime | yes | Codex, Claude Code, or another internal LLM/IDE that can load project instructions and expose the cp-skill-* skill directories |
| uv | yes | Install the Commonplace command tool and run source-development dependencies |
| git | yes | Versioning, history-preserving renames in convert |
ripgrep (rg) | yes | Structured search — frontmatter queries, keyword matching, link scanning |
| curl | yes | PDF downloads in snapshot-web |
| gh | no | GitHub issue/PR snapshots in snapshot-web and commonplace-github-snapshot |
License
Commonplace is dual-licensed: