Structure-First Code Retrieval with @knolo/code

Coding agents spend a lot of their context window reading files they only needed a few lines from. A whole module gets pasted in so the model can find one function signature. The answer might be right, but nobody can say afterwards exactly which code the agent was looking at.

@knolo/code takes a different route. It builds a local Knolo pack from your source tree, lets a tool look at structure first, and returns only the chunks that match, each one tied to a digest you can check. This post walks through what the package does, what the published check showed and where its limits are.

What @knolo/code builds

@knolo/code builds a local V4 .knolo pack from TypeScript, JavaScript and Python files. It is open source under Apache-2.0, and the current npm release is 0.1.1. The full reference lives on the code image docs page.

For each file the pack stores:

• function, class, method and export chunks
• a signature skeleton, which is the outline of the file without the bodies

Because it is a normal V4 pack, everything you know from the V4 quickstart still applies. It mounts locally, retrieval is deterministic and lexical-first, and nothing is sent to a remote index.

Structure first, then the exact chunk

The idea is to let an agent narrow down before it reads. It can ask for the structure of the code, pick the symbol it cares about, then query or expand just that piece.

The published MCP server exposes five tools for this:

• code_image_status
• code_image_build
• code_image_structure
• code_image_query
• code_image_expand

Any host that speaks MCP can call them. The MCP server docs cover how Knolo tools plug into a host. For Grok Build there is also a ready-made plugin in the repository:

grok plugin install HiveForensics-AI/knolo-core#plugins/knolo-code --trust

Every answer carries a receipt

This is the part that makes it Knolo rather than another code search tool. Results come back with receipts:

• Query receipts are checked with verifyReceipt from @knolo/core. The query receipts docs explain the format.
• Structure and expand receipts carry the packDigest and the source digest of the block they came from.

If the pack on disk doesn't match the pin, the tools return an error and no chunk text. You get a failure instead of quietly getting code from a different build. That fail-closed behavior is the same principle described in roots and receipts for Knowledge Images.

What the published check showed

The repository records a check of the published @knolo/code@0.1.0 tarball, run on 2 November 2026 in a clean directory against the sample project in packages/code/examples/sample. Note that this check is for 0.1.0, and the docs don't repeat it as a result for 0.1.1. Here's what it recorded:

• Two builds produced the same pack bytes and the same packDigest.
• The signature skeleton of routes.ts came to 31 tokens, 11.3% of the file's 275 tokens. Tokens here are a simple size unit, UTF-8 bytes divided by four, not a model tokenizer.
• A structure call plus a code_image_query for addRouteHandler returned 1,166 bytes, against 8,612 bytes for the four source files. That is 86.5% smaller.
• The query receipt was receipt-v1 and it verified.
• Flipping one byte of the pack made the command exit with CODE_PIN_MISMATCH and return no chunk text.

Those numbers come from one small sample project, so treat them as a sanity check of the mechanics, not a benchmark for your codebase.

What it doesn't claim

The docs are direct about the limits, and they're worth repeating:

• The host owns the model. @knolo/code doesn't embed your workspace or call a model.
• A retrieval result is evidence of what the code says. It is not a claim that an edit based on it is correct.
• It is a V4 pack. It is not a V5 Knowledge Image.

Try it

Install the package from npm, build a pack over a small repository and call the structure tool before the query tool. If you're new to Knolo, start with installation and then read the code image page. The source, the plugin and the published check all live in the public knolo-core repository.