commonplace

Commonplace

Research on knowledge systems, running as one.

Commonplace is a living doctrine for agent-operated knowledge systems, developed and tested by running one.

It has two goals. The practical one is an LLM wiki, in the sense Andrej Karpathy sketched: a persistent, linked Markdown layer in which agents, directed by people, turn a person's or project's work into retained, connected notes. The theoretical one is a new learning paradigm, the theory builder: a system that states theories, acts on them, criticizes them, and keeps what criticism shows for the next round, following Karl Popper's method of conjecture and criticism. We bet that a fully automated theory builder that learns can be built with today's LLMs, their weights held fixed. No test of the bet has been run yet.

The goals reinforce each other, because memory is always about learning: a note is worth something when it changes what the system does next. Theories that are acted on, criticized, and revised are what make a wiki learn, and real use of the wiki supplies the problems and criticism a theory builder learns from.

Reflection is the core of the method. Commonplace's doctrine, how it writes, connects, and revises notes, is one of the theories it criticizes and revises, so an improvement to the method is reused by all later work. People still perform many of its operations; the work is moving them to computation.

This repository holds the adopted doctrine, research and evidence that can challenge it, and the tool: the types, conventions, skills, schemas, validators, tests, and commands that you can install to build a knowledge base of the same kind in your own project. Research does not become doctrine merely by being stored here. This README covers the tool; the research routes below point into the rest.

Use it

Install Commonplace in a project

Install the command-line tool once per OS user:

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

Restart the shell or agent runtime, then scaffold the current project:

commonplace-init --root .

Fill in the generated AGENTS.md.template and use it as the project's AGENTS.md, and rename CLAUDE.md.template to CLAUDE.md. The installation supplies the Commonplace types, conventions, skills, and commands, which the project reads in place from the installed package rather than copying; the new knowledge base accumulates knowledge about its own project. The package does not include this repository's external-system reviews or source corpus. See INSTALL.md.

Vendor the research read-only

To let agents consult the full research corpus without installing a Commonplace system, place this repository inside the project as a submodule, clone, or copy, then append AGENTS.md.reader-fragment to the project's agent instructions. Reader mode needs no Python; the agent runtime only needs file access and rg. See Reader install.

Develop Commonplace

git clone https://github.com/zby/commonplace.git
cd commonplace
uv tool install --python ">=3.11" --editable .
uv tool update-shell

Restart consumers of the command path. Ordinary source changes are then visible through the editable installation. After dependency, entry-point, build-metadata, or packaged-scaffold changes, reinstall with uv tool install --reinstall --python ">=3.11" --editable .. Run development checks with uv run pytest and uv run ruff check .. Do not run commonplace-init in the source checkout.

uv run pytest excludes expensive analysis workflow tests marked slow. Use uv run pytest -m slow for those tests, or uv run pytest -m "" for the complete suite. CI runs the complete suite. Run the slow tests when changing the analysis workflow or its acceptance checks.

What's in the box

kb/                       Knowledge base
  notes/                  Transferable research claims and theory
  articles/               Self-standing technical explanations
  reference/              Current system documentation and ADRs
  types/                  Global artifact contracts and schemas
  instructions/           Skills, review gates, and procedures
  agent-memory-systems/   Reviews of agent-memory systems
  agentic-systems/        Reviews of agent runtimes and harnesses
  sources/                Snapshotted sources with analysis
  reports/                Operational state and retained reports
  work/                   In-flight workshops
  tasks/                  Work tracking
  log.md                  Improvement log
  index.md                Rendered-site homepage

src/commonplace/          Packaged operational engine
  cli/                    commonplace-* commands
  review/                 Review system
  lib/                    Shared runtime helpers
  docs/                   ProperDocs hooks and assets

Core design choices

Claims form a network. Note titles are assertions, not topics, and links state how claims relate—such as grounds, extends, contradicts, or exemplifies. This makes traversal a form of reasoning rather than generic browsing. See title as claim and the linking methodology.

Structure is earned progressively. A frontmatter-free file is valid text. Add a description and note type when the material deserves a durable claim; specialize it further only when the extra contract enables useful operations. See the wikiwiki principle.

Authored knowledge remains file-backed. Markdown and Git provide a universal interface, versioning, diffs, and rollback. Derived indexes handle scale without replacing authored files. Review execution state is the scoped exception and lives in SQLite; see ADR 010 and ADR 035.

Local contracts stay revisable. Different parts of the knowledge base support different kinds of work, so task-specific types and link conventions stay local to each part. Structures can also become obsolete as questions, evidence, or model capabilities change, so those local choices remain revisable. Shared rules are kept for constraints that hold across parts and over time. See why task-fitted structure costs cross-task reuse.

Doctrine is explicit; exact operations are code. Skills and conventions tell the model what to do and which of its capabilities to use. Code, schemas, and validators carry operations whose behavior should not depend on repeated interpretation, because code executes them the same way every time. Both sides remain revisable as evidence and model capabilities change.

Research routes

The rendered site is the main route into the research. Starting points:

• The theory builder definition and Commonplace builds a theory builder and tests whether it learns — what a theory builder is, and the research program that tests whether one learns.
• Deployment-time learning and the learning theory index — durable changes to prompts, rules, tools, and code that affect later sessions without updating model weights.
• Self-improving systems and Commonplace as a reflective system.
• Reviews of agent memory systems and agentic systems, with a comparative review.

Commands, skills, and instructions

Commands are deterministic Python entry points called by name. Examples:

commonplace-validate kb/notes
commonplace-init --root .
commonplace-github-snapshot https://github.com/owner/repo/issues/123

The review system adds commands for selecting targets, queuing jobs, and finalizing outputs. commonplace-x-snapshot requires the snapshot package extra. See the review system overview.

Skills (cp-skill-*) are agent procedures auto-loaded by compatible harnesses when a task matches their description. They stay in the installed package; commonplace-init writes a small stub for each into a consuming project's skill directories that points the agent to the real skill.

Instructions are Markdown procedures invoked explicitly rather than auto-loaded. They live under kb/instructions/.

Prerequisites

Reader mode needs only an agent runtime with project-file access and rg. The full installation uses:

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