# True Memory Fragments **Category:** 🧠 Knowledge & Memory **Repository:** https://github.com/kyle641320/true-memory-fragments **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/true-memory-fragments ## Description Detect stale source context and retain traceable code-chain understanding for AI coding agents. ## Claude Desktop Quick Installation Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "true-memory-fragments": { "command": "npx", "args": ["-y","true-memory-fragments"] } } ``` ## Documentation & README # True Memory Fragments [![PyPI](https://img.shields.io/pypi/v/true-memory-fragments.svg)](https://pypi.org/project/true-memory-fragments/) [![License](https://img.shields.io/github/license/kyle641320/true-memory-fragments.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/) **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](#demo) · [MCP setup](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/docs/early-preview.md) · [Evidence](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/docs/AGENT_RUNTIME_VALUE_STATUS.md)** ![TMF demo: source changes, stale claims are omitted, and source reread is required.](https://raw.githubusercontent.com/kyle641320/true-memory-fragments/HEAD/docs/assets/tmf-stale-gate.gif) *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](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/docs/validation/2026-09-06-test-snapshots.md) for historical rc3 and master results, explicit skips, and the intermittent master failure recorded at that time. The [rc6 release notes](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/docs/releases/0.1.0rc6.md) 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](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/docs/AGENT_RUNTIME_VALUE_STATUS.md) before making broader claims. ## Flow ```mermaid 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): ```bash 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: ```text 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](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/docs/case-studies/guava-m10-stale-gating.md) and [multi-worktree / controlled continuation evidence](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/docs/validation/2026-09-12-branch-freshness.md). For implementation details, see the [architecture](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/DESIGN.md). ## 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. ```text 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](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/docs/releases/0.1.0rc6.md). ## Install For explicit multi-worktree binding and MCP configuration, use the [pinned installation and MCP guide](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/docs/early-preview.md). Install this preview (Python 3.10+): ```bash python -m pip install "true-memory-fragments==0.1.0rc6" ``` See the [rc6 release notes](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/docs/releases/0.1.0rc6.md) for version scope and validation boundaries. Java parsing support is optional: ```bash python -m pip install "true-memory-fragments[java]==0.1.0rc6" ``` Development checkout: ```bash 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: ```sh 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](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/docs/reflex-doctor.md). 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](#demo) above. Share installation or reproduction feedback in [Discussion #1](https://github.com/kyle641320/true-memory-fragments/discussions/1). ### Offline Java verifier For Linux x86_64 / CPython 3.12 source checkouts, the repository includes an offline verifier for Java step0 review: ```bash bash scripts/verify_java_offline.sh ``` Expected success marker: ```text 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](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/docs/OPEN_SOURCE_MINIMUM_CHECKLIST_20260905.md) — release and promotion gates - [Agent runtime value status](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/docs/AGENT_RUNTIME_VALUE_STATUS.md) — current experiment ruling - [Java enterprise roadmap](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/docs/JAVA_ENTERPRISE_ROADMAP.md) — enterprise capability scope - [Guava validation report](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/GUAVA_VALIDATION_REPORT.md) — routing shape + boundary detection validation ## License MIT - Guava M10 scoped case study: [docs/case-studies/guava-m10-stale-gating.md](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/docs/case-studies/guava-m10-stale-gating.md) - Offline stale-gate demo: `python3 scripts/demo_stale_gate.py` (recording: [recordings/stale-gate.cast](https://github.com/kyle641320/true-memory-fragments/blob/HEAD/recordings/stale-gate.cast))