TypeScript SDK

Integrate ZizkaDB in Node.js, Bun, Deno, or edge runtimes. Core HTTP client matches Python for log, why, search, and related APIs. LangChain and CrewAI adapters are Python-only — use MCP or REST from Node for those stacks.

Prerequisites

Node.js 18+ (or Bun / Deno). TypeScript optional but recommended.

bashnode --version # v18+

Choose your environment

Managed cloud: Sign up → Settings → Create API key.

Self-host: new ZizkaDB({ host: 'http://localhost:8000' }) — see Self-host docs for dashboard setup.

Install

bashnpm install zizkadb-sdk # or: pnpm add zizkadb-sdk / yarn add zizkadb-sdk / bun add zizkadb-sdk

Initialize the client

typescriptimport { ZizkaDB } from 'zizkadb-sdk'

// Managed cloud
const db = new ZizkaDB({ apiKey: 'zizkadb_live_xxxx' })

// Self-hosted
// const db = new ZizkaDB({ host: 'http://localhost:8000' })

Log your first event

typescriptconst result = await db.log({
  agent: 'support-bot',
  event: 'tool_call',
  data: { tool: 'search', query: 'pricing' },
  sessionId: 'sess_abc123',
})
console.log(result.eventId)

Link events causally

typescriptconst msg = await db.log({
  agent: 'support-bot',
  event: 'user_message',
  data: { text: 'why is my bill $200?' },
  sessionId: 'sess_abc123',
})

const tool = await db.log({
  agent: 'support-bot',
  event: 'tool_call',
  data: { tool: 'get_billing' },
  parentId: msg.eventId,
  sessionId: 'sess_abc123',
})

const chain = await db.why(tool.eventId)
chain.print()

Search, replay, context, baseline

typescript// Search: keyword out of the box, hybrid with embeddings
const hits = await db.search({
  query: 'billing complaint',
  agent: 'support-bot',
  limit: 5,
})

// Safe retries, batches, and proof the history is untouched
await db.log({ agent: 'support-bot', event: 'tool_call', data: { tool: 'refund' }, idempotencyKey: 'req-42' })
await db.logBatch([{ agent: 'support-bot', event: 'user_message', data: { text: 'hi' } }])
const check = await db.verifyChain('support-bot')

// Logged state at timestamp (ISO string)
const state = await db.at({
  agent: 'support-bot',
  timestamp: '2026-05-01T15:00:00Z',
})

// Memory for system prompt
const context = await db.contextFor({
  agent: 'support-bot',
  task: 'user asking about refund',
  maxTokens: 2000,
})

// Behavioral drift
const baseline = await db.baseline({ agent: 'support-bot', recentWindow: 50 })

Framework example: Express + OpenAI

typescriptimport express from 'express'
import OpenAI from 'openai'
import { ZizkaDB } from 'zizkadb-sdk'

const app = express()
app.use(express.json())
const db = new ZizkaDB({ apiKey: process.env.ZIZKADB_API_KEY! })
const openai = new OpenAI()

app.post('/chat', async (req, res) => {
  const { message, sessionId } = req.body
  const msg = await db.log({
    agent: 'api-bot', event: 'user_message',
    data: { text: message }, sessionId,
  })
  const completion = await openai.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: message }],
  })
  const text = completion.choices[0]?.message?.content ?? ''
  await db.log({
    agent: 'api-bot', event: 'assistant_response',
    data: { text }, parentId: msg.eventId, sessionId,
  })
  res.json({ reply: text })
})

app.listen(3000)

Anonymous SDK telemetry: one ping per process on client construct (or MCP server startup). Opt out: ZIZKADB_TELEMETRY=false

All TypeScript methods

db.log()Log any event. parent_id links cause → effect; idempotency_key makes retries safe; supersedes retires an outdated fact.

db.logbatch(events)Up to 500 events in one request, with per-event results.

db.why(eventid)Walk the causal chain from an event to its root.

db.search(query)Search agent history in plain English: keyword out of the box, hybrid keyword + vector with embeddings.

db.verifychain(agent)Prove no event was edited, removed or reordered (per-agent hash chain).

db.at(agent, timestamp)Reconstruct logged state at a past timestamp.

db.query(agent)List recent events, optionally filtered by event type.

db.contextfor(agent, task)Memory block formatted for system prompt injection.

db.baseline(agent)Behavioral baseline and drift score vs historical sessions.

db.memorydiff(session_id)Summary of what happened in one session.

db.forget(key, value)GDPR erasure by metadata filter; leaves a content-free tombstone in the audit chain.

db.exportevents(agent)Stream every event as NDJSON; import_events() loads it into another workspace.

db.iterevents(agent)Every event, newest first, cursor-paged.

db.agents()List all agents for your tenant.