• Choose your path
  • Coding agents
  • Cowork / Work
  • Research
• Installation and first use
• CLI and plugin quick reference
• What you can do with kpopper
• Go deeper
  • How it works
  • Followups and background checks
  • Optional experimental applications
  • Karl Popper, K-pop and the name
  • Availability and limits
• Try it, get help and contribute

Coding agents
Catch assumptions that break across branches and worktrees.

Example 1: Coding Agent (assumption checks)

Private data exposure

Two agents start from a search service whose results are all public. PR A adds private projects and filters results for each user. PR B adds a shared cache keyed only by the query, relying on those results being public and identical for everyone.

Phone layout

The files merge cleanly. The reason for sharing the cache no longer holds.

The same record retains the surrounding design: query matching, cache behavior, test coverage, operational limits and open questions.

Phone layout · Full design record

A selected excerpt from PR B:

known:
  search.results_public:
    v: true
    from: s.search
    at: INCLUDE_PRIVATE_PROJECTS is false
    measure: search_results_public
  cache.key_fields:
    v: query
    from: s.cache
    at: 'lookup: query not in _CACHE; _CACHE[query]'
  cache.hit_reuses_result:
    v: true
    from: s.cache
    at: 'lookup: return _CACHE[query]'
  cache.test_data:
    v: One mocked public project; no private-result fixture in that test.
    from: s.cache_tests
    at: test_public_query_is_served_once_across_users
judgments:
  search.shared_cache:
    rests_on:
    - search.results_public
    - cache.key_fields
    - cache.goal
    verdict: Search responses can share a cache keyed only by query because all results are public.
    wrong_if: search.results_public == false
    seen:
      search.results_public: true
      cache.key_fields: query
      cache.goal: Avoid a second search for the same public query across users.
  cache.hit_authorization:
    rests_on:
    - search.shared_cache
    - cache.hit_reuses_result
    - cache.miss_delegate
    verdict: Treat cross-user cache hits as depending on the public-results decision, not as a fresh
      authorization check.
    reopened_by: The hit path, key scope or public-results decision changes; review the combined
      path.

rests_on names the premise. seen keeps its value at the last review. When the measured value becomes false, wrong_if fires and identifies the cache decision. Source locators and the complete record are in the example.

The opening overview uses a download promise and a retention policy. The complete merge example shows the same 7-versus-30-day conflict across two branches, with executable code, measurement recipes and a separate integration probe.

These are executable examples. Checks cover the assumptions the record declares and the inputs deliberately measured or recorded. The examples on this page retain their compact legacy records, which kpopper 1.7 continues to read without migration. New records also preserve immutable history.

Two working modes

The difference is whether sessions share one project context or work against different versions of the code. Both modes support several sessions and competing hypotheses.

GROUNDING.yaml is the readable project record shown below: one shared context in Simple, and a version kept with each branch, including main, in Advanced. New history-backed records also keep their supporting history in .kpopper/; carry that directory with the YAML when sharing or versioning the record.

Phone layout

View the full-size illustration · View the vertical version

Simple — one shared context. Sessions read and contribute to the same project graph. Competing ideas are named hypotheses beside it: several sessions can examine the same proposal, and one session can work on several. For a research project, for example, sessions can read different papers and compare explanations against the same sourced record. Consolidation is how those proposals become part of the shared record: compare them with what it already holds, check the combined dependencies and resolve conflicting claims. A proposal can be folded in, refuted with its reason retained, or left pending.

Advanced — branch contexts and shared findings. Each branch's record describes its version of the code. A cache decision on one branch may depend on results being public, while another branch introduces private results. Keeping those premises with their branches lets review check whether the reasoning still holds when the changes are combined. Consolidation reconciles those records: it identifies overlapping subjects and conflicting claims, and checks which decisions need another look under the combined premises. Resolve what needs judgment before folding a proposal in; unresolved hypotheses remain explicit.

Knowledge then follows two paths:

• Feature knowledge travels with its branch. Its assumptions, measurements and hypotheses stay attached to the code they describe. Consolidation tests their combination with the target record as part of reviewing the change.
• Shared findings have a continuing path of their own. Shareable findings that apply independently of the feature enter pending_grounding, with their sources and scope. They remain available even if the originating session closes or its worktree is removed.

