Memory and knowledge

The knowledge flywheel

TRW's architecture is built around a reinforcing loop: capture what mattered, rank it by usefulness, and retrieve it when a later task asks for it. Early sessions can produce raw learnings; later sessions explicitly recall candidates and re-check them against the current repository.

How it works

A learning can move through six explicit stages from initial discovery to durable, revisable project context.

1. 1

   Learn

   Your AI discovers a gotcha, pattern, or architecture decision during work.

2. 2

   Persist

   trw_learn() stores the discovery in the project memory layer under .trw/ with tags and metadata.

3. 3

   Recall

   The agent explicitly calls session start or recall to retrieve ranked candidates.

4. 4

   Re-check

   The agent validates recalled context against the current repository before reuse.

5. 5

   Update

   Explicit feedback can update utility; stale entries can be superseded or retired.

6. 6

   Preserve

   The durable store remains available after context compaction and across later sessions.

Learning lifecycle

Every learning goes through a managed lifecycle. This is not a flat key-value store - it is a managed knowledge system with scoring, decay, feedback, and retirement.

Impact scoring

Not all learnings are equally useful for a query. TRW composes effective utility from four runtime inputs and uses that score as one signal in recall priority.

Scores range from 0.0 to 1.0. A high score affects ranking but does not copy a learning into a client instruction file. Low-value or stale entries can become consolidation or retirement candidates under the configured policy.

Instruction files and memory are separate

Learnings remain in the memory store and surface through trw_session_start() or trw_recall(). trw_instructions_sync() refreshes the TRW protocol in the selected client instruction file; it does not promote arbitrary learning content into that file.

Benchmark evidence and claim boundary

These measurements establish retrieval behavior on named surfaces. They do not establish a universal improvement rate for arbitrary repositories, tasks, models, or coding clients.

Memory tools

Four common MCP tools cover session startup, recording, retrieval, and updates. The agent or client invokes them explicitly; optional hooks are additive reminders, not the memory lifecycle itself.

See the Tools Reference for the complete list of all 45 MCP tools.

Code examples

Here is what the memory system looks like in practice across a typical session.

# AI discovers a gotcha during implementation:
trw_learn(
  summary="FastAPI dependency overrides must be reset in teardown",
  detail="Without resetting app.dependency_overrides in test teardown, "
         "overrides leak between tests causing flaky failures.",
  tags=["fastapi", "testing", "fixtures"]
)
# -> Learning recorded
# -> Impact score: 0.51
# -> Stored in the project learning store under .trw/

# Next session: AI is about to write FastAPI tests
trw_recall("fastapi testing fixtures")
# -> 3 relevant learnings found:
#
#   [0.72] FastAPI dependency overrides must be reset in teardown
#          tags: fastapi, testing, fixtures
#
#   [0.65] TestClient requires app factory pattern for isolation
#          tags: fastapi, testing
#
#   [0.41] pytest-asyncio auto mode conflicts with sync fixtures
#          tags: pytest, async, testing

# End of session: deliver checks policy and persists delivery state
trw_deliver()
# -> Build gate: PASS (caller-reported project checks)
# -> Delivery state persisted
# -> Run closed: api-tests-refactor

Project and user tiers

Learnings live in one of two tiers. The project tier is the default — repo-specific knowledge stored under .trw/ in the project namespace. Whether that state travels with the codebase depends on repository policy. The opt-in user tier is a machine-local store at ~/.trw (or your XDG data dir) that every repo on the same machine shares, so portable knowledge follows you instead of being relearned in each project.

Routing a learning

trw_learn() takes a scope argument. "auto" (the default) classifies portability and routes accordingly: a finding with a repo-relative path or local symbol stays in the project tier, while a cross-cutting preference or workflow rule goes to the user tier when one is present. Passing "project" or "user" overrides the classifier.

# Repo-specific gotcha -> stays in the project tier (.trw/)
trw_learn(
  summary="Reset app.dependency_overrides in test teardown",
  detail="Leaks between tests in src/api/conftest.py cause flaky failures.",
  tags=["fastapi", "testing"]
)  # scope="auto" -> project (a repo-local path was detected)

# Cross-cutting preference -> routes to the user tier (~/.trw) when enabled
trw_learn(
  summary="Prefer path-limited git commits to avoid index races",
  detail="Holds across every repo; not tied to one codebase.",
  tags=["workflow", "git"]
)  # scope="auto" -> user (portable, no repo-local signal)

# Force a tier explicitly when you know better than the classifier
trw_learn(summary="...", detail="...", scope="user")

Recall across tiers

trw_recall() federates the project and user tiers into one ranked result, so a single query surfaces relevant learnings from both. A precise project hit keeps its rank; user-tier hits are bounded by recall_user_tier_cap (default 5) so a busy user store can never bury project precision. Pass include_tiers=["project"] to restrict a recall to the project tier only.

Memory routing

TRW memory and a coding client's native memory can coexist. Use TRW when you need an explicit MCP lifecycle and project-local retrieval contract; use client memory according to that client's documented scope and loading behavior.

Where learnings live

TRW memory is project-local and travels with your repo. The runtime uses a local storage layer under .trw/, so the base workflow does not depend on a hosted service.

Some memory artifacts are human-readable, while the retrieval layer is optimized for local search performance rather than hand-editing every internal file. Treat .trw/ as project state managed by TRW, and use the memory tools for normal day-to-day updates.

Next steps