ZizkaDB
The audit trail database for AI agents
Tamper-evident, checksum-backed decision logs with session replay and time-travel debugging,
built to support EU AI Act Article 12 record-keeping.
Drift detection · MCP server · Python & TypeScript SDKs · Self-host or cloud
Quickstart · Docs · Integrations · Connect · Cloud · Discussions · Contributing
Every agent team eventually asks: Why did it say that? Why did it call that tool? ZizkaDB links every agent step to the step that caused it, so you get the answer in one call instead of scrolling through traces.
- Causal, not just traces. Each event carries a
parent_id. db.why(event_id) walks back to the user message, wrong tool, or bad context that started it.
- Time-travel.
db.at(agent, timestamp) rebuilds exactly what the agent knew at any past moment.
- Tamper-evident audit trail. Every decision is logged with a checksum, so you have a verifiable record for EU AI Act Article 12.
- Drift detection. See when an agent's behavior shifts from its baseline.
- Self-host or cloud. Run it on your own Postgres with one Docker command, or use ZizkaDB Cloud. AGPL-3.0, no per-trace billing; self-hosted data never leaves your infrastructure.
Contents
Quickstart (60 seconds)
From zero to your first causal chain with one command. No repo clone needed.
1. Start Docker. Docker must be running. The first image pull can take 5–10 minutes; later starts take seconds.
2. Install and run. This downloads config and pre-built images, starts Postgres, Qdrant, Redis, the API and the dashboard, then runs a demo agent:
curl -fsSL https://raw.githubusercontent.com/Zizka-ai/ZizkaDB/main/scripts/quickstart-remote.sh | bash
3. See why. The demo prints the causal chain behind the agent's tool call:
tool_call · lookup_order · ORD-8842
└── llm_response · gpt-4o
└── user_message · Why was my order delayed?
4. Open the dashboard. localhost:3001/login → Open my dashboard → Activity → click any event → Why? (causal) tab.
Run the demo again anytime: pip install zizkadb-sdk && zizkadb demo
Self-host from a clone
git clone https://github.com/Zizka-ai/ZizkaDB.git && cd ZizkaDB
bash scripts/setup-local.sh
Full guide: DEVELOPMENT.md · Troubleshooting: wiki/Troubleshooting.md
Integrations
Works with the stack you already use — add one package and every step is logged with its cause.
| Integration | Install | What you get |
|---|
| Python |
pip install zizkadb-sdk |
Any Python agent |
| TypeScript |
npm install zizkadb-sdk |
Any JavaScript / TypeScript agent |
| LangChain |
pip install zizkadb-langchain |
Drop-in callback handler |
| CrewAI |
pip install zizkadb-crewai |
Crew logger for your agents |
| LiveKit |
pip install zizkadb-livekit |
Voice agents — one call, one session |
| MCP |
uvx zizkadb-mcp |
Ask Cursor or Claude why |
| REST API |
Swagger docs |
Any language |
Click a name for its setup guide. New project? Scaffold one with zizkadb init my-agent --template basic.
Connect your agent
import asyncio
from zizkadb import ZizkaDB
async def main():
async with ZizkaDB(host="http://localhost:8000") as db:
user = await db.log(agent="my-bot", event="user_message", data={"text": "Why is my order late?"})
tool = await db.log(agent="my-bot", event="tool_call", data={"tool": "lookup_order"}, parent_id=user.event_id)
(await db.why(tool.event_id)).print()
asyncio.run(main())
TypeScript
import { ZizkaDB } from 'zizkadb-sdk'
const db = new ZizkaDB({ host: 'http://localhost:8000' })
const user = await db.log({ agent: 'my-bot', event: 'user_message', data: { text: 'Why is my order late?' } })
const tool = await db.log({ agent: 'my-bot', event: 'tool_call', data: { tool: 'lookup_order' }, parentId: user.eventId })
;(await db.why(tool.eventId)).print()
From the terminal: zizkadb why <event_id>. Full guide: CONNECT.md
What it does
| Function |
What you get |
db.why(event_id) |
The causal chain behind any event |
db.at(agent, timestamp) |
What the agent knew at a past moment |
db.search(query) |
Semantic search over the agent's history |
db.context_for(agent, task) |
Relevant past events, ready to inject into the next prompt |
db.baseline(agent) |
Drift detection: alerts when agent behavior shifts from past sessions |
db.forget(key, value) |
GDPR erasure by metadata filter, including the search index |
Audit trail and EU AI Act Article 12
Article 12 of the EU AI Act requires high-risk AI systems to automatically keep logs of what they did. ZizkaDB gives you that record:
- Checksum-backed decision logs. Every event is stored with a SHA-256 checksum of its content, so any later edit is detectable.
- Causally linked history. Each decision points to the event that caused it, so an auditor can follow the full chain.
- Session replay. Step through any past session event by event.
- Time-travel debugging. Rebuild exactly what the agent knew at any moment with
db.at().
- Drift detection.
db.baseline() flags when an agent starts behaving differently from its history.
ZizkaDB supports your record-keeping obligations; it doesn't make a system compliant on its own.
How it works
flowchart LR
A[Your agent<br/>SDK · LangChain · CrewAI · LiveKit] -->|events + parent_id| B[ZizkaDB API]
D[Dashboard] --> B
M[MCP server<br/>Cursor · Claude] --> B
B --> P[(PostgreSQL<br/>source of truth)]
B --> Q[(Qdrant<br/>semantic search)]
B --> R[(Redis<br/>cache)]
- Causal lineage lives in Postgres: every event stores its parent, and
why() walks the chain with a recursive query. No separate graph store.
- Every event is written twice: to Postgres for structured queries and to Qdrant for semantic search. Design decisions: docs/adr/.
Use with your AI assistant (MCP)
Ask Cursor or Claude "why did support-bot call lookup_order?" and get the chain back. Add this to your MCP config:
{
"mcpServers": {
"zizkadb": {
"command": "uvx",
"args": ["zizkadb-mcp"],
"env": { "ZIZKADB_HOST": "http://localhost:8000" }
}
}
}
For ZizkaDB Cloud, use ZIZKADB_API_KEY instead. Setup for each client: mcp/README.md. The MCP server is MIT-licensed.
Tools like Langfuse and LangSmith observe span trees. ZizkaDB audits decisions.
|
ZizkaDB |
Typical LLM tracing tools |
| Explicit cause → effect links |
✅ |
Span nesting |
One-call root cause (db.why()) |
✅ |
Manual trace reading |
| Time-travel to past agent state |
✅ |
— |
Memory for future runs (db.context_for()) |
✅ |
— |
| Pricing |
Free self-host (AGPL) |
Often per-trace |
Managed cloud (Pro / Team)
The same features, hosted at db.zizka.ai. No Docker to maintain.
|
Pro |
Team |
| Price |
€29 / mo |
€69 / mo |
| Events / mo† |
50k |
100k |
| API keys |
2 |
5 |
Sign up →
† Plan targets on managed cloud; not enforced in API yet. See docs/README.md.
FAQ
Do I need to clone this repo?
No. The curl quickstart downloads config and Docker images only.
Do I need an API key locally?
No. http://localhost:8000 uses a built-in dev key.
zizkadb demo says connection refused?
The stack isn't running. Start it with the curl command above or bash scripts/setup-local.sh.
Docs & community
Contributors
Thanks to everyone who has helped build ZizkaDB. Want to join? Read CONTRIBUTING.md or pick up an open issue.
AGPL-3.0 · MCP server MIT · Disable telemetry: export ZIZKADB_TELEMETRY=false
This repo is the open-source self-host stack. The operator console and VPC deploy live in a private repo (why).
ZizkaDB 是一个为 AI 智能体构建的审计追踪数据库。它记录智能体的每个决策，附有 SHA-256 校验和以及指向成因的因果链接，因此你可以回放会话并“时间旅行”到过去任一时刻，查看智能体当时确切知道什么，支持欧盟 AI 法案第 12 条的记录保存要求。