<div align="center">

ZizkaDB

The operational database for AI agents.

Try it live · Documentation · Wiki · Architecture · Contributing · Development

</div>

When an agent misbehaves in production, you need more than scattered traces and a vector index. ZizkaDB is one store for causal lineage (why()), time-travel state (at()), semantic search, and fleet dashboards — open source, self-hostable, and model-agnostic.

Log every decision with parent_id, walk backward to the root cause in one call, and ship the same SDK to managed cloud or your own Docker stack.

<p align="center"> <a href="https://db.zizka.ai"> <img src="docs/assets/hero-dashboard.png" alt="ZizkaDB dashboard — fleet of agents" width="100%"/> </a> </p>

<p align="center"> <a href="https://db.zizka.ai"><img src="docs/assets/gallery-homepage.png" alt="Homepage" width="23%"/></a> <a href="https://db.zizka.ai/dashboard"><img src="docs/assets/gallery-dashboard.png" alt="Agent fleet" width="23%"/></a> <img src="docs/assets/gallery-why.png" alt="Causal chain from db.why()" width="23%"/> <a href="mcp/README.md"><img src="docs/assets/gallery-mcp.png" alt="MCP in Cursor" width="23%"/></a> </p>

Online viewer

[db.zizka.ai](https://db.zizka.ai) — managed cloud with signup, API keys (zizkadb_live_...), live dashboard (auto-refreshes every 30s), and billing. No credit card for the free tier.

<p align="center"> <img src="docs/assets/hero-live.png" alt="ZizkaDB at db.zizka.ai" width="100%"/> </p>

why() — causal chain in the terminal

Self-host locally, then run the demo script. The SDK prints a tree from any event_id back to the root.

<p align="center"> <img src="docs/assets/why-demo.gif" alt="db.why() printing a causal chain" width="100%"/> </p>

bash scripts/setup-local.sh
pip install zizkadb-sdk
python scripts/demo-why.py

Start a new agent project

pip install zizkadb-sdk
zizkadb init my-agent --template basic      # log + why()
zizkadb init my-agent --template langchain  # LangChain callbacks
zizkadb init my-agent --template crewai     # CrewAI logger
zizkadb init my-agent --template openai     # AsyncOpenAI + parent_id
zizkadb init my-agent --template mcp-cursor # Cursor MCP config

Framework adapters: integrations/ · runnable examples/

Development

Want to contribute? Read CONTRIBUTING.md — setup, PR expectations, and database/schema guidelines. CODE_OF_CONDUCT.md · SECURITY.md

Prerequisites

• Docker + Docker Compose v2
• Python 3.10+ (for the demo script and SDK)
• Optional: Node 18+ if you hack on dashboard/

Installation (self-host, ~30 seconds)

git clone https://github.com/Zizka-ai/ZizkaDB.git && cd ZizkaDB
bash scripts/setup-local.sh

Or with Compose only:

cp .env.example infra/.env
docker compose -f infra/docker-compose.yml -f infra/docker-compose.dashboard.yml up -d

Run the demo

pip install zizkadb-sdk
python scripts/demo-why.py

Localhost uses an auto-injected dev key — no API key required.

Managed cloud (same SDK)

pip install zizkadb-sdk

import asyncio
from zizkadb import ZizkaDB

async def main():
    async with ZizkaDB("zizkadb_live_...") as db:  # https://db.zizka.ai/signup
        user = await db.log(agent="my-bot", event="user_message", data={"text": "..."})
        tool = await db.log(
            agent="my-bot", event="tool_call", data={"tool": "search"},
            parent_id=user.event_id,
        )
        (await db.why(tool.event_id)).print()

asyncio.run(main())

PyPI: zizkadb-sdk · import: from zizkadb import ZizkaDB · pass `event_id` to why(), not the agent name.

Production on a VPS

bash infra/deploy-production.sh   # backs up Postgres first — never uses -v

Or API-only self-host:

docker compose -f infra/docker-compose.yml up -d
bash infra/deploy-selfhost.sh

Never run docker compose down -v on a server with real users — it wipes all accounts. Local dev reset only: bash scripts/reset-local-db.sh.

Configure EMAIL_* in infra/.env for team OTP login. On managed cloud set ENV=production and leave DEV_API_KEY unset. Full guide: db.zizka.ai/docs · Production Deployment wiki.

Refresh README assets

python scripts/generate-readme-assets.py

Re-record a cinematic terminal GIF: docs/assets/RECORD_DEMO.md.

Opt out of anonymous telemetry: export ZIZKADB_TELEMETRY=false

What is ZizkaDB?

Not a vector DB alone. Not traces alone. Operational data for agents in production.

Integrate

Self-host: ZizkaDB(host="http://localhost:8000") or ZIZKADB_HOST for MCP.

License

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