Knolo for the Vercel AI SDK: Read-Only Knowledge Image Tools
Knolo's @knolo/ai-sdk 0.1.0 turns pinned Knowledge Images into read-only Vercel AI SDK tools for search, get, verify and status, with a receipt on every search.
Knolo is the open-source, local-first Knowledge Image runtime and format from Hive AI: you pack documents once, pin the image by digest, and retrieve evidence locally. The runtime is @knolo/core on npm (6.2.1 is npm latest), released under Apache-2.0. As of 9 November 2026 npm also lists @knolo/ai-sdk 0.1.0, a small adapter that hands Knolo's read-only tools to an app built on the Vercel AI SDK.
This post covers what that adapter does, what it needs, and where it stops.
What Knolo's AI SDK adapter gives you
@knolo/ai-sdk exports knoloTools(config). It returns Vercel AI SDK tools for the same read-only calls that the Knolo MCP server exposes:
knolo_searchsearches a pinned, mounted Knowledge Image.knolo_getreads an object from it.knolo_verifychecks the image against its pins.knolo_statusreports what is mounted.
import { knoloTools } from '@knolo/ai-sdk';
const tools = await knoloTools(config);
config is the same object you would put in knolo-mcp.json, with absolute paths. Your app passes tools to its own model call. Knolo does not call a model: the host owns the model, the credentials and the network, and Knolo owns the artifact, the pins and the receipts. The example smoke test in the repository searches a fixture and prints modelCalled: false.
What Knolo checks before any tool exists
The adapter fails before it returns tools, not halfway through a chat. A bad image pin or policy root throws. A relative config path throws QUERY_INVALID: Knolo config path must be absolute. Invalid JSON throws IMAGE_INVALID. Every thrown message has the form CODE: text, and the fixture tests check that it matches the text the MCP tool returns for the same input and image.
Caller identity is agentId in the config, with a default of mcp. A tool argument cannot set it, so a model cannot claim to be a different caller. A policy denial throws ACCESS_DENIED.
Knolo receipts come with every search
Pins, policy and receipts come from @knolo/tools. Each knolo_search writes an openclaw-knolo-query-v1 receipt before hits come back, with an id that starts with qr_. If the audit directory can't be written, the call throws AUDIT_UNAVAILABLE and returns no hits. A receipt is an integrity check of what was mounted and returned; it does not mean an answer is true. The query receipts docs explain replay.
Search in this adapter matches every space-separated term as a substring of the normalized text.
Requirements for Knolo with the AI SDK
- The peer dependency is
ai^7.0.0. - Node.js 22 or newer, matching that package. Knolo does not run these tools on the edge runtime.
- Dependencies are
@knolo/core^6.2.0and@knolo/tools^0.2.0. - The license is Apache-2.0.
The function does not watch files. After you change a pin, call knoloTools again. If you'd rather keep a separate process that reloads changed config, use the stdio MCP server instead:
npx -y @knolo/mcp --config /absolute/knolo-mcp.json
That server is @knolo/mcp 0.2.1 on npm today. The adapter does not start it and does not open a port.
Where to go next with Knolo
- Knolo docs on knolo.dev, including installation and versions.
- Knolo in agent frameworks, the earlier post on the OpenAI Agents SDK, Pydantic AI, Langflow and Dify.
- The Knolo source on GitHub, where the adapter landed in pull request #135 with its example and integration note.
- Knolo open technology on knolo.org, for the specifications and compatibility side.