Storage

Storage and Observability

Agiwo separates runtime storage into two independent concerns:

• run-log persistence
• trace collection

Run log storage

Run-log storage records canonical runtime facts as append-only RunLog entries.

from agiwo.agent import RunLogStorageConfig
from agiwo.agent.storage.factory import create_run_log_storage

storage = create_run_log_storage(
    RunLogStorageConfig(
        storage_type="sqlite",
        config={"db_path": "runs.db"},
    )
)

Stored facts include:

• RunStarted, RunFinished, RunFailed, TerminationDecided
• LLMCallStarted, LLMCallCompleted
• committed user, assistant, and tool steps
• runtime decisions such as compaction, retrospect, rollback, and hook failures

Replay/query helpers such as list_step_views(...) and list_run_views(...) are rebuilt from the stored RunLog.

Trace storage

Trace storage persists trace snapshots built from committed run-log facts.

from agiwo.agent import TraceStorageConfig
from agiwo.observability import create_trace_storage

trace_storage = create_trace_storage(
    TraceStorageConfig(
        storage_type="sqlite",
        config={"db_path": "traces.db"},
    )
)

Wire storage through AgentOptions

from agiwo.agent import (
    AgentConfig,
    AgentOptions,
    AgentStorageOptions,
    RunLogStorageConfig,
    TraceStorageConfig,
)

config = AgentConfig(
    name="assistant",
    description="Helpful assistant",
    system_prompt="Use tools only when useful.",
    options=AgentOptions(
        storage=AgentStorageOptions(
            run_log_storage=RunLogStorageConfig(
                storage_type="sqlite",
                config={"db_path": "runs.db"},
            ),
            trace_storage=TraceStorageConfig(
                storage_type="sqlite",
                config={"db_path": "traces.db"},
            ),
        )
    ),
)

Backend choices

Backend	Best fit
memory	Tests, demos, ephemeral runs
sqlite	Single-node development or self-hosted deployments

What this enables

• inspect replayable run and step views
• calculate token and cost metrics from committed facts
• query traces by agent, session, or time range
• support Console views for sessions, scheduler state, and traces

The Console owns session storage and projections separately; the SDK itself does not expose a standalone session storage abstraction.