True Memory Fragments

True Memory Fragments

代码已更改，但你的 AI 编码 Agent 仍记得旧调用链？TMF 是与源代码绑定的代码记忆，可标记过时的说法，并指向当前源代码。

试用演示 · MCP 设置 · 证据

以 30 秒节奏回放真实的确定性演示输出，并标注源代码摘录——不是 Agent 端到端测试。系统会请求重新读取，但不会执行。

• **可追溯的代码关系：**将调用、读取、写入、继承和 API 相关说法绑定到源代码指纹。
• **明确的过时结果：**省略过时说法，并停止扩展已覆盖的图谱，而不是悄然复用旧上下文。
• **有针对性的重新读取指导：**返回源代码锚点，方便 Agent 检查已更改的代码。

开发者预览版：是否执行取决于宿主、配置和被拦截的操作，并不会自动阻止所有写入。新鲜不代表正确；尚未证实能普遍节省 Token，也未证实适用于生产环境。

适用对象

• 跨会话处理不断变化的代码库的 AI 编码 Agent
• 需要理解源代码的记忆，而非过时缓存事实的开发者
• 希望以保守方式扩展图谱，并明确处理过时／未知情况的工具作者

目前已验证

• 与源代码绑定的新鲜度和过时说法检测
• 可阻止不安全图谱扩展的强制过时门控
• 确定性的 Python 和 Java 验证
• 展示如何防止上下文过时的限定范围 Agent 实验

TMF 的核心上下文过时保护机制已在所涵盖的场景中得到验证。 针对更多语言、代码库和长时间运行的生产工作流的评估仍在进行中。

TMF 是什么——不是什么

TMF 适用于：

• 跨会话处理不断变化的代码库的 AI 编码 Agent
• 防止对调用链和依赖关系作出过时假设
• 与源代码绑定的代码记忆和保守的代码图谱导航
• 需要明确的过时／未知结果的 Agent 集成

TMF 不适用于：

• 通用聊天记忆产品或向量数据库
• 替代阅读源代码
• 保证每条说法都正确，只因为它是新鲜的
• 已证实的通用生产力提升或节省 Token 方案

新鲜表示源代码绑定仍然匹配。正确性仍需通过源代码和验证来确保。

此代码库包含一个 Java 资格测试套件：46/46 项资格检查和 731/731 项检查。历史上尚未发布的审计基线为 478/478 项测试；这不是当前测试总数。有关历史 rc3 和 master 的结果、明确跳过的项目，以及当时记录的 master 间歇性失败，请参阅固定版本的测试验证。rc6 发行说明介绍了 Java reflex 和接收者解析修复，并区分了源代码验证与发布证据。这些是源代码分析和回归测试结果，并不代表已做好生产准备，也不代表 Agent 的普遍成效。中间件机制已得到验证，GUAVA M10 预读取实验也提供了上下文过时安全性的积极证据。更广泛的生产力、速度、Token 节省和普遍防止 Bug 的说法仍未得到证实。作出更广泛的声明前，请参阅权威证据状态。

流程

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]

这就是整个循环：TMF 让声明始终绑定到源代码，拒绝重用过时上下文，并提供源代码锚点以便重新阅读；指导信息可能包含其他相关匹配项或启发式匹配项。

演示

上方的 GIF 重放了提交 de0236a57939 中 scripts/demo_stale_gate.py 的输出。它展示了确定性地省略过时声明并回退到源代码的过程，而不是展示 Agent 遵循重新阅读信号或完成任务。30 秒的时长是为了演示节奏，并非运行时基准。

从源代码检出目录运行（需要 Python 3.10+ 和 Git）：

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

已经克隆？只需从仓库根目录运行最后一条命令。此演示会导入检出目录中的源代码；它并非独立的 PyPI wheel 验证，而且仅安装软件包不会下载演示脚本。

它会创建一个临时 Git 仓库，推导出一条声明，更改其绑定的源代码，并演示省略过时内容、回退到源代码以及重新阅读指导。它不需要模型、网络、Java 解析器或预先存在的 .tmf/ 存储库。

