Growing context

A new project starts with no terms, voice profile or approved wording. Its context grows as you work: an assistant notices the name the files always use, or the word you changed in its draft, and records it. Each note arrives as a suggestion. A suggestion advises from the moment it is recorded, and you decide about it when it suits you. A suggestion you keep becomes a rule.

A note arrives as a suggestion that advises at once; it becomes a rule when a person keeps it.

In Kapi Desktop you decide on the Decide page and go back to an earlier state from Sessions, under Assistants in Project Settings. On the command line, the commands are these:

Command	Does
`kapi context suggest`	record what kapi can see in the project's files as suggestions
`kapi rules`	decide about each suggestion, list the rules in force, narrow or drop one
`kapi context review`	the same decisions, as an assistant records them, and applying a rule more widely
`kapi context reset --before <when>`	go back to how the context stood at an earlier point
`kapi context note`	record what you noticed, or what a person changed (an assistant runs this)
`kapi context log`	list what was recorded, or what one assistant session recorded

An assistant notes as it works

A coding agent using kapi's MCP server records with the context_note tool; one running kapi from its shell runs kapi context note. Each call records one thing:

# something the files do every time
kapi context note --term Quickcast --instead-of "Quick cast" \
  --seen-in docs/guide.md --quote "Quickcast forecasts the next hour."

# wording a person changed, and the rule it implies
kapi context note --from "sign in" --to "log in" --seen-in web/src/auth.tsx --suggest

# a fact in prose
kapi context note "the docs address the reader as you"

From --term and --instead-of, kapi works out the other spellings to avoid, with spaces, hyphens and capitals. This note avoids Quick cast, Quick-cast and QuickCast. The lower-case quickcast stays allowed, because it is often the name's own slug; name it in --instead-of when the project avoids it too.

A note holds only where the assistant saw it: in the part of the project the file in --seen-in belongs to. Applying it more widely is a person's decision in review.

Everything one assistant run records belongs to its session. An assistant that recorded something ends its report with the session's id and the command that reviews it:

kapi context log --session this           # the assistant reads back its own run
kapi context review --session s4980103f5148

An assistant can take back a note of its own that was wrong, in the session that recorded it:

kapi context note --withdraw 0n794e2gk7 --why "recorded the wrong way round"

What kapi sees in the files

kapi context suggest reads the files the recipe declares and records what it can see in them, with no AI model:

It sees	It suggests
one word written more than one way, such as `e-mail` and `email`	the form written most often, instead of the others
three or more words a starter voice pack avoids, in a project that binds no voice	a note naming the pack and the words
most blocks with a personal pronoun addressing the reader as you, and none saying we	a note that the files address the reader as you

kapi context suggest             # record the suggestions
kapi context suggest --dry-run   # print them and record nothing
kapi context suggest --ai        # then ask the connected AI model as well

Each suggestion is noticed by kapi, with the counts and a quote from the files, and waits for you in review like an assistant's note. You decide about each one. Running the command again records nothing new, and a suggestion you dropped stays dropped.

With --ai, kapi then asks the connected AI model about the same blocks, through term-extract and voice-infer, and records what the model proposes the same way. A term is recorded when the files write it as the model wrote it in two or more blocks; a term the files write in more than one way is left to the spelling suggestion in the table. A name with spellings to avoid, such as Harbor Help, becomes a term rule; a single word becomes a note naming the term. Each voice measure the model reads becomes a note that names it, such as (sentence_length: short); in a project that binds a voice, no voice measures are recorded. These suggestions are noticed by kapi with the model's name, and the line before them names the model, the blocks it read and the tokens the provider reported. The model reads a bounded sample of a large project. A project that declares redaction has it applied before the model reads anything. With no AI provider configured, or no key for the one configured, the command refuses before it records anything; kapi models setup connects one. --dry-run with --ai still asks the model and records nothing. In Kapi Desktop, Deeper look with AI on the Map does the same.

A suggestion never stops your work

A suggestion advises at once: kapi context <path> lists it under Suggested, not yet established, and checks report text that goes against it. No check fails on it and no score changes until it becomes a rule. A suggestion nobody answers keeps advising, so nothing here has to be cleared.

Deciding with kapi rules

kapi rules

In a terminal, kapi rules asks one question per suggestion. For a name the files write more than one way, the options are the forms, each with the blocks and files that use it. Before you answer, it says what keeping the marked form does: how many blocks a check then reports, and where the rule applies.

[1/2] Which one do your files use?  #0rbavbmqsx
  * 1) Quickcast  2 blocks in 2 files
    2) Quick cast  1 block in 1 file
    3) Quick-cast  0 blocks in 0 files
    4) QuickCast  1 block in 1 file
    5) Other…
  If you keep "Quickcast": the other 3 forms become findings in 2 blocks. Applies to the whole project.
  Seen "Quickcast forecasts the next hour." in docs/billing.md
