Daily use

After install, kenkeep runs itself. Capture and injection happen on their own; the only thing you ever do by hand is curate, review, and commit.

TIP

Most days you do nothing. When the nudge appears, it’s three steps: /kk-curate, then git diff, then git commit what you want to keep.

</Callout>

The loop

Code with your AI assistant as usual. Anything you wrap in <kk-private>…</kk-private> mid-session is stripped from the capture before it touches disk.
When you see the curate nudge (or whenever you feel like it), run /kk-curate.
If the curator reports any contradictions, the skill walks you through each one in-session and applies your chosen resolution.
Inspect the resulting changes under .ai/kenkeep/nodes/ with git diff (or your preferred diff tool, e.g. self-review).
git commit what you want to keep; git restore <path> to discard.

The pre-commit hook regenerates ENTRY.md and GRAPH.md and stages them into the same commit, so the injected index never drifts from the committed nodes. If you git restore <path> to discard nodes without committing another nodes/ change, that hook doesn’t fire — run npx kenkeep index rebuild so the regenerated index drops the removed nodes too.

That is the entire daily workflow. The rest of this page is reference: the intake skills, and the two manual actions you reach for occasionally.

Skills

Four in-session skills cover knowledge intake. Run them inside your harness session; the LLM call happens in that same session, with the model, prompt cache, and tools you already use interactively.

Skill	What it does	When you reach for it
`/kk-add`	Conversationally gathers a node’s fields, checks `ENTRY.md` for overlap, writes it under `nodes/`.	When you already know the node you want.
`/kk-session-extract`	Extracts durable knowledge from the visible current session, stages a done session log, and runs the same curation tail as `/kk-curate` for that one session only.	When the current session just produced teaching moments you want to process now.
`/kk-curate`	Reads pending captured sessions, drafts proposed notes under `nodes/`, rebuilds `ENTRY.md`/`GRAPH.md`, and walks you through any contradictions with the `y/n/s/k` prompt.	The daily loop, when nudged — deferred batch processing of captured logs.
`/kk-bootstrap`	Seeds nodes from your existing docs — a one-time setup step, see Installation → Seed from existing docs.	Once, at setup.

CAUTION

Run only one LLM skill at a time per repo. /kk-curate and /kk-bootstrap are single-author by design and take no cross-process lock, so concurrent runs against the same repo can silently waste work (sessions reprocess on the next run — no data loss). See Architecture → Locking.

</Callout>

The curate nudge

You don’t have to remember to curate. SessionStart counts the curation queue, meaning captured sessions that still need /kk-curate; this includes both logs awaiting proposal extraction and extracted logs awaiting curator review. Once the queue is worth your attention, it appends a one-line nudge to the injected context and prints a visible warning to stderr. It also attempts a native desktop notification when supported by the OS (osascript on macOS, notify-send on Linux). Missing or headless notification backends are skipped silently. It escalates to a loud heading when the queue is large or stale. The thresholds and notification opt-out are configurable. See Internals → Hooks and Installation → Configuration.

Curate

In a harness session:

/kk-curate

The curator reads every captured session that’s been processed but not yet curated and applies its decisions directly to nodes/:

Decision	Effect
add	Writes the new note into the best-fitting existing folder under `nodes/` (or the `nodes/` root when nothing fits). The note id is independent of the folder.
modify	Updates the target note in place by id; no relocation. Fails loud if `target_node_id` is missing on disk.
contradict	Records the conflict under `.ai/kenkeep/conflicts/<id>.md` with `status: pending`; writes nothing to `nodes/`.
drop	No change.

The home folder is chosen in the same pass that links a note to its neighbors. Curation only places notes in existing folders; it never creates, splits, or merges them. The end-of-run summary lists each written note’s placement (its folder, or root fallback) so you can review placement alongside content.

Rebalance (act-and-fold)

Structural upkeep folds into curate as its last phase — no separate command, no extra nudge. A deterministic, LLM-free trigger checks the per-folder metrics with a hysteresis margin; if nothing trips, the phase is skipped. When a threshold trips, the LLM splits a folder, splits a bloated note, merges a sparse branch, or creates a branch for a new topic, on the affected branches only.

The moves land in the same diff as the note writes (act-and-fold), reviewed with the gate you already use: git diff to inspect, git commit to accept, or a path-scoped git restore <path> to reject just the moves. They preserve content byte-for-byte, so git diff --summary shows them as R renames; ids stay stable, so cross references survive. Curate prints a structural summary as a legend for the diff. If you git restore the moves rather than committing them, run npx kenkeep index rebuild afterward so the generated index matches the restored layout.

Fast path

Zero conflicts and zero failures → the skill prints one summary line and exits. Once a project stabilizes, this is the common case.

Conflict walkthrough

When the curator reports contradictions, the skill walks each one with the existing node shown side-by-side and a single-character prompt:

Accept this proposal? [Y/n/s/k] (default: Y)

Key	Action
`y`	Accept: rewrite the node with the proposed body, then `git restore` the conflict file.
`n`	Reject: `git restore` the conflict file; node unchanged.
`s`	Skip: leave the conflict file pending; it re-surfaces next pass.
`k`	Keep: `git commit` the conflict file as a historical record; node unchanged.

Defaults are heuristic per conflict (small diffs default y, rewrites n, otherwise s). Long forms (yes, skip) and uppercase work; anything else is re-prompted.

Add knowledge manually

/kk-add writes a node directly from the current session. Review with git diff and commit. Reach for it when you want to capture a decision the moment you make it, without waiting for the next curate pass.

Extract from the current session

/kk-session-extract applies the same proposal-extract.md gate to the visible conversation, stages a proposal_status: done log under _sessions/, and immediately runs curation for that session only. Use it when a session has converged on durable project knowledge and you do not want to wait for capture hooks plus a later /kk-curate.

Meta-only or planning sessions may correctly yield no proposals — that is success, not failure. If compaction has occurred, extraction covers only what remains visible. When the runtime cannot expose a UUID-v4 session id, the skill reports degraded idempotency; whole-tree dedup remains the secondary safety net.

Status

npx kenkeep status reports both queue names: the proposal extraction queue is logs with proposal_status: pending, while the curation queue is logs that /kk-curate still needs to process, including extracted done logs without curator_processed_at.