Docs

Core concepts

TRW separates temporary conversation context from durable records. This page explains the small set of boundaries that matter before you choose tools or configuration: what is explicit, what is advisory, and what can block delivery.

The mental model

TRW does not preserve an entire conversation. It gives agents explicit tools for carrying selected knowledge, resumable work, and validation evidence across session boundaries.

Concept: Session
What it is: One client conversation and its available context window
Boundary: Temporary by default; TRW records only what tools explicitly preserve

Concept: Run
What it is: A tracked unit of work with phases, checkpoints, and artifacts
Boundary: A checkpoint provides a concrete resume record after interruption

Concept: Learning
What it is: A selected discovery recorded with trw_learn
Boundary: Recall returns a candidate to verify, not an automatically trusted instruction

Concept: Validation receipt
What it is: Caller-reported evidence from project-native checks
Boundary: Records what ran and passed; TRW does not execute the checks itself

Concept: Delivery boundary
What it is: The task-scoped gate evaluated by trw_deliver
Boundary: Coding delivery needs a passing receipt, a structured acceptable-failure record, or an authorized override

Concept	What it is	Boundary
Session	One client conversation and its available context window	Temporary by default; TRW records only what tools explicitly preserve
Run	A tracked unit of work with phases, checkpoints, and artifacts	A checkpoint provides a concrete resume record after interruption
Learning	A selected discovery recorded with trw_learn	Recall returns a candidate to verify, not an automatically trusted instruction
Validation receipt	Caller-reported evidence from project-native checks	Records what ran and passed; TRW does not execute the checks itself
Delivery boundary	The task-scoped gate evaluated by trw_deliver	Coding delivery needs a passing receipt, a structured acceptable-failure record, or an authorized override

Sessions are temporary; records are explicit

A session is one client conversation and its available context window. Conversation state can disappear when the session closes or compacts. TRW does not copy that whole window into the next session.

The agent or client calls trw_session_start() as its first TRW action to retrieve bounded learning candidates and detect an active run. It then verifies recalled context against the current repository before reuse.

Runs preserve resumable work state

A run is a named unit of work with checkpoints and lifecycle state under .trw/runs/. trw_checkpoint() records a milestone so an interrupted task has a concrete resume point.

A later trw_session_start() can report the active run and its last checkpoint. Recovery is explicit: the agent inspects that record and continues from current source, rather than assuming the old plan is still correct.

illustrative run sequence

trw_init("auth-refactor")

trw_checkpoint("middleware complete; targeted tests are next")

# Later, after interruption or compaction:
trw_session_start()
# Inspect the returned active run and checkpoint before continuing.

Learnings preserve selected discoveries

A learning is a deliberately recorded pattern, gotcha, or decision. The agent calls trw_learn() with a useful summary, detail, and optional tags. Merely mentioning something in chat or calling trw_deliver() does not turn every discovery into memory.

Recall ranks entries by relevance to the query; ties break on utility, which is the entry's impact under time decay and recall-frequency decay. No reward or outcome signal feeds the ranking. A recalled entry remains a candidate to re-check. Learning memory and client instruction files are separate; delivery does not promote arbitrary entries into startup instructions.

record a reusable finding

trw_learn(
  "SQLite WAL mode required for concurrent readers",
  "Without WAL, concurrent reads block on writes in src/storage.py.",
  tags=["sqlite", "concurrency"]
)
# A later trw_recall("sqlite") may return this as a candidate to verify.

The continuity loop

The product mechanism is modest: record selected state, retrieve relevant candidates, verify them, and update or retire them when explicit evidence changes. This can reduce rediscovery; it does not prove that every later session performs better.

explicit continuity loop

Record selected state
        ↓
Recall bounded candidates
        ↓
Verify against current source
        ↓
Update, supersede, or retire explicitly

Process and evidence

TRW names phases, records caller-run validation, and checks delivery requirements. The details belong on the lifecycle page; client hooks can provide reminders but remain optional adapters.