README.md

---
license: apache-2.0
library_name: pytorch
language:
  - en
  - zh
tags:
  - agent-memory
  - long-term-memory
  - memory-graph
  - information-retrieval
  - longmemeval
  - pytorch
---

# TMCRA — Agent Memory Engine

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

<p align="center">
  <a href="README.zh-CN.md">简体中文</a> ·
  <a href="https://github.com/reshuibuduo/TMCRA-Agent-Memory">GitHub</a> ·
  <a href="https://github.com/reshuibuduo/TMCRA-Agent-Memory/releases/tag/v2026.07.18">Release v2026.07.18</a>
</p>

TMCRA is a memory engine for long-running agents. It converts multi-turn and multi-session conversations into scope-isolated, source-traceable memory, then recalls compact evidence after the user's next question arrives.

This Hugging Face repository contains the Apache-2.0 release of the TMCRA algorithm, its LongMemEval reproduction pipeline, and the inference-only graph scoring weights used by the released benchmark chain. Hosted APIs, accounts, billing, and production control-plane services are not included.

## LongMemEval S500

TMCRA achieved **411 / 500 = 82.2%**.

| Task category | Correct / Total | Accuracy |
| --- | ---: | ---: |
| Knowledge Update | 71 / 78 | 91.0% |
| Multi-session | 90 / 133 | 67.7% |
| Single-session Assistant | 55 / 56 | 98.2% |
| Single-session Preference | 27 / 30 | 90.0% |
| Single-session User | 67 / 70 | 95.7% |
| Temporal Reasoning | 101 / 133 | 75.9% |
| **Overall** | **411 / 500** | **82.2%** |

The machine-readable scorecard is [`results/latest_benchmark.json`](results/latest_benchmark.json). The maintained reproduction entrypoint is [`benchmarks/longmemeval/`](benchmarks/longmemeval/README.md). The benchmark answer layer is fixed to GPT-5.4; fresh runs that call external model services can vary slightly.

## Architecture

TMCRA separates memory construction from downstream answer generation.

```text
Conversation history
        │
        ▼
      Writer ─────────────── subject / entity attribution
        │
        ├── Source layer ─── immutable, traceable evidence
        ├── Fast layer ───── atomic current-state memory
        └── Slow layer ───── durable semantic graph
                 │
                 └────────── scope-bound indexes

New question
        │
        ▼
Recall Planner → layered retrieval → node/path scoring → reranker
        │
        ▼
Source-bound evidence packet → downstream agent
```

The TMCRA core ends at the evidence packet. The answer model and benchmark judge are harness components, not part of the online memory engine. User statements and assistant progress remain separately attributed, while both can be recalled when relevant.

## Released weights

All three checkpoints contain only their public inference contracts and model state. Training state, machine paths, and private run metadata are excluded. Load them with `torch.load(..., weights_only=True)` through the repository runtime.

| File | Purpose | Size | SHA-256 |
| --- | --- | ---: | --- |
| `node_scorer.pt` | Graph node scoring | 207,356,243 bytes | `d2318aafb07f9a15a1d95e6eac1b3e09afa07c570dd9d15d3f75544c9950f201` |
| `path_scorer.pt` | Graph path scoring | 207,356,243 bytes | `ecdc2bca51b7646a8a56c7db9cea4aeec581e64c3b61e6e06f7e9fa2a93b3bf5` |
| `tmcra_v3_reranker.pt` | Learned retrieval reranking | 4,232,213 bytes | `09a285b484ca857b24b53ad19d5998302f16d224ca9e4fd73a4eb5a52f022942` |

The files and their machine-readable contract are under [`models/tmcra_v4_longmemeval_s500_20260715/`](models/tmcra_v4_longmemeval_s500_20260715/README.md).

## Download

Install the current Hugging Face CLI and download only the released inference package:

```bash
python -m pip install -U huggingface_hub

hf download 2009YU/TMCRA-Agent-Memory \
  --include "models/tmcra_v4_longmemeval_s500_20260715/*" \
  --local-dir ./TMCRA-Agent-Memory
```

For source, benchmark setup, environment examples, asset checksums, and stage validation, use the [GitHub release](https://github.com/reshuibuduo/TMCRA-Agent-Memory/releases/tag/v2026.07.18) or [`benchmarks/longmemeval/README.md`](benchmarks/longmemeval/README.md).

## Version history

- Current release: [`v2026.07.18`](https://huggingface.co/2009YU/TMCRA-Agent-Memory/tree/v2026.07.18)
- Preserved pre-release snapshot: [`legacy-2026.05.25`](https://huggingface.co/2009YU/TMCRA-Agent-Memory/tree/legacy-2026.05.25)

## Developers

- **Yu Haoxin** — creator, lead developer, and TMCRA algorithm engineering.
- **OpenAI Codex** — development and reproducibility engineering assistant.

See [`AUTHORS.md`](AUTHORS.md) and [`CITATION.cff`](CITATION.cff) for attribution and citation details.

## License

TMCRA is released under the [Apache License 2.0](LICENSE). Third-party datasets, models, and components retain their own licenses.