ZizkaDB

Overview

ZizkaDB stores agent events — decisions, tool calls, messages, and outcomes — with causal links, semantic search over history, reconstruction of logged state at a timestamp, and statistical behavioral baselines per agent.

Agent runtime
 ├── Vector DB          →  RAG / knowledge retrieval
 ├── Postgres / Redis   →  app state, caches, users
 ├── ZizkaDB            →  events, why(), at(), baseline, forget()
 └── OTel / LangSmith   →  distributed traces (optional)

Problem domain

Production agent systems typically need:

• Causal debugging — walk from a bad output to the event that triggered it
• State at time T — what was logged for an agent before a given timestamp
• Cross-session memory — under your API keys, retention policy, and erasure controls
• Behavior change detection — compare recent sessions to that agent's historical pattern

ZizkaDB targets these operational concerns. It does not replace embedding indexes for document RAG or distributed tracing for infrastructure spans.

Architecture

Managed (db.zizka.ai)

Self-hosted

Docker Compose stack: Postgres (pgvector), Qdrant, Redis, API. Dashboard is optional (run from dashboard/). Requires OPENAI_API_KEY for embedding-backed features; logging and causal APIs work without it.

git clone https://github.com/Zizka-ai/ZizkaDB
cp .env.example infra/.env
docker compose -f infra/docker-compose.yml up -d

Data model

Every record is an event:

Multi-tenancy: API keys (zizkadb_live_*) scope all reads and writes to a tenant. Dashboard auth uses email OTP → JWT.

Capabilities

Time travel semantics

at(agent, timestamp) reconstructs logged state by aggregating all events for that agent with timestamp ≤ T. The returned structure reflects what was recorded in ZizkaDB, not a re-execution of the LLM or tools.

Integrity & retention

• Events are stored in Postgres with an append-by-default write pattern; each payload includes a SHA-256 checksum for integrity verification.
• forget() removes events matching metadata filters (GDPR right to erasure) — storage is not WORM/immutable.
• Managed plans enforce retention windows (90 days Pro, 1 year Team); self-hosted retention is operator-defined.
• Bulk signed audit export is on the product roadmap; today, export via API/query and verify checksums per event.

Performance expectations

ZizkaDB is built for normal agent loops — tool calls, messages, and decisions — not for blockchain-scale write throughput. Stack: Postgres (events), Qdrant (vectors), Redis (cache).

High-frequency fleets (thousands of parallel writes per second) are not a v1 target. Async embedding queues and published benchmarks are on the roadmap as usage grows.

Security (early stage)

ZizkaDB v1 is aimed at developers and small teams — not enterprise compliance certification yet. Here is what we do today:

• In transit: TLS on managed cloud (db.zizka.ai via nginx).
• Tenant isolation: every API call scoped by API key or JWT to a tenant_id; no cross-tenant reads.
• At rest: standard Postgres / disk encryption on the operator's infrastructure (AWS EBS on managed; your disk when self-hosted).
• BYOK embedding keys: encrypted in Postgres (Fernet) when you bring your own OpenAI key.
• GDPR erasure: forget() deletes matching events and vectors.
• Telemetry: one anonymous SDK/MCP startup ping — opt out with ZIZKADB_TELEMETRY=false.

Not claimed today: SOC 2, HIPAA, or formal DPAs. For enterprise security review, contact founder@zizka.ai.

Integration

Concurrency: Python and TypeScript SDKs are stateless HTTP clients — no thread-local storage or contextvars. Pass agent, session_id, parent_id, and event_id explicitly on each call. Safe in FastAPI, Celery, and parallel async workers.

Cloud default host: https://db.zizka.ai. Self-host: pass host= to the SDK or set ZIZKADB_HOST for MCP.

pythonfrom zizkadb import ZizkaDB

db = ZizkaDB("zizkadb_live_xxxx")  # managed
# db = ZizkaDB(host="http://localhost:8000")  # self-host

msg = await db.log(agent="bot", event="user_message", data={"text": "..."})
tool = await db.log(agent="bot", event="tool_call", data={...}, parent_id=msg.event_id)
chain = await db.why(tool.event_id)

Cursor MCP (30 seconds)

Add to ~/.cursor/mcp.json or project .cursor/mcp.json, then reload MCP:

json{
  "mcpServers": {
    "zizkadb": {
      "command": "uvx",
      "args": ["zizkadb-mcp"],
      "env": { "ZIZKADB_API_KEY": "zizkadb_live_xxxx" }
    }
  }
}

Self-host: set ZIZKADB_HOST to http://localhost:8000 instead (dev key auto-injected).

MCP tools

log_event, search_memory, get_context, why, query_events, time_travel, memory_diff, forget — see setup guide for config.

Telemetry: one anonymous SDK startup ping (name, version, OS, cloud vs self-host). Opt out: ZIZKADB_TELEMETRY=false.

REST API

Base URL https://db.zizka.ai. Auth: Authorization: Bearer <token>. Interactive schema: /swagger.

Deployment

Onboarding: signup → email OTP → Settings → API key → SDK or MCP env.

Comparison

Capability matrix (May 2026). Verify competitor docs before external debates; ~ = partial support.

Licensing

AGPL applies when you modify and distribute the server. MCP is MIT for IDE integration. Commercial embedding requires legal review.

Plan limits

Baseline/drift requires sufficient session_id coverage; early agents report warming_up or insufficient_data.

FAQ

Contact