# TMCRA 长记忆运行时

<p align="center">
  <img src="assets/tmcra-logo.png" alt="TMCRA logo" width="420">
</p>

[English version](README.md)

TMCRA 是给 Agent 系统提供长期记忆能力的运行时层。它帮助大语言模型在长对话历史中检索、连接和推理相关记忆，而不需要在每一轮都暴露完整上下文。

本仓库包含一个冻结的 TMCRA 基线包，包括模型权重、运行时代码快照、训练元数据和 LongMemEval S500 测评结果。

许可证：MIT。

## TMCRA 的作用

TMCRA 在 Agent 应用和回答模型之间增加一层专门的记忆运行时。

在写入阶段，TMCRA 会把对话转成记忆节点、事件单元、profile 信号和图路径。这让系统不仅能保存孤立事实，也能保存不同轮次、不同会话之间的事实关系。

在召回阶段，TMCRA 会对图节点和路径进行打分，选择紧凑的证据，并只把最相关的记忆上下文注入给回答模型。回答模型仍然负责自然语言推理和最终表达，TMCRA 负责长记忆组织、召回和证据呈现。

当前运行时重点覆盖：

- 用户事实记忆
- 助手回答细节记忆
- profile 与偏好记忆
- 时间记忆
- 跨会话图隧穿
- 学习式节点/路径打分
- 面向下游 LLM 的紧凑证据选择

## 算法结构图

```mermaid
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 权重：

```text
models/action_frame_tunnel_graph548_tunnel_fusion_train_20260524_042557/
```

主要运行时文件是：

```text
node_scorer.pt
path_scorer.pt
export_manifest.json
```

典型运行配置如下：

```bash
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"
```

测评入口代码快照：

```text
code/run_lme_s10_native_tmcra.py
```

核心适配器代码快照：

```text
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 输出文件位于：

```text
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
```