Project memory a later session can explicitly recall
TRW Memory stores selected project learnings outside the conversation that produced them. When the agent calls session start or recall, ranked candidates can be added to context and re-checked before substantive work; optional graph expansion is shown at right.
Memory that survives compaction
Learnings use a project-local SQLite store with no hosted service required. Optional backup and sync surfaces depend on configuration. Project data lives under .trw/ inside your repo and travels with it.
Durable storage survives conversation compaction, but context injection is still an explicit ceremony action. The agent or client calls trw_session_start() first, or uses trw_recall(), to retrieve candidates again before substantive work.
id: M-a3f2c1b9 summary: JWT refresh tokens need rotation on every use tags: [security, auth] importance: 0.93 q_value: 0.87 created_at: 2026-04-01T09:12:43Z outcome_history: - "tests_passed:delta=+0.08:session=249"
4000+
repository inventory, not outcome proof
Local
primary SQLite storage
Not just vectors. A scoring engine.
Retrieval combines keyword matching with dense vector similarity, and the fused ranking is adjusted by stored utility and retention signals. Learnings recalled often stay visible; learnings left unused quietly fade. Explicitly reported build outcomes can update utility; the retrieval path does not independently run or observe repository checks.
Query-time scoring reads the stored Q-value and applies the Ebbinghaus-style decay without mutating the entry. Q-value updates happen separately when explicit outcome feedback is recorded, and those updates persist the new score and observation state.
UTILITY FORMULA
utility = effective_q × retention
+ access_boost
retention = recurrence_strength
× exp(−(ln2 / 14d) × days_unused)
combined = 0.6 × relevance
+ 0.4 × utilityDecay is applied at query time, not mutated in storage. Entries fade unless reinforced by recall.
HYBRID RETRIEVAL PIPELINE
BM25 (keyword)
BM25Okapi sparse retrieval — exact match, token overlap
Dense (vector)
Cosine similarity via sqlite-vec — conceptual similarity
RRF fusion
Reciprocal Rank Fusion — entries present in both lists score higher
Utility re-rank
Combined relevance + utility score applied last
Graceful degradation: if embeddings are unavailable, BM25 runs alone. If BM25 is unavailable, dense runs alone. Neither being unavailable returns an empty list.
Measured, not asserted.
Every number here is a same-harness ablation — retrieval strategies compared on one fixed corpus and query set, each reported with its sample size and, where the claim is comparative, non-overlapping 95% confidence intervals or a paired test. These are not leaderboard claims. Review the broader claim boundary in the public benchmark tables and methodology. The retrieval gold set, rediscovery readout, and controlled recall benchmark are identified there with their sample sizes and caveats. The internal controlled readout is iter-30-membench-readout.
HYBRID BEATS EITHER RANKER ALONE · Recall@10
Gold set of real engineering learnings · n=889 typed queries · same-harness ablation
Same direction replicated on a second, independent benchmark (LongMemEval_S, n=500). Fusion earns its keep on temporal / multi-session questions — exact-match queries are near ceiling for every retriever.
BETTER RECALL PREVENTS RE-DISCOVERY · PRR (95% CI)
TRW's own active store · n=175 rediscoveries · Preventable Rediscovery Ratio
[0.649, 0.781]
[0.898, 0.969]
Share of near-duplicate learnings a recall would have caught before re-deriving them. Non-overlapping CIs: retrieval quality, not just storage, is what stops an agent re-learning what it knows.
KNOWLEDGE COMPOUNDING, MEASURED
58 / 58
with memory
0 / 50
without memory
paired McNemar p = 3.6×10⁻¹⁵ · 49 matched pairs
Controlled recall-dependent benchmark (H1-MEMORY-BENCH): with memory, agents solved every task that needed a fact recalled from an earlier session; without it, zero — the fact is absent by construction. Replicated on a second model family.
This proves the mechanism — cross-session recall lets an agent finish work it otherwise cannot. Whether it compounds into broad, end-to-end coding-task improvement is a separate question, and the measured answer so far is unfavourable: on SWE-bench Verified, TRW solved 56 of 112 paired-valid problems against the baseline’s 79 (McNemar p = 6.6×10⁻⁵). We treat that surface as contaminated and it settles nothing in either direction — but no general outcome-lift claim is supported today, and we will not make one.
A typed knowledge graph, not a flat index
Each learning can become a node and relationships can become typed edges. When a caller explicitly enables graph expansion, BFS traversal from a matched root can surface related entries that share no query keywords. Graph expansion is disabled on the default recall path; the hero demo visualizes the opt-in capability.
INFERRED SIMILARITY
similarityCosine similarity above threshold
tag_cooccurrenceShared tags, Jaccard-weighted
related_toGeneral associative relation
co_anchoredEntries anchor to one source
LIFECYCLE + PROVENANCE
consolidationMerge lineage
anchored_toBound to a source file
producedAction generated the entry
motivated_byCreated in response to another
supersedesNewer entry replaces an older one
DECLARED REASONING
same_root_causeOne failure mode
depends_onValidity depends on another entry
evidence_forEmpirical support for another entry
conflicts_withContradictory entries
When enabled, BFS traversal depth is capped at 3. Cross-edge propagation rates vary by type: evidence_for propagates impact at 30%, co_anchored at 20%, same_root_cause at 15%.
Required first call, inspectable recall path
TRW requires the agent to call trw_session_start() as its first TRW action. The call is explicit: storage does not autonomously place memories into a prompt, and optional client hooks are only additive reminders.
- 01Agent callsSession start supplies project and task context to the memory query.
- 02Memory ranksAvailable keyword, dense, and utility signals produce a bounded candidate list.
- 03Agent re-checksCandidates enter working context and must be verified against the current repository before reuse.
Explicit deposits use trw_learn(); targeted lookups use trw_recall().
Order is real; timings are omitted deliberately. Run-to-run latency varies by index size and whether embeddings are enabled.
Technical specification
DEFAULT PATH
OPTIONAL CONTROLS
PACKAGE SURFACE
What memory does not do
Accurate scoping saves debugging time later.
No pre-populated graph
The knowledge graph builds entirely from entries you deposit. A fresh install has no edges and no semantic clusters — those emerge over sessions.
Q-values need outcome feedback to matter
The scoring system needs explicitly reported test and build outcomes. Until then, scores reflect impact estimates, not observed utility.
Embeddings are optional
Dense vector search requires the [embeddings] and [vectors] extras. Without them, retrieval falls back to BM25 keyword matching only — still useful, not identical.
Memory does not self-correct wrong entries
If an agent stores an incorrect learning, it persists until it is explicitly forgotten or superseded. Memory is as reliable as the agents depositing into it.
Not a replacement for checkpoints
Memory stores learnings — patterns, gotchas, decisions. Checkpoints save resumable execution state. They are complementary, not interchangeable.
Recall is an explicit action
The agent or client must call session start or recall. Optional hooks can remind or invoke compatible paths, but storage alone does not inject context.
Graph expansion is opt-in
Typed graph traversal is available when recall enables graph expansion. The default recall path does not traverse graph neighbors.
Common questions
What is the difference between TRW Memory and Claude Code's built-in memory?
Does TRW Memory send code or project data to a server?
What happens to recalled learnings when context compacts?
How long before Memory starts being useful in a new project?
Give your agents persistent memory
Install the open framework, store one material project learning, then retrieve and re-check it from a later session. The tool signatures, defaults, and storage layout are in the memory spec.
# install
$ curl -fsSL https://trwframework.com/install.sh | bash