Where the audit trail is written
The audit trail is the record of every verdict the gate reached, and the toolkit can write it in three different places, none of which is the kernel's own in-memory list.
Last updated: 14 Oct, 2026 · Agent Governance Toolkit 4.1.0
The gate lessons kept a trail for free. For a real deployment you choose where that trail is stored, because the choice decides whether it survives a restart and whether it can be proven unedited. This part builds all three stores. This lesson is the map, and it clears up one trap first.
The three places a trail can live
- A SQLite flight recorder writes each decision to a database file on disk, with a hash chain so edits can be detected. It is the durable default.
- A JSONL logger appends one line of JSON per decision to a text file, which is the format log collectors expect.
- A Merkle audit chain keeps the decisions in memory with a Merkle root, so you can hand someone a short proof that one entry belongs to the set.
The trap: the kernel's list is not the audit trail
The kernel keeps its own list in memory, returned by get_audit_log(). It is a copy, it starts empty, and it is gone when the process ends. It is useful for a quick look inside one run, and it is not where a lasting record goes.
from agent_control_plane.agent_kernel import AgentKernel
kernel = AgentKernel() # no store attached
kernel.intercept_tool_execution(agent_id="shop", tool_name="order_status", tool_args={})
print(type(kernel.get_audit_log()).__name__, len(kernel.get_audit_log()))Seeing the durable file against the in-memory list
A short setup builds a flight recorder and a bare kernel, and records one call in each. The recorder leaves a database file on disk; the kernel holds its list in memory, and with no policy loaded that list stays empty.
import warnings; warnings.simplefilter("ignore")
import tempfile, os
from agent_control_plane.flight_recorder import FlightRecorder
from agent_control_plane.agent_kernel import AgentKernel
# a durable store on disk, and a bare kernel with no store attached
db = os.path.join(tempfile.mkdtemp(), "shop.db")
recorder = FlightRecorder(db_path=db, enable_batching=False)
recorder.start_trace(agent_id="shop", tool_name="order_status", tool_args={})
kernel = AgentKernel()recorder.flush()
print("flight recorder file on disk:", os.path.exists(db))
# the kernel keeps only an in-memory list, separate from any durable store
log = kernel.get_audit_log()
print("kernel list is a", type(log).__name__, "of length", len(log))flight recorder file on disk: True kernel list is a list of length 0
Which store to pick
| Store | Lives in | Survives a restart | Taught in |
|---|---|---|---|
| Flight recorder | A SQLite file | Yes | Recording every decision: the flight recorder |
| JSONL logger | A text file | Yes | The audit log as JSONL |
| Merkle chain | Memory + a root hash | No | Merkle proofs and CloudEvents |
| Kernel list | Memory only | No | this lesson |
Where you use each trail
- The flight recorder when you want one durable, queryable, tamper-evident record on the machine.
- The JSONL logger when a log collector or SIEM reads your files and you want plain lines.
- The Merkle chain when you must hand someone a compact proof about one entry without the whole log.
kernel.get_audit_log() as your audit trail is the common mistake. It is an in-memory copy that starts empty and vanishes with the process. Pick one of the three durable stores for anything you need to keep.Related
- Previous: Risk scores
- Next: Recording every decision: the flight recorder
- Run the kernel intercept twice and confirm
get_audit_log()still reports the length you expect for a no-policy kernel. - Delete the SQLite file after
flush()and re-checkos.path.exists. - Call
chain.get_root_hash()before adding any entry and read what it returns.
This is what real progress feels like.