save_event
Record agent actions, decisions, and state changes in an append-only event log to enable deterministic replay and maintain an immutable audit trail.
Instructions
Append an event to the shared event log with optional metadata.
Use this to record agent actions, decisions, and state changes. All events are append-only with stable UUIDv7 ordering, enabling deterministic replay.
Side effects: Creates a new event in the SQLite event log. Triggers an automatic snapshot when the event threshold is reached. This is the primary write operation for the event-sourced architecture.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Event type identifier (e.g., "TASK_CREATED", "TASK_ASSIGNED", "TOOL_CALLED", "DECISION_MADE"). | |
| branch | No | Optional branch name (for git-based project tracking). | |
| source | No | Event source label (default "agent"). Use "allbrain" for system-generated events, or the agent name for agent actions. | agent |
| payload | Yes | Event data as a JSON-serializable dict. Should contain the relevant state or information being recorded. | |
| caused_by | No | Optional causal event reference (creates event provenance). | |
| file_path | No | Optional source file path (for code-related events). | |
| task_hint | No | Optional task hint string (helps with memory building). | |
| importance | No | Optional importance rating (1-5); higher values may trigger more frequent snapshots. | |
| session_id | No | Optional session ID to associate with (for multi-agent tracing). | |
| impact_score | No | Optional impact score for decision events. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||