Skip to main content

Decision Trail — Inference Audit Log

Every inference decision your agent logs is recorded — which model, what query, which facts were retrieved (with similarity scores), what the model output, how many tokens were used, and how long it took.

Each record gets a BLAKE2b-128 content-addressed ID and, when a signing key is configured, an Ed25519 signature over that ID. Together they make a record tamper-evident: change any signed field and the ID no longer matches, and the signature no longer verifies.

Decision record schema​

FieldTypeDescription
decision_idstringBLAKE2b-128 hex digest (deterministic)
tenant_idstringTenant that owns the decision
store_idstringMemory store queried
session_idstringSession identifier (optional)
model_idstringLLM model used (e.g. gpt-4o)
querystringThe user's query
retrieved_refsint[]Memory fact refs that were retrieved
retrieved_contentsstring[]Content of each retrieved fact
retrieved_scoresfloat[]Similarity scores
outputstringModel's generated output
token_countintTokens consumed
latency_msfloatEnd-to-end latency in milliseconds
timestampdatetimeISO-8601 with microsecond precision
signaturebytesEd25519 signature (optional)
public_keybytesSigner's public key (optional)

Provenance — what is covered, and what is not​

The decision_id is computed deterministically over the canonical decision fields:

decision_id = BLAKE2b-128(tenant_id ‖ query ‖ model_id ‖ output ‖ timestamp)

When a signing key is configured, the Ed25519 signature is over those same bytes. So:

  • Covered: tenant, query, model, output, timestamp. Any change to these is detectable.
  • Not covered: retrieved_refs, retrieved_contents, retrieved_scores, token_count, latency_ms, session_id, store_id. These are stored alongside the record and can be edited without breaking the signature. In particular the GDPR scrub (below) rewrites retrieved_contents in place and the signature stays valid — by design, so an erasure does not invalidate the decision's provenance.
  • Records are independent. There is no hash chain between decision records: deleting a record, or inserting a back-dated one, is not detectable from the trail alone. (The erasure ledger is chained; the decision trail is not.)

API reference​

POST /v1/decisions/log​

Log a new decision record.

curl -X POST https://api.grafomem.com/v1/decisions/log \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"store_id": "default",
"model_id": "gpt-4o",
"query": "Where does Aria live?",
"retrieved_refs": [42, 87],
"retrieved_contents": ["Aria lives in Rome", "Aria works at ACME"],
"retrieved_scores": [0.95, 0.72],
"output": "Based on the memory, Aria lives in Rome.",
"token_count": 145,
"latency_ms": 230.5
}'

GET /v1/decisions/​

List decisions with pagination and filtering.

ParameterTypeDescription
model_idstringFilter by model
store_idstringFilter by store
session_idstringFilter by session
limitintPage size (default 20, max 200)
offsetintPagination offset

GET /v1/decisions/stats​

Summary statistics: total decisions, models used, average latency, total tokens.

GET /v1/decisions/{decision_id}​

Get a single decision record by ID.

GET /v1/decisions/{decision_id}/replay​

Replay a decision — returns which of its retrieved facts have been deleted since the decision was made.

{
"decision": { ... },
"facts_since_deleted": [42]
}
Why replay matters

Replay answers: "If this decision were made today, would it have the same inputs?" If facts have been deleted since, the answer is no — and the erasure certificate for each one is the evidence.

GET /v1/decisions/export​

Bulk export all decisions as NDJSON (newline-delimited JSON). Opens as a file download.

DELETE /v1/decisions/scrub/{fact_ref}​

GDPR scrub — replaces the content of a deleted fact with [REDACTED — GDPR Article 17] in every decision record that retrieved it. Records are updated in place; the retrieved_refs stay, so the fact that a retrieval happened remains visible while its content does not.

Portal UI​

The Decision Trail tab in the Cloud Portal provides:

  • Stats grid — total decisions, models used, avg latency, total tokens
  • Filter bar — search by model, store, session
  • Decision table — paginated list with time, model, query preview, facts count, tokens, latency, signed status
  • Detail panel — click any row to see full query, retrieved facts with scores, model output
  • Provenance badge — Ed25519 signature + public key, when signed
  • Replay — see which facts have been deleted since the decision
  • NDJSON export — one-click bulk download