← Blog

· Hive AI

Knolo Composition: Citing Knowledge Images Without Copying Their Bytes

How Knolo composition records cite Knowledge Images by digest, what attestations claim and do not, and the current limits of the open contract.

Knolo is an open-source, local-first runtime and file format for Knowledge Images, released under Apache-2.0 with @knolo/core on npm. A Knowledge Image is one portable, content-addressed file that can be mounted, queried and verified locally. Sooner or later, though, one image needs to rely on another: a research pack builds on a policy image, or an agent answers from several sources at once. Knolo composition is the open contract for saying exactly which images were relied on, without copying their bytes and without changing their identity.

This note explains what a Knolo composition record commits to, what its attestations claim and what they do not, and the current limits. The source is the composition documentation in the public Knolo repository on GitHub, and the developer reference is Knolo composition on knolo.dev.

Knolo composition is a sidecar, not a new image

A composition record cites Knowledge Images, V4 packs, Domain Packs, bounded excerpts and other composition records. The citation is a sidecar. It is not a new V5 commit view and it is not an input to the cited image's stateRoot. An image keeps its identity whether or not anyone composes it.

That separation is deliberate. @knolo/core does not load the composition module unless a host imports it, and the core does not read the filesystem, the network or the clock. Knolo Hub is optional and is not called from this entry point.

What a Knolo composition record commits

The record's identity is compositionRoot, a domain-separated digest over the canonical CBOR encoding of the record body. The stored compositionRoot field is not part of its own preimage, and the same rule applies to excerpt, attestation and signature roots.

Each member has a role fixed by its kind: dependency, evidence, vocabulary, excerpt or nested. A role does not grant precedence. The same alias, or the same primary identity twice, fails closed, and the host image cannot also be a member.

Two availability modes exist:

  • availability: material requires every member's bytes.
  • availability: digest commits to digests only.

Supplied bytes are always checked. Upgrading from digest to material changes compositionRoot when the bytes were not already committed, so the record never quietly claims more than it holds.

Policy lives inside the composition root as { default, allow, deny }. An explicit deny wins, and a parent record cannot override a child record's deny.

Knolo attestations say what happened, not what is true

An attestation over a composition carries one of three statements:

  • mount: the record references members.
  • cited: the record names sources.
  • used: a composed query ran over the members.

used does not mean a claim is true or false. Knolo keeps that line everywhere: verification answers whether bytes match the roots they declare, not whether a source is correct. An optional Ed25519 envelope can sign the attestation's content root, with one signer and no delegation. Core verifies with SubtleCrypto and never generates keys or reads the clock; the CLI signs.

How Knolo uses composition today

The newest example is the Knolo CLI research pack, released in CLI 6.2.5 on npm. knolo research package --cite stores a composition record that cites another image by stateRoot and SHA-256 and checks the record's root before writing anything. The developer walkthrough is on the knolo.dev blog.

The CLI also exposes the record directly with knolo compose create, knolo compose verify, knolo compose excerpt and knolo attest create / knolo attest verify.

Current limits of Knolo composition

The documentation states the limits plainly. The current slice is local and offline. There is no merged evidence graph, no Merkle inclusion proof and no zero-knowledge disclosure. A bounded excerpt commits object id and kind for at most 64 objects. Nesting stops at 8 composition records, and cycles fail closed.

Naming limits is part of an open specification's job. Implementers can build to what exists and know what does not.

Where to read more about Knolo

knolo · composition · open-technology · specifications · attestations