X · Governance & ObservabilityMature★★

Provenance Ledger

also known as Audit Trail, Action Log

Log every agent decision and state change with enough metadata to explain or reverse it later.

This pattern helps complete certain larger patterns —

  • specialisesDecision Log★★— Persist the agent's reasoning trace alongside its actions so post-hoc review can explain why.
  • used-byCompensating Action★★— Pair every irreversible-looking agent action with a compensating action that can undo or counteract it.
  • used-bySandbox Escape Monitoring★— Treat sandbox boundary violations as telemetry; alert on syscalls, network egress, or filesystem writes outside expected scope.
  • used-byEmotional State Persistence★— Track the agent's affective state as bounded, decaying scalars across ticks so reasoning can react to its own emotional load instead of treating each turn as emotionally blank.

Context

A team runs an agent that takes consequential actions in the real world: approving or rejecting insurance claims, modifying production records, sending money. Sometimes weeks or months later, a regulator, a customer, or an internal auditor asks why the agent did what it did on a specific date. Answering that question requires both the action and the chain of reasoning, retrieved evidence, and model version that surrounded it.

Problem

Without an immutable, append-only record of every decision and state change tied to a justification, agent behaviour becomes inscrutable after the fact. Rolling back a specific bad action is impossible because there is no event identifier to reverse, and patterns of failure across time are invisible because the trail is not queryable. The team is forced to choose between trusting that nothing will ever be questioned or attempting to reconstruct months-old behaviour from logs that were never designed for audit.

Forces

  • Auditability vs storage cost of every event.
  • Schema rigidity vs evolvability over the agent's lifetime.
  • PII in events: redaction at write time vs read time.

Example

A regulator asks an insurance-claims agent why it rejected a specific claim three months ago. The team can show the final decision but not the chain of reasoning, the retrieved policy clauses, or which model version answered — the audit trail is partial. They add a provenance-ledger: every decision and state change appends an immutable event with timestamp, actor, action, target, justification link, and diff hash. Rollback by event id becomes trivial; the next regulator question is answered with a full reconstruction.

Diagram

Solution

Therefore:

Append events to an immutable log with: timestamp, actor, action, target, justification (link to thought or decision), diff hash. Enable rollback by id. Reject events that lack the required fields.

What this pattern forbids. Self-edits and other recorded actions are rejected if they lack a valid justification reference.

And the patterns that stand alongside it, or against it —

  • composes-withAppend-Only Thought Stream★— Make the agent's thought log append-only so the agent cannot rewrite its own history.
  • complementsLineage Tracking★★— Track which prompt version, model version, and data sources produced each agent output.
  • alternative-toBlack-Box Opaqueness✕— Anti-pattern: ship an agent without traces, decision logs, or provenance, then debug from user reports.
  • complementsMemo-As-Source Confusion★— Anti-pattern: the agent cites its own past memos as ground truth instead of re-verifying them against the artifacts they describe, accumulating false confidence in stale summaries.
  • complementsWorld-Model Separation★— Maintain an explicit, surprise-updated model of the environment (humans, repos, services, capabilities) in a separate file from the agent's self-model, so the two cannot be confused or co-mutated by reflection.
  • complementsDurable Workflow Snapshot★— Capture workflow execution state as a snapshot in a pluggable storage provider so a paused run can resume across deployments, process restarts, and host crashes.
  • alternative-toErrors Swept Under the Rug✕— Anti-pattern: scrub failed actions, stack traces, and error observations from the agent's own context so the trace looks clean, leaving the model with no evidence of what did not work.
  • complementsRigor Relocation★— Relocate verification rigor from the model loop to surrounding scaffolding (evals, judges, decision logs, policy gates) so failures are caught by the wrapper rather than the agent.
  • complementsHidden State Coupling✕— Anti-pattern: agent workflows read or write undeclared shared state (caches, env vars, process globals) instead of explicit inputs and outputs.
  • complementsPolicy-Gated Agent Action (KRITIS)★— Each agent action passes through a policy gate (NIS2, EU the agent Act, BSI rules) and is tagged with Run ID + Model Digest + Policy Hash for WORM-audit reconstruction.

Neighbourhood

Click any neighbour to follow the language. Scroll to zoom, drag to pan.

Used in recipes

Used in frameworks

References

Provenance