Knolo .knolo File Format: V4 Packs and V5 Images

Knolo is an open-source, local-first Knowledge Image runtime and file format. The portable unit you copy, pin, and mount is a .knolo file: one content-addressed binary artifact that @knolo/core can verify and query without a separate index service. The reference runtime on npm is currently @knolo/core 6.2.0 under Apache-2.0. This note maps what the Knolo .knolo format contains today—V4 packs, V5 images, digests, and identity—using the live docs on Knolo on knolo.dev.

What a Knolo .knolo file is

A Knolo Knowledge Image is a bounded, content-addressed bundle of knowledge. On disk and in registries it usually ends in .knolo. You build it once, pin it by digest, mount the same bytes elsewhere, and retrieve evidence locally. Identity lives in digests and roots, not in a floating remote index.

That is the product primitive Hub calls out plainly: the Knolo Hub pack format page opens with “The .knolo artifact is the product primitive.” The same idea appears on Knolo on knolo.org: one portable file you can mount, query, and prove.

Knolo V4 packs: the everyday build path

With @knolo/core, buildPack emits a versioned V4 container by default. The documented binary layout is compact and mount-friendly:

[metaLen][meta]
[lexLen][lexicon]
[postCount][postings]
[blocksLen][blocks]
[semantic?]

Properties the npm docs list for that layout: versioned, compact, immutable, optional semantic section auto-detected, designed for fast mount and query. Lexical retrieval stays the default path; optional semantic reranking sits on top and does not require an external vector database. Install with npm install @knolo/core and follow the Knolo installation guide.

V4 packs remain discoverable on Hub. Magic bytes for the pack surface are documented as KNLOV4. Older v1–v3 packs remain readable; use { format: 3 } only when you intentionally target a legacy runtime.

Knolo V5 images: roots you can check

V5 is the current verifiable Knowledge Image contract in source and docs. A V5 image is still a portable .knolo artifact, with a stronger identity story:

• Magic: KNLOV5 (alongside V4’s KNLOV4 on Hub).
• Dual superblocks, generation-based recovery, and an active commit pointer.
• Immutable object and event segments.
• A commit record with parent, object, event, view, schema, policy, runtime, and sequence roots.
• Per-section bounds and digests, plus fail-closed checks for missing sections, overlaps, overflows, and digest mismatches.
• Forward-compatible handling of unknown optional sections.

V5 adds an explicit stateRoot so mounted state can be identified alongside the artifact digest. The Knolo V5 concepts page is the developer overview; Knolo verification states the narrow question a check answers: do these bytes match the roots they declare? A pass is not a claim that a source document or model answer is true.

V5.5 adds optional VQF-1 physical compression of object and event segments. Compression does not change logical format, object identities, or stateRoot. Hub’s pack-format note records that clients on older lines can fail closed on compressed required segments—pin the runtime version you mean.

Knolo digests, Hub paths, and lockfile identity

Immutable identity pairs publisher/name@version with sha256 and, for V5, stateRoot. That is what a lockfile, receipt, or deployment record should keep. On Hub, blob pathnames follow sha256/<64-hex>.knolo. Pinning a digest means one immutable byte sequence—not “whatever the wiki said last Tuesday.”

Public packs live on Knolo Hub. Hub lists digests and verification status so you can inspect before you pull; queries still run after you mount locally with @knolo/core.

How to work with Knolo .knolo files today

1. Install @knolo/core 6.2.0 and build a small V4 pack, or migrate toward V5 when you need stateRoot and the stronger commit layout (installation, V5 concepts).
2. Inspect and verify with the CLI or runtime helpers described under verification.
3. Discover public images on Knolo Hub and read the pack format note before you pin.
4. For open specifications and licensing orientation, use Knolo on knolo.org.
5. Source and releases: the Knolo core repository on GitHub.

Knolo keeps knowledge in a file you can copy and check: Apache-2.0, local-first, pin-by-digest. The .knolo extension is that contract on disk—V4 for everyday packs, V5 when you need explicit roots and fail-closed image identity.