Skip to content

Audit & incident-reconstruction records

Soulacy keeps two separate records of agent activity. They serve different purposes and have very different guarantees. Know which one is authoritative.

The authoritative record: SQLite action log

internal/actionlog is THE authoritative incident-reconstruction record.

  • Backed by SQLite (agent_events table) plus a mirrored per-agent <agent-id>.log JSON-Lines file that the GUI Logs page tails.
  • Always on. It is part of the core storage backend (storage.backend: sqlite by default; also available via Postgres) and is wired unconditionally at startup: there is no config switch to turn it off.
  • Durable and queryable. Survives restarts, supports cross-agent queries, and is written by a single buffered async writer that batches and fsyncs.
  • Records the full lifecycle of every run: run start, LLM calls, tool calls/results, replies, and errors, flowing through the gateway EventHub.

When you need to reconstruct what an agent did: for an incident review, forensic timeline, or audit: this is the source of truth.

Location: <workspace>/logs/ for the per-agent JSONL mirror and <workspace>/data/actions.db (SQLite) for the durable store. With storage.backend: postgres, the durable store lives in Postgres instead.

The optional record: JSONL audit log

internal/audit writes an optional per-session JSONL tool-call log.

  • Optional debug output. OFF by default. Controlled by runtime.audit_dir, which now defaults to empty (disabled). When empty, the audit logger is a no-op.
  • Redundant. It captures a subset of what the action log already records (tool name, redacted args, result length, duration, denied/error flags). It exists as a convenience tail for quick grep/tail -f inspection during development, not as a system of record.
  • Best-effort. Write failures are swallowed silently so they never crash an agent run. That is exactly why it must not be relied upon for incident reconstruction.

To enable it (for example during debugging), set an explicit directory:

runtime:
  audit_dir: /Users/yourname/.soulacy/audit

Each session then gets <audit_dir>/<YYYY-MM-DD>/<sessionID>.jsonl. Secret- looking argument values (api_key, password, secret, token, credential, auth) are redacted before they hit disk.

Summary

SQLite action log (internal/actionlog) JSONL audit log (internal/audit)
Authority Authoritative: system of record Optional convenience copy
Default state Always on (cannot be disabled) Off (audit_dir: "")
Storage SQLite (+ GUI JSONL mirror) / Postgres Per-session JSONL files
Durability Durable, queryable, async-batched Best-effort, failures swallowed
Use for incident reconstruction Yes No: use the action log