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 topicsWhat 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
→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 hereOnboarding
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.
→Understand
05 topicsArchitecture
src/adapters/ implements one pure line parser for Claude, Codex, omp, Factory Droid, and Kimi. src/hooksegments.rs ingests Tama closed segments or the legacy hook log. Adapters own vendor-field interpretation, not masking or IO. Malformed/incomplete lines yiel
→UnderstandCore 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.
→UnderstandIngestion pipeline reference
Directory disappearance during discovery yields no entries. Unowned paths and unrelated artifacts are ignored. Parsers tolerate malformed and torn lines by emitting no event; complete prior lines still stream.
→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 byte cursor records how far Transcript Lake has consumed one append-only source file:
→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: claude, codex, omp, droid, kimi, 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
06 topicsCLI reference
No command, -h, or --help prints general help without reading or writing state. -V/--version prints the package version. help [command] accepts at most one exact command name. Global --data-dir may appear anywhere, must appear once, and selects an absolute roo
→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.
→OperateIntegration contracts
Transcript Lake's core is the local masking, partition, cursor, status, and query model defined in core contract. Integrations translate external formats at narrow boundaries and may fail without invalidating unrelated core state.
→OperateRelease and versioning policy
The distribution coordinate is the transcript-lake crate in this repository. Cargo.toml is the single canonical source of the product version; the build compiles it into the binary, so the installed transcript-lake --version command cannot disagree with the ar
→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
1. Goal: Produce an attributable binary archive, checksum, and provenance record for one exact release candidate. 2. Status: Release tooling implemented; publication and qualification pending. 3. Risk: Local build mutation and publication preparation. Building
→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
1. Goal: Replace one immutable Transcript Lake release with another while retaining a reversible state boundary. 2. Status: Release process defined; no immutable release is currently published, so commands are templates pending a real release. 3. Risk: Network
→ExamplesRebuild into an empty root
1. Goal: Recover from cursor damage or non-append source change without risking the existing Lake. 2. Risk: Destructive/recovery workflow and provider-facing read. No deletion is part of the recovery command. 3. Environment: macOS, installed Transcript Lake, s
→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.
→