II.

Architecture

Kernl

The runtime itself. Registers agents, manages thread execution, connects to storage. One instance per application.


import { Kernl } from "kernl";
import { postgres } from "@kernl-sdk/pg";
import { turbopuffer } from "@kernl-sdk/turbopuffer";
 
const kernl = new Kernl({
  storage: {
    db: postgres({ connstr: process.env.DATABASE_URL }),
    vector: turbopuffer({ apiKey: process.env.TURBOPUFFER_API_KEY }),
  },
});
 
kernl.register(agent);

Agent

Holds instructions, tools, and memory settings — but no conversation state. Agents are stateless; threads hold state.


import { Agent } from "kernl";
import { anthropic } from "@kernl-sdk/ai/anthropic";
 
const agent = new Agent({
  id: "jarvis",
  name: "Jarvis",
  model: anthropic("claude-sonnet-4-20250514"),
  instructions: "You are a helpful assistant.",
  memory: { enabled: true },
  toolkits: [math],
});

An agent can have many threads. Each thread is an independent execution.

See Agents for more.

Thread

A single execution of an agent. Contains state, message history + other events (e.g. tool calls + results …). Can be persisted and resumed.


// start a new thread
await agent.run("Hello");
 
// resume an existing thread
await agent.run("Continue where we left off", { threadId: "thread_abc123" });

Threads are the unit of execution. When you call agent.run(), you’re either spawning a new thread or resuming an existing one.

See Threads for more.

Toolkits

Tools give agents the ability to act. Toolkits group related tools together.

Toolkit — Define tools as TypeScript functions.


import { tool, Toolkit } from "kernl";
import { z } from "zod";
 
const add = tool({
  id: "add",
  description: "Add two numbers",
  parameters: z.object({ a: z.number(), b: z.number() }),
  execute: async (ctx, { a, b }) => a + b,
});
 
const math = new Toolkit([add]);

MCPToolkit — Connect to any MCP server. Use tools from the ecosystem without writing integration code.


import { MCPToolkit, MCPServerStreamableHttp } from "kernl";
 
const github = new MCPToolkit({
  id: "github",
  server: new MCPServerStreamableHttp({
    url: "https://api.githubcopilot.com/mcp/",
    requestInit: {
      headers: { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` },
    },
  }),
});

Memory

Knowledge that persists beyond individual threads. Agents can create, search, and update memories. Scoped by agent, optionally by namespace or entity.


// create a memory
await jarvis.memories.create({
  collection: "preferences",
  content: { text: "User prefers dark mode." },
});
 
// search memories
const mems = await jarvis.memories.search({
  query: "user preferences",
  limit: 5,
});

See Memory for more.

Storage

kernl separates storage into two layers:

db — Primary store. Source of truth for threads and memories. (postgres, etc.)
vector — Search index. Projection of memory for semantic retrieval. (turbopuffer, etc.)

Only db is strictly required. The vector store enables semantic search over memories.