Suppose a session building an integration discovers a documented change to the vendor's API limit. The feature may be abandoned; the finding can still help the project. Other local worktrees can read it immediately, marked as pending, without waiting for the feature to merge. It appears alongside their branch record; reading it does not adopt it or replace their recorded premises.

With the project's publication permission, shared findings accumulate in one knowledge PR. Consolidation reconciles the proposed knowledge with the target record before acceptance; conflicts and changed premises need resolution. Accepted contributions are then verified in the target branch, shown as main above. The same publication branch is reused for the next batch, while the local contribution history persists across review cycles. Local capture and reading also work without publication.

A measurement of an unmerged commit can be a fact about that commit. A proposed conclusion remains a hypothesis. Merging means the team accepted the contribution; it does not prove the claim, increase confidence or refresh its last review. Private material and information whose sharing permission is unclear stay in a structured private draft.

Projects without Git start in Simple; new Git projects start in Advanced, including those with only one checkout. Simple can also be configured for a Git project with one external shared record. Existing registered shared records keep their current location and behavior; changing mode requires explicit reconciliation.

See project modes and publication for routing, reproducible reads and the publication lifecycle, and consolidation for the dry run, folding and refutation commands.

These project modes also apply to document and research work.

Cowork / Work
Keep plans current when the brief changes.

Example 2: Claude Cowork / ChatGPT Work (freshness)

Outdated planning assumptions

A cooking workshop is planned around the venue's shared kitchen, equipment and ingredients. A later client brief moves it entirely online. For ChatGPT Work, see the runtime requirements and current limits.

Phone layout

Once the agent records the new format, kpopper flags the saved plan for review. It does not decide whether the activities can work remotely. The next session can recover the old reason, read the updated brief, and work out what participants need. Try the Cowork example.

The planning record connects 13 readings to five saved plans and four open questions. The format change reaches the agenda, equipment, ingredients, group arrangement and supervision; the earlier review snapshots remain visible.

Phone layout · Full planning record

Selected entries from the after record:

known:
  workshop.format:
    v: remote
    from: s.updated_brief
    at: Participants join online from home
  workshop.participants:
    v: 18
    from: s.session_plan
    at: Client constraints
  workshop.duration_minutes:
    v: 90
    from: s.session_plan
    at: Client constraints
  venue.workstations:
    v: 6
    from: s.logistics_plan
    at: Venue provision
judgments:
  workshop.agenda:
    rests_on:
    - workshop.format
    - venue.shared_kitchen
    - workshop.duration_minutes
    - workshop.recipe
    verdict: Use the shared-kitchen agenda and provide ingredients at the venue.
    reopened_by: The format or access to the shared kitchen changes; review activities, equipment
      and preparation.
    seen:
      workshop.format: onsite
      venue.shared_kitchen: true
      workshop.duration_minutes: 90
      workshop.recipe: Fresh pasta with tomato sauce.
  workshop.equipment_plan:
    rests_on:
    - workshop.format
    - venue.equipment_supplied
    - venue.workstations
    verdict: Plan equipment around the six venue workstations.
    reopened_by: The format, supplied equipment or access to the workstations changes.
    seen:
      workshop.format: onsite
      venue.equipment_supplied: true
      venue.workstations: 6
  workshop.ingredient_plan:
    rests_on:
    - workshop.format
    - venue.ingredients_supplied
    - workshop.participants
    verdict: Prepare ingredient portions at the venue for the 18 participants.
    reopened_by: The format, ingredient provision or participant count changes; review purchasing,
      portions and distribution.
    seen:
      workshop.format: onsite
      venue.ingredients_supplied: true
      workshop.participants: 18

The current value is remote; the decision was reviewed against onsite. That is a MOVED notice. The prose in reopened_by tells the agent what deserves attention; it is not an executable predicate. Read the complete after record.

Before the first answer

The next session opens with the saved context: all five plans need review because workshop.format changed from onsite to remote. Then the user asks:

Prepare the ingredient portions for the 18 participants.

On a host with the prompt hook enabled, this matching prompt produces a focused pointer (actual hook output, shown here with Codex skill syntax):

kpopper: the record holds workshop.ingredient_plan on this - $ground workshop.ingredient_plan before answering from memory.

