Core Concepts

How ZizkaDB thinks about agent memory — events, causality, search, replay, and drift.

Runnable examples: zizkadb init my-agent or the examples/ folder on GitHub. Framework guides in .

Events

Everything is an event: agent name, event type string, JSON data, timestamp. Log what matters — user messages, tool calls, decisions, errors.

pythonawait db.log(agent="support-bot", event="tool_call",
    data={"tool": "get_billing", "user_id": 123})

Causal lineage

parent_id links child → parent. db.why() walks from any event back to the root. This is how you debug "why did the agent do that?"

pythonmsg  = await db.log(..., event="user_message", data={...})
tool = await db.log(..., event="tool_call", parent_id=msg.event_id)
await db.why(tool.event_id)  # user_message → tool_call

Sessions & baselines

Use session_id on every event in one run. After enough sessions, baseline() compares recent behavior to historical patterns and returns a drift score.

pythonbaseline = await db.baseline("support-bot", recent_window=50)
# drift.score: 0 = identical, 1 = totally different

Search

Search in plain English. Keyword search (Postgres full-text) always works; with embeddings on, results combine keywords and meaning (hybrid). Facts that a later event superseded are left out.

pythonresults = await db.search("angry customer billing", agent="support-bot")

Provable history

Every event has a checksum and is hash-chained to the agent's previous event. verify_chain() proves nothing was edited, removed or reordered; GDPR erasure and retention leave content-free tombstones. Keep chain_head elsewhere and check from it later.

pythoncheck = await db.verify_chain("support-bot")
print(check["intact"], check["chain_head"])

Time travel

at() reconstructs logged state from events up to a timestamp. Replays what was recorded, not a re-run of the LLM.

pythonfrom datetime import datetime, timezone
state = await db.at("support-bot", datetime(2026, 5, 1, 15, 0, tzinfo=timezone.utc))

Context injection

context_for() returns recent + relevant events within a token budget, ranked by relevance × importance × recency, with superseded facts and exact repeats removed — paste into your system prompt.

pythonctx = await db.context_for(agent="support-bot", task="refund question", max_tokens=2000)