预期标记：

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

演示到需要重新阅读为止；它不会执行后续的重新阅读或刷新。

有关 Agent 层面的结果，请参阅范围限定的 Guava 案例研究和多工作树／受控续接证据。有关实现细节，请参阅架构。

工作原理

TMF 维护一个保守的代码记忆图。只有当声明的源代码绑定仍与工作树匹配时，这些声明才有用。

1. 从源代码推导声明：函数、类、调用、读取、写入、继承和 API 关系。
2. 将每条声明绑定到源代码指纹：文件 blob，以及（如果可用）函数／节点哈希。
3. 在检索时检查新鲜度，然后才能使用声明。
4. 遇到过时或未知的边时停止，并返回明确的重新阅读信号，而不是过时的上下文。

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

这是有意采用的保守策略。缺失或过时的记忆会回退到源代码；它绝不会被提升为事实。

已验证的资产

• 绑定到源代码的声明存储，支持工作树新鲜度检查和源代码回退
• 精简的检索规范，以及按选定声明 ID 进行完整／说明式深入查询
• 保守提取 Python 函数／类／声明／配置／API 节点，以及部分调用／读取／写入
• 可选的 Java tree-sitter 语法节点和保守的继承边
• 有界片段查询，支持语义边界检测（writes、publishes_to）
• 异步交接标记（ASYNC_RELATIONS：publishes_to、subscribes_to、publishes_type、listens_type）
• 四种停止类型语义（boundary／async／stale／limit），对应不同的 stop_reason 值
• 有界查询限制（4 跳／64 个节点／128 条边）；这是工程限制，并非生物学验证结论
• 留出验证和自用验证工具集
• 本地指标和仅限完全匹配 blob 的重命名身份识别

核心前提

• 显式刷新／预热维护： retrieve 会检查现有声明，不会修改或重新推导存储；refresh_path 和 warm 会执行显式推导／刷新操作。
• 新鲜度基于工作树： 绑定到当前工作树中的 blob，而非提交
• 新鲜不代表正确： 新鲜仅表示绑定与当前源代码匹配。正确性取决于验证和源代码支持
• 置信度来自验证： 使用频率不会提高置信度
• 保守解析： TMF 只连接能够解析的内容。未知／动态／含糊的事实会被省略或标记为未解决
• 源代码具有权威性： 如果记忆缺失、过时、不受支持或不完整，TMF 会回退到源代码
• 不可信文本绝不是指令： 源代码、注释、文档字符串、提交消息、模型输出都是数据，而非命令

候选版本：0.1.0rc6。包含 Java 反射覆盖、保守的类型化／继承接收器解析，以及解析依赖项新鲜度。请参阅 rc6 发行说明。

安装

如需配置显式的多工作树绑定和 MCP，请使用固定版本的安装与 MCP 指南。

安装此预览版（Python 3.10+）：

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

有关版本范围和验证边界，请参阅 rc6 发行说明。

Java 解析支持为可选项：

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

开发检出：

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

运行时依赖刻意保持精简。可选的模型、嵌入器和路由器集成通过 TMF_* 环境变量调用命令。

安装了引擎不代表已启用反射钩子。 MCP 注册、预热后的索引和 Agent 使用规则都不会注册 Claude Code 的 PreToolUse 钩子。 安装 rc6 或更新后的源代码检出后，请运行：

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

如果注册缺失或未生效，将返回非零状态，并显示 reflex NOT armed — operating as opt-in memory。此检查针对配置， 不代表运行时确实触发。请参阅反射钩子设置与诊断。 诊断工具在 rc5 中引入；rc6 还会检测已识别的、无法识别 Java 的旧版钩子。 现有反射钩子部署必须更新整个集成目录，而不仅仅是引擎 wheel。 在钩子解释器中安装 [java] extra， 然后运行常规的 tmf warm --repo /absolute/path/to/task-repo，以刷新较旧的 Java 推导结果。静态诊断成功并不能证明宿主已分发调用。

