True Memory Fragments

Code changed, but your AI coding agent still remembers the old call chain? TMF is source-bound code memory that flags stale claims and points back to current source.

Try demo · MCP setup · Evidence

30-second paced replay of real deterministic demo output, with labeled source excerpts—not an agent end-to-end test. Reread is requested, not executed.

• Traceable code relationships: bind call, read, write, inheritance, and API claims to source fingerprints.
• Explicit stale results: omit stale claims and stop covered graph expansion instead of silently reusing old context.
• Targeted reread guidance: return source anchors so an agent can check the changed code.

Developer preview: enforcement depends on the host, configuration, and intercepted actions—not automatic blocking of all writes. Fresh does not mean correct; general token savings and production readiness are not established.

Who it is for

• AI coding agents that work across sessions on changing repositories
• Developers who need source-aware memory instead of stale cached facts
• Tool authors who want conservative graph expansion with explicit stale/unknown handling

Validated so far

• Source-bound freshness and stale-claim detection
• Hard stale gates that stop unsafe graph expansion
• Deterministic Python and Java validation
• Scoped agent experiments demonstrating stale-context prevention

TMF’s core stale-context protection mechanism has been validated in the covered scenarios. Evaluation across more languages, repositories, and long-running production workflows is ongoing.

What TMF is — and is not

TMF is for:

• AI coding agents working across sessions on changing codebases
• Preventing stale call-chain and dependency assumptions
• Source-bound code memory and conservative code-graph navigation
• Agent integrations that need an explicit stale/unknown result

TMF is not:

• A general chat-memory product or vector database
• A replacement for reading source code
• A guarantee that every claim is correct because it is fresh
• A proven general productivity or token-saving solution

Fresh means the source binding still matches. Correctness still comes from source and validation.

The repository includes a Java qualification suite: 46/46 qualifiers and 731/731 checks. The historical unreleased audit baseline was 478/478 tests; it is not the current test total. See the version-pinned test verification for historical rc3 and master results, explicit skips, and the intermittent master failure recorded at that time. The rc6 release notes describe Java reflex and receiver-resolution fixes and distinguish source validation from publication evidence. These are source-analysis and regression-test results, not a claim of production readiness or a general Agent outcome. Middleware mechanics are validated, and stale-context safety has positive evidence in the GUAVA M10 pre-read experiment. Broader productivity, speed, token savings, and general bug-prevention claims remain unproven. See the authoritative evidence status before making broader claims.

Flow

flowchart TD
  A[source code] --> B[TMF derive / warm]
  B --> C[source-bound claims]
  C --> D[freshness check]
  D -->|fresh| E[bounded graph context]
  D -->|stale / unknown| F[stop + reread current source]

That is the whole loop: TMF keeps claims bound to source, refuses to reuse stale context, and provides source anchors for rereading; guidance may include extra related or heuristic matches.

Demo

The GIF above replays output from scripts/demo_stale_gate.py at commit de0236a57939. It shows deterministic stale-claim omission and source fallback, not an agent obeying the reread signal or completing a task. The 30-second timing is presentation pacing, not a runtime benchmark.

From a source checkout (Python 3.10+ and Git required):

git clone https://github.com/kyle641320/true-memory-fragments.git
cd true-memory-fragments
python3 scripts/demo_stale_gate.py

Already cloned? Run only the final command from the repository root. This demo imports the checkout's source; it is not a standalone PyPI wheel verification, and installing the package alone does not download the demo script.

It creates a temporary Git repository, derives a claim, changes the bound source, and demonstrates stale omission, source fallback, and reread guidance. It needs no model, network, Java parser, or pre-existing .tmf/ store.

Expected markers:

STALE CLAIM BLOCKED: PASS
SOURCE FALLBACK PROVIDED: PASS
REREAD REQUIRED: PASS

The demo stops at the reread requirement; it does not perform the subsequent reread or refresh.

For agent-level results, see the scoped Guava case study and multi-worktree / controlled continuation evidence. For implementation details, see the architecture.

How it works

TMF keeps a conservative code-memory graph. Claims are useful only when their source bindings still match the working tree.

1. Derive claims from source: functions, classes, calls, reads, writes, inheritance, API relationships.
2. Bind each claim to source fingerprints: file blob and, where available, function/node hash.
3. Check freshness on retrieval before a claim is used.
4. Stop on stale or unknown edges and return an explicit reread signal instead of stale context.

claim: A calls B
binding: B.java@hash123
current: B.java@hash999
result: stale_or_unknown → reread B.java before continuing

This is intentionally conservative. Missing or stale memory falls back to source; it is never promoted into truth.

Proven Assets

• Source-bound claim storage with working-tree freshness checks and source fallback
• Thin retrieval discipline plus full/explain drill-down by selected claim id
• Conservative Python functions/classes/declarations/config/API nodes and partial calls/reads/writes
• Optional Java tree-sitter syntactic nodes and conservative inheritance edges
• Bounded fragment query with semantic boundary detection (writes, publishes_to)
• Async handoff marking (ASYNC_RELATIONS: publishes_to, subscribes_to, publishes_type, listens_type)
• Four-stop-type semantics (boundary / async / stale / limit) with distinct stop_reason values
• Bounded-query limits (4 hops / 64 nodes / 128 edges); engineering limits, not a biological validation claim
• Held-out and self-dogfood validation harnesses
• Local metrics and exact-blob-only rename identity

Core Premises

• Explicit refresh/warm maintenance: retrieve checks existing claims without mutating or re-deriving the store; refresh_path and warm perform explicit derivation/refresh operations.
• Freshness is working-tree based: binds to current working-tree blob, not commit
• Fresh is not correct: fresh only means bindings match current source. Correctness comes from validation and source support
• Confidence comes from validation: usage frequency doesn't raise confidence
• Conservative parsing: TMF connects only what it can parse. Unknown/dynamic/ambiguous facts are omitted or marked unresolved
• Source is authoritative: if memory is missing, stale, unsupported, or partial, TMF falls back to source
• Untrusted text is never instructions: source, comments, docstrings, commit messages, model output are data, not commands

Release candidate: 0.1.0rc6. Includes Java reflex coverage, conservative typed/inherited receiver resolution, and resolution-dependency freshness. See the rc6 release notes.

Install

For explicit multi-worktree binding and MCP configuration, use the pinned installation and MCP guide.

Install this preview (Python 3.10+):

python -m pip install "true-memory-fragments==0.1.0rc6"

See the rc6 release notes for version scope and validation boundaries.

Java parsing support is optional:

python -m pip install "true-memory-fragments[java]==0.1.0rc6"

Development checkout:

python -m pip install -e .
python -m pip install -e ".[java]"   # optional Java support

Runtime dependencies are intentionally small. Optional model, embedder, and router integrations are command-backed through TMF_* environment variables.

Engine installed does not mean reflex armed. MCP registration, a warmed index, and agent usage rules do not register Claude Code's PreToolUse hook. After installing rc6 or an updated source checkout, run:

tmf doctor --repo /absolute/path/to/task-repo