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 selects and coordinates how model-mediated and symbolic operations are used. Explicit artifacts can activate model capabilities and give their use project authority; code and validators can faithfully execute operations that should not be reconstructed on every call. The doctrine, prompts, code, and models can all change. Like the Ship of Theseus, Commonplace remains the same project through a governed sequence of revisions, not because any component is permanent.

Its first application is an LLM wiki, in the sense AI researcher Andrej Karpathy sketched: a persistent, linked Markdown layer around a person's or project's work. Human-directed agents turn vague thoughts into retained notes, connect them to evidence and related claims, and revise both the knowledge base and its operating machinery.

This repository is Commonplace's current reference embodiment. It contains adopted doctrine, research and evidence that can challenge it, and the types, conventions, skills, schemas, validators, tests, and commands that make the current system operative. Research does not become doctrine merely by being stored here. This README covers the tool; the rendered site is the main route into the research.

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. The installation supplies the Commonplace types, conventions, skills, and commands; 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.

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 and revision solve different problems. Different collections support different kinds of work, so task-specific types and link conventions stay local. Structures can also become obsolete as questions, evidence, or model capabilities change, so those local choices remain revisable. Shared invariants are reserved for constraints that survive both variation across collections and change over time. See why task-fitted structure costs cross-task reuse.

Doctrine is explicit; exact operations can be symbolic. Skills and conventions activate and authorize relevant model capabilities. Code, schemas, and validators carry operations whose behavior should not depend on repeated interpretation. Both sides remain revisable as evidence and model capabilities change.

Research routes

Learning software factories. Can a software factory configured to produce factories construct and adopt a better successor without training a new model? The research program tests whether an LLM-based factory can acquire and hold project theory strongly enough to keep modification coherent across novel demands; retained natural-language theory is the addressable realization under test. Commonplace is the live human-inclusive testbed; a controlled programming-agent comparison is planned. The Naur note reopens the bearer question, while the coherent-search note states the longitudinal test. Companion articles develop the Bitter Lesson's scaling test and why the hardest decisions stay human.

Deployment-time learning. Durable changes to prompts, rules, tools, schemas, tests, and code can affect later sessions without updating model weights. Storage is insufficient: later operation must load or enforce the result. Start with retained system-definition artifacts enable persistent deployment-time adaptation and the learning theory index.

Self-improving systems. Improvement requires evidence-responsive change to the system's own behavior-determining organization. Reflection is a separate property that supplies addressability, not improvement by itself. The self-improving systems index maps the distinction, and Commonplace as a reflective system applies it locally.

Agent-usable memory. Agents need discoverable, composable, and trusted knowledge under bounded context. The repository also contains reviews of agent memory systems and agentic systems; the comparative review focuses on activation and verification rather than storage alone.

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. commonplace-init installs them into consuming projects.

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