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.
- Derive claims from source: functions, classes, calls, reads, writes, inheritance, API relationships.
- Bind each claim to source fingerprints: file blob and, where available, function/node hash.
- Check freshness on retrieval before a claim is used.
- 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]"
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
Absent or ineffective registration returns nonzero with
reflex NOT armed — operating as opt-in memory. This checks configuration,
not runtime firing. See reflex setup and diagnostics.
Doctor was introduced in rc5; rc6 also detects recognized Java-blind legacy hooks.
Existing reflex deployments must update the whole integration directory, not
just the engine wheel. Install the [java] extra in the hook interpreter,
then run a normal tmf warm --repo /absolute/path/to/task-repo to refresh older
Java derivations. Static doctor success is not proof of host dispatch.
Quick Start
Start with the 30-second stale-gate demo above. Share installation or reproduction feedback in Discussion #1.
Offline Java verifier
For Linux x86_64 / CPython 3.12 source checkouts, the repository includes an offline verifier for Java step0 review:
bash scripts/verify_java_offline.sh
Expected success marker:
JAVA OFFLINE VERIFY: PASS
Reflex Hook: Git-Aware Staleness Blocking for AI Agents
TMF includes a reflex hook integration that gives AI coding agents a biological-style reflex: when an agent is about to act on code understanding while that code has changed, the supported hook can request a stop and source reread. Enforcement depends on host interception, configuration and coverage.
This is not a code memory cache — it's a reflex arc that intercepts agent tool calls before execution.
Three Components
- Sensory organ = TMF function-level
fn_hash freshness (source-bound change detection; no fixed latency guarantee)
- Reflex arc = OpenClaw
before_tool_call hook / Claude Code PreToolUse harness (supported intercepted actions only)
- Reflex action = Hard block + localized single-file re-warm
Git Hook Auto-Calibration
Four git hooks automatically generate function-level invalidation manifests after code changes:
.git/hooks/post-commit — after local commits.git/hooks/post-merge — after git pull.git/hooks/post-checkout — after branch switches.git/hooks/post-rewrite — after rebase/amend
These hooks call integrations/reflex/scripts/git_calibrate.py, which compares baseline_rev → HEAD Python function signature changes and outputs structured invalidation manifests.
OpenClaw Plugin Integration
The tmf-reflex OpenClaw plugin intercepts agent tool calls:
- Checks TMF function-level freshness (latency depends on source, cache and host)
- Hard-blocks when agent touches a file with stale function claims
- Returns
requireApproval with exact changed function names
- Agent must run
integrations/reflex/scripts/local_warm.py to re-warm that one file
SessionStart Cognition Calibration
On new session start, the plugin reads unconsumed invalidation manifests and injects changed / deleted symbols as "pre-alert" context, preventing agents from relying on stale memory.
Boundary
- Function-level precision depends on TMF's language coverage (currently Python AST)
- Files without function-scope claims fall back to pass-through
- TMF engine remains read-only (reflex hook only uses
freshness / derive)
- Failure behavior depends on hook state and host integration; verify it on the intended host. If TMF is unavailable, disclose the failure and use current source rather than cached claims.
Installation
Reflex integration code lives in integrations/reflex/. See that directory's README.md and DESIGN.md for:
- OpenClaw plugin installation (
openclaw-plugin/)
- Git hook setup (
git-hooks/)
- Claude Code / Codex harness configuration (
examples/)
- Health validation tests (
tests/)
SEO and discoverability plan
Search terms this project is intended to match include AI coding agent memory, stale context prevention, source-aware code memory, code graph for LLM agents, Claude Code memory, and cross-session code understanding. These describe the user problem; they are not claims that every integration is already production-ready.
The repository description and external launch materials should use the same vocabulary, link to a reproducible demo, and distinguish validated mechanics from still-open productivity claims.
Documentation
License
MIT