The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Knolo listing page.
Knolo turns organizational knowledge into portable, deterministic, and cryptographically verifiable runtime artifacts.
AI products are becoming easier to build. The hard problem is making their knowledge dependable: traceable to evidence, reproducible across environments, safe to move, and defensible under review. Knolo is infrastructure for that problem.
Knowledge should be an asset you can inspect, verify, migrate, and run—not opaque context trapped inside an application.
V6 · KAR · V5 Knowledge Images · V4 compatible · Local-first · Deterministic · Verifiable
This tree is Knolo 6.2.0. V6 adds KAR: deterministic retrieval of a minimum evidence set from a V5 Knowledge Image and a Committed Evidence Graph. 6.1.0 adds verifiable composition. 6.2.0 adds Knolo Cortex: bounded evidence retrieval with a verifiable trace. The host owns any model. Verification does not mean an answer is true. Lexical retrieval, V5 images, and V4 packs stay in place.
The root @knolo/core entry does not load KAR. @knolo/core/experimental/kar remains a compatibility entry for this cycle. SATISFIED means the declared evidence requirements were met. It does not mean a claim is proven. UNSATISFIED_EVIDENCE_REQUIREMENTS means those requirements were not met. It does not mean the claim is false.
The npm packages in this repository are 6.2.0. @knolo/cli depends on @knolo/core ^6.2.0. The other packages that depend on @knolo/core stay at ^6.0.0. Publishing that version, and moving the npm latest dist-tag, is a separate step. @knolo/reflex stays 0.2.0. @knolo/evidence-gate stays 0.1.0. Rust, Python, and the ICP canister stay 5.5.1 and do not implement KAR, composition, or Cortex. The bundled contracts, policy, and operations Domain Packs are review-required. The local tag v6.0.0 stays on the 6.0.0 commit. The local tag v6.1.0 stays on the 6.1.0 commit.
Start with the KAR guide, the composition guide, the Cortex guide, the 6.2.0 release notes, examples/kar-v6, examples/kar-coverage, and examples/composition-v1.
The next generation of AI products will compete on the quality and trustworthiness of their knowledge layer. Models may change quickly; durable value accumulates in the evidence, policies, retrieval behavior, runtime state, and operational history surrounding them.
Knolo provides a neutral substrate for that layer:
This is the strategic thesis behind Knolo: a trusted knowledge runtime can become shared infrastructure beneath many AI applications, agents, and enterprise workflows.
| Conventional AI knowledge layer | Knolo |
|---|---|
| Context assembled opaquely at request time | A mounted, inspectable Knowledge Image |
| Retrieval changes with hidden indexes and environment state | Deterministic plans, roots, and receipts |
| Evidence is often discarded after generation | Stable identities and provenance remain queryable |
| Data is coupled to one application or vendor | Portable artifacts with compatibility paths |
| Audit is added after the product ships | Verification and bounded validation are core contracts |
| Runtime state is difficult to reproduce | Immutable segments, commits, snapshots, and diagnostics |
Knolo does not try to be another model provider or another chat application. It is the knowledge and runtime foundation those products can build on.
The repository contains the V6 KAR surface on the V5 Knowledge Image foundation, alongside the unchanged V4 reference path.
V5 defines a minimum verifiable container with:
The result is a bounded byte artifact that can be mounted, inspected, verified, copied, and compared across runtimes. V5 stateRoot identifies the image. KAR's knowledgeRoot is a different digest.
KAR asks for the minimum applicable evidence set required to evaluate a proposition under a declared plan. Support, opposition, qualification, temporal applicability, and authority stay typed by that plan. The evaluation is replayable. It is not a ranked-passage search and it does not replace query().
A Committed Evidence Graph is compiled from editable CEG Source. compileCegSource() is the writer of those bytes. Authoring imports come from @knolo/core/kar/authoring. A coverage report says which supplied evidence requirements are met, which are gaps, and which plans did not decide. The worked demos are examples/kar-v6 and examples/kar-coverage. Public vectors are conformance/kar/v1 and conformance/kar/coverage-v1.
Contracts, policy, and operations Domain Packs can propose CEG Source. Their maturity is review-required in domains/v6-catalog.json. Human review is still required before those proposals are treated as validated semantics. KAR evaluates an already committed graph either way.
Rust and TypeScript share golden vectors for the core byte and root contracts:
knolo:<domain>:v1 SHA-256 digests;Existing V1–V4 artifacts remain readable. A V4 artifact can be verified first and then migrated deterministically into a V5 genesis image. The migration imports sources, chunks, claims, agents, and metadata; maps legacy block identifiers to stable evidence identities; and emits a receipt containing the source digest, destination root, and identity mappings.
The current V5 kernel supports the primitives needed to build trustworthy knowledge products:
Transactions, authority mutation workflows, network orchestration, model inference, and the Studio UI/service remain deliberate follow-on layers.
The boundary is intentional. Knolo owns the artifact, identity, evidence, roots, validation, deterministic planning, and bounded runtime state. Host applications own networking, credentials, model inference, external side effects, and deployment choices.
| Layer | Role | Current path |
|---|---|---|
| Knowledge artifact | Portable sources, chunks, claims, agents, metadata, objects, and events | @knolo/core |
| Verification | Container validation, roots, digests, receipts, and recovery | TypeScript and Rust |
| Retrieval | Lexical V4 retrieval plus bounded V5 query planning and indexes | @knolo/core |
| KAR | Minimum evidence set under a declared plan | @knolo/core/kar |
| CEG authoring | Compile CEG Source into a Committed Evidence Graph | @knolo/core/kar/authoring |
| Domain Packs | Review-required rules, vocabulary, and plan templates | domains/ |
| Agent boundary | Durable runs, evidence-aware context, policy, and authority primitives | @knolo/core |
| Evidence Gate | Claim-level support, conflict, abstention, and offline certificate checks | @knolo/evidence-gate |
| Operations | Health, diagnostics, Studio snapshot, sync, merge, and replay | @knolo/core and @knolo/cli |
| Application integration | LangChain, LlamaIndex, Python, ICP, and starter workspace paths | examples/, packages/ |
| Behavior packs | Deterministic scoped procedures, constraints, context selection, and receipts | @knolo/reflex |
The starter workspace gives an application a V4-compatible retrieval path while leaving room to adopt V5 artifacts incrementally.
The CLI can discover published packs at the production Hub and install one only after verifying its manifest, Blob bytes, digest, size, and local V4/V5 Knowledge Image structure:
Installs are content-addressed and recorded in knolo.lock.json. Use
KNOLO_HUB_URL or --registry when testing a local or partner Hub.
Hub write APIs accept dashboard kno_… tokens with the required
Authorization: Bearer kno_… header. knolo login stores the raw secret
locally; GitHub sign-in is needed only to mint a token at
https://hub.knolo.dev/dashboard/tokens. knolo publish uses that token to ask
Hub for a public Blob PUT grant, uploads bytes to the grant URL (never with
the kno_… token), then completes with the public pack URL. Do not set
PACKS_READ_WRITE_TOKEN in the CLI — that is Hub’s store secret.
The CLI uses pathname sha256/<64-lowercase-hex>.knolo. It rejects private
Blob hosts because Hub verification must fetch the artifact. It never sends
the kno_… token to Blob, in query strings, cookies, or pack bytes. A 401
normally means the Bearer word is missing or the token was revoked—not that
Hub requires a GitHub browser session. To smoke-test the stored credential,
use:
POST /api/v1/tokens is not a CLI login endpoint; it is dashboard/session
token minting only.
The V5 APIs are additive. Existing V4 retrieval APIs and behavior remain the compatibility default for ordinary search.
From a checkout:
knolo kar demo runs the same script. knolo kar conformance checks the public vectors. The KAR quickstart covers the session, the dossier, and verification.
@knolo/reflex is a separate public package for
building and running verifiable behavior packs above @knolo/core. Reflex
packs contain scoped atoms, procedures, constraints, and renderable bundles.
At runtime, Reflex selects bounded context for a request and returns a receipt
with the selected IDs, roots, and token accounting. Model inference remains
under the host application's control.
The package is independently versioned as 0.2.0, compatible with
@knolo/core ^6.0.0, and includes an optional adapter for a local Ollama
server. See the Reflex package guide for the CLI,
verification, evaluation, optimization, distillation, and security details.
The current Reflex 0.2 development line adds frozen teacher provenance, behavior-signature clusters, calibrated MRS selection, offline Pareto frontiers, and a split-aware benchmark harness. These additions remain experimental until the larger frozen evaluation set, conformance review, and release gates are complete.
Knolo’s trust model is expressed in executable contracts rather than marketing language. Run the repository checks locally:
The release check covers TypeScript build and tests, CLI compatibility, Rust tests, conformance fixtures, documentation formatting, and the V5 verification path. Cross-runtime fixtures are maintained under conformance/v5.
Corruption is treated as a normal operating condition to test: truncation, invalid offsets, overlapping or duplicate sections, malformed required sections, invalid generations, oversized declarations, and digest mismatches must fail closed. Unknown optional sections are accepted for forward compatibility.
| Runtime | Role |
|---|---|
| TypeScript | V4 reference implementation and complete V5 foundation APIs |
| Rust | Native V5 byte contracts, verification, migration, and future embedded kernel |
| Python | Read-only V5 verifier/query with preserved V1–V3 pack APIs |
| Internet Computer | Legacy compatibility profile with a synchronized Rust template |
| LangChain / LlamaIndex | Adapter examples for application adoption |
| CLI | Human and automation entry point for artifact inspection and diagnostics |
The architecture is host-neutral: an agent can use Knolo as its knowledge substrate regardless of which model, orchestration framework, deployment target, or UI surrounds it.
Knolo is designed for teams building:
The active roadmap is maintained in docs/ROADMAP.md.
review-required.6.1.0 and run the registry smoke;5.5.1;V5 remains the portable image and verification layer. V6 adds KAR on that layer. Domain Pack extraction is not a validated automatic semantic layer.
Knolo 6.2.0 is the product line in this repository. V5 Knowledge Images remain the evidence container. V4 retrieval remains the compatibility path for ordinary search. KAR semantics stay kar-1-research-1. Composition cites those artifacts and does not change their roots. Cortex retrieves over them and does not change their roots. Domain Packs stay review-required until a person validates them.
Before opening a change, run the relevant package tests and npm run release:check. Changes to byte formats, digest domains, identity rules, or required sections must include updated specification text and cross-runtime fixtures.
See LICENSE.