The agent follows that pointer with pull workshop.ingredient_plan. It retrieves remote, the old venue-based plan and its onsite review snapshot before answering. The next decision is how ingredients will reach participants at home. See the opening and retrieval output.

Keep your existing documents, notes and task tools. The record links back to relevant evidence; there is no need to migrate your knowledge system. For another example that needs judgment, explore a replacement offer with an uncertain deadline.

Research
Connect evidence and revisit conclusions as findings change.

Example 3: Research (evidence synthesis)

Dark matter across studies

The original three-paper view shows the shared-record idea:

Phone layout

A research record can connect observations across scales and retain the tensions between them. This worked example follows six papers: Rubin's galaxy rotation, SPARC's galaxy catalog, the radial acceleration relation, Bullet Cluster lensing, Planck's cosmological fit and the first LZ particle search.

Phone layout

The argument includes 36 source readings, two scope readings, one calculation, seven linked judgments and five open questions. Its depth comes from the links: SPARC and the acceleration paper share data; the Planck density ratio comes from one model fit; a null WIMP search constrains specific interactions without settling the identity of the astronomical mass component.

Phone layout · Complete research record · Sources and exact locations

A source-grounded excerpt:

known:
  sparc.sample_size:
    v: 175
    from: paper.sparc
    at: Abstract
    unit: galaxies
  rar.sample_size:
    v: 153
    from: paper.rar
    at: p. 1, Data / Galaxy Sample
    unit: galaxies
  rar.points:
    v: 2693
    from: paper.rar
    at: 'p. 1, Galaxy Sample: velocity-precision cut'
    unit: points
  cmb.omega_c_h2:
    v: 0.12
    from: paper.cmb
    at: Abstract, combined analysis
    uncertainty: 0.001
    confidence: 68%
  cmb.omega_b_h2:
    v: 0.0224
    from: paper.cmb
    at: Abstract, combined analysis
    uncertainty: 0.0001
    confidence: 68%
  lz.si_limit:
    v: 9.2e-48
    from: paper.lz
    at: 'Abstract, version 4: limit at 36 GeV/c^2'
    unit: cm^2
    confidence: 90%
  lz.mass_at_limit:
    v: 36
    from: paper.lz
    at: Abstract, version 4
    unit: GeV/c^2
  cmb.dark_to_baryon_density:
    rule:
      expr: cmb.omega_c_h2 / cmb.omega_b_h2
judgments:
  evidence.shared_catalog:
    rests_on:
    - sparc.sample_size
    - sparc.inputs
    - rar.catalog
    - rar.selection
    verdict: Treat SPARC and the RAR analysis as related evidence, not two independent observational
      votes.
    reopened_by: A different catalog, sample selection or independently calibrated replication changes
      the dependence between these findings.
  synthesis.dark_matter:
    rests_on:
    - galaxy.extended_mass
    - galaxy.baryon_coupling
    - cluster.mass_location
    - cosmology.cold_component
    - particle.search_scope
    - research.framework
    - research.selection
    verdict: Under the stated models, the selected evidence supports a dark-matter account across
      scales, while baryonic regularities and direct-search limits constrain its explanation.
    reopened_by: A source finding or shared assumption is revised, or a worked alternative jointly
      addresses the galaxy, cluster, cosmological and particle-search constraints. Reassess the
      affected paths and the synthesis.

The next session inherits the argument, including its unresolved questions.

Run the checker on that same record:

kpop check examples/dark-matter/GROUNDING.yaml

Its final summary (exit 0; the full response also lists the seven prose review conditions):

7 judgments, 58 entries, 0 problems, 7 declared

For a starting overview use open; to inspect a subject use pull; to trace a premise use affects. The ground skill guides that workflow for an agent.

kpop open examples/dark-matter/GROUNDING.yaml --chars 1000

Six-paper worked example; selected source readings and an authored synthesis, not a complete review or live research-agent evaluation.
holds: rar (8) · research (8) · cmb (7) · lz (6) · paper (6) · sparc (6) · lensing (5) · rotation (5)
58 entries, 7 judgments, 5 open questions, updated 2026-09-19

kpop pull cmb.dark_to_baryon_density examples/dark-matter/GROUNDING.yaml --budget 1100

