Skip to main content

​
Immutable Decision Trace Store

A decision trace records how an agent turned what it knew into what it did. amfs_explain reconstructs that for the session you are in. Pro persists the same thing permanently, signed and tamper-evident, so you can answer “why did the agent do that?” months after the agent has stopped running.

​
What Every Trace Captures

Committing an outcome snapshots the whole session:
  • Session timing — session_started_at, session_ended_at, session_duration_ms
  • Query events — each search() and list() call with its parameters, result count, and latency
  • Error events — anything that failed during a read, write, or tool call
  • State diff — entries created and updated, and how confidence moved
  • Entry snapshots — the value, memory_type, and written_by of everything read, captured as it was at read time
That last point is what makes a trace worth keeping. It records what the agent actually saw, not what the entry says today, so a later edit cannot rewrite the explanation of a past decision.

​
What Pro Adds

Tamper-evident storage. Each trace is hashed with SHA-256 over its contents and signed with HMAC-SHA256. Traces are chained within a session — each one carries the hash of the one before it and its position in the sequence — so altering or removing a trace after the fact breaks the chain and is detectable. LLM call spans. Record the model, provider, token counts, cost, latency, temperature, and finish reason for each call an agent makes, and every trace carries total_llm_calls, total_tokens, and total_cost_usd. This is what turns a trace from “what the agent decided” into “what that decision cost.” A full record of actions — writes, tool calls, and interactions between agents, not just reads. Search across history. Query stored traces by entity path, agent, outcome type, or time range, which is how you find every decision that preceded a particular kind of failure.
Recording is automatic once you are on a plan that includes it. Use amfs_record_llm_call to attach model and cost data to the current session, and amfs_list_traces and amfs_get_trace to read history back. To add nested steps, tokens and cost to every run — over OpenTelemetry, MCP or HTTP — see Instrument your agent.

​
OpenTelemetry Export

Traces export as OpenTelemetry spans, so agent decisions show up alongside the rest of your system in whatever you already use — Jaeger, Grafana Tempo, Datadog, or Honeycomb. The mapping follows GenAI semantic conventions: each LLM call becomes a gen_ai.completion span, and memory operations become amfs.* spans — amfs.session for the session as a whole, then amfs.read, amfs.write, and amfs.query beneath it.