Transcript Lake is the local, privacy-masked canonical archive for coding-agent conversations. It reads supported vendor transcript stores without modifying them, normalizes their records into one event schema, masks credential-shaped text before durable output, and keeps append-only daily NDJSON partitions that can be queried through DuckDB.
It is useful when one machine has conversations in several coding-agent harnesses and Tama hook telemetry, and the operator needs one inspectable history instead of separate vendor formats. transcript-lake sources --json lists the adapter registry and the roots it discovers on the current machine; the ingestion reference explains supported store modes and qualification.
The four-owner boundary#
| Owner | Owns | Relationship to the Lake |
|---|---|---|
| Vendor runtimes | Raw transcript stores on disk | Transcript Lake reads them; it never rewrites, migrates, adopts, or deletes them. |
| Transcript Lake | Masked canonical partitions, durable cursors, and exports/oko | This repository defines and writes these artifacts. |
| Oko | Its merged catalogue, rebuildable search projection, sessions its broker started, and Oko bookkeeping | Oko scans the Lake export read-only. It does not mask transcripts or write under LAKE_DATA. |
| Oko Desktop | Native application lifecycle and UI | It consumes Oko; it replaces neither Transcript Lake nor the Oko executables. |
The boundary is operational: deleting a vendor store destroys vendor-owned history; deleting Lake partitions destroys the canonical masked archive; deleting an Oko catalogue removes a rebuildable index, not the archive.
What it does#
- Discovers supported transcript roots under the current
HOME. - Watches existing roots and catches up from newline-aligned byte cursors.
- Parses vendor records into provider-neutral raw events.
- Applies the single masking boundary to
textand retained string data. - Caps retained values and writes canonical events to daily runtime partitions.
- Materializes the affected per-session Oko export.
- Advances the source cursor only after durable outputs succeed.
- Exposes bounded read commands, DuckDB views, labels, Parquet mirrors, and recovery replay.
What it does not do#
- It does not own or mutate raw transcripts.
- It does not promise anonymization. Project paths, timestamps, session identifiers, model names, tool names, machine identity, short secrets outside the documented patterns, and ordinary conversation text can remain sensitive.
- It does not route model calls, own provider credentials, or manage remote retained history.
- It does not make Oko the archive.
exports/okois a rebuildable projection of the Lake. - It does not automatically delete authoritative events or individual records.
- It does not support Gemini or Qwen transcript adapters in this revision.
Start here#
The existing data contract, core contract, integration contracts, onboarding guide, and release policy remain normative.