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. Self-hosted runs one agent with one API key; multiple agents, agent fleets and agent-to-agent messaging are on Cloud.

Contents

• Quickstart (60 seconds)
• Integrations
• Connect your agent
• What it does
• Audit trail and EU AI Act Article 12
• How it works
• Use with your AI assistant (MCP)
• ZizkaDB vs. tracing tools
• Cloud, FAQ and docs
• Contributors

---

Quickstart (60 seconds)

One command, one container. No repo clone, no Python, no config files.

1. Run it. With Docker running:

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

This pulls a single image (Postgres, the API and the dashboard together), starts it, and logs a demo agent run. After the download, startup takes a few seconds.

2. See why. It prints the causal chain behind the demo agent's tool call:

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

3. Explore. The dashboard opens on that agent, already signed in: localhost:3001/dashboard/activity?agent=support-bot. Click any event → Why? (causal) tab.

Now log your own agent: pip install zizkadb-sdk, then see CONNECT.md. The local API is http://localhost:8000 with key zizkadb_dev_local.

Prefer plain docker run? Day-two commands

The script is a wrapper around this:

docker run -d --name zizkadb -p 127.0.0.1:8000:8000 -p 127.0.0.1:3001:3001 \
  -v zizkadb_data:/data ghcr.io/zizka-ai-sl/zizkadb

Do this	Command
Stop / start	docker stop zizkadb / docker start zizkadb
Logs	docker logs -f zizkadb
Upgrade (keeps data)	re-run the quickstart command
Erase everything	docker rm -f zizkadb && docker volume rm zizkadb_data
Dashboard port busy	ZIZKADB_DASHBOARD_PORT=3005 before the quickstart command

The single container is for your own machine: it keeps the ports on 127.0.0.1, signs you in with one click and accepts a well-known API key. It runs without Qdrant, so semantic search and embeddings need the full stack below. For a server other people can reach, use Self-host on a server.

The self-hosted dashboard is just your dashboard: no signup, no email, no account. Accounts and plans exist only on ZizkaDB Cloud.

Self-hosted is single-agent: the first agent name you log with becomes your agent, and a second name is rejected with a message naming it. The support-bot demo agent does not count. For several agents, use ZizkaDB Cloud.

Self-host from a clone

The full stack (Postgres, Qdrant, Redis, API, dashboard as separate containers) — use this for development, semantic search, or production:

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

Service	URL
API	http://localhost:8000
Dashboard	http://localhost:3001
Swagger	http://localhost:8000/swagger

Self-host on a server

On a machine other people can reach, set these in infra/.env before starting the stack:

ENV=production                      # turns off the one-click button and dev API keys
DEV_API_KEY=<random>                # must not be the default, or the API refuses to start
JWT_SECRET=<random>                 # openssl rand -hex 32 (also JWT_REFRESH_SECRET)
DEPLOYMENT_MODE=self_hosted
SELFHOST_ADMIN_TOKEN=<long-random>  # python -c "import secrets; print(secrets.token_urlsafe(32))"

The dashboard then asks for the admin token instead of showing the one-click button. Without SELFHOST_ADMIN_TOKEN, dashboard login stays disabled. Everyone who has the token signs in to the same single owner workspace. Check your config with bash scripts/validate-selfhost-config.sh --production. Full steps: wiki/Self-Hosting.

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)]

Loading

• 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.

---

ZizkaDB vs. tracing tools

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

Worked example	worked/01-support-order-delay
Examples	examples/
Self-hosting	DEVELOPMENT.md · wiki/Self-Hosting
Integrate any agent	docs/integrate/
Issues · Discussions	Issues · Discussions
Security	SECURITY.md
AI-assisted development	AGENTS.md

---

Contributors

Thanks to everyone who has helped build ZizkaDB. Want to join? Read CONTRIBUTING.md or pick up an open issue.

saadamjad	Zizka-ai	arshadgit23	saadwashmen
Subhajitdas99	mikeaig4real	aqilaziz	lamenting-hawthorn
abdurrehman616	HafizHamzaShahid	eaz1337	mbilalzeeshan
AbdelazizBs	Mephistopheles9631	Qalbeabbas-12	towfiq-ul

---

_{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).}