true-memory-fragments

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]"   # 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

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

• Open-source minimum checklist — release and promotion gates
• Agent runtime value status — current experiment ruling
• Java enterprise roadmap — enterprise capability scope
• Guava validation report — routing shape + boundary detection validation

License

MIT

• Guava M10 scoped case study: docs/case-studies/guava-m10-stale-gating.md
• Offline stale-gate demo: python3 scripts/demo_stale_gate.py (recording: recordings/stale-gate.cast)