Skip to main content

Capture pipeline

A capture comes in as a single sentence. A backlog item comes out as a structured, prioritizable, traceable record. This page explains what happens between those two states.

Stages​

1. Normalize and extract context​

When a capture arrives via the CLI, MCP, or GitHub webhook, Kleio enriches it with whatever context it can grab automatically:

  • From the CLI: repo, branch, current commit SHA, and the file/line if you passed --file/--line.
  • From MCP: the editor's working directory and (depending on editor) the active buffer.
  • From GitHub webhooks: repo, PR number, author, commit metadata, file paths from the diff.
  • signal_at: when the underlying event happened (commit time, comment time, capture time), distinct from the ingestion time. This is what makes backfilled history land on the correct timeline.

2. Embed​

The capture's text gets passed through an embedding model (OpenAI). The resulting vector is what enables the dedup step in (3).

3. Dedup against existing backlog items​

The new capture's embedding is compared against existing open backlog items in the same workspace. There are two thresholds:

  • High-confidence match (>= 0.90): treat as a duplicate. The capture is linked to the existing item rather than creating a new one. The item's evidence count goes up; its priority may drift up if the same thing keeps getting captured.
  • Below the threshold: treat as new. Proceed to synthesis.

Dedup is workspace-scoped. Captures in workspace A never match against items in workspace B.

There's a mid-band between "obvious duplicate" and "obviously new" where Kleio currently leans toward creating a new item; the roadmap (see LLM-verified dedup) is to disambiguate that mid-band with an LLM check rather than embeddings alone.

4. Synthesize the backlog item​

Only signal_type=work_item captures synthesize into backlog items today. The synthesis step:

  • Generates a clean title and description from the raw capture text plus its context.
  • Assigns initial urgency and importance (the Eisenhower axes that replace the old single "priority" field).
  • Mints a human-readable ID like KL-42.
  • Persists the item with links back to the originating capture(s).

Other signal types (PR reviews, CI failures, security alerts) get stored and indexed for queries via kleio_ask, but do not auto-create backlog items yet. That's what the Evaluation Engine roadmap item addresses — expanding synthesis beyond work_item so PR comments and repeated CI failures also become actionable backlog.

Whenever a new signal (capture, decision, checkpoint, commit, PR) lands, the system also runs a lighter pass to check whether it belongs to an existing thing. High-confidence links produce signal_links rows so the provenance graph stays connected:

  • A capture made during a PR review gets linked to the PR.
  • A checkpoint mentioning KL-42 gets linked to that backlog item (and may auto-close it).
  • A commit on a branch named after a backlog item gets linked.

These links are what power the "derived from" trail in the UI: any backlog item should be one click away from the captures, decisions, and commits that produced it.

Provenance, end-to-end​

Once the pipeline has run, a single backlog item like KL-42 will typically point back to:

  • The original capture(s) that surfaced the work.
  • The decision (if any) that committed to a direction.
  • The PR / commits where the work was implemented.
  • The checkpoint that recorded the slice (and closed the item).

That chain is the unit of value Kleio is selling: six weeks later, anyone — human or agent — can ask kleio_ask "why does the auth middleware look like this?" and get back the full trail, not just git blame.