Evidence, code intelligence, and drift

An atom can remain active after the code it describes changes. Evidence and drift checks make that gap visible without treating every external source as automatically verifiable.

Evidence and symbols

Evidence types are file, symbol, commit, test, command, url, user, and agent. Each link has a supports, contradicts, or derived_from relationship.

knowl evidence <item-id>
knowl index-code
knowl symbols src/store/repository.ts

Automatic staleness is limited to hashed file evidence and indexed symbol evidence. URL, commit, test, command, user, and agent records do not become stale automatically. File evidence compares its stored hash with the current file. Symbol evidence uses a symbol:// locator against the local index.

The incremental Tree-sitter index supports .ts, .tsx, .js, and .jsx. It records relevant symbols and import/export relationships for local inspection; code indexing and symbol resolution never fan out to workspace peers.

Change impact, when two sessions touch the same code

Off by default. impact.enabled is absent from a new configuration rather than present and false, so upgrading Knowl cannot switch it on. Turn it on with knowl config set impact.enabled true; the MCP tool below is registered only when it is on.

While it is on, Knowl records which files a session actually read, and tells a session when another one has since changed code underneath it — the case where you are working from something that was true when you read it and is not any more.

Findings come in three tiers. certain and likely are returned by default; possible is unmeasured path matching and is returned only when asked for by name. A certain finding also refuses the next edit to that file until you have re-read it, which is the one place this feature does more than report.

• knowl_impact — scope: "mine" (the default) lists findings against reads still held open, which is the work someone can still act on; scope: "all" includes findings whose session has since ended and which nobody has adjudicated. Pass resolve to close one.

Closing a finding is the only way it ever closes, and the resolution is the measurement: repaired (you reconciled your work with the change), false_positive (the change does not affect what you were doing), dismissed (it does, and you are proceeding anyway), or expired (the work it concerned is gone). false_positive is what makes a precision number possible, so it is worth using when it is the true answer.

Pull-request drift and retrieval feedback

Preview affected knowledge before changing freshness:

knowl pr --since origin/main --dry-run
knowl pr --since origin/main

The check considers affectedPaths, source strings, path-like tags, and stale symbol evidence. Without --dry-run, matching candidates are changed to needs_review. It does not rewrite their content or decide a replacement.

Retrieval access logging stores a query fingerprint rather than the raw query. Agents can append feedback only after using or rejecting a result:

knowl_feedback({
  "itemId": "<item-id>",
  "used": true,
  "useful": true,
  "causedCorrection": false
})

knowl access summarizes frequently used, stale, and correction-causing items. Garbage collection also uses this heat: an item is hot when it has at least three retrievals or was retrieved within the last 21 days.