@knowl/ai-sdk

Project memory for AI SDK agents.

Every other memory integration for the AI SDK is a hosted service behind an API key. This one is not. Knowl is a local-first engine that stores typed knowledge atoms in SQLite under your project, speaks MCP, and retires superseded facts at write time so a stale decision stops being a retrieval candidate instead of competing with its replacement.

No account, no key, nothing leaves the machine.

Install

pnpm add @knowl/ai-sdk ai

The Knowl server itself is fetched on demand through npx, so there is nothing else to install.

Setup

Knowl scopes memory to a project, so initialize one first:

npx -y @dat999zx/knowl init

That creates .knowl/ in the directory. Agents pointed at that directory read and write its memory; agents pointed elsewhere see nothing from it.

Usage

import { knowlTools } from '@knowl/ai-sdk';
import { ToolLoopAgent } from 'ai';

const memory = await knowlTools({ projectRoot: '/srv/app' });

try {
  const agent = new ToolLoopAgent({
    model: 'anthropic/claude-haiku-4.5',
    tools: memory.tools,
  });

  const result = await agent.generate({
    prompt: 'What did we decide about retry backoff, and why?',
  });
} finally {
  await memory.close();
}

memory.tools is the full Knowl tool surface, 27 tools covering query, store, decisions, conflicts, timeline and session handoff. Spread it into tools and the model uses what it needs.

Options

| Option | Default | Notes | | --- | --- | --- | | projectRoot | process.cwd() | The directory whose memory this agent uses. Pass it explicitly in a request handler; the default is right for a single-project server and wrong for a multi-tenant one. | | command / args | npx -y @dat999zx/knowl serve | Point at a global install or a local build to skip npx resolution on cold start. | | env | inherited | Extra environment for the server process. |

Closing

knowlTools spawns the Knowl server as a child process. Create it once at module scope for a single-project server:

const memory = await knowlTools({ projectRoot: process.cwd() });

If you create one per request instead, always await memory.close(), or you leak a process per request.

Windows

Handled. npx on Windows is npx.cmd, and since the fix for CVE-2024-27980 Node will not spawn .cmd files unless shell: true — which the AI SDK's stdio transport hardcodes to false with no way to override. Wiring createMCPClient to npx directly therefore fails with EINVAL on Windows. This package routes through cmd.exe /c so it works the same everywhere.

Relationship to createMCPClient

This is a thin, typed wrapper over the AI SDK's own MCP client. If you would rather wire it yourself, you can: point Experimental_StdioMCPTransport at @dat999zx/knowl serve and call .tools(). What this package adds is the project scoping, the Windows launcher fix, and lifecycle handling you would otherwise write yourself.

License

Apache-2.0