Reference

Reference documentation for the commonplace system — how to operate it and how it works.

Navigation: directory index.

This collection answers two kinds of question:

  • How do I...? — operational how-tos for the common workflows your agent runs on your behalf: writing, ingesting, connecting, validating, reviewing, and so on.
  • How does this work? — the shipped architecture, type system, control-plane conventions, authoring procedures, and the decision record behind major design choices.

Use this collection when the question is specifically about the shipped commonplace system. For transferable claims and theory about knowledge-base methodology, see kb/notes/. For authoring conventions, each collection has a COLLECTION.md at its root.

Mental model

You do not operate the KB directly. You instruct an agent, and the agent operates the KB for you.

The agent reads the shipped skills (.claude/skills/cp-skill-*/SKILL.md or .agents/skills/cp-skill-*/SKILL.md), reads the target collection's COLLECTION.md, and writes output under kb/.

The practical consequence: ask for outcomes, not internal procedures. "Write a note about X" is better than "read the write skill and then ...". The skill is the agent's concern; the outcome is yours.

This guide assumes you have a running agent session (Claude Code, Codex, etc.) with commonplace's skills in its discovery path. If commonplace-init has run and .claude/skills/ or .agents/skills/ exists, you're ready.

How to

Most operations are things you ask the agent to do. Each entry below shows what the operation is for, how to phrase the request, what the agent does, and the practical limits.

Add a note

What it's for. Capture an insight, decision, or observation as a structured artifact in the KB.

How to ask.

  • "Write a note arguing that rate limits should be applied per-tenant rather than per-endpoint. Connect it to existing notes on rate limiting."
  • "I just realized our retry logic is swallowing errors. Write that up."
  • "Capture the decision we just made about moving auth to a sidecar."

What happens. The agent searches the KB for related notes, picks a type, reads the writing conventions, drafts the file under kb/notes/, and connects it to related notes and indexes.

What you get. A new markdown file under kb/notes/ with frontmatter, a claim-shaped title, and inbound and outbound links to related notes.

Limitations. The agent's sense of "what's worth a note" depends on the ## KB Goals section in AGENTS.md. The Exclude subsection is load-bearing; without it, scope creeps.

Ingest a source

What it's for. Pull an external source (URL, PDF, GitHub issue, tweet) into the KB as a snapshot plus an analysis.

How to ask.

  • "Ingest https://example.com/some-article and connect it to our notes on context engineering."
  • "Read this PDF and ingest the key claims."
  • "Ingest the README at github.com/org/project as a related system."

What happens. The agent snapshots the source into kb/sources/, reads the snapshot, classifies it, finds related notes, and writes an analysis report. In this repo, agent-memory-system reviews use the local write-agent-memory-system-review skill so checkout setup, delegated drafting, semantic QA, and validation stay together.

What you get. A snapshot under kb/sources/ and an ingest report named <slug>.ingest.md with summary, claims, and links into kb/notes/.

Limitations. Paywalled or JavaScript-heavy pages can snapshot incompletely. Classification into "related system" versus "source" is sometimes a judgment call.

Search and navigate

What it's for. Find notes relevant to a question without reading the whole KB.

How to ask.

  • "Find notes about how we decided to validate schemas."
  • "What do we have on retry backoff strategies?"
  • "Is there anything in the KB about the tradeoff between X and Y?"

What happens. The agent combines frontmatter search, generated directory indexes, tag indexes, structured ripgrep over note bodies, and link following. It filters by descriptions first, then loads only the notes that look relevant.

What you get. A short list of notes with justifications, usually followed by a synthesised answer that cites them inline.

Limitations. Search quality depends heavily on frontmatter descriptions, tag coverage, and the query terms an agent chooses. Vocabulary-mismatched concepts need synonym searches and link traversal rather than an external semantic-search daemon.

For the full read path and scaling direction, see navigation.md.

Connect an existing note

What it's for. Discover relationships between a note and the rest of the KB, and wire them up.

How to ask.

  • "Connect kb/notes/my-new-note.md to related notes."
  • "I just wrote a note on X. Find what it should link to."

What happens. The agent reads the source collection's COLLECTION.md for its per-destination outbound rules, prospects each authorised destination (dir-index, tag indexes, body search, link-following), applies the articulation test, labels candidates from the destination's authorised set, and writes a connection report. The skill never edits notes — the report is the entire deliverable.

What you get. A report at kb/reports/connect/<collection>/<note-name>.connect.md (gitignored) listing candidate outbound edges, bidirectional candidates, reverse-edge candidates (notes that should link to this target under their own COLLECTION.md rules), off-authorisation candidates (articulated but outside the authorised label set), index memberships, synthesis opportunities, and a discovery trace. Review the candidates and apply the ones worth keeping — connect never mutates the source, so applying the suggestions is a separate step.

Limitations. Relationship labels are judgment calls and sometimes need correction. Connection is often underdone at write time, so running connect explicitly on new notes is a reasonable habit.

Convert between types

What it's for. Promote a rough capture to a more structured form as understanding matures.

How to ask.

  • "Convert kb/notes/scratch.md from text to a note."
  • "This note has enough argument behind it now. Promote it to a structured-claim."

What happens. The agent adds frontmatter, renames the file to match the title where needed, or adds required structural sections such as Evidence and Reasoning.

