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

   Recording a correction with trw_learn(learning_id=...) updates an entry; 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(). CLI trw-mcp 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

What each test shows, and where it stops. None of them is a promise about your repository, your model or your coding tool.

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 15 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

Every checkout on a machine uses one store, at ~/.trw, served by the memory daemon. Learnings live in one of two namespaces in it. The project tier is the default — repo-specific knowledge in the checkout's own namespace, which install pins as project_namespace and grants to that checkout. The user tier is the user:local namespace that every checkout on the 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. 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 user:local
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() reads 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 per-project retrieval contract; use client memory according to that client's documented scope and loading behavior.

Where learnings live

TRW memory is local-first. The store is a SQLite file on your machine, served by the trw-mcp memory daemon, with one namespace per project, so the base workflow does not depend on a hosted service. Your repo's .trw/ directory holds the project's settings and a YAML copy of each learning, not the searchable store.

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