← Blog

· Hive AI

Knolo Evidence Identity: Why a Citation Should Survive a Format Change

How Knolo keeps evidence identity stable across V4-to-V5 migration and retrieval, what a migration receipt records, and why identity is neither a truth verdict nor authorization.

Knolo is the open-source, local-first Knowledge Image runtime and format, released under Apache-2.0 as Knolo's @knolo/core on npm. A format that is meant to outlive any one model or provider has to answer a quiet but important question: when the container changes, does a citation still point at the same source material? In Knolo, that property is called evidence identity. This note explains what it covers in the public contract today, and where its limits are.

Why Knolo treats evidence identity as part of the contract

The Knolo specifications page describes a V5 Knowledge Image as a bounded, content-addressed artifact with deterministic encodings, domain-separated SHA-256 roots and a commit history, while V4 remains a supported compatibility path. Two formats in use at once means older packs and newer images live side by side for a while.

That is exactly when references break in most systems. A record is re-chunked, an identifier changes, and an old citation now points at nothing, or worse, at something else. The Knolo evidence identity docs state the goal plainly: stable evidence identity lets a later operation point at the same source material after a format change.

What a Knolo migration records

Readable V1–V4 artifacts can migrate deterministically into a V5 genesis image. Per the Knolo migration docs, migration imports sources, chunks, claims, agents and metadata, maps legacy block identifiers onto stable V5 evidence identities, and emits a receipt carrying the source digest, the destination root and the identity mappings.

Three properties follow:

  • Determinism. The same source bytes produce the same destination root, so two parties can run the migration independently and compare results.
  • Continuity. The identity map is a public record of which old identifier became which new one. It is continuity, not a rewrite.
  • No new judgment. A migration receipt is not a semantic verdict about the documents. It says how the bytes moved, not whether they are right.

The docs also recommend verifying the source before migrating. Identity is only as good as the bytes it was derived from.

Knolo evidence identity after retrieval

Identity has to survive the query path too, not just the file format. Knolo query hits keep their source, namespace and block identity. When an application adds a model to pick among hits, that model may return indexes, but the application keeps the original hits. Text a selector rewrites is not evidence.

Knolo Cortex, the runtime's verifiable trace layer, enforces a stricter form of the same rule. Evidence must be selected by a replayed retrieval round, and an identifier, citation or claim that names an id outside that round fails closed with CORTEX_MODEL_UNBOUND. The trace's evidenceRoot commits the source label, so a verifier can recompute it later.

The Knolo Evidence Gate (@knolo/evidence-gate, 0.1.0) applies identity at the level of claims. The host declares the relation it wants checked, and the gate confirms that a claim's cited span and relation match the verified image and policy. It does not infer the relation from prose.

How roots tie it together

All of these records rely on the same rule described in Knolo roots and receipts: each root is a SHA-256 digest over canonical CBOR in an explicit domain (knolo:<domain>:v1), and a stored root field is never part of its own preimage. Migration receipts, query receipts and Cortex traces form an inspectable chain from artifact state to the operation that used it.

A matching root means the operation is bound to those bytes. It does not promote the operation into a truth verdict. The same caution applies to evidence identity: a stable identifier tells you which material was cited, not that the material is correct.

What Knolo evidence identity is not

Identity is not authorization. Knolo's docs are explicit that filters and identity do not replace access control, which must be enforced before a query runs. Identity is also not endorsement. Under the Knolo compatibility principles, an independent implementation that preserves the same identities makes a claim that should rest on versions, fixtures and test results, not on the name.

For implementers, that is the practical takeaway. If you build a tool that reads or writes Knolo Knowledge Images, preserving evidence identity across migration and retrieval is part of what compatibility means, and it is something your tests can show. TypeScript and Rust already share fixtures for deterministic CBOR, roots and migration receipts, as described in the Knolo verification docs are a good starting point, and the Knolo verify page lists the official Knolo domains so readers can tell the project from look-alikes.

Follow Knolo

Read the open records on Knolo at knolo.org, and propose changes through the Knolo KIP process. Build with the Knolo developer docs on knolo.dev, and follow the source in the Knolo GitHub repository.

knolo · specifications · evidence-identity · migration · compatibility · knowledge-image