Skip to content

Keep what an episode learned, without a model and without a conversation

Record a decision inside an episode, derive it into a candidate knowledge record from the ledger, read the evidence that the derivation ran, and watch a second derivation change nothing.

guaranteed Repository knowledgebasicmaintaineragentwrites state

Situation

A worker decided something an hour ago, in a conversation that will be compacted by lunch and gone by tomorrow. The decision is in the ledger of one machine, under a retention cap, and nowhere a second checkout or a public surface can reach it. Nobody will remember to write it down, and a paragraph somebody did write would be a summary of a conversation, which the layer refuses to store.

Scenario

setup: session-open
given:
  - 'Majordomus installed, with one execution episode open in this worktree'
  - 'the knowledge section carries the curated and candidates source classes and no candidate yet'
steps:
  - id: open-the-work
    run: ['start', 'keep what this episode learned', '--scope', '.ai/repo/knowledge']
    note: 'a task is optional for the derivation; it is here so the decision has one to name'
    expect:
      exit: 0
  - id: decide-something
    run: ['decision', 'add', 'A candidate is reviewed by a person before it is curated', '--why', 'a record only one machine can read is a record nobody reads']
    note: 'one decision.recorded line in the ledger, stamped with the open episode'
    expect:
      exit: 0
  - id: derive-it
    run: ['knowledge', 'derive']
    note: 'from the ledger and git, deterministically: one candidate record, status candidate, origin extracted, derived_from naming the episode and the decision'
    expect:
      exit: 0
      stdout_contains: ['^written \.ai/repo/knowledge/candidates/', 'knowledge derive: 1 written']
  - id: the-evidence-it-ran
    run: ['history', '--event', 'knowledge.derived']
    note: 'the ledger says which episode was derived and what was written; the line exists even when nothing was'
    expect:
      exit: 0
      stdout_contains: ['knowledge.derived']
  - id: derive-it-again
    run: ['knowledge', 'derive']
    note: 'the same evidence yields the same bytes: the record id is the episode plus a digest of the evidence, so the file is rewritten identically and reported unchanged'
    expect:
      exit: 0
      stdout_contains: ['^unchanged \.ai/repo/knowledge/candidates/', 'knowledge derive: 0 written. 1 unchanged']
then:
  - 'the decision is a tracked record with resolvable provenance, readable from every checkout and every surface'
  - 'verified is still nobody''s: the deriver wrote a candidate, and promotion is an act a person performs with evidence'

Outcome

knowledge derive turns the episode's ledger lines into candidate records under .ai/repo/knowledge/candidates/, the ledger records that it ran, and a second run over the same evidence writes nothing. The provider's end and compaction events do the same without anybody typing the command; majordomus knowledge promote is where a person makes a candidate verified.

The scenario

Executed against the real tool, in a repository prepared by session-open, every time this site is generated. What follows is not a description of what should happen; it is what happened.

given

  • Majordomus installed, with one execution episode open in this worktree
  • the knowledge section carries the curated and candidates source classes and no candidate yet

when

  1. 1majordomus start keep what this episode learned --scope .ai/repo/knowledge
  2. 2majordomus decision add A candidate is reviewed by a person before it is curated --why a record only one machine can read is a record nobody reads
  3. 3majordomus knowledge derive
  4. 4majordomus history --event knowledge.derived
  5. 5majordomus knowledge derive

then

  • the decision is a tracked record with resolvable provenance, readable from every checkout and every surface
  • verified is still nobody's: the deriver wrote a candidate, and promotion is an act a person performs with evidence

What the tool did

Evidence of the run this page was generated from: pass, 5 step(s). Output is normalised: the repository's path, timestamps, ids and durations are placeholders; nothing else is edited.

Tested by test/cases/94_use_cases.sh, which runs every scenario and refuses a step whose recorded output is not what it produced.

  1. a task is optional for the derivation; it is here so the decision has one to name

    started t-<id>  profile=implementation  scope=.ai/repo/knowledge
    next: majordomus context; checkpoint every 15m; majordomus check before claiming anything
    • exit 0
  2. one decision.recorded line in the ledger, stamped with the open episode

    recorded: A candidate is reviewed by a person before it is curated
    • exit 0
  3. from the ledger and git, deterministically: one candidate record, status candidate, origin extracted, derived_from naming the episode and the decision

    written .ai/repo/knowledge/candidates/s-<id>-eb92bb74aa02.md
    knowledge derive: 1 written, 0 unchanged, 0 skipped for episode s-<id>
    • exit 0
    • stdout_contains /^written \.ai/repo/knowledge/candidates//
    • stdout_contains /knowledge derive: 1 written/
  4. the ledger says which episode was derived and what was written; the line exists even when nothing was

    <time>  knowledge.derived   -                      <head>  
    • exit 0
    • stdout_contains /knowledge.derived/
  5. the same evidence yields the same bytes: the record id is the episode plus a digest of the evidence, so the file is rewritten identically and reported unchanged

    unchanged .ai/repo/knowledge/candidates/s-<id>-eb92bb74aa02.md
    knowledge derive: 0 written, 1 unchanged, 0 skipped for episode s-<id>
    • exit 0
    • stdout_contains /^unchanged \.ai/repo/knowledge/candidates//
    • stdout_contains /knowledge derive: 0 written. 1 unchanged/

Why the tool knows this

The chain from this page to the code: the use case names commands, rules and claims; each rule is dispatched from the registry and each claim names the test that proves it; the scenario above executed the commands. Nothing in this chain is prose about intent.

The rules that make it hold

Guarantees exercised

Related use cases

Computed from what they share: claims, rules, commands, category, applications. Nobody maintains this list.

Searches the titles and descriptions of every page this site publishes.