The kb notebook

The notebook, in depth

A repo-local knowledge base, written and read by agents, living in .coldstart/notebook/. It's the one place semantics belong: authored by the agent that just did the work, kept honest by the index, and recalled when a later task matches. No human writes or grooms it.

What a note is

Every note carries anchors — the concrete file paths and symbols its claims rest on. Anchors are what make a note checkable rather than a floating assertion.

Where notes reach the agent

• Summary lines on find results — a past agent's verified overview, right where the file ranks. fresh means the file is byte-identical to when the summary was verified.
• Recall at prompt time — injected straight into the agent's context as a compact block before it acts. Matching notes arrive automatically; nothing matches means nothing injected.
• kb search / kb lookup — search the notebook and exact-address lookup before editing a file.

Why it can be trusted

Freshness is mechanical (content-hash, re-checked on every read — a drifted note renders evidence changed instead of passing as fact), writes go through a dedup gate, and concurrent sessions never silently lose or merge a note. Full mechanics: how the notebook works →

Language-agnostic. The freshness machinery is content-hash based, so the notebook works on any codebase — including languages the navigation index doesn't parse.

When capture happens

Capture is trigger-timed, not every-turn — the hook scores what the session actually read or edited (search hits and path mentions never count) and asks at natural boundaries, when a burst of work settles or a commit lands. The ask is non-blocking: it arrives with your next prompt as a worklist of the files the session touched, each annotated with its existing note's state, and is also written durably to .coldstart/notebook/.worklist-<session>-<agent>.md so a long session can re-read it after the one-shot delivery scrolls away. Missed files simply reappear on the next trigger; a warmed-up repo (notes already fresh) asks less over time.

/capture-notes — capture on demand

Sometimes you know a moment is worth recording before the automatic score crosses — a hard-won insight, a confirmed absence, a decision that didn't touch many files. /capture-notes fires the capture flow immediately, with the same worklist and gate. It never forces a write.

coldstart init wires it for your client: Claude Code and Cursor get a /capture-notes slash command; Codex gets a capture-notes skill. All three run the same one-liner, so it also works by hand:

.coldstartignore — files that never get notes

coldstart init scaffolds .coldstart/.coldstartignore (gitignore syntax). Built-in defaults are *.json, lockfiles, dist//build//coverage/, minified files, binaries and images, and .env* (notes are committed; secrets must never enter them). Every collaborator gets that baseline; lines you add extend it on your machine.

Ignored files are filtered at the root — they never appear in a capture worklist. Logic-bearing configs (vite.config.ts, CI workflows, routes.rb) are deliberately not ignored by default: they carry exactly the gotchas notes exist for.

• Batch is the capture path. The spec file may be a JSON array of notes, written in one call: well-formed notes land, malformed ones are reported together, and the call ends naming any worked file still without a note.
• A single new flow/lesson exits 3 with candidate matches. Resolve it with --into <id> (merge) or --new (declare it new).
• Reads a spec file, or - to stream from stdin.
• Correct a note: {"op":"retract","id":"<id>","target":{"kind":"note"}} removes it, or target one part with target:{kind:"anchor"|"alias"…, key:"…"}.
• Freshly-coined ids are created exclusively — a same-moment duplicate becomes two notes, never a silent merge.

Once generated, the keeper re-renders it whenever notes change, so a browser reload shows the latest — you don't re-run the command.

Sharing with a team

The notebook is private by default — .coldstart/ is gitignored. Opt in to sharing and the whole team's agents contribute to one growing corpus.

Once committed, the .raw logs travel with the repo and union-merge across branches and machines — parallel branches of notes reconcile without conflicts. Every teammate's agent both reads from and writes to the same notebook, so the corpus grows at the speed of the whole team.