Agent Governance ToolkitAgent Governance Toolkit 4.1.0 · Python 3.10+
Dashboard
0%

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.

python
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.

python
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()
ExampleThe durable file against the empty in-memory list
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))

Which store to pick

StoreLives inSurvives a restartTaught in
Flight recorderA SQLite fileYesRecording every decision: the flight recorder
JSONL loggerA text fileYesThe audit log as JSONL
Merkle chainMemory + a root hashNoMerkle proofs and CloudEvents
Kernel listMemory onlyNothis 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.
Watch out. Reaching for 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.
Try it yourself
  • 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-check os.path.exists.
  • Call chain.get_root_hash() before adding any entry and read what it returns.
PreviousRisk scores

This is what real progress feels like.