Core concepts

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.

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.

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.

Stored impact and Q-value contribute to query-time utility alongside retention, access, and source signals. 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.

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.

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

Phases

TRW names six lifecycle phases, but ceremony tier determines which ones a task uses. Validation is always present; Research appears only in COMPREHENSIVE work. The phase names make evidence and handoffs legible without forcing every task through the longest path.

When validation or review exposes a problem, return to the work that needs correction. Phase progression warns and proceeds by default unless stricter configuration applies. See the Lifecycle page for full detail on each phase, reversion rules, and exit criteria.

Ceremony

Ceremony matches lifecycle depth to task complexity. A narrow fix still implements, validates, and delivers. STANDARD work adds planning and review. COMPREHENSIVE work adds a distinct Research phase.

The resolved profile and active run complexity influence the effective ceremony behavior. You can inspect or override relevant settings in configuration.

Phase gates

TRW uses three distinct policy layers. Phase exit criteria guide progression. A validation receipt records caller-run evidence. The server-side delivery gate applies the hard, task-scoped requirement for coding, RCA, and eval work.

Putting it together

This illustrative sequence shows the explicit calls in a validated workflow. Actual commands, counts, findings, and scope must come from the repository being changed.

# Recall candidates and active-run state
trw_session_start()

# Optional focused recall
trw_recall("authentication middleware")

# Track and checkpoint the work
trw_init("auth-refactor")
trw_checkpoint(
  "JWT validation extracted; tests next"
)

# Run checks, then record the outcome
pytest tests/auth -q
mypy src/auth
trw_build_check(
  tests_passed=True,
  test_count=24,
  failure_count=0,
  static_checks_clean=True,
  scope="tests/auth",
)

# Record a substantive diff review
trw_review(
  findings=[],
  review_completed=True,
)

# Preserve a reusable discovery
trw_learn(
  "JWT validation must check aud",
  "Verified in src/auth/jwt.py",
)

# Evaluate gate and persist
trw_deliver()

Where to go next

Continue into lifecycle if you want the operational flow. Continue into requirements if you want to see how that flow turns into PRDs and sprint plans. Continue into memory if you want to understand explicit recall, scoring, and evidence boundaries.