# ZizkaDB
**When your agent misbehaves, see why.**
Self-hosted audit trail for AI agents — one command or one dashboard click from any step back to root cause.
**This repository is the open-source self-host stack** (API, tenant dashboard, SDKs, MCP). Operator admin console and VPC deploy live in private [zizkadb-cloud](https://github.com/Zizka-ai/zizkadb-cloud) — see [docs/REPO_SPLIT.md](docs/REPO_SPLIT.md).
[](https://github.com/Zizka-ai/ZizkaDB/actions/workflows/ci.yml)
[](LICENSE)
[](https://github.com/Zizka-ai/ZizkaDB/releases)
[](https://pypi.org/project/zizkadb-sdk/)
[](https://pypi.org/project/zizkadb-langchain/)
[](https://pypi.org/project/zizkadb-crewai/)
[](https://pypi.org/project/zizkadb-livekit/)
[](https://pypi.org/project/zizkadb-mcp/)
**[Try it ↓](#try-it-60-seconds)** · **[DEVELOPMENT.md](DEVELOPMENT.md)** · **[CONNECT.md](CONNECT.md)** · **[Contributing](CONTRIBUTING.md)**
## Try it (60 seconds)
Requires [Docker](https://docs.docker.com/get-docker/). First image pull may take 5–10 minutes.
```bash
curl -fsSL https://raw.githubusercontent.com/Zizka-ai/ZizkaDB/main/scripts/quickstart-remote.sh | bash
```
You should see:
```text
tool_call · lookup_order · ORD-8842
└── llm_response · gpt-4o
└── user_message · Why was my order delayed?
```
Run again anytime: `pip install zizkadb-sdk && zizkadb demo`
### Self-host from a clone
```bash
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](DEVELOPMENT.md)** · Troubleshooting: [wiki/Troubleshooting.md](wiki/Troubleshooting.md)
---
## Why?
Every agent team asks: *Why did it say that? Why did it call that tool?*
1. **Log** agent steps with `parent_id` (each step links to the one that caused it).
2. **Ask why** — terminal: `zizkadb why ` or Python: `(await db.why(event_id)).print()`
3. **See the chain** — walk back to the user message, wrong tool, or bad context.
**Dashboard (same chain):** [Activity → support-bot](http://localhost:3001/dashboard/activity?agent=support-bot) → click an event → **Why? (causal)** tab.
---
## Connect (3 lines)
```python
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())
```
Full guides: **[CONNECT.md](CONNECT.md)** · [LangChain](CONNECT.md#langchain) · [CrewAI](CONNECT.md#crewai) · [LiveKit (voice)](CONNECT.md#livekit-agents-voice) · [MCP / Cursor](mcp/README.md)
---
## Integrations
| Python | TypeScript | LangChain | CrewAI | LiveKit | MCP | REST |
| :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| [`zizkadb-sdk`](https://pypi.org/project/zizkadb-sdk/) | [`zizkadb-sdk`](https://www.npmjs.com/package/zizkadb-sdk) | [`zizkadb-langchain`](https://pypi.org/project/zizkadb-langchain/) | [`zizkadb-crewai`](https://pypi.org/project/zizkadb-crewai/) | [`zizkadb-livekit`](https://pypi.org/project/zizkadb-livekit/) | `uvx zizkadb-mcp` | [Swagger](https://db.zizka.ai/swagger) |
Scaffold a project: `zizkadb init my-agent --template basic`
### Voice agents (LiveKit)
```bash
pip install zizkadb-livekit
```
One LiveKit call → one **Session** in Activity (transcript only, no audio in ZizkaDB). Full guide: [CONNECT.md → LiveKit](CONNECT.md#livekit-agents-voice) · [docs/integrations/livekit.md](docs/integrations/livekit.md) · [example](examples/livekit-agent/).
---
Managed cloud (Pro / Team) — optional
Same **Why?** feature — hosted at [db.zizka.ai](https://db.zizka.ai). No Docker to maintain.
The operator admin console, VPC deploy, and cloud-only marketing routes live in the private **[zizkadb-cloud](https://github.com/Zizka-ai/zizkadb-cloud)** repo — see [docs/REPO_SPLIT.md](docs/REPO_SPLIT.md).
| | **Pro** | **Team** |
| --- | --- | --- |
| Price | €29 / mo | €69 / mo |
| Events / mo† | 50k | 100k |
| API keys | 2 | 5 |
[Sign up →](https://db.zizka.ai/signup/plan)
† Plan targets on managed cloud; not enforced in API yet. See [docs/README.md](docs/README.md#plan-limits-honest).
More features — drift, time-travel, search, GDPR
| Function | What it does |
| --- | --- |
| `db.baseline()` | Detect when agent behavior drifts vs past sessions |
| `db.at()` | Reconstruct what the agent knew at a timestamp |
| `db.search()` | Semantic search over agent history |
| `db.context_for()` | Inject relevant past events into prompts |
| `db.forget()` | GDPR erasure by metadata filter |
FAQ
**Do I need to clone this repo?**
No — the curl quickstart downloads config + Docker images only.
**Do I need an API key locally?**
No — `http://localhost:8000` uses a built-in dev key. Dashboard: [localhost:3001/login](http://localhost:3001/login).
**How is this different from Langfuse / LangSmith?**
They **observe** span trees. ZizkaDB **audits** with explicit `parent_id` chains and `db.why()` on your Postgres — self-host under AGPL, no trace billing.
**Voice agents with LiveKit?**
Install **`zizkadb-livekit`** — one pip command, connect to Docker with `ZIZKADB_HOST=http://localhost:8000`. See [LiveKit guide](CONNECT.md#livekit-agents-voice).
**`zizkadb demo` connection refused?**
Start the stack: `curl -fsSL …/quickstart-remote.sh | bash` or `bash scripts/setup-local.sh`.
Docs & community
| | |
| --- | --- |
| Worked example | [worked/01-support-order-delay](worked/01-support-order-delay/) |
| Examples | [examples/](examples/) — includes [LiveKit voice agent](examples/livekit-agent/) |
| LiveKit integration | [docs/integrations/livekit.md](docs/integrations/livekit.md) |
| Self-hosting | [DEVELOPMENT.md](DEVELOPMENT.md) · [wiki/Self-Hosting](https://github.com/Zizka-ai/ZizkaDB/wiki/Self-Hosting) |
| Troubleshooting | [wiki/Troubleshooting.md](wiki/Troubleshooting.md) |
| Integrate any agent | [docs/integrate/](docs/integrate/) |
| Issues · Discussions | [Issues](https://github.com/Zizka-ai/ZizkaDB/issues) · [Discussions](https://github.com/Zizka-ai/ZizkaDB/discussions) |
| Contributing · Security | [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) |
| AI-assisted development | [AGENTS.md](AGENTS.md) · [docs/ai/CODING_STANDARDS.md](docs/ai/CODING_STANDARDS.md) |
AGPL-3.0 · MCP server MIT · Disable telemetry: export ZIZKADB_TELEMETRY=false