← Blog

· Hive AI

Pack Once, Pin by Digest: Getting Started with @knolo/core

Meet @knolo/core, the open-source runtime for portable, verifiable Knowledge Images. Pack knowledge once, pin it by digest, and retrieve evidence locally.

Most AI applications treat knowledge as loose context: a folder of documents, a vector index, a prompt template. It works until someone asks a simple question. Which exact knowledge produced this answer, and can you show me the same thing again tomorrow?

Knolo is built for that question. The open-source @knolo/core runtime turns a knowledge base into a portable, verifiable artifact. You pack knowledge once, pin it by digest, and retrieve evidence locally. No vector database is required, and no hosted service sits in the middle.

This post is a practical introduction for developers. It covers what a Knowledge Image is, how the runtime is split, and how to get from npm install to a verified image in a few minutes.

What a Knowledge Image is

A Knowledge Image is one portable file that holds your knowledge in a form you can copy, mount, inspect, verify and compare.

Knolo has two artifact generations that live side by side:

  • V4 packs are the path for ordinary search. A .knolo pack is a versioned, immutable binary that you can mount in Node, the browser or React Native and query with lexical-first retrieval.
  • V5 Knowledge Images are the evidence container. A V5 image uses deterministic encodings, domain-separated SHA-256 roots, bounded sections and a commit history. Its stateRoot identifies the image.

That root is what makes pinning possible. If two machines hold images with the same root, they hold the same knowledge state. If the bytes change, the root changes, and verification fails closed.

Pack once, pin by digest

Software teams already pin dependencies by version and hash. Knolo applies the same idea to knowledge.

You build an artifact once in CI or on your laptop. You record its digest. Every environment that needs it mounts those exact bytes and can check them before use. The Knolo Hub registry follows the same pattern: the CLI downloads a pack, checks its SHA-256 against the manifest and records it in knolo.lock.json. Digest checks cannot be bypassed.

The result is knowledge that behaves like a build artifact rather than a moving target.

Retrieve evidence locally

Retrieval runs inside your process. There is no remote index to call and nothing to keep in sync with a separate database.

V4 retrieval is deterministic and lexical-first. Semantic reranking is optional and never replaces lexical grounding. Results carry source, namespace and identity metadata, so you can trace a hit back to where it came from. Query receipts let you record what was asked and what came back, and knolo explain can walk through a receipt later.

Because everything runs locally, the same pack gives the same results offline, in a serverless function or on a phone.

Quickstart

These steps come straight from the installation guide and the quickstarts. The current npm release is @knolo/core@6.2.0.

1. Install the runtime

npm install @knolo/core

The root entry covers V4 packs, V5 images, policy and diagnostics. Node filesystem helpers live on @knolo/core/node.

2. Build, mount and query a V4 pack

import { buildPack, mountPack, query } from '@knolo/core';

const bytes = await buildPack(docs, {
  semantic: { enabled: false },
});

const pack = await mountPack({ src: bytes });
const hits = query(pack, 'refund policy', { topK: 5 });

3. Migrate to a verifiable V5 image

import {
  migrateV4ToV5,
  mountKnowledgeImageV5,
  verifyKnowledgeImageV5,
} from '@knolo/core';

const { image, receipt } = await migrateV4ToV5(v4Bytes);
const verification = verifyKnowledgeImageV5(image);
const mounted = mountKnowledgeImageV5(image);

console.log({
  verified: verification.valid,
  stateRoot: mounted.commit.stateRoot,
  migratedFrom: receipt.sourceDigest,
});

The migration receipt records the source digest, the destination root and the evidence identity mappings. See the V5 quickstart for details.

4. Use the CLI

The CLI (@knolo/cli) does not call a model and does not need an API key.

npm install -g @knolo/cli

knolo build
knolo inspect dist/knowledge.knolo
knolo verify dist/knowledge.knolo
knolo query "billing policy" --receipt receipt.json --json

knolo v5 info ./dist/knowledge.v5
knolo v5 health ./dist/knowledge.v5

What verification does and does not mean

Verification answers a narrow question: do these bytes match the roots they declare? It does not tell you whether a source document is correct or whether an answer is true. The verification docs are explicit about this, and so is the runtime.

That boundary is deliberate. Knolo owns artifact structure, roots, evidence identity, validation and deterministic planning. Your application owns models, credentials, networking, deployment and tools.

Where to go next

Knolo is open source and local-first. Pack your knowledge once, pin it, and know exactly what your AI is reading.

knolo-core · knowledge-images · quickstart · open-source

Pack Once, Pin by Digest: Getting Started with @knolo/core — Knolo Blog