The agent thought graph

kcp-dashboard shows not just what an AI agent did, but why it was given the knowledge it used — the deterministic decision behind every governed context load.

KCP · Knowledge Context Protocol Bubble Tea TUI · Go Apache-2.0

▶ Open the interactive demo

Runs entirely in your browser. Pick a real-world scenario — customer support, incident response, a coding agent, financial compliance, or a clinical assistant — across Starter → Standard → Advanced complexity, and watch which documents KCP lets the agent read, and why.

Why this exists

Agent monitors show a stream of tool calls: a flat list of what happened. What they can't show is the reasoning structure — and an LLM's true chain-of-thought isn't faithfully observable (emitted "reasoning" is an unreliable narrator).

So we don't scrape thoughts. We reconstruct the graph from deterministic, observable signals the KCP toolchain already produces. Two faithful layers:

Action layer

The ordered steps a session took — tool, command, whether KCP guidance matched. Reconstructed from tool_events.

Decision layer

The deterministic 13-gate cascade behind every knowledge load — which units were selected or skipped, and at which gate. Reconstructed from kcp-harness's kcp_trace.

How it works

The decision layer is the interesting half, and it's genuinely faithful because the governance is deterministic: the kcp-agent planner runs a fixed cascade of gates over every unit in a manifest and records the verdict for each. kcp-harness emits a compact, content-free projection of that trace; kcp-dashboard stores and renders it.

kcp-harness (governs a tool call) │ kcp_trace → DecisionTrace (13-gate cascade per unit) │ toTraceEvent() — ids, paths, gate verdicts, scores only · no content └── POST /trace ──► kcp-dashboard :7734 ──► decision_traces + trace_units │ press s → browse sessions press g → Steps ⇄ Decisions │ task → gate funnel → ✓ selected (score) / ✗ skipped-at-<gate>

Emission is opt-in (a dashboard URL must be configured) and fail-open — telemetry can never block or delay governance. Traces carry no file content, only structural facts.

Setup

1 · Install & run the dashboard

go install github.com/Cantara/kcp-dashboard@latest

# TUI (reads ~/.kcp/usage.db + memory.db)
kcp-dashboard

# hook + ingest daemon on :7734 (receives /trace)
kcp-dashboard serve

2 · Point kcp-harness at it

Add a dashboard block to your harness.yaml. Absent = disabled, so it's safe to leave out in environments without a dashboard:

dashboard:
  url: http://localhost:7734/trace

Now, whenever an agent behind the harness calls kcp_trace, the harness POSTs the decision trace to the dashboard. Browse it live in the TUI.

Using the drill-down

Key	Action
`s`	Enter / leave the session drill-down
`j` / `k`	Move the session selection (reloads its steps & decisions)
`g`	Toggle the right pane between Steps and Decisions
`esc`	Back to the aggregate dashboard
`q`	Quit

Steps is the action layer — the ordered timeline. Decisions is the decision layer — each governed decision as task → gate funnel → per-unit verdict.

Reading a decision

A decision renders as a task, a funnel showing how many candidate units each gate passed, and the per-unit outcome:

access resolve incident INC-4821          5 selected / 5 skipped
  relevance   ██████████████████░░░░  8/10
  temporal    ████████████████████░░  9/10
  payment     ██████████████████░░░░  8/9
  …
  ✓ oncall-runbook  (0.86)
  ✓ escalation-policy  (0.71)
  ✗ pci-scope    — skipped at temporal
  ✗ vendor-intel — skipped at payment
  ✗ prod-secrets — skipped at access

You can see exactly where a unit dropped out of the cascade — a superseded doc dies at temporal, a paywalled feed at payment, a restricted path at access. That is the thought graph: not a guess about what the model was thinking, but the deterministic reason it was handed this knowledge and not that.

The 13 gates, in plain English

Every candidate document is tested against these rules in order and stops at the first one it fails. That failing rule is the reason it was blocked.

Gate	Blocks a document when…
`audience`	it isn't written for AI agents
`not_for`	it's explicitly excluded for this kind of use
`temporal`	it's out of date / not yet valid
`deprecated`	it's marked deprecated
`supersession`	a newer document replaces it
`relevance`	it isn't relevant to the task
`attestation`	it needs an attestation the agent doesn't have
`payment`	it costs money to read and hasn't been paid for
`access`	it's restricted and the agent isn't permitted
`strict`	strict mode drops anything not fully eligible
`max_units`	the context is already full — only the top few (by relevance) are kept
`money_budget`	loading it would exceed the money budget
`context_budget`	loading it would exceed the token budget

A document that clears every gate is loaded. Because the checks are fixed and ordered, the same inputs always produce the same decision — which is what makes this a faithful record rather than a guess about the model's reasoning.

Words you'll see

Term	Meaning
Session	One agent working on one job, start to finish.
Step	A single thing the agent did (read a file, run a command, plan).
Manifest	A catalogue of an organisation's knowledge — the documents KCP can hand out, each with rules attached.
Unit	One document in the manifest — the thing that gets allowed in or blocked.
Gate	One rule in the 13-rule check.
Decision / trace	The full record of a knowledge request: which documents were considered and the gate verdict for each.
Score	How relevant a document is to the task (higher = more relevant).
✓ selected	Allowed in — the agent may read it.
✗ skipped	Blocked — labelled with the gate that stopped it.

▶ See it in action