快速入门

从上面的 30 秒过时门禁演示开始。在 讨论 #1 中分享安装或复现反馈。

离线 Java 验证器

对于 Linux x86_64 / CPython 3.12 源代码检出，仓库包含一个离线验证器，用于 Java step0 审查：

bash scripts/verify_java_offline.sh

预期的成功标记：

JAVA OFFLINE VERIFY: PASS

反射钩子：为 AI Agent 阻止 Git 感知的过时内容

TMF 包含一个反射钩子集成，为 AI 编码 Agent 提供类似生物反射的能力：当 Agent 即将依据对代码的理解采取行动，而这些代码已经发生变化时，受支持的钩子可以请求停止并重新读取源代码。强制执行效果取决于宿主拦截、配置和覆盖范围。

这不是代码记忆缓存，而是一个在执行前拦截 Agent 工具调用的反射弧。

三个组成部分

• 感觉器官 = TMF 函数级 fn_hash 新鲜度（基于源代码的变更检测；不保证固定延迟）
• 反射弧 = OpenClaw before_tool_call 钩子／Claude Code PreToolUse 框架（仅支持已拦截的操作）
• 反射动作 = 强制阻止 + 定位到单个文件的重新预热

Git Hook 自动校准

四个 Git Hook 会在代码更改后自动生成函数级失效清单：

• .git/hooks/post-commit — 本地提交后
• .git/hooks/post-merge — 执行 git pull 后
• .git/hooks/post-checkout — 切换分支后
• .git/hooks/post-rewrite — 变基或 amend 后

这些 Hook 会调用 integrations/reflex/scripts/git_calibrate.py，比较 baseline_rev → HEAD 之间的 Python 函数签名变更，并输出结构化失效清单。

OpenClaw 插件集成

tmf-reflex OpenClaw 插件会拦截 Agent 工具调用：

• 检查 TMF 函数级新鲜度（延迟取决于来源、缓存和主机）
• 当 Agent 操作的文件中存在过时的函数声明时，强制阻止操作
• 返回带有准确变更函数名称的 requireApproval
• Agent 必须运行 integrations/reflex/scripts/local_warm.py，为该文件重新预热

SessionStart 认知校准

新会话开始时，插件会读取尚未消费的失效清单，并将 changed / deleted 符号作为“预警”上下文注入，防止 Agent 依赖过时记忆。

边界

• 函数级精度取决于 TMF 的语言覆盖范围（目前为 Python AST）
• 没有函数范围声明的文件会回退为直接放行
• TMF 引擎仍为只读（reflex Hook 仅使用 freshness / derive）
• 失败行为取决于 Hook 状态和主机集成；请在目标主机上验证。若 TMF 不可用，请说明故障，并使用当前源码，而不是缓存的声明。

安装

Reflex 集成代码位于 integrations/reflex/。有关以下内容，请参阅该目录中的 README.md 和 DESIGN.md：

• OpenClaw 插件安装（openclaw-plugin/）
• Git Hook 设置（git-hooks/）
• Claude Code / Codex harness 配置（examples/）
• 健康验证测试（tests/）

SEO 与可发现性计划

本项目旨在匹配的搜索词包括 AI 编码 Agent 记忆、过时上下文预防、源代码感知代码记忆、面向 LLM Agent 的代码图谱、Claude Code 记忆和跨会话代码理解。这些词描述的是用户问题，并不表示每种集成都已达到生产就绪状态。

仓库描述和外部发布材料应使用相同的词汇，链接到可复现的演示，并区分已验证的机制与仍待验证的生产力效果主张。

文档

• 开源最低要求清单 — 发布和推广门槛
• Agent 运行时价值状态 — 当前实验结论
• Java 企业路线图 — 企业能力范围
• Guava 验证报告 — 路由形态 + 边界检测验证

许可证

MIT

• Guava M10 范围案例研究：docs/case-studies/guava-m10-stale-gating.md
• 离线过时门控演示：python3 scripts/demo_stale_gate.py（录制文件：recordings/stale-gate.cast）