flowchart LR
    A["对话轮次"] --> B["写入层"]
    B --> C["记忆节点"]
    B --> D["事件单元"]
    B --> E["Profile 信号"]
    B --> F["时间信号"]

    C --> G["图记忆库"]
    D --> G
    E --> G
    F --> G

    G --> H["学习式节点 Scorer"]
    G --> I["学习式路径 Scorer"]
    H --> J["证据选择"]
    I --> J

    J --> K["紧凑记忆上下文"]
    K --> L["回答模型"]
    L --> M["Agent 回复"]

    N["用户问题"] --> H
    N --> I
    N --> J
    N --> L

写入层从对话中生成记忆单元。图记忆库保存事实、事件、profile 信号、时间信号和跨会话连接。学习式节点/路径 scorer 会根据当前问题选择相关证据，回答模型使用这些紧凑证据生成最终回复。

为什么需要 TMCRA

长期运行的 Agent 不能只依赖简单向量召回。它需要保存用户事实、偏好、时间线变化、跨会话事件，以及多步证据链。

TMCRA 将记忆组织成图节点和学习得到的召回路径，再把压缩后的证据提供给回答模型。目标是让外部 Agent 可以通过运行时/API 层使用长期记忆，同时保持记忆算法和模型权重可以独立部署。

如何使用

推理或运行时使用时，加载下面目录中的图 scorer 权重：

models/action_frame_tunnel_graph548_tunnel_fusion_train_20260524_042557/

主要运行时文件是：

node_scorer.pt
path_scorer.pt
export_manifest.json

典型运行配置如下：

export TMCRA_NODE_MODEL_PATH="models/action_frame_tunnel_graph548_tunnel_fusion_train_20260524_042557/node_scorer.pt"
export TMCRA_PATH_MODEL_PATH="models/action_frame_tunnel_graph548_tunnel_fusion_train_20260524_042557/path_scorer.pt"
export TMCRA_RETRIEVAL_MODE="hybrid_node_scored"
export TMCRA_REQUIRE_LEARNED_SCORER="1"

测评入口代码快照：

code/run_lme_s10_native_tmcra.py

核心适配器代码快照：

code/memory_adapters.py

部署时，将两个 scorer 文件加载到 TMCRA adapter 中，并让 Agent 的记忆中间件调用 TMCRA 召回 API。回答模型可以是任意 OpenAI 兼容接口或本地 LLM；TMCRA 提供选中的记忆证据，回答模型生成最终回复。

依赖环境

当前代码快照基于 Python。建议运行环境包括：

Python 3.10 或更高版本
PyTorch，推荐使用 CUDA 做模型推理
NumPy 及常见 Python 数据处理库
用于回答层和写入层的 OpenAI 兼容接口或本地 LLM endpoint
从 GitHub 拉取完整模型包时建议支持 Git LFS

benchmark 脚本使用 LongMemEval 格式输入数据，并输出 JSONL 格式的预测和 judge 结果。实际运行时部署可以直接使用同一套模型文件，不需要运行 benchmark harness。

可开启模块

TMCRA 当前也保留了用于召回和规划实验的可选接入口。部署或评估时，如果目标场景需要，可以按需开启这些模块。

Embedder 接入口：可选的语义 embedding 通道，可以和图记忆 scorer 并行工作。它用于在图证据选择前或选择过程中提供额外的稠密语义召回，但不替代学习式图节点/路径 scorer。
LLM planner 接入口：可选的规划 hook，可以调用外部 LLM 来整理证据、扩展 query intent，或在最终回答前生成 answer plan。它适合实验和更高成本的部署场景；默认基线仍保持核心图 scorer 链路可以独立测量。

这些接口是可集成的扩展点，不是冻结 S500 基线的必需依赖。下游部署可以根据成本和效果选择轻量的 scorer-only 路径，或开启 embedder/planner 辅助的增强路径。

包含内容

code/：该基线使用的运行时和测评代码快照。
models/action_frame_tunnel_graph548_tunnel_fusion_train_20260524_042557/：完整训练后的图模型输出目录。
results/：预测结果、judge 输出、汇总指标和压缩后的运行结果。
docs/：基线记录和结果说明。

补充文档：

docs/BASELINE_S500_20260525.md：benchmark 记录和子任务指标。
docs/TRAINING.md：模型训练方向和随包发布的训练产物说明。
docs/OPTIONAL_MODULES_AND_PARALLEL.zh-CN.md：embedder/planner 可选接入口和并行评估推进方案。
docs/OPTIONAL_MODULES_AND_PARALLEL.md：上述文档的英文版本。

模型包

随包发布的模型目录保留了图 scorer 栈的完整训练输出：

node_scorer.pt 和 path_scorer.pt：运行时图打分权重。
node_scorer_best.pt 和 path_scorer_best.pt：验证表现最好的 checkpoint 别名。
node_scorer_last.pt 和 path_scorer_last.pt：训练结束时的 checkpoint 别名。
checkpoints/：按 epoch 和 step 保存的中间 checkpoint。
export_manifest.json、train_summary.json 和 train.log：模型元数据和训练轨迹。

当前优势

单会话直接用户事实召回较强。
助手细节召回较强。
对变化事实的 knowledge-update 任务有较稳定表现。
已具备可工作的时间记忆和偏好召回层，后续仍有专项优化空间。

当前改进方向

multi-session 聚合和 unit coverage。
更深的时间图推理。
偏好 profile 抽象和跨会话隧穿。
query graph 与 memory graph 的复杂问题匹配。

适用场景

本仓库是 TMCRA 长记忆运行时工作的对外展示包，适合用于：

benchmark 审阅
模型和结果检查
复现冻结基线
展示 TMCRA 如何作为外部 Agent 的记忆运行时进行封装

Benchmark 结果

本包包含一次完整 LongMemEval S500 测试。

Benchmark：LongMemEval S set，500 条样本
Evaluation：official-compatible LongMemEval judge prompt
Judge 模型：gpt-4o，解析为 gpt-4o-2024-08-06
本轮使用的写入层：DeepSeek v4 Flash
本轮使用的回答层：GPT5.4-compatible API
总准确率：310 / 500 = 62.00%

各任务类型结果

任务类型	准确率	数量
single-session-user	81.43%	70
single-session-assistant	78.57%	56
knowledge-update	70.51%	78
temporal-reasoning	63.16%	133
single-session-preference	56.67%	30
multi-session	39.85%	133

benchmark 输出文件位于：

results/predictions.jsonl
results/judge_gpt4o_alias_vectorengine.jsonl
results/judge_gpt4o_alias_vectorengine.jsonl.summary.json
results/lme_s500_frozen_baseline38_full10_20260525_results.tar.gz