Your project, more self-aware.

• Choose your path
  • Coding agents
  • Claude Cowork / ChatGPT Work
  • Research
• Installation and first use
• CLI and plugin quick reference
• What you can do with kpopper
• Keep the conversation moving
• Keep your existing knowledge system
• What “deterministically checkable” means
• Go deeper
  • How it works
  • Followups and background checks
  • Optional experimental applications
  • Availability and limits
  • Karl Popper and falsifiability
• Try it, get help and contribute

Claude Code · Codex · Cursor · and more
Explore workflows and examples

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.

known holds values taken from a source or derived from other entries; judgments holds the decisions that rest on them. 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 the native runtime continues to read without migration. New records also preserve immutable history.

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 (experimental) — 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.

[!WARNING] Advanced mode is experimental. Parallel branches can add different entries to the same part of GROUNDING.yaml, leaving an already-checked PR with a merge conflict after another PR lands. Resolving it can trigger another CI run. Automatic conflict-free integration is not implemented. We are keeping the readable file while this remains an open design question: the problem, alternatives and their tradeoffs.

For a supported local record conflict, preview a resolution with kpop consolidate --resolve --dry-run. Competing claims still need a decision.

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. Their consolidation dry run tests it against that record too, and turns red when accepting it would break a recorded decision, until a person decides the finding.

kpopper Board is this continuing shared-findings area. At the start of meaningful work in an unconfigured Git project, kpopper offers Simple (recommended) with a chosen external shared record, or Advanced (experimental) with branch-specific knowledge. The illustration above explains both. Advanced can keep Board findings local or publish them to a named repository and target through one continuing knowledge PR. A publication choice enables branch and PR updates, not merging; it is remembered across local worktrees. kpop board shows the current mode, selection and publication state.

With the project's publication permission, Board 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 currently start in experimental Advanced mode, 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.

Keep plans current when the brief changes.
Explore workflows and examples

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.

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.

Connect evidence and revisit conclusions as findings change.
Explore workflows and examples

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.

Inside Claude Code, enter these slash commands one at a time:

/plugin marketplace add ilanbm/kpopper
/plugin install kpopper@kpopper

Or, in a terminal, run the equivalent commands:

claude plugin marketplace add ilanbm/kpopper
claude plugin install kpopper@kpopper --scope user

Both routes install the plugin. The native runtime is a separate required step; ask Claude Code to finish it, or follow the manual runtime setup. That guide explains how to find the installed plugin directory and includes Windows instructions. Start a new session after setup is complete.

In a terminal:

codex plugin marketplace add ilanbm/kpopper
codex plugin add kpopper@kpopper

Install the native runtime in the plugin root printed by codex plugin add using the native runtime setup guide. Then start a new task and review and trust kpopper's hooks when Codex asks. You can also inspect the hook definitions inside Codex with:

/hooks

See Codex setup and behavior.

In a terminal, clone the repository where it can stay:

git clone https://github.com/ilanbm/kpopper.git

Follow the adapter linked above. Add to the agent's existing configuration rather than replacing it. What runs automatically differs by agent; see the capability matrix and verification status.

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.

Supported reports can update stored values and add new readings, rules and judgments. Related changes from one source can be applied together. The agent supplies the source quotation and explicit updates; background processing does not guess what an ambiguous message means. Existing judgments still require deliberate review.

Supported record layouts and authoring limits are described in the background capture guide. Delivery after an answer requires the host capabilities described in the native delivery guide.

GROUNDING.yaml presents the claims the work relies on, with links back to their sources; new records retain their history in .kpopper/. There is no need to migrate the existing notes or replace the agent's memory system. This applies to coding, planning and research.

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.

How a decision gets checked is explained above.

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.

The native runtime preserves immutable versions of new 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.

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.

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.

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 a native kpop on PATH:

sh examples/merge-assumptions/run.sh

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.

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.

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.

Lean is part of kpopper's packaged reasoning runtime. Ordinary use needs no Lean installation. Its kernel checks formal proofs; compiled programs perform the supported calculations and checks. These serve related but distinct purposes:

• Deterministic computation. The default reasoning core evaluates supported arithmetic, compound conditions and collection queries from explicit recorded inputs.
• Specific formal guarantees. Named theorems cover defined properties of the evaluator and checked-session core. For example, successful evaluation of closed rational arithmetic agrees with its mathematical meaning, and an accepted session view preserves declared conflict signals. See the arithmetic proof scope and the checked-session guarantees.
• An optional checked view. Experimental checked sessions expose a revision-bound view through CLI or MCP. A changed record rejects reads using the old revision. Enable this mode separately with kpop session enable; setup and compatibility instructions cover the packaged bundles.

These guarantees do not establish that a source is accurate, that the recorded premises logically imply an agent's verdict, or that an action is permitted. The adapters, renderer, compiler and runtime are not covered by an end-to-end formal proof. You do not need to write Lean to maintain a record. Lean's reference explains the distinction between proof checking and compiled execution.

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:

Release bundles include the compiled HTML applications. Request them explicitly; installation alone does not activate either application.

kpop experimental hub --open
kpop experimental annotated-doc guide

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 activating the HTML applications.

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:

kpop 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 the native 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 0.9.0 in every reader and writer that touches them; see reader compatibility. 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.

No, he isn't really the father of K-pop. :) Karl Popper was a philosopher of science who argued that a scientific theory must be falsifiable: there must be a possible observation or experiment that would contradict it.

So let's put our own claim to the test: what evidence would make us give it up? If “father of K-pop” means Popper helped create the genre, we can investigate that: check his biography, look for songwriting and recording credits, and compare the claim with histories of Korean popular music.

But suppose we keep changing what “father” means whenever the evidence disagrees. Whatever we find, we invent another explanation that saves the claim. Now it can survive anything. We've made it impossible to test.

That is the challenge Popper posed to scientific theories: they must risk being wrong. A theory must rule something out—something an observation or experiment could reveal. If every possible result can be made to fit, it fails his criterion for empirical science.

For the historical comparison, the Library of Congress timeline traces Korean popular music and identifies the emergence of Seo Taiji and Boys as a turning point in the 1990s. Popper's biography tells the story of his work in philosophy. The banner's pop-star story is our invention.

Surviving tests does not prove a theory true, and an apparent counterexample still needs careful checking. The Stanford Encyclopedia of Philosophy explains this distinction between falsifiability and refutation in practice.

kpopper borrows that discipline to build a working picture of reality for your project. It connects claims and decisions to their evidence and assumptions, and preserves what would make us change that picture. When new evidence is recorded, its checks show which declared conditions fail and which decisions need another look. The person or agent interprets the evidence and revises the record. The picture stays open to criticism, refutation and revision as the work changes.

In our fictional launch story, 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:

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}

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

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

The launch example gives the announcement a concrete condition: the venue booking must stay confirmed. It is this declared condition that the check tests.

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.