ZizkaDB

Delete all events matching a filter (GDPR right to erasure). Removes events from both the database and the vector index. Commonly used to delete all data for a specific user on request. Args: filter_key: Field in event data to match (e.g. "user_id", "email", "session_id") filter_value: Value to match (e.g. "user_123", "alice@example.com") Returns: deleted_events count

Behavioral baseline and drift score for an agent.

Get a formatted memory context block ready to inject into a system prompt. This is the drop-in replacement for LLM-provided memory (Claude Projects, ChatGPT memory). It combines recent events with semantically relevant past events, fits within a token budget, and formats as plain text. Typical usage: context = await get_context("support-bot", "user asking about billing") system_prompt = f"You are a support agent.\n\n{context}" Args: agent: Your agent identifier task: What the agent is about to do (guides semantic retrieval) max_tokens: Token budget for the context block (default 2000) session_id: Current session ID to exclude from context (optional) Returns: Formatted context string -- paste directly into your system prompt

Deterministic token optimization suggestions from real usage events.

Token usage and cost report for an agent over a date range.

Log an event to ZizkaDB. Use this every time your agent takes an action: a tool call, a decision, a user message, or an agent response. Logging builds the causal graph that powers why(), search_memory(), and get_context(). Args: agent: Unique identifier for your agent (e.g. "support-bot"): letters, numbers, dots, dashes and underscores, starting with a letter or number event: What happened (e.g. "tool_call", "user_message", "decision") data: Any dict of relevant data (tool name, query, result, etc.) session_id: Groups related events into a session (optional) parent_id: event_id of the event that caused this one -- enables causal lineage (optional) Returns: event_id, timestamp, sequence_no, checksum

Summarise what happened in a session. Returns event counts, types seen, causal depth, whether any errors occurred, and event types that had never appeared in prior sessions. Call this at the end of a session to understand what changed. Args: session_id: The session to analyse Returns: summary, event_types, total_events, has_errors, new_event_types

List recent events for an agent. Args: agent: Agent identifier to query limit: Number of events to return (default 20) event_type: Filter by event type, e.g. "tool_call" (optional) Returns: List of events ordered by time (most recent first)

Start a fresh causal chain (new session_id, clear parent_id).

Search over all logged agent events. Finds past decisions, tool calls, conversations, or any event. Works on any server: keyword search without embeddings, keyword + meaning (hybrid) with them. Useful before a new task to see what happened in similar situations. Args: query: Natural language description of what you're looking for agent: Filter to a specific agent (optional -- leave blank to search all) limit: Number of results (default 10, max 50) mode: Leave blank for the server default, or "keyword", "semantic", "hybrid" Returns: List of matching events with relevance scores

Replay the exact state of an agent at a specific point in time. Reconstructs what the agent knew and had done up to that moment. Useful for investigating complaints ("what did the agent tell them at 3pm?") or comparing behaviour across versions. Args: agent: Agent identifier timestamp: ISO 8601 datetime, e.g. "2026-05-10T15:00:00Z" Returns: Agent state snapshot at that moment (events, summary, last_event)

Prove an agent's history is untouched. Rechecks every event's checksum and its link in the agent's hash chain. "intact": true means no event was edited, removed or reordered (GDPR deletions show up as tombstones, not breaks). Keep "chain_head" as proof of the history at this moment. Args: agent: The agent whose history to check Returns: intact, a summary, any problems found, and chain_head

Trace the causal chain that led to an event. Given any event ID, walks back through parent_id links to reconstruct the full decision tree: user message -> tool call -> result -> response. Essential for debugging why an agent did something unexpected. Args: event_id: The event you want to explain depth: How many levels back to trace (default 10) Returns: Ordered list of events from root cause to the specified event