k keep, n not a rule, l later, 1-5 pick another, q quit:

A number marks another form and says again what keeping it does. Other… takes a form you type. k keeps the marked form, n sets the suggestion aside as not a rule, and l leaves it waiting. Outside a terminal, kapi rules prints the same questions, and the decisions take the id:

kapi rules --keep 0rbavbmqsx --use "Quickcast"
kapi rules --drop 0rbavbp7cv
kapi rules --later 0rbavbp7cv

kapi rules list lists the rules in force, one line each, grouped as names, words, tone and suggested:

1 rule · 1 suggested · 0 narrowed

Names
  Write Quickcast, not Quick cast, Quick-cast or QuickCast.  terms · kept by you, 2026-10-30  #0rbavbmqsx

Suggested
  Write use, not utilise.  suggested by claude-code  #0rbavbp7cv

kapi rules keep <id> and kapi rules drop <id> decide about one line. kapi rules narrow <id> --to <collection> limits a kept rule to one collection or folder, and kapi rules find <word> lists the rules, suggestions and decisions that mention a word. kapi context review, below, records the same decisions; it is the spelling an assistant uses, and it also applies a rule more widely.

Reviewing what kapi learned

kapi context review

In a terminal, review asks about each suggestion in turn and shows the evidence behind it:

[1/2] 0pjby7f9fx  Write Quickcast, not Quick cast, Quick-cast or QuickCast.
  seen "Quickcast forecasts the next hour." in docs/billing.md
  noticed by claude-code
k keep, w keep and apply more widely, d drop, s skip, q quit:

Each answer is recorded as you give it, so quitting part way keeps what you decided.

Run anywhere else, such as in a script or by an assistant, review lists what is waiting since you last looked, with the id each decision takes:

Since you last looked (Tuesday 22 September 09:14):

Needs you
  These rules say different things about the same word. Choose one, and the others are set aside.
    0njy7pxnst  Write log in, not login.
          noticed by codex
    0njy7pwmtj  Write sign in, not login.
          noticed by claude

Established
  0njy7pghcn  Write studio, not business.
        seen "Our business plan" in docs/billing.md
        docs/ says "studio" 41 times and "business" twice
        merged in #412 · your correction in docs/billing.md

Suggested
  Names and spellings
    0njy7pfhjp  Write Quickcast, not Quick cast, Quick-cast or QuickCast.
          seen "Try Quick cast today" in docs/intro.md
          seen in 2 sessions · noticed by claude

kapi knows 23 rules for Fernwell; 4 are new this week. 1 suggestion is advising.

The sections come in the order you read them: disagreements that need you, the rules that came into force and what they rest on, suggestions grouped by theme (names and spellings, words to avoid, how the project writes), content drifting away from a rule, and the project in numbers.

Reviewing moves your "since you last looked" marker, which kapi keeps on this machine and never in the project. --peek leaves it where it is, --since reads from a date instead, and an assistant reading the list never moves it. --json prints the same sections for a program. Kapi Desktop shows the same list when you open a project's Context.

Keeping a rule

Name a suggestion by its id. Any start of an id that names one suggestion will do, and --keep repeats:

kapi context review --keep 0pjby7nz7z

#0pjc4e498b  2026-10-08T13:03:48Z  person  keep  of #0pjby7nz7z
  written to the project's terms store

A rule you keep is in force from then on, in every command that reads the project's context, on any branch and in any worktree. A use of the word it avoids fails a check, unless the rule is advisory, in which case it reports.

Change the rule as you keep it, and say why:

kapi context review --keep 0pjby7nz7z --use "module" --advisory --note "house style"

Keep everything one session suggested that nothing disagrees with:

kapi context review --session s4980103f5148 --keep all

Dropping a suggestion or a rule

kapi context review --drop 0pjby7f9fx --note "we say it both ways on purpose"

A dropped suggestion stops advising at once. Dropping a rule already in force takes it back out of the project's terms or content memory, so checks stop failing on it. The record stays either way, so the same suggestion is recognisable the next time somebody makes it.

To change your mind about a rule, decide again: drop it, or keep a different one.

How a suggestion becomes a rule

Keeping is the direct way. A suggestion also becomes a rule when your own work backs it and nothing contradicts it:

you change wording toward it, and an assistant records your change (kapi context note --from widget --to component --seen-in docs/guide.md);
a change that writes its preferred form, or removes a form it avoids, is merged to the default branch (kapi context sync --merged, run after a merge; see the kapi loop in CI).

Other evidence adds to a suggestion's standing without making it a rule: another session recording the same thing, an agent's edit writing the preferred form, and your content writing it, which kapi check over the whole project and kapi up count. The review list shows the standing as plain counts:

0njy7pfhjp  Write Quickcast, not Quick cast, Quick-cast or QuickCast.
      seen in 3 sessions · merged in #412

