ZizkaDB

Know why your agent did what it did.

Get started · SDKs · Wiki · Managed cloud

ZizkaDB is a database built specifically for AI agents. It gives you:

• Causal lineage — trace every decision your agent made and understand exactly why it happened (db.why())
• Time-travel state — go back to any moment and see exactly what your agent knew (db.at())
• Memory injection — give your agent relevant past context in a single call (db.context_for())
• Semantic search — search your agent's entire history in plain English (db.search())

No more guessing. No more digging through logs.

This repository is the open-source product runtime (API, self-host dashboard, SDKs, MCP, examples).
Managed cloud marketing pages and the operator admin panel live in a private repo (zizkadb-cloud) and are not part of a public clone.
All product links on GitHub point here: https://github.com/Zizka-ai/ZizkaDB

Who uses ZizkaDB?

Get started

Choose how you want to run ZizkaDB:

Run locally (no sign-up needed):

curl -fsSL https://raw.githubusercontent.com/Zizka-ai/ZizkaDB/main/scripts/quickstart-remote.sh | bash

Downloads ~4 config files and pulls pre-built Docker images. No code is cloned. Once running: open http://localhost:3001/login → click Open my dashboard.

Already have the repo cloned?

bash scripts/quickstart.sh

No Docker? → Self-hosting guide

SDKs

Pick your language and install:

Python

pip install zizkadb-sdk

Minimal working example (Python):

import asyncio
from zizkadb import ZizkaDB

async def main():
    # Use api_key for Zizka Cloud, or host for local
    async with ZizkaDB(api_key="zizkadb_live_...") as db:
    # async with ZizkaDB(host="http://localhost:8000") as db:   ← local

        # Log three linked events
        user = await db.log(agent="my-bot", event="user_message", data={"text": "Why is my order delayed?"})
        llm  = await db.log(agent="my-bot", event="llm_response", data={"model": "gpt-4o"},      parent_id=user.event_id)
        tool = await db.log(agent="my-bot", event="tool_call",    data={"tool": "lookup_order"}, parent_id=llm.event_id)

        # Ask why the tool was called — walks the causal chain backward
        chain = await db.why(tool.event_id)
        chain.print()

asyncio.run(main())

Expected output:

tool_call · lookup_order
  └── llm_response · gpt-4o
        └── user_message · Why was my order delayed?

parent_id links one event to the previous one — this is how ZizkaDB builds causal lineage. session_id groups events into a single run (useful for db.baseline() and db.memory_diff()).

→ Full Python guide · zizkadb init my-agent --template basic

TypeScript / JavaScript

npm install zizkadb-sdk

Minimal working example (TypeScript / JavaScript):

import { ZizkaDB } from 'zizkadb-sdk'

const db = new ZizkaDB({ apiKey: 'zizkadb_live_...' })
// const db = new ZizkaDB({ host: 'http://localhost:8000' })   ← local

const user = await db.log({ agent: 'my-bot', event: 'user_message', data: { text: 'Hello' } })
const tool = await db.log({ agent: 'my-bot', event: 'tool_call', data: { tool: 'search' }, parentId: user.eventId })

const chain = await db.why(tool.eventId)
console.log(chain)

TypeScript uses camelCase: parentId, eventId. LangChain and CrewAI adapters are Python-only.

→ Full TypeScript guide

LangChain

pip install zizkadb-sdk zizkadb-langchain

Minimal working example (LangChain):

from zizkadb import ZizkaDB
from zizkadb_langchain import ZizkaDBCallbackHandler

async with ZizkaDB(api_key="zizkadb_live_...") as db:
    handler = ZizkaDBCallbackHandler(db, agent="my-bot")

    # Pass the handler to any LangChain chain — events are logged automatically
    result = await chain.ainvoke({"input": "..."}, config={"callbacks": [handler]})

    # Trace why the agent made its final decision
    await db.why(handler.last_event_id).print()

→ Full LangChain guide · zizkadb init my-agent --template langchain

CrewAI

pip install zizkadb-sdk zizkadb-crewai

Minimal working example (CrewAI):

from zizkadb import ZizkaDB
from zizkadb_crewai import ZizkaDBCrewLogger

async with ZizkaDB(api_key="zizkadb_live_...") as db:
    logger = ZizkaDBCrewLogger(db, agent="research-crew")

    kickoff = await logger.log_kickoff(goal="Research AI trends")
    result = crew.kickoff()
    await logger.log_output(str(result), parent_id=kickoff.event_id)

→ Full CrewAI guide · zizkadb init my-agent --template crewai

AI Editor (Cursor, Claude Desktop, Windsurf)

uvx zizkadb-mcp

Minimal working example (MCP config):

{
  "mcpServers": {
    "zizkadb": {
      "command": "uvx",
      "args": ["zizkadb-mcp"],
      "env": {
        "ZIZKADB_API_KEY": "zizkadb_live_...",
        "ZIZKADB_HOST": "http://localhost:8000"
      }
    }
  }
}

Add this to ~/.cursor/mcp.json (or your editor's MCP config file). Your AI editor can now call ZizkaDB tools directly from chat.

→ Full MCP guide · zizkadb init my-agent --template mcp-cursor

REST — any language

Minimal working example (REST):

curl -X POST http://localhost:8000/v1/events \
  -H "Authorization: Bearer zizkadb_dev_local" \
  -H "Content-Type: application/json" \
  -d '{"agent":"my-bot","event":"user_message","data":{"text":"Hello"}}'

Expected response:

{ "event_id": "b3a1c...", "timestamp": "2026-07-15T10:00:00Z", "sequence_no": 1 }

→ Swagger / API explorer · Docs

What you can do

db.log(), db.why(), and db.at() work without an OpenAI key. db.search() and db.context_for() require OPENAI_API_KEY for embeddings.

Common workflows

Environment variables

Local dev tip: When connecting to localhost:8000, no API key is needed — the local stack uses a built-in dev key automatically.

More resources

License

• API, dashboard, and SDKs: AGPL-3.0
• MCP server: MIT

To turn off anonymous telemetry: export ZIZKADB_TELEMETRY=false