Skip to main content

Learn kapi › The context engine

The context engine

What the project knows, drawn as a graph that grows with the work.

kapi keeps what a project knows about its own content in one place: the voice it writes in, the words it uses and avoids, the content memory, and the record of every decision. Checks and translations read that graph, every decision feeds it, and an assistant gets the same answer a person does. This lab draws the graph above the terminal and takes the Compass project through one cycle: read the context in, converge, review, converge again. Each command adds something to the picture.

  1. A project before it knows anythingkapi ls --statsCompass has one source file, 38 blocks of interface strings, and three editions of it: German and Norwegian nearly complete, Dutch half done. The graph shows the content and the point it sits at, and nothing else: no voice, no terms, no memory, no record. Nothing says who wrote those translations or whether anyone approved them, so every gate would answer from an empty store.
  2. Read the context inkapi store import ./contextThe context arrives as files in the repository: a voice profile, the terms, two content-memory bundles and a record of decisions a reviewer made earlier. Reading them in fills the right-hand side of the graph in one step, and the editions already show the share a person established.
  3. What applies at this pointkapi context site/locales/en-GB.json | head -20Content sits at a point: the Northsea profile on the app channel. Ask what applies there and the answer is the voice, the terms and the rules that hang off that point in the graph. An assistant working in the repository asks the same question and reads the same answer.
  4. Converge, and the memory growskapi upThe loop reads the memory before it writes anything. Blocks the project already settled are recycled, the rest are drafted, and what was written joins the memory for the next run: watch the entry count rise and the edges to each edition thicken. Dutch waits for review: its drafts are AI-translated and nobody has reviewed them.
  5. The graph learns where words livekapi terms occurrences berthOnce the engine has read the content, a term is no longer just a rule: it is placed. Each concept now points at the blocks that use it, and a check or a rewrite can go straight to them.
  6. The gate reads the same graphkapi check --ship --gate voiceThe ship gate asks each edition the question the picker will ask: translated, and established by a person? Dutch fails on the second count, which is a reviewer's job, and the exit code says so without anyone reading a report.
  7. Pick what to approvekapi status --review --json --jq '.pending[]|select(.locale=="nl" and (.target|startswith("⟦")|not))|{op:"decide",at:{doc:.relative,block:.key,edition:.locale},if_match:"*",outcome:"establish"}' > dutch.jsonThe review queue is data. One filter keeps the Dutch blocks that carry a real translation, and turns each into a decide operation addressed at its block.
  8. A review becomes a recordkapi apply dutch.jsonApplying the change set establishes twenty blocks. Nothing is written into a target file; what changes is what the project knows: twenty Dutch blocks now carry a decision a person made, the edition's established share rises to match, and the decisions join the record at the bottom of the graph beside the imports.
  9. The record is the historykapi context log | head -8The log prints what was recorded about the context: who imported or noted what, when, and from which evidence. The block decisions sit beside it in the same record, and both travel with the project, so a colleague's clone and a server share one history.
  10. Converge againkapi upThe second run reads the twenty decisions, draws on the memory for the rest, and every gated edition is shippable. The graph is the same graph, with more in it: that is the whole mechanism, and it is what an agent, a reviewer and a build all read.