Documentation

Connect ZizkaDB to your agents with the Python or TypeScript SDK, the MCP server, or LangChain, LangGraph, CrewAI and LiveKit. Every event becomes part of a tamper-evident audit trail with causal lineage, and doubles as agent memory (LLM memory) for the next run.

Current releases: PyPI zizkadb-sdk 0.5.0 · npm zizkadb-sdk 0.5.0 · zizkadb-mcp 0.1.12 · zizkadb-langchain / zizkadb-crewai 0.1.5 · zizkadb-livekit 0.2.3

Open-source guides for self-hosting ZizkaDB with Docker. Start with the quickstart, then connect your stack. Managed cloud docs are at the bottom if you prefer hosted.

OSS quickstart (recommended):

bashgit clone https://github.com/ZIZKA-AI-SL/ZizkaDB
cd ZizkaDB
bash scripts/quickstart.sh

Pulls pre-built GHCR images when available — no local compile. Runs the why() demo and opens the dashboard at http://localhost:3001/login (no signup). Full connect guide: CONNECT.md

Environment variables (self-host + cloud):

bashexport ZIZKADB_HOST=http://localhost:8000   # self-host only
export ZIZKADB_API_KEY=zizkadb_live_...   # managed cloud only
export ZIZKADB_AGENT=my-bot
export ZIZKADB_TELEMETRY=false            # optional

SDKs are stateless — pass agent, session_id, and event_id explicitly. See performance and security on the technical reference.

Choose your integration

In CI — GitHub Actions

Run ZizkaDB inside your agent's test job, with no account and no secrets: the data stays in the runner. ZizkaDB Why explains agent test failures as causal chains in the pull request, and ZizkaDB Audit proves the recorded history is intact, with an attested report. Both are on GitHub Marketplace.

yaml- uses: ZIZKA-AI-SL/zizkadb-why-action@v1
  with:
    run: pytest tests/agent

OSS path — self-host with Docker

Full guide in · connect snippets in CONNECT.md

Quickstart (one command)

bashgit clone https://github.com/ZIZKA-AI-SL/ZizkaDB
cd ZizkaDB
bash scripts/quickstart.sh

Starts API + dashboard. Uses pre-built ghcr.io/zizka-ai/* images when published; otherwise builds locally. Runs zizkadb demo (causal lineage).

Open dashboard (no email)

Go to http://localhost:3001/login → click Open my dashboard →. This is your local workspace.

Connect your agent

pythonpip install "zizkadb-sdk>=0.5.0"
# zizkadb demo          # repeat the worked example
# zizkadb init my-agent --template basic

from zizkadb import ZizkaDB
db = ZizkaDB(host="http://localhost:8000")  # auto-uses local dev key
await db.log(agent="my-bot", event="started", data={})

Important: SDK and dashboard must use the same tenant. Local dev: green dashboard button + host= SDK. Production VPS: email OTP + API key from Settings.

See your data in the dashboard

Agents appear as soon as you log events. Click an agent for events, sessions, and drift.

Managed cloud (optional)

Prefer not to run Docker? Use hosted ZizkaDB at db.zizka.ai.

Connect SDK, MCP, or REST

Use your API key and the same agent name in every db.log(agent=…) call.

Open your dashboard

db.zizka.ai/dashboard shows the same agents and events your code logs.

After connecting

Log events with session_id

Log user_message, each tool_call, and assistant_response with parent_id links. Use the same session_id for one conversation so baselines and diffs work.

Configure embeddings (managed)

In Settings → Embeddings, pick your OpenAI model (platform-hosted or your own key) to add vector results to search and context_for(); without embeddings both use keyword search. Logging and why() work without embeddings.

Use drift & search

Once you have enough sessions, use baseline() and search in the dashboard or SDK.