Documentation / development channel
Build a durable memory
for agent work.
Learn the stream contract, privacy boundary, data model, operations, recovery paths, and every supported outcome in Transcript Lake.
Start here
04 topicsOnboarding
This guide moves a new operator from a clean macOS environment to the first observable Transcript Lake result. Core streaming is local, requires no account or credential, and never modifies vendor transcript stores.
→Start hereConfiguration reference
Transcript Lake has no configuration file. Configuration is the global --data-dir flag, environment variables, command flags, and external binaries on PATH. Empty environment values are treated as unset unless stated otherwise.
→Start hereQuick start: a synthetic local Lake
This quick start was executed against Transcript Lake 0.2.0 on 2026-08-24 with DuckDB 1.5.5. It used a synthetic Claude-format fixture under an isolated HOME; no real transcript was opened and no credential was used.
→Start hereWhat is Transcript Lake?
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 outpu
→Understand
05 topicsCore functionality contract
This document defines the smallest provider-neutral system that fulfills Transcript Lake's README promise. Integrations may consume or extend these contracts but cannot redefine them.
→UnderstandTranscript Lake
A single, privacy-masked, real-time archive of the coding-agent conversations on this machine, queryable with plain SQL through DuckDB.
→UnderstandArchitecture
Runtime adapters interpret native transcript stores; shared readers handle appended lines and whole stores, then canonicalize, mask, and publish events. Tama telemetry enters through its separate segment reader.
→UnderstandIngestion pipeline reference
A directory that disappears during discovery yields no entries; an entry that exists but cannot be read is named on stderr with its cause. A complete line that is not JSON emits no event and is named with its byte offset, file and parser error.
→UnderstandMasking guarantees and limits
Masking is the boundary between adapter output and every durable Lake event. Adapters parse unmasked vendor records in memory; only the stream canonicalizer may write partitions or Oko projections.
→Concepts
08 topicsConcept: cursor and writer lease
A source cursor records a complete-line boundary, verified source prefix, and file identity. Rewritten journals recover missing history without duplicating retained events.
→ConceptsConcept: canonical event
A canonical event is the smallest durable unit in Transcript Lake: one masked, provider-neutral observation serialized as one NDJSON line.
→ConceptsConcept: export and derived data
An export is a rebuildable representation of authoritative NDJSON partitions.
→ConceptsConcept: label
A label is an operator-owned aspect/value annotation over an existing Lake session. Each assignment appends one fsynced line to LAKEDATA/labels/labels.ndjson with timestamp, session id, runtime, normalized aspect, value, optional note, and provenance source.
→ConceptsConcept: masking
Masking is a deterministic string transformation applied after vendor parsing and before durable Lake output. It replaces each complete detected assignment, provider-shaped token, or guarded high-entropy run with [masked:<class>:<length>:<fingerprint>].
→ConceptsConcept: partition
A partition is an append-only daily NDJSON file of canonical masked events:
→ConceptsConcept: runtime and adapter
A runtime is the stable origin namespace attached to every canonical event: one per harness in the adapter registry, or hooks.
→ConceptsConcept: session
A session is the runtime-native conversation identity aggregated from canonical events. The stable key is (runtime, sessionid); project is best-effort metadata, not identity.
→Operate
35 topicsIntegration contracts
Transcript Lake's core is the local masking, partition, cursor, status, and query model defined in the core contract. Integrations translate external formats at narrow boundaries and may fail without invalidating unrelated core state.
→OperateRelease and versioning policy
Transcript Lake versions its CLI and durable archive contract together. Releases identify exact committed source, qualified artifacts, source-prefix migration, and rollback limits.
→OperateCLI command reference
Exact invocations, inputs, outputs, state effects, and source-grounded refusals for every public Transcript Lake CLI command.
→CLItranscript-lake paths
Print every resolved Transcript Lake, derived-data, DuckDB, Tama, and Oko path.
→CLItranscript-lake sources
Discover supported transcript and hook stores and count candidate files.
→CLIadopt
Validate, ingest, and persist one discovered existing transcript source through Transcript Lake's canonical boundary.
→CLItranscript-lake doctor
Check the declared masking policy, state, cursors, source discovery, DuckDB, and Oko availability.
→CLItranscript-lake status
Inspect Lake partitions, cursor health, live-stream state, and Oko freshness.
→CLItranscript-lake stream
Continuously catch up supported sources and commit masked appends into the Lake and Oko projection.
→CLItranscript-lake rebuild
Replay source history through the masker into a separate empty recovery Lake.
→CLItranscript-lake reconcile
Supersede canonical rows that the current adapter projects differently from their retained original.
→CLItranscript-lake sessions
List the newest sessions from the canonical DuckDB views.
→CLItranscript-lake events
List the newest masked canonical events.
→CLItranscript-lake search
Search masked event text using a case-insensitive literal substring.
→CLItranscript-lake show
Reconstruct one masked conversation in chronological order.
→CLItranscript-lake stats
Summarize recent Lake activity and token counters by runtime.
→CLItranscript-lake hooks
Inspect canonical adaptive-hook decision events.
→CLItranscript-lake signals
Query cross-source Oko/Lake signal views.
→CLItranscript-lake label
Route operator label writes and label analytics to a public subcommand.
→CLItranscript-lake label add
Append one durable, provenance-bearing label to an existing Lake session.
→CLItranscript-lake label remove
Withdraw the label in force for one session and aspect by appending a record with no value; the history stays whole.
→CLItranscript-lake label list
List the latest label assignment per session and aspect.
→CLItranscript-lake label aspects
Summarize the currently assigned label aspects.
→CLItranscript-lake goal
Route local goal-title inference or model-produced goal labeling.
→CLItranscript-lake goal title
Distill caller-supplied text into a short goal title with the qualified local GGUF.
→CLItranscript-lake goal label
Infer a goal from a session’s first masked user prompt and persist it as a model label.
→CLItranscript-lake query
Execute operator-supplied DuckDB SQL after loading the canonical Lake views.
→CLItranscript-lake compact
Rebuild per-runtime Parquet mirrors from authoritative NDJSON partitions.
→CLItranscript-lake projection
Reconstruct the per-session projection one consumer imports from authoritative Lake partitions, or hand the current projection to that consumer's own CLI; the consumer is an adapter behind the operation.
→CLItranscript-lake clean
Preview or remove rebuildable derived data without touching canonical evidence.
→CLItranscript-lake onboarding
Walk the first-use journey and optionally adopt one discovered source through the canonical ingestion boundary.
→CLItranscript-lake help
Print general guidance or exact syntax for one public top-level command.
→OperateOperator runbook
Preserve evidence before intervention. Never edit vendor transcripts, partitions, or cursors in place. Use transcript-lake paths, sources, doctor, and status --json to identify the selected root and failure domain.
→OperateWalkthrough: catch up and commit a synthetic live append
This walkthrough records an execution performed on 2026-08-24 against an isolated synthetic Claude transcript. It demonstrates the online path without opening any real transcript.
→OperateWalkthrough: audit synthetic masking and derived output
This walkthrough uses the same isolated 2026-08-24 synthetic fixture as the live-append walkthrough. All apparent credentials were invented specifically to exercise the three masker classes.
→Examples
19 topicsTranscript Lake examples
This is the canonical catalog of supported user outcomes for the development channel. Each example uses the installed transcript-lake interface, names its risks and side effects, includes observable verification and a representative failure path, and owns its
→ExamplesCLI tour
1. Goal: Use the installed executable for streaming, inspection, analytics, projection recovery, and safe reconstruction. 2. Risk: Streaming and labels mutate local Lake state; compaction and export mutate rebuildable projections. Oko and DuckDB are optional.
→ExamplesInspect zero state and product identity
1. Goal: Confirm the installed product identity and inspect configuration without creating Lake state. 2. Risk: Read-only. 3. Environment: macOS terminal with installed transcript-lake. 4. Preconditions: Choose a path that does not exist and is not used by ano
→ExamplesKeep a Lake current with the live stream
1. Goal: Follow complete source bytes as agents append them, without periodic rescans. 2. Risk: Local mutation and provider-facing reads. 3. Environment: macOS terminal with installed Transcript Lake and one existing valid Lake. 4. Preconditions: No other writ
→ExamplesQuery cross-runtime sessions
1. Goal: Retrieve recent masked session summaries across every streamed runtime, single out conversations left unfinished, and locate events containing literal text. 2. Risk: Read-only for the documented query; external DuckDB process. 3. Environment: macOS te
→ExamplesRestore one conversation
Outcome: read a past coding-agent conversation back in full — in order, untruncated — after the runtime that produced it has moved on, closed the session, or stopped mid-turn.
→ExamplesDiagnose representative failures
1. Goal: Interpret invalid input, missing dependencies, source-local failures, and writer contention without guessing from exit status alone. 2. Risk: Read-only except for the ordinary live stream. Never alter vendor files to manufacture a failure. 3. Environm
→ExamplesCreate the first local archive
1. Goal: Install the development build, start the stream, and observe its masked Lake inventory. 2. Risk: Local mutation and provider-facing read. No network or credential use after installation. 3. Environment: macOS, local user account, isolated terminal, re
→ExamplesQuery cross-source signals with Oko
1. Goal: Join masked Lake events with the local Oko transcript index to inspect hook decisions and frustration signals. 2. Risk: Read-only, external DuckDB process. A fresh DuckDB installation may fetch and cache the SQLite extension. 3. Environment: macOS, Du
→ExamplesReconstruct the Oko projection
1. Goal: Rebuild masked per-session JSONL from authoritative Lake partitions after projection loss or damage. 2. Risk: Derived local mutation. Oko is not invoked unless --reindex is supplied. 3. Environment: macOS terminal and valid Lake partitions. Oko instal
→ExamplesReindex Oko after projection changes
1. Goal: Make Lake sessions searchable in Oko after the live projection or a reconstruction changes. 2. Risk: Derived mutation in Oko's local SQLite index and external process invocation. 3. Environment: macOS, valid Lake projection, compatible installed oko-c
→ExamplesStream Tama hook decisions
1. Goal: Stream closed, validated adaptive-hook decision segments without double counting legacy telemetry. 2. Risk: Local mutation and provider-facing read. No hook control or runtime reload occurs. 3. Environment: macOS, Transcript Lake, and a Tama producer
→ExamplesBuild release assets
Run real source recovery journeys, submit one committed revision through Stado, and inspect exact publication receipts and refusals.
→ExamplesCompact partitions to Parquet
1. Goal: Create faster-scanning Parquet mirrors without replacing authoritative NDJSON evidence. 2. Risk: Derived local mutation and external DuckDB process. 3. Environment: macOS terminal, valid Lake, DuckDB CLI 1.5.x. 4. Preconditions: Sufficient free disk f
→ExamplesReset local state and uninstall
1. Goal: Remove the executable and, only by explicit separate decision, remove retained local Lake data. 2. Risk: Destructive and irreversible for deleted local data. 3. Environment: macOS terminal and known installed package/state paths. 4. Preconditions: Sto
→ExamplesUpgrade and roll back an exact release
Check exact release provenance, the supervised stream, and the 0.2.1 source checkpoint boundary before upgrading or rolling back.
→ExamplesRebuild into an empty root
Reconstruct damaged authoritative state into a separate empty Lake while preserving the old root. Ordinary source rewrites recover automatically without this operation.
→ExamplesSynthetic example: live append
Status: executed 2026-08-24. Risk: isolated local mutation only. Input: invented Claude-format JSONL. No real transcripts, credentials, provider calls, or network actions.
→ExamplesSynthetic example: masking audit
Status: executed 2026-08-24. Risk: read-only inspection of an isolated synthetic Lake; optional derived local mutation for compact. No real transcripts.
→