Python SDK

Python SDK

Package: zizkadb-sdk on PyPI
Import: from zizkadb import ZizkaDB

pip install zizkadb-sdk

Quickstart

import asyncio
from zizkadb import ZizkaDB

async def main():
    async with ZizkaDB("zizkadb_live_...") as db:
        user = await db.log(
            agent="my-bot",
            event="user_message",
            data={"text": "Why is my bill high?"},
            session_id="sess_001",
        )
        tool = await db.log(
            agent="my-bot",
            event="tool_call",
            data={"tool": "get_billing", "user_id": 123},
            parent_id=user.event_id,
            session_id="sess_001",
        )
        chain = await db.why(tool.event_id)
        chain.print()

asyncio.run(main())

Scaffold a project

zizkadb init my-agent --template basic
zizkadb init my-agent --template langchain
zizkadb init my-agent --template crewai
zizkadb init my-agent --template openai
zizkadb init my-agent --template mcp-cursor

Main methods

Method	Description
log(agent, event, data, ...)	Append event (embeds when tenant embeddings are configured)
query(agent, ...)	List events
why(event_id)	Causal chain via parent_id
search(query, agent?)	Semantic search
at(agent, timestamp)	Time-travel state
context_for(agent, task)	Prompt-ready memory block
forget(filter_key, filter_value)	GDPR delete
baseline(agent)	Behavioral drift signal
agents()	List agents

Errors

from zizkadb import AuthError, AgentScopeError, NotFoundError

try:
    await db.log(agent="wrong-name", event="x", data={})
except AgentScopeError as e:
    print(e)  # Key scoped to different agent
except AuthError:
    print("Invalid API key")

Self-hosted

db = ZizkaDB(host="http://localhost:8000")

Localhost auto-uses dev key zizkadb_dev_local.

Telemetry opt-out

export ZIZKADB_TELEMETRY=false