ZizkaDB README

The project's README from github.com/ZIZKA-AI-SL/ZizkaDB. As one markdown file: README.md.

ZizkaDB — visit db.zizka.ai

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

CI License: AGPL-3.0 Release Python SDK TypeScript SDK GitHub stars

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.

Animated: db.why() walks from a tool_call back through llm_response to the root-cause user_message

Contents

Quickstart (60 seconds)

From zero to your first causal chain with one command. No repo clone needed.

Terminal animation: one curl command downloads config, pulls images, starts the stack, installs the SDK and prints a causal chain

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
Service URL
API http://localhost:8000
Dashboard http://localhost:3001/login
Swagger http://localhost:8000/swagger

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.

Python    TypeScript    LangChain    CrewAI    LiveKit    MCP    REST API

IntegrationInstallWhat 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:

ZizkaDB supports your record-keeping obligations; it doesn't make a system compliant on its own.

ZizkaDB dashboard showing agent activity

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

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
saadamjad		 Zizka-ai
Zizka-ai		 arshadgit23
arshadgit23		 saadwashmen
saadwashmen
Subhajitdas99
Subhajitdas99		 mikeaig4real
mikeaig4real		 aqilaziz
aqilaziz		 lamenting-hawthorn
lamenting-hawthorn
abdurrehman616
abdurrehman616		 HafizHamzaShahid
HafizHamzaShahid		 eaz1337
eaz1337		 mbilalzeeshan
mbilalzeeshan
AbdelazizBs
AbdelazizBs		 Mephistopheles9631
Mephistopheles9631		 Qalbeabbas-12
Qalbeabbas-12		 towfiq-ul
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).

ZizkaDB (ZIZKA-AI-SL/ZizkaDB)

Searching Database…

144 ·GitHub
ZizkaDB
Что это?ZizkaDB — база данных журнала аудита, созданная для AI-агентов. Она логирует каждое решение агента с контрольной суммой SHA-256 и причинно-следственной ссылкой на то, что его вызвало, так что можно воспроизводить сессии и «путешествовать во времени», чтобы увидеть, что именно агент знал в любой прошлый момент; это поддерживает ведение записей по статье 12 EU AI Act.
Чем это отличается от инструментов трассировки вроде Langfuse или LangSmith?Инструменты трассировки наблюдают деревья спанов, которые приходится читать вручную; ZizkaDB хранит явный родительский id в каждом событии, поэтому db.why() за один вызов проходит причинно-следственную цепочку до первопричины, плюс она добавляет «путешествие во времени» к прошлому состоянию агента, чего типичные инструменты трассировки не делают.
Как его запустить?Запустите Docker, затем выполните quickstart-команду установки — она подтянет конфиг и готовые образы, запустит Postgres, Qdrant, Redis, API и дашборд и запустит демо-агента, без клонирования репозитория. Чтобы встроить его в своего агента, добавьте 'pip install zizkadb-sdk' или 'npm install zizkadb-sdk', либо создайте новый проект командой 'zizkadb init my-agent --template basic'.
Нужны ли Docker или API-ключ, чтобы попробовать?Для самостоятельного хостинга должен работать Docker; первая загрузка образов может занять 5-10 минут, последующие запуски — секунды. Локально API-ключ не нужен, так как используется встроенный dev-ключ, но ZizkaDB Cloud требует ZIZKADB_API_KEY.
Делает ли использование ZizkaDB мою AI-систему автоматически соответствующей статье 12?Нет — в README прямо сказано, что ZizkaDB поддерживает ваши обязательства по ведению записей, но сама по себе не делает систему соответствующей требованиям. Кроме того, месячные лимиты событий облачных тарифов (50k / 100k) — заявленные цели, которые в API пока не принуждаются.
Куда уходят мои данные при самостоятельном хостинге?Данные при самостоятельном хостинге никогда не покидают вашу инфраструктуру. ZizkaDB также поддерживает удаление по GDPR через db.forget(key, value), которое удаляет совпадающие записи и очищает их из поискового индекса.
Какие агентные фреймворки имеют готовые интеграции помимо чистых Python/TypeScript?Есть готовые пакеты для LangChain (callback handler), CrewAI (crew logger) и LiveKit (голосовые агенты), плюс MCP-сервер, так что любой MCP-совместимый клиент вроде Cursor или Claude может обращаться к нему.
Можно ли напрямую спросить Claude или Cursor, почему мой агент что-то сделал?Да — добавьте MCP-сервер (uvx zizkadb-mcp) в конфиг клиента, и вы сможете задавать вопросы вроде «почему support-bot вызвал lookup_order?» и получать обратно причинно-следственную цепочку.
Какие цены на управляемое облако?ZizkaDB Cloud Pro стоит €29/мес за 50k событий и 2 API-ключа, Team — €69/мес за 100k событий и 5 API-ключей; самостоятельный хостинг под AGPL-3.0 бесплатен и без оплаты за каждую трассировку.
Как ZizkaDB хранит причинно-следственные цепочки без графовой базы данных?Каждое событие хранится в Postgres со ссылкой на родительское событие, и db.why() проходит эту цепочку рекурсивным SQL-запросом; события также зеркалируются в Qdrant для семантического поиска, поэтому отдельное графовое хранилище не нужно.
What are similar projects?Tracely-ai, overmind, bisibility, mcp-toolbox, mlflow, opik, labtether, QuantDinger
Which topics is it in?session-replay, gdpr, compliance, llmops, audit-log, mlops, langchain, vector-database, semantic-search, redis, observability, agpl
Creator
ZIZKA-AI-SL
Size
5.8 MB
Stars
144
Updated
CommitOct 18Releasev0.2.8Sep 02
Age
5mo
Commits · 90 Days