kb_write
Record what you learned during a coding session: save file notes, workflow flows, or absence lessons. The two-phase reuse gate matches existing concepts before writing, preventing duplicates.
Instructions
Save or correct a NOTEBOOK note after finishing real work here — you have the files in context, so no future agent is better placed to record what you learned. Write a file note (what a file is for), a flow note (how a task spans files), or an absence lesson (a confirmed "there is no X"). Also the tool to FIX or RETRACT a note you used that proved wrong (op: "put" replaces, op: "retract" removes).
TWO-PHASE reuse gate: a flow/lesson spec sent WITHOUT an id first searches the notebook for the same concept. If plausible matches exist, kb_write returns {status:"candidates", candidates:[...]} INSTEAD of writing — re-call with into: "<id>" to merge into an existing note, or is_new: true to declare a genuinely new one. This makes note identity reliable (matching, not guessing an exact title). File notes skip the gate (id derives from the path).
The spec shape is documented in coldstart.md — briefly: type ("file"|"flow"|"lesson", or sugar "file-hub"/"file-single"), title, summary, anchors ([{path, symbols?}] — the addresses the note is about, which drive freshness), plus type-specific fields (file: facets/character; flow: steps; lesson: kind:"absence"/scope/body). Call with NO arguments to get the full spec guide. This tool WRITES to the repo notebook; it never commits to git — publishing notes is a human-only step (coldstart kb commit).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| into | No | Phase-2 answer: merge this write into the existing note with this id (from a prior `candidates` response). | |
| spec | No | The note spec (JSON object). Fields: type, title, summary, anchors:[{path,symbols?}], and type-specific fields (facets/character for file; steps for flow; kind/scope/body for lesson). See coldstart.md. Omit `id` on a new flow/lesson to trigger the reuse gate. | |
| is_new | No | Phase-2 answer: declare this a genuinely new concept, bypassing the candidate matches from a prior `candidates` response. | |
| session | No | Optional session id (given in a capture prompt). Enables the flow-evidence check: a flow whose step files this session never actually read gets a warning. |