cmb.dark_to_baryon_density: 75/14 = cmb.omega_c_h2 / cmb.omega_b_h2 (Ratio of the abstract central physical de ...
+ cosmology.cold_component: Within base Lambda-CDM, the fitted physical cold-dark-matter density exceeds the b ...
    holds
    because: The density ratio connects two central values from the same fit. The model assumptions and
             retained lensing-amplitude tension limit the interpretation.
    reopened by: The likelihood, data combination or cosmological model changes enough to alter the inferred c ...

affects <entry> shows what a change reaches

kpop affects research.framework examples/dark-matter/GROUNDING.yaml

cluster.mass_location
    via research.framework -> flagged only
cosmology.cold_component
    via research.framework -> flagged only
galaxy.extended_mass
    via research.framework -> flagged only
synthesis.dark_matter
    via research.framework -> flagged only

4 judgments reached

See all captured commands and responses, including pull synthesis.dark_matter. Here check reports record consistency; the scientific review conditions still require judgment.

The illustrations are schematics drawn from the record. The full example distinguishes source readings, authored interpretations, shared assumptions and the computed 75/14 density ratio. That arithmetic does not establish the scientific synthesis.

Run the shared-record example: three concurrent CLI writers retain the prepared six-paper contributions, and the writer records each judgment's review snapshot. A proposed change of framework then reopens several interpretations and the synthesis. No model call or claim of live independent research is part of that replay.

The collection changes; the answer stays five

The advanced continuation starts with the five astronomical papers and an explicit selection rule: include a study when it is in this review and classified as astronomy. Adding the existing LZ laboratory paper grows the captured collection while leaving that selection equal.

The core/v1 record uses composition/v1 for the inclusion condition and query/v1 for selection. Its basis includes nonmatching members, so an equal numeric answer does not hide a changed collection. The retained Snapshot recovers the earlier inputs and result even with the source files unavailable.

These are scripted CLI and public API results, checked without model calls. The runnable exercise and captured output also preserve the exact 75/14 density ratio and an unchanged qualitative review judgment. Five papers is a coverage count: RAR still reuses SPARC, model assumptions remain explicit, and neither the count nor replay proves the synthesis.

These commands can record decisions, update project state or configure work. The linked guides describe their arguments and review steps.

See the command reference, history commands, background capture and followups. review records your assessment; it does not make that assessment for you.

A project is work around a goal. Its materials may span documents, conversations, calendars, task systems, files and earlier sessions. In software, they also include code, commits and pull requests. One project can cross several tools; one source can serve several projects.

kpopper presents a picture of the project's reasoning in GROUNDING.yaml: a readable record that connects claims to sources and decisions to their premises, backed by immutable history in .kpopper/ for new records. Your documents and tools keep their own content. The record makes the reasoning between them available to the next person or agent working on the goal.

The same five questions orient the work:

1. What are we trying to achieve? Goals, outcomes and priorities.
2. What is known now? Facts, commitments, deadlines and constraints.
3. What was decided, and why? Decisions, assumptions and alternatives.
4. Where is the evidence? Sources and enough detail to find the relevant passage again.
5. What needs another look? Open questions, conflicting reports and changed premises.

These questions guide what to record. Learn from findings during ordinary work, or ask for an initial map or deeper investigation of selected materials. The agent uses the sources available in your context; access to a file alone does not make it part of the project.

Keep the work connected across time: the sources and decisions behind it, what needs attention now, and the checks or actions to return to later.

Phone layout

The Future panel shows deferred work tracked by followups and scheduled reviews when configured in the host. The return arrow is the agent's step of recording useful outcomes as evidence; marking a followup complete is a separate operation and does not automatically rewrite the knowledge record.

New information often arrives halfway through another task. kpopper can retain an explicit report and process a supported update in a separate worker. Routine results stay quiet; important unresolved findings are available for delivery back to the conversation.

Phone layout

Today, that worker can update an existing stored scalar value in a single record file, using a supplied source quote, target, value and report date. It does not infer what an ambiguous message refers to. Unresolved identity or meaning remains a question. Delivery after an answer requires the host capabilities described in the background capture guide and native delivery guide.

Captured, applied and checked are different states. If the current answer depends on an update, inspect its outcome before relying on it. Background work is useful precisely where the conversation can safely continue without that result.

What deterministic reasoning means here

Deterministic reasoning applies fixed rules to explicit inputs. A completed evaluation of the same inputs and rules gives the same result.

In kpopper, this means:

• Repeatable checks. A $1,200 plan exceeds a $1,000 budget: total_cost > budget evaluates to true each time those values are checked. No fresh model response is needed to decide that comparison.
• Explicit assumptions. The record names what a conclusion depends on and the condition that would make it fail or deserve another look.
• Traceable support. Follow a result through its recorded inputs, rule, source references and last-review snapshot.

The same answer can rest on different evidence. Consider this illustrative exchange after adding LZ to the research example:

User: “Include the LZ paper. Does our selection of astronomy studies change?”

Agent: “I'll apply the recorded selection rule and compare its evidence basis with the last review.”

The selection rule requires in_review and domain == "astronomy". The agent runs the following against the generated history-backed record. jq selects four fields from the actual CLI assessment for display:

kpop assess m.astronomy_count m.particle_identities d.review_scope \
  --record /tmp/dark-matter-query/history/GROUNDING.yaml --history |
  jq -f examples/dark-matter/advanced/assessment-summary.jq

{
  "studies_scanned": 6,
  "astronomy_studies_selected": 5,
  "particle_identity_status": "unknown",
  "review_basis": "changed"
}

Five studies matched before; five still match. LZ is recorded as laboratory evidence, so it joins the scope without entering that selection. The retained review still names the earlier basis, and missing particle-identity readings stay unknown.

The agent can now explain: “The selection is unchanged, but the evidence considered has changed. The saved review needs another look.” The runnable example also replays the earlier Snapshot after removing access to the source files, recovering its original five-paper scope and basis. Run it and inspect the full responses.

Agents still interpret sources, choose which assumptions to record and make judgments. The reliability of a conclusion depends on that evidence and those choices. A free-text review condition remains a prompt for judgment; it is not silently treated as an executable rule.

See the supported calculations and conditions and the reasoning core's formal scope.

The knowledge record

The technical term is an epistemic record: a record of what is known and how it is grounded. These are roles in the method, not six mandatory YAML sections. Start with what the work needs; a source and one finding can be enough.

Since 1.7, new records preserve immutable versions of their claims and recorded acts. GROUNDING.yaml presents the current readable record; .kpopper/ holds the history and its authority metadata. Retain both together. Supported CLI writes update the record through that history, and ordinary reads automatically use core/v1. An existing legacy YAML record is not migrated by reading it. See the history contract for adoption and editing rules.

The method is opinionated about grounding conclusions, declaring dependencies and preserving a basis for review. A judgment needs the values it was reviewed against to make drift detectable, and a meaningful condition for reconsideration. A record with no judgments yet does not need invented conclusions, snapshots or derivations just to fill a template. Field names and project-specific categories are described below.

Change is compared with the last review. When a recorded scalar differs from a judgment's seen snapshot, the reader identifies the movement. A supported wrong_if comparison says whether the change crosses the judgment's stated boundary. Movement can call for review without refuting the conclusion; a movement inside its declared threshold can stay quiet. affects traces the wider reach through declared judgments and rule references.

The record does not observe the world on its own. A changed document matters only after someone or an authorized tool supplies a new reading. Optional measurement recipes can re-read selected values when explicitly run. These are reviewed commands, not general source monitoring.

History and the present belong together, with their dates intact. An old conversation can explain why a deadline was chosen; it does not establish that the deadline still holds. A session's proposed action does not establish that anyone performed it. Reusing a recommendation requires evidence for its conditions now.

Competing claims can stay separate. A conflicting write can become a hypothesis beside the base record. Consolidation checks the proposed combination before an explicit fold; it can also retain a refuted hypothesis as a negative finding. A signal never grants permission to change a decision or act outside the record.

On return, open gives a bounded orientation and attention report; pull retrieves the subject you need. The optional checked session mode below adds a complete, navigable view within a token budget. In both cases, the aim is to spend the next session's context on the work at hand.

A structure that grows with the project

Start with a finding, not a database design. A research project can name claims and experiments; a workshop can name participants and supplies; a codebase can name interfaces and deployment assumptions. Add subjects, categories and views when the work creates a reason for them.

The readable record is YAML, and Git is optional. Keep it and its .kpopper/ directory with the project or in a deliberately configured external location; your source documents stay in their existing tools. Storage and location.

The vocabulary is flexible. The ordinary reader recognizes dependency, predicate and snapshot roles by their shape; facts/claims can serve the same purpose as known/judgments. The documented names are the easiest starting point. When two fields fit the same role, an explicit schema mapping resolves the ambiguity. Some control fields, including reopened_by and blocked_on, are recognized by name; flexible vocabulary does not mean every keyword can be renamed.

The relationships stay explicit: where a reading came from, what a decision depends on, what it was reviewed against, and what would bring it back for review. Supported checks enforce their structural and comparison rules; arbitrary prose still needs interpretation.

This is the useful sense of an evolving record: the person or agent can adapt its structure as needs emerge, and later checks recompute what moved from the current values and saved snapshots. Conclusions are not silently rewritten, and a structural change should migrate the existing record and pass its checks in the same change. See the shape and how structure grows.

When a review needs judgment

Some conditions can be compared mechanically; others require reading a source and making a judgment. reopened_by preserves a prose condition for reconsideration. blocked_on records why a condition cannot currently be checked. Neither field calls a model or schedules work.

When a declared, comparable premise changes, the write response and subsequent open or check can surface the affected decision. During the task, the agent reads the relevant sources and decides whether to retain, revise or question it. A review explicitly updates seen; the checker never does that on its own.

For a review that must happen later, attach a followup to a date or recorded change and connect it to an available host schedule. The optional daily review can also select one flagged decision for attention. A prose condition alone is not an automatic background review of every judgment. See followups for triggers, work budgets and scheduling.

Deferred work can become ready on a date, after a recorded value changes, when a threshold is crossed, or after another task finishes. Keep the task in your existing system; kpopper connects it to the knowledge it depends on and has a private local fallback when needed.

A configured daily review can revisit due work and a flagged decision within a small budget, surfacing meaningful results. During active sessions, supported host hooks also surface changed readiness. A saved followup alone does not start an agent or create a schedule.

With local watch enabled, worktree graph changes are checked in a separate background process against the selected main ref. Results identify the exact versions checked; comparison rewrites neither graph. Scoped external observations can live in one canonical record outside the branches, while branch experiments remain local.

Run /kpopper:watch in Claude Code or $watch in Codex to inspect and configure these routines. The host supplies scheduling within your authorization. Recording a followup's outcome and reviewing a decision are explicit actions.

See setup and host limits, followup routing and review budgets, and branch compatibility and shared observations.

Karl Popper is releasing his debut K-pop single. An agent has prepared Friday's launch-party announcement. The venue has confirmed the booking. The decision: the announcement is ready, provided the booking stays confirmed.

The next day, the venue cancels. A later session picks up the launch plan. The announcement copy is unchanged; the reason it was ready to publish has disappeared.

kpopper preserves that connection:

sources:
  booking:
    name: "Venue confirmation"
    quoted: "Your booking for Friday is confirmed."
    read: "2026-09-09"

known:
  venue.status: {v: confirmed, from: booking, as_of: "2026-09-09"}

judgments:
  launch.announcement:
    rests_on: [venue.status]
    verdict: "Friday's announcement is ready, provided the venue booking stays confirmed."
    because: "The announcement names the date and venue confirmed in the booking email."
    wrong_if: 'venue.status != "confirmed"'
    seen: {venue.status: confirmed}

After the session records the cancellation, the next check reports:

launch.announcement: wrong_if holds (venue.status != "confirmed") - broken by its own condition

The next agent sees which decision needs review, which premise changed, and what the earlier decision was based on. It knows to revisit the announcement before reusing “ready to launch.”

Try the example · See a PR and CI case

Two branches can pass their own tests and undermine each other's decisions when merged. Git checks whether their text can be combined. kpopper adds a check on the recorded premises and conditions behind the work.

The two executable merge stories reproduce the opening illustrations in disposable local Git repositories:

Run them with Git and the package's Python dependencies installed:

python3 examples/merge-assumptions/run.py

Each branch's tests and measurement checks pass. Git merges the branches without a text conflict, and the combined branch tests still pass. Measurement then fails the recorded condition. The runner also uses a separate integration probe that detects each problem; these examples show a gap in those branch tests, not a limit on what tests can express.

The recipes connect explicit inputs in the merged tree to the record: the search visibility switch, the storage policy and the promise in an email template. remeasure --run tests changed readings as a hypothesis without silently rewriting the canonical record. A plain check cannot see a tree change while its recorded input remains unchanged.

There are three useful checks:

• Across branches during work: kpop consolidate --dry-run --from <branch-or-ref> reads another branch's committed record as proposed changes and tests it against the current record.
• On the proposed merge result in CI: kpop check checks the combined record; kpop consolidate --dry-run also tests the hypotheses stored beside it.
• Against the actual tree: kpop remeasure --run runs the deliberately configured recipes and tests their readings against the declared conditions.

A changed premise that needs review can be reported without failing CI; an affected hypothesis still needs review before it can be folded. Decisions are revised explicitly: a verdict laid over a standing judgment folds only when the record's own condition has broken it, or when a person names it (--take), and what it replaced stays beside the record.

These commands already run in kpopper's own CI workflow on pull requests and pushes to main, alongside the test suite. Record checks use the record's declared interpretation; the experimental Hub has a separate HTML verification step. See Add reasoning checks to CI for setup, including measurement recipes.

The coverage is what the record declares. These checks do not infer intent from arbitrary code or prove that all goals are mutually compatible. Keep relevant readings current and review measurement recipes as code. A contradiction expressed only in prose, or hidden behind unrelated IDs, can still require human review.

The man in the banner is Karl Popper, cast here as an unlikely K-pop star.

Karl Popper was a philosopher of science who argued that scientific theories should expose themselves to tests that could prove them wrong. Surviving a test does not make a theory certain. The Stanford Encyclopedia of Philosophy explains the idea and its limits.

kpopper borrows that discipline for agent reasoning: preserve the evidence, state what would undermine a conclusion, and know when to reconsider it. This is the idea behind the name.

Now prove that Karl Popper isn't the father of K-pop.

Our imaginary announcement, “Popper's K-pop debut is out,” has a more concrete test:

wrong_if: 'popper.single_status != "released"'

If the recorded status is planned, that condition fires and check fails. A green check means no failing condition was found by these checks; it does not establish that the recommendation is true, wise, complete or authorized.

This legacy example uses one comparison over declared inputs. The current core also supports compound conditions. Free-form reasoning still needs interpretation. If a condition cannot yet be checked, blocked_on records why. A decision that needs a person's judgment can instead carry reopened_by, describing the sign that would bring it back for review. Preferences and open questions need no invented scientific certainty. See the checking rules.

This is a practical use of falsification, not an automated implementation of the scientific method. Choosing good evidence and meaningful breaking conditions remains intellectual work.

An agent's working instructions and the work it produces serve different readers. Plan section numbers can leak into code comments; a website can start describing the prompt that produced it. The useful boundary resembles the fourth wall: keep production instructions in the working context, and put what the audience needs in the finished work. A report may still need its assumptions, evidence and sources.

kpopper provides a separate place to preserve decisions and their reasons across sessions. The agent still has to respect that boundary; the record does not enforce it.

The excitement around building an organizational second brain is well deserved. A team's knowledge already lives across notes and agent memory, documents and research, conversations, plans and commitments, code and data. An agent can connect the relevant pieces into a shared, evolving picture of the work.

Andrej Karpathy's LLM Wiki describes how an agent can maintain that picture as a persistent wiki: synthesizing sources, surfacing contradictions and revisiting stale claims.

As that knowledge becomes a basis for action, its reasoning deserves an explicit record: why a conclusion was accepted, which sources and assumptions support it, and what would call for reconsideration.

kpopper gives that record structure. It connects conclusions to their grounds, preserves what they were reviewed against, and checks declared conditions as recorded facts change. We call this reasoning and review layer a third brain; the agent supplies the interpretation.

Keep the knowledge system already in use. A folder of Markdown files, an Obsidian vault, a project wiki, or memory files used by Claude or Codex can stay where they are. The agent reads relevant material through its available tools and records the claims it relies on, with links back to those sources, in the project record. GROUNDING.yaml presents those claims; new records retain their history in .kpopper/. There is no need to migrate the existing notes or replace the agent's memory system.

That distinction is useful when a perfectly retrievable note contains a decision whose premises have expired. Finding the note is one job; noticing that its recommendation needs another look is another.

There is a loose parallel with human memory: remembering can involve updating what was previously learned. In a laboratory study of episodic memory, reminders led participants to incorrectly include newly learned items when recalling an earlier list. Hupbach et al., 2007 provide one concrete example. This motivates an analogy, not a claim that kpopper models the brain or that neuroscience validates the product.

Operationally, the analogy is straightforward: retrieve the relevant context, compare it with new information, draw attention to a consequential mismatch, and review the conclusion. In kpopper those steps are explicit records and checks. The person or agent supplies the interpretation; the software follows the declared connections. You retain the decision.

In September 2026, Anthropic reported that Claude had formalized a proof of Fermat's Last Theorem in the Lean programming language, producing a complete computer-checked proof. The achievement was formalizing existing mathematics, building on Wiles's proof and community work. See Anthropic's account and the published proof.

“If it's good enough for Claude, it's good enough for you.”

— Karl Popper, father of K-pop.

kpopper uses a compiled Lean 4 runtime for deterministic reasoning in new records. It evaluates supported calculations and conditions from explicit inputs. The optional, experimental checked-session mode also uses Lean to check rules about an agent's view of the record. The language is a theorem prover: its kernel checks formal proofs against a precisely defined type theory. The Lean reference explains how proof checking and compiled execution fit together.

For the default reasoning core, Python captures the record and the packaged Lean runtime evaluates supported rules. Reasoning and history describes its scope, supported platforms and formal guarantees.

In checked-session mode, Python prepares a normalized snapshot, a separate local Lean core checks the proposed session view, and CLI or MCP exposes the result. Reads are bound to the revision returned at opening, so a changed record rejects a request using the old revision.

The checked-session Lean source contains formal proofs of specific properties:

The proof audit names these theorems and prints their axiom dependencies. Other runtime checks cover such details as exact recovery references, topic bindings and event values. The session CI workflow builds the pinned Lean source and runs integration tests on Linux, macOS and Windows.

These are guarantees about defined data structures and checks. They do not prove that a source is accurate, that rests_on logically implies a verdict, that an agent's prose follows from the evidence, or that an action is permitted. The Python adapter, router, renderer, compiler and runtime are outside an end-to-end formal proof. You do not need to write Lean to maintain a record.

To use checked sessions, install kpopper[session] with Python 3.10+, make Lean 4.33.1 available, then build and enable the local core. The complete instructions, CLI and MCP examples, predicate subset and rollback are in Checked sessions. The ordinary commands remain available without it.

Logo source and trademark information.

kpopper's core keeps claims, their sources and dependencies, and the conditions that make decisions worth revisiting. Optional applications build on that core:

From a source checkout, install the optional HTML dependencies:

python -m pip install '.[html]'
kpop experimental hub --open
kpop experimental annotated-doc guide

For a release that includes these applications, use kpopper[html] instead of .[html]; check the changelog when using an older installation. Request these applications explicitly or give the agent a standing preference. Their interfaces and artifact formats may change. Ordinary installation, record checks and session hooks work without the HTML runtime. Plugin users can add it with plugin_runtime.py setup --applications html at their active plugin path.

See installation, boundaries and maturity, Annotated Documents, and kpopper Hub.

To share a small part of the record in a task, document or pull request, use kpop export. The excerpt separates readings captured at review from current recorded readings and marks values omitted from the selection. From a source checkout:

python3 scripts/cli.py export launch.announcement \
  --record examples/launch-party/GROUNDING.yaml

Add --format markdown-mermaid to keep the text and append a diagram for destinations that support Mermaid. See focused exports for selection limits, original-field details and output options.

This table describes the current repository. Check the changelog when updating an older installation; a merged feature may still be awaiting a release.

Use kpopper 1.7 or later across the CLI, plugins and CI for the new default history-backed records. The reasoning runtime is packaged; existing legacy records require explicit adoption.

Legacy records with structured expressions and computed snapshots require at least 1.6.0 and their documented Lean setup. Upgrade every reader and writer together. On native Windows, legacy records support individual add/set writes and deliberate reviews; durable report batching requires POSIX file locking.

New history-backed records also require POSIX locking for creation and writes. On native Windows, create and author history on a POSIX host such as WSL; read-only assessment and the packaged Windows reasoning runtime remain available.

Mapping runs in the calling agent session, using its available tools and the sources you authorize. It does not install connectors or scan accounts by itself. See starting a knowledge record for the workflow and host requirements.