What you get. The same note at a higher point on the type ladder, with the required structure filled in or drafted from the existing prose.

Limitations. Demotion is not supported, and converting weak content into a stronger type does not create rigor by itself.

Revise a note

What it's for. Improve the prose of an existing note without changing its claims.

How to ask.

  • "Revise kb/notes/foo.md for flow and clarity. Don't change what it argues."
  • "This note feels redundant in the middle section. Tighten it."

What happens. The agent makes a revision pass, writes the result to a numbered copy, and asks you to compare before applying.

What you get. A revised version for review and, after approval, an updated original.

Limitations. Iterative revision can drift semantically over many passes. Keep passes short and verify that the claims survived.

Validate the KB

What it's for. Check that notes have well-formed frontmatter, required fields, resolvable links, and valid type-specific structure. This is deterministic and does not call an LLM.

How to ask.

  • "Validate kb/notes/foo.md."
  • "Run validation across the whole KB and report any failures."
  • Or run uv run commonplace-validate kb/notes/foo.md.

What happens. The validator checks schemas, links, filename constraints, and type-specific structural requirements.

What you get. A pass/fail report per note with FAIL, WARN, and INFO lines.

Limitations. Validation is structural only. Vacuous descriptions or weak claims are review problems, not validator problems.

Review notes

What it's for. Run semantic-quality gates against notes and either accept or fix what the gates flag.

How to ask.

  • "Review kb/notes/foo.md with the prose bundle."
  • "Run the semantic review sweep over anything I've changed recently."
  • "Ack the trivial changes in the review queue."

What happens. The review system stores state in SQLite, runs one or more gates, writes per-gate reviews, and records acceptance events once all gates report.

What you get. Per-gate PASS / WARN / FAIL decisions with rationale text, plus acceptance history.

Limitations. The review UX is still in flux. Gate selection depends on note traits, and acceptance semantics are still more complex than they should be. Treat review as an agent-driven workflow rather than a first-class end-user CLI today.

See REVIEW-SYSTEM.md and FIX-SYSTEM.md for the current design.

Direct CLI commands

Most operations go through the agent, but a few CLI commands are reasonable to run directly:

Command Purpose
uv run commonplace-validate <path> Run the deterministic validator on a note or directory
uv run commonplace-relocate-note <note> --to <dest> [--apply] Move or rename a note with link rewrites and mkdocs redirect; dry-run by default
uv run commonplace-generate-notes-index <dir> Rebuild an auto-generated index file
uv run commonplace-refresh-indexes Rebuild generated index sections across the KB
uv run commonplace-github-snapshot <url> Snapshot a GitHub issue, PR, or repo README into kb/sources/
uv run commonplace-x-snapshot <url> Snapshot a Twitter/X post into kb/sources/

commonplace-relocate-note dry-runs by default. Pass --apply to write changes.

For the full CLI surface, see commands.md.

Reference

Look up how the shipped system is put together: its architecture, type system, always-loaded context, authoring procedures, and decision history.

Architecture and packaging

  • architecture.md — installed project layout (library under kb/commonplace/, user collections at top level), packaged runtime, promoted skills, and path invariance across source and ship
  • scenario-architecture.md — scenario-derived architecture: the library/user split under kb/commonplace/, package-provided commands, and measurable scenario decomposition
  • storage-architecture.md — markdown as source of truth, derived indexes, and SQLite as a scoped exception for review state
  • navigation.md — how agents move through the KB using control-plane pointers, rg, titles/descriptions, indexes, links, connect reports, and future search layers
  • control-plane-goals.md — how commonplace ships KB goals in always-loaded context via AGENTS.md
  • instruction-generation.md — build-time instruction generation flow and commonplace-init
  • review-architecture.md — code architecture for commonplace.review and commonplace.cli.review
  • lib-modules.md — internal API reference for commonplace.lib modules

Type system and collection model

  • collections-and-types.md — orientation: how collections (register conventions, per-destination outbound rules) and types (structural contracts) compose, and how the connect/write skills read each source COLLECTION.md directly for linking rules
  • available-types.md — catalog of shipped types: global (text, note, instruction, definition, index) and directory-scoped specialised types
  • type-loading.md — how authoring skills and validation resolve a type contract through collection-scoped lookup
  • link-vocabulary.md — linking approach and label catalogue: collection-owned outbound rules, reader-need labels, articulation tests, connect reports, and guidance for COLLECTION.md authors
  • definitions/ — vocabulary terms used by the shipped system (e.g., collection)

Authoring and operator procedures

Imperative how-to procedures live in kb/instructions/ rather than this collection, but they are part of the shipped surface:

  • Each collection's COLLECTION.md — register-specific writing conventions, quality goals, and placement rules
  • REVIEW-SYSTEM.md — current review-system workflow
  • FIX-SYSTEM.md — current fix-system workflow

Decision history

adr/ contains the architecture decision records for major shipped-system choices. Notable entries:

Collection boundary

  • Use kb/notes/ for transferable claims and theory.
  • Use kb/reference/ for shipped-system documentation, operator guidance, and decision history.
  • Use kb/instructions/ for imperative procedures and operator-facing process details.

Keep these docs self-contained within the shipped surface. A consuming project should be able to read kb/reference/ without needing links back to the commonplace source repository or methodology library.