Memory and knowledge

The knowledge flywheel

TRW's architecture is built around a reinforcing loop: capture what mattered, rank it by usefulness, and surface it when the next task needs it. Early sessions produce raw learnings. Later sessions inherit refined, higher-signal guidance automatically.

How it works

A learning flows through six stages from initial discovery to permanent 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

   Future sessions search past learnings via trw_recall() - hybrid keyword + semantic match.

4. 4

   Apply

   The AI uses recalled knowledge to avoid known mistakes and follow proven patterns.

5. 5

   Improve

   Each recall boosts the learning's impact score. Unused learnings decay naturally.

6. 6

   Promote

   High-impact learnings get promoted into the repo’s instruction surfaces - permanent context for future sessions.

Learning lifecycle

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

Impact scoring

Not all learnings are equal. TRW scores each learning across four dimensions and uses the composite score to determine recall priority, decay rate, and promotion eligibility.

Scores range from 0.0 to 1.0. Learnings above 0.7 are considered high-impact and eligible for startup instruction promotion. Learnings that decay below 0.1 are candidates for pruning during consolidation.

Instruction surface promotion

The most valuable learnings graduate from the learning store into CLAUDE.md, .cursor/rules/, .codex/INSTRUCTIONS.md, GEMINI.md, or the other startup surfaces your repo targets. This means high-impact discoveries become permanent context without manual curation.

# Learning recorded in session 12:
trw_learn(
  summary="SQLite WAL mode required for concurrent reads",
  detail="Without WAL, parallel test runners deadlock on write",
  tags=["sqlite", "testing"]
)
# -> Impact score: 0.45 (new, untested)

# Session 18: recalled and applied successfully
# -> Impact score: 0.72 (boosted by utility + frequency)

# Session 22: trw_instructions_sync() refreshes the client instruction file
# -> Latest TRW protocol lives in the repo's startup instructions - loaded on every later session

Memory tools

Five MCP tools manage the full knowledge lifecycle. Your AI calls them automatically at the right moments - you see them in the activity log during sessions.

See the Tools Reference for the complete list of all 43 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 persists everything
trw_deliver()
# -> Build gate: PASS (312 tests, mypy clean)
# -> Learnings: 4 new, 2 updated, 1 promoted to startup instructions
# -> Instruction sync: +1 entry (FastAPI overrides gotcha)
# -> Run closed: api-tests-refactor (3h 12m)

Developer experience

MemoryConfig and MemoryEntry both implement __repr__ for quick inspection during debugging. Print any object in a REPL or log output and get a readable one-liner showing the most useful fields at a glance.

>>> print(config)
MemoryConfig(backend=sqlite, path=/home/user/.trw/memory, encryption=off, rbac=off)

>>> print(entry)
MemoryEntry(id=M-a1b2c3d4e5f6, content="Workstreams sprint: st...", tags=[sprint, integration], importance=0.8)

Project and user tiers

Learnings live in one of two tiers. The project tier is the default — repo-specific knowledge stored under .trw/ that travels with the codebase. 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 uses trw_learn() for knowledge, not the AI tool's native auto-memory. This is a deliberate architectural decision - here is why.

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