Skip to content
Back to search

commonplace

The theory of LLM wikis, running as one. A framework for agent-operated knowledge: typed, linked, review-gated markdown your agents execute.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/zby/commonplace with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/zby/commonplace'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zby--commonplace/badge.svg)](/listings/zby--commonplace)

HTML

<a href="/listings/zby--commonplace"><img src="/api/listings/zby--commonplace/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](./INSTALL.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 151 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Commonplace
  2. **Research on knowledge systems, running as one.**
  3. The premise is simple. LLM-written text can be useful even when no person reads it directly, because it can improve how an LLM answers your questions. Commonplace is a **living doctrine for agent-operated knowledge systems, developed and tested by running one**.
  4. It has two goals. The practical one is an **LLM wiki**, in the sense [Andrej Karpathy sketched](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f): 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.
  5. 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](./kb/theory/system-use-selects-theory-fit-without-a-fixed-oracle.md) a theory builder learns from.
  6. [Reflection](./kb/theory/definitions/theory-builder.md#qualifiers) 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](./kb/theory/an-optimal-long-run-learning-strategy-invests-in-its-own-machinery.md). People still perform many of its operations; the work is moving them to computation.
  7. 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.
  8. ## Use it
  9. ### Install Commonplace in a project
  10. Install the command-line tool once per OS user:
  11. ```bash
  12. uv tool install --python ">=3.11" llm-commonplace
  13. uv tool update-shell
  14. ```
  15. Restart the shell or agent runtime, then scaffold the current project:
  16. ```bash
  17. commonplace-init --root .
  18. ```
  19. 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](./INSTALL.md).
  20. ### Vendor the research read-only
  21. 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](./INSTALL.md#reader-install-the-kb-as-a-vendored-reference).
  22. ### Develop Commonplace
  23. ```bash
  24. git clone https://github.com/zby/commonplace.git
  25. cd commonplace
  26. uv tool install --python ">=3.11" --editable .
  27. uv tool update-shell
  28. ```
  29. 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.
  30. `uv run pytest` excludes expensive analysis workflow tests marked `slow`.
  31. Use `uv run pytest -m slow` for those tests, or `uv run pytest -m ""` for
  32. the complete suite. CI runs the complete suite. Run the slow tests when changing
  33. the analysis workflow or its acceptance checks.
  34. ## What's in the box
  35. ```text
  36. kb/ Knowledge base
  37. theory/ Transferable research claims and theory
  38. articles/ Self-standing technical explanations
  39. reference/ Current system documentation and ADRs
  40. types/ Global artifact contracts and schemas
  41. instructions/ Skills, review gates, and procedures
  42. agent-memory-systems/ Reviews of agent-memory systems
  43. agentic-systems/ Reviews of agent runtimes and harnesses
  44. sources/ Snapshotted sources with analysis
  45. reports/ Operational state and retained reports
  46. work/ In-flight workshops
  47. tasks/ Work tracking
  48. log.md Improvement log
  49. index.md Rendered-site homepage
  50. src/commonplace/ Packaged operational engine
  51. cli/ commonplace-* commands
  52. headless/ Workflows over headless harness launches
  53. lib/ Shared runtime helpers
  54. docs/ ProperDocs hooks and assets
  55. ```
  56. ## Core design choices
  57. **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](./kb/theory/title-as-claim-enables-traversal-as-reasoning.md) and the [linking methodology](./kb/tags/links-README.md).
  58. **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](./kb/theory/wikiwiki-principle-lowest-friction-capture-then-progressive-refinement.md).
  59. **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 state is files too: one result per reviewed (note, criterion) pair, carrying the hashes of the texts it judged; see [ADR 127](./kb/reference/adr/127-review-runs-as-workflows-over-result-files.md).
  60. **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](./kb/theory/current-task-fit-alone-does-not-warrant-costly-entrenchment.md).
  61. **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](./kb/theory/scheduler-llm-separation-exploits-an-error-correction-asymmetry.md). Both sides remain revisable as evidence and model capabilities change.
  62. ## Research routes
  63. The [rendered site](https://zby.github.io/commonplace/) is the main route into the research. Starting points:
  64. - The [theory builder definition](./kb/theory/definitions/theory-builder.md) and [Commonplace builds a theory builder and tests whether it learns](./kb/theory/commonplace-builds-a-theory-builder-and-tests-whether-it-learns.md) — what a theory builder is, and the research program that tests whether one learns.
  65. - [Deployment-time learning](./kb/theory/retained-artifacts-enable-persistent-deployment-time-adaptation.md) and the [learning theory index](./kb/tags/learning-theory-README.md) — durable changes to prompts, rules, tools, and code that affect later sessions without updating model weights.
  66. - [Self-improving systems](./kb/tags/self-improving-systems-README.md) and [Commonplace as a reflective system](./kb/theory/evidence/commonplace-as-a-reflective-system.md).
  67. - [Agentic Systems research](./kb/agentic-systems/README.md): research topics, architectural comparisons and source-grounded system analyses. Start with [Agent Memory](./kb/agentic-systems/topics/memory.md); the [earlier memory comparative review](./kb/agent-memory-systems/agentic-memory-systems-comparative-review.md) remains a historical snapshot.
  68. ## Commands, skills, and instructions
  69. Commands are deterministic Python entry points called by name. Examples:
  70. ```bash
  71. commonplace-validate kb/theory
  72. commonplace-init --root .
  73. commonplace-github-snapshot https://github.com/owner/repo/issues/123
  74. ```
  75. `commonplace-review` reviews notes against criteria with headless workers and runs the full improvement pass. `commonplace-x-snapshot` requires the `snapshot` package extra. See the [review system overview](./kb/reference/README-REVIEW-SYSTEM.md).
  76. 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.
  77. | Skill | Purpose |
  78. |---|---|
  79. | `cp-skill-write` | Write or edit an artifact under its collection and type contracts |
  80. | `cp-skill-validate` | Validate artifacts, collection landings, and site redirects |
  81. | `cp-skill-connect` | Discover connections and write a connect report |
  82. | `cp-skill-convert` | Convert a plain text file into a structured note |
  83. | `cp-skill-ingest` | Turn one URL or local snapshot into a tracked source analysis |
  84. | `cp-skill-snapshot-web` | Capture a URL into ignored local snapshots |
  85. | `cp-skill-ground` | Retain the minimum quotations needed to ground a source claim |
  86. | `cp-skill-add-collection` | Add a new collection with its contract, landing, tag participation and routing |
  87. | `cp-skill-health-check` | Diagnose a broken Commonplace installation |
  88. | `cp-skill-revise-autoreason` | Experimentally revise a note with critic, author, synthesizer, and blind-judge agents, keeping the original as fallback |
  89. | `cp-skill-write-multistage` | Write or rebuild an unsettled artifact through staged authorship and independent review |
  90. | `cp-skill-library` | Find and follow a Commonplace library procedure, instruction, or type by name |
  91. Instructions are Markdown procedures invoked explicitly rather than auto-loaded. They live under [`kb/instructions/`](./kb/instructions/README.md).
  92. ## Prerequisites
  93. Reader mode needs only an agent runtime with project-file access and `rg`. The full installation uses:
  94. | Tool | Required | Purpose |
  95. |---|---|---|
  96. | Agent runtime | yes | Load project instructions and expose installed skills |
  97. | [uv](https://docs.astral.sh/uv/) | yes | Install Commonplace and run development dependencies |
  98. | [git](https://git-scm.com/) | yes | Versioning and history-preserving relocation |
  99. | [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) | yes | Search, frontmatter queries, and link scanning |
  100. | [curl](https://curl.se/) | yes | PDF downloads in `snapshot-web` |
  101. | [Poppler](https://poppler.freedesktop.org/) | yes | PDF metadata and text extraction |
  102. | [Trafilatura](https://trafilatura.readthedocs.io/) | no | Web-page capture in `snapshot-web`; without it, paste the page text |
  103. | [gh](https://cli.github.com/) | no | GitHub issue and PR snapshots |
  104. ## License
  105. Commonplace is dual-licensed:
  106. - Code in `src/` and package tooling: [MIT](./LICENSE-CODE)
  107. - Knowledge-base content, documentation, templates, and bundled instructional artifacts: [CC BY 4.0](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.