Persistent memory across language models
A shared substrate for accumulated experience. Adaptable interfaces for the models that use it.
Quick start · Models 🤗 · Paper ↗ · Try the demo ↗ · Overview · Architecture · Evidence · Documentation · Citation
Why MIGRO
MIGRO keeps long-term experience available as language models change. It stores observations, historical relationships and retrieval addresses in a persistent state that successive hosts can read and extend.
- Useful memory. Exact evidence and query-time selection support answers about events, revisions and context across long histories.
- Portable experience. Host-specific interfaces let a receiving model access inherited state and keep writing after handoff.
- Economical growth. Compact semantic addresses and reversible archives reduce persistent storage while retaining the saved evidence.
News
- 2026-11-12 — Shared runtime assets released, with core and host-interface checkpoints, setup and verification tools.
- 2026-11-11 — MIGRO technical report published on arXiv.
Quick start
Try it in your browser. Open the interactive demo to compare recorded model answers and inspect retrieved evidence. Download the offline demo for local replay.
Install from source. The base installation provides reporting tools and portable text controls.
git clone https://github.com/zOUMINGXI/MIGRO.git
cd MIGRO
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python scripts/render_results.py --helpRun the memory system. Follow runtime setup to install runtime dependencies, download shared assets, compile the coding kernels and run the provided verification. Then use the local demo guide to generate fresh answers with the required backbone and reranker models.
Documentation index · Experiment commands · Release scope
System design
The Handoff · interactive demo
A kitchen supplier asks for sign-off just as Leah changes assistants. The new quote, drawing and delivery options are in the latest emails; her spending cap, site measurements and building restrictions are in April’s correspondence. Take over the decision desk: make your own call, recover the earlier context and reconsider. Then compare the actual answers from five memory conditions. A second case reconstructs our own demo-download support issue from the release commits.
Open the interactive demo ↗ · Download the offline demo (.zip) · Run your own session
Open the online demo in any browser—no download or installation required. Explore the recorded model runs, switch memory conditions and inspect their retrieved evidence. To generate fresh answers from your own inputs, use the local runtime linked above.
A persistent substrate with adaptable host connections
MIGRO separates the stored experience from the machinery used to expose it to a particular host.
Writing preserves a connection to observed history. Native reference writing uses the source host to construct memory from observations. Persistent payloads and metadata retain the relationship between stored content and its originating experience.
Addressing and encoding serve different roles. Semantic addresses support evidence selection. The anchor-and-residual representation is evaluated against anchor-only and full-address controls. Persistence encoding is evaluated separately, including exact restoration of source IDs, address geometry and metadata.
The read interface handles the receiving host. Lexical transport connects source representations to the target vocabulary and embedding interface. Calibration adapts the host connection where the protocol permits it. This factorization makes host-specific adaptation an explicit part of the system.
The diagram describes the research architecture. The code release includes the persistent state backend, exact coding kernels and benchmark entry points. Shared checkpoints and datasets are supplied separately; see the runtime setup.
Architecture and component contracts · Implementation details · Ablation configurations
Carry state or rebuild history
The migration protocol distinguishes two concrete operations:
| Operation | Persistent state | Target-side work |
|---|---|---|
| State Transfer | Reuse existing memory state. | Connect it to the receiving host; small read-interface calibration is permitted and reported separately. |
| Full-History Rebuilding | Construct memory again from the full raw history. | Run the target-side construction process, including model-specific memory training when required. |
The label belongs to the run. A method can have both transferred-state results and independently rebuilt target controls. Rebuilding memory does not, by itself, mean fine-tuning the backbone.
Migration operations and calibration budgets
Experimental evidence
The report evaluates answer quality, cross-host continuity and persistent storage. These measurements use their respective cohorts and accounting scopes.
| Study | Representative result |
|---|---|
| Long-term QA · LongMemEval-S | 68.40 under the Qwen 4B reference host |
| Continued writing · Qwen 4B → Mistral 7B | 45.13, compared with 45.19 for target-side full-history rebuilding |
| Million-token BEAM histories | 1.857 MB private state per history, averaged over five histories |
| Shared deployment · 1,000 independent memories | 2.154 MB per memory, including required shared assets |
All benchmark and baseline tables · Metrics and scoring · Migration settings
Carry the experience. Keep writing.
Continued writing after a Qwen 4B → Mistral 7B handoff: answer quality, private memory footprint and quality retained relative to target-side rebuilding.
Released components
The repository provides entry points into the implementation and the evaluation workflow.
| Component | Role | Source |
|---|---|---|
| Persistent state | Shared anchors and residuals, exact content bindings, save/restore and continued writes. | migro.memory |
| Exact coding | Literal and causal content candidates, address/archive coding and native kernels. | migro.backend |
| Benchmark runs | Incremental MAB, matched read budgets, format-aware scoring and post-transfer continuation. | Running experiments |
| Transport | Vocabulary-aware piecewise transport, boundary composition and lexical mapping. | migro.transport |
| Calibration | Residual and evidence-conditioned host interfaces. | migro.calibration |
| Reference writing | Frozen-host causal writing from observed history. | migro.native_writer |
| Observation handling | Deterministic formatting and temporal notes. | migro.observations |
| Memory controls | Portable BM25 and recent-window baselines. | migro.controls |
| Paired analysis | Matched-cohort comparison and conversation-level bootstrap intervals. | migro_eval.ablations |
Reporting and paired analysis
# Render the checked-in aggregate results.
python scripts/render_results.py
# Aggregate an already-scored LoCoMo cohort.
python scripts/summarize_locomo.py /path/to/scored_records.json --output summary.json
# Inspect the paired-ablation analysis interface.
python scripts/summarize_ablations.py --help
# Run the component and reporting checks.
python -m unittest discover -s tests -vThe reporting tools consume scored records and require complete cohorts by default. Per-question scoring remains upstream. Optional-dependency tests skip when their dependencies are unavailable.
Reporting input format · Paired analysis usage
Repository structure
assets/ Visual identity and system figures
src/migro/ Transport, calibration, writing and controls
src/migro_eval/ Scored-record aggregation and paired analysis
configs/ablations/ Component-level experiment contracts
docs/ Architecture, protocols and implementation notes
results/ Selected manuscript summary tables (CSV / JSON)
scripts/ Reporting and analysis entry points
tests/ Component and reporting checksRelease status
The shared runtime bundle and implementation are available. The release includes persistent memory, coding kernels, host interfaces, setup and verification helpers, the demo and documented benchmark entry points. Backbone and reranker models and datasets are obtained from their publishers. The release scope lists available components and remaining reproduction work.
MIGRO-owned code and runtime assets use Apache-2.0. Bundled upstream components retain the licenses described in third-party notices.
Contributing
Contributions to documentation, integrations, memory interfaces and evaluation tooling are welcome. Read the contribution guide, report a bug, or propose an improvement.
Citation
If MIGRO is useful in your research, please cite the technical report. Machine-readable metadata is available in CITATION.cff.
@article{zou2026migro,
title = {{MIGRO}: A Decoupled and Portable Long-Term Memory System for Language Models},
author = {Zou, Mingxi and
Xu, Yinghui and
Chen, Jiaxiang and
Liang, Langzhang and
Zhu, Wei and
Ye, Peng and
Zhao, Runkai and
Jiang, Ruoxi and
Chen, Sijin and
Wang, Song and
Wang, Zhuo and
Qu, Lizhen and
Xu, Zenglin},
year = {2026},
eprint = {2611.15315},
archivePrefix = {arXiv},
primaryClass = {cs.AI},
url = {https://arxiv.org/abs/2611.15315}
}
