ZizkaDB

The operational database for AI agents.

Try it live · Documentation · Wiki · Architecture · Development

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.

---

Online viewer

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.

---

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.

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

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

Service	URL
API	http://localhost:8000/health
Swagger	http://localhost:8000/swagger
Dashboard	http://localhost:3001/login → Open my dashboard →

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

docker compose -f infra/docker-compose.yml up -d
bash infra/deploy-selfhost.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.

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?

Problem	Primitive
Why did the agent do that?	parent_id → why(event_id)
What did it know at 2pm Tuesday?	at(agent, timestamp)
Find similar past failures	search() / context_for()
Is this agent drifting?	Baselines + fleet views

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

---

Integrate

Path	Getting started
Scaffold	zizkadb init my-agent -t langchain
Python	pip install zizkadb-sdk
LangChain	pip install zizkadb-langchain — integrations/langchain
CrewAI	pip install zizkadb-crewai — integrations/crewai
TypeScript	npm install zizkadb-sdk — sdk/typescript
MCP	uvx zizkadb-mcp — mcp/README.md
REST	OpenAPI at /swagger

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

---

License

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