Evidence against a suggestion is a change away from it, its withdrawal, or your content moving to a form it avoids after it was recorded. Any of these beside evidence from you leaves the suggestion waiting for you to decide. Time alone makes nothing a rule.

When two suggestions disagree

Two suggestions that name different forms for one word are contested. Both still advise, review shows them together under Needs you, and neither can be kept on its own. Choose one side:

kapi context review --choose 0njy7pxnst

The side you choose is kept and the other is dropped. --keep all for a session leaves a contested suggestion where it is and says so.

A suggestion that contradicts a rule is contested too, and the rule stays in force. When you change wording against a rule yourself, the rule is contested: it reports instead of failing, so your own edit never fails your build. Keep the rule again, or drop it, to settle it.

Where a rule holds

A rule holds where its evidence was seen: a term noticed in one product's reference pages holds for that product, and stays out of another product's tutorials. Evidence alone never widens a rule, and an assistant's note holds only where the assistant saw it until a person applies it more widely. The Context page explains how the recipe divides a project.

Apply a rule more widely as you keep it, or later, by naming a rule already in force:

kapi context review --keep 0pjby7nz7z --widen-to project     # across this project
kapi context review --keep 0pjby7nz7z --widen-to workspace   # in every project you work on
kapi context review --keep 0pjby7nz7z --widen-to mode        # across every mode, the rest unchanged

A rule applied to the workspace holds in every project you work on, and kapi context sync carries it to every machine that syncs the project. A project with its own decision about the word keeps it, because the more specific answer wins.

Going back to an earlier state

An assistant run can record a great deal in an evening. Go back to how the context stood before it:

kapi context reset --before s4980103f5148 --dry-run
kapi context reset --before s4980103f5148 --note "start over"

Set aside 2 suggestions and rules and 2 decisions recorded since s4980103f5148.
  #0pjby7f9fx  2026-10-08T13:00:24Z  agent claude-code/s4980103f5148  observe  term "Quickcast", not "Quick cast", "Quick-cast", "QuickCast"  [suggested]
  #0pjby7nz7z  2026-10-08T13:00:25Z  agent claude-code/s4980103f5148  correct  term "log in", not "sign in"  "sign in" became "log in"  [established]
Recorded as reset #0pjc4e94p0; `kapi context reset --before 0pjc4e94p0` takes it back.

--before takes an assistant session, a date such as 2026-10-01, an instant, or an id from kapi context log. Everything recorded from that point on is set aside, including what people decided since, and the project's terms, approved wording and voice are rebuilt as they stood. Nothing is erased: what was set aside stays in the history marked reset, and the reset is recorded too, so resetting to before it brings everything back. --dry-run says what would be set aside without doing it.

Reset works on the whole context from a point onward. To change one rule, decide again in review.

Who may do what

People and assistants both record notes. Only a person keeps, drops or chooses a suggestion, changes somebody else's suggestion, applies a rule more widely, imports into the project's store, or resets. kapi refuses these from an assistant and tells it to ask you to run kapi context review. The evidence of a merge, and the rules it settles, are recorded as kapi acting for the merge, never as an assistant.

An assistant can withdraw only its own notes, in the session that recorded them.

How kapi knows who recorded a note

The MCP server identifies the caller as an assistant, uses the client's name, and groups its notes under one session. For shell commands, kapi recognises supported agent hosts from their environment and assigns an assistant identity and session automatically. Three variables cover the rest:

Variable	Says
`KAPI_ACTOR`	`agent` or `person`, for a shell kapi would otherwise read the other way
`KAPI_AGENT_NAME`	what the assistant is called, for a host kapi does not recognise
`KAPI_AGENT_SESSION`	the id that groups this run, for the same case

When the host provides no session id, kapi derives one from the process tree, so the commands of one run share a session. On Windows, where that information is unavailable, each command is its own session unless KAPI_AGENT_SESSION is set. When kapi cannot tell, it treats the caller as an assistant, so what it records stays a suggestion for you to review.

`kapi apply` writes the same history

The term and content-memory changes of kapi apply are decisions about the same context, and appear in kapi context log beside the rest:

#0n79x4m0cb  2026-09-21T19:37:31Z  person  edit  term "use", not "leverage"  [established]
  applied with `kapi apply`

A person's changes are in force at once. An assistant's term, content-memory and recipe changes are refused, through the MCP apply_edits tool and through kapi apply from its shell alike, because writing a rule directly is a person's decision. The assistant records the rule with kapi context note instead, and you keep it. kapi store import also puts context in force directly, and records each file it read.

An assistant notes as it works​

What kapi sees in the files​

A suggestion never stops your work​

Deciding with kapi rules​

Reviewing what kapi learned​

Keeping a rule​

Dropping a suggestion or a rule​

How a suggestion becomes a rule​

When two suggestions disagree​

Where a rule holds​

Going back to an earlier state​

Who may do what​

How kapi knows who recorded a note​

kapi apply writes the same history​

What to read next​