Introduction
USL — the agent-session database
USL (Universal Session Log) is the storage-first reference implementation of the Agent Session Protocol. It is a complete database for agent session logs — not just a library:
| component | what it is | where |
|---|---|---|
| Storage format | append-only single file, framed records + CRC | crates/usl-core/src/format.rs |
| Query API | scan / get / verify / fromSeq over sessions | crates/usl-core/src/store.rs |
| Query plane | SessionQL, typed Query IR, search, lineage, subscriptions | RFC 0001 (Draft) |
| Durability & recovery | group-commit append, crash recovery from the log | crates/usl-core/src/recover.rs |
| Identity | content-addressed session ids | crates/usl-core/src/identity.rs |
| Live capture | file-boundary ingest, chunk-invariant framing | crates/usl-capture/ |
| Conversion | pi / dimagent / claude / codex inter-conversion | packages/usl-convert/ |
USL is schema-agnostic: the engine stores opaque records (seq + session_id + kind + ts + body); the ASP canonical schema lives a layer above. That separation is what makes it a database rather than a format.
Why USL
Agent runtimes proliferate, and each locks its session history in its own log format. USL is the durable, portable layer underneath: any runtime's session can be ingested, queried, recovered after a crash, and converted into another runtime's resumable format.
Where to start
- Getting started — open a store, append, scan.
- Storage format — the on-disk byte layout.
- Query API — what you can ask of a store.
- SessionQL — the draft portable query language and typed IR.
- Search & indexing — evidence-bearing search, snapshots, and sidecars.
- Insights & subscriptions — derived knowledge and replay-plus-tail audit streams.
- Live capture — ingesting a running harness's log.
- Conversion — moving sessions across harnesses.
- Architecture — the whole picture, with a diagram.