MIGRO / README.md
dasd1231's picture
Release MIGRO shared core and host interfaces
9fae2a1 verified
|
Raw History Blame Contribute Delete
5.11 kB
---
license: apache-2.0
library_name: pytorch
tags:
- arxiv:2611.15315
- agent-memory
- long-term-memory
- persistent-memory
- model-handoff
- custom-code
---
# MIGRO — Portable Long-Term Memory
**Memory Should Outlive the Model.**
MIGRO is a decoupled long-term memory system that stores experience in a persistent state, allowing successive language models to read inherited observations and continue writing.
[Paper](https://arxiv.org/abs/2611.15315) · [Code](https://github.com/zOUMINGXI/MIGRO) · [Interactive demo](https://zoumingxi.github.io/MIGRO/) · [Runtime guide](https://github.com/zOUMINGXI/MIGRO/blob/main/docs/runtime.md)
## Released components
This repository hosts the shared runtime payload released with MIGRO, including its memory core, semantic-address components, coding tables, source tokenizers and frozen host interfaces.
| Component | File or directory | Role |
|---|---|---|
| Shared core | research/rd_shared_pages_20261025/deployment/minimal_core.pt | Frozen semantic encoder, source embeddings and shared runtime tensors |
| Semantic encoder configuration and tokenizer | research/rd_shared_pages_20261025/deployment/semantic_config/ and semantic_tokenizer/ | Configure semantic addressing |
| Source tokenizer | research/rd_shared_pages_20261025/deployment/source_tokenizer/ | Interpret canonical source-token bindings |
| Address and coding resources | research/rd_shared_pages_20261025/model/ and research/rd_semantic_factor_20261025/ | Reconstruct compact addresses and support persistence |
| Phi interface | research/decomem_v1_20261028/frozen_interfaces/Phi_boundary.pt | Frozen host input interface |
| Mistral interface | research/decomem_v1_20261028/frozen_interfaces/Mistral_cal64.pt | Frozen calibrated host input interface |
The directory layout is compatible with MIGRO_ASSETS. ASSETS.json lists the payload files. The custom PyTorch modules are loaded through the MIGRO runtime.
## Download and use
Install MIGRO from its source repository, following the [tested runtime dependencies](https://github.com/zOUMINGXI/MIGRO/blob/main/docs/runtime.md).
~~~bash
git clone https://github.com/zOUMINGXI/MIGRO.git
cd MIGRO
python -m pip install -e '.[runtime,benchmarks]' -c constraints/runtime-tested.txt
python -m pip install huggingface_hub
~~~
Download the shared assets from this model repository:
~~~python
from huggingface_hub import snapshot_download
snapshot_download(
repo_id="dasd1231/MIGRO",
local_dir="./migro-assets",
)
~~~
Use the downloaded folder as the runtime asset root and compile the native coding kernels:
~~~bash
export MIGRO_ASSETS="$PWD/migro-assets"
python -m migro.backend.build_native
python scripts/verify_runtime.py --assets-dir "$MIGRO_ASSETS"
~~~
For fresh answer generation, obtain the supported backbone and reranker models from their publishers, as described in the runtime guide. Then run a local session:
~~~bash
MIGRO_DEVICE=cuda python demo/run.py --case demo/starter.json --output trace.json
MIGRO_DEVICE=cuda python demo/serve.py --trace trace.json
~~~
The [demo guide](https://github.com/zOUMINGXI/MIGRO/blob/main/demo/README.md) describes replay, input editing and generating new answers.
## Intended use and evaluation
These resources support MIGRO memory construction, persistence, host-interface reading and continued writing. Answer generation combines them with an external host language model and the runtime's retrieval components.
The [technical report](https://arxiv.org/abs/2611.15315) evaluates the complete system on long-term question answering, cross-host transfer and persistent storage. [Evaluation details](https://github.com/zOUMINGXI/MIGRO/blob/main/docs/evaluation.md) describe the settings, cohorts and baseline operations. Deployment behavior depends on the selected host, interface and retrieval budget.
Host-interface weights are specific to their supported host configurations. The [runtime guide](https://github.com/zOUMINGXI/MIGRO/blob/main/docs/runtime.md) specifies required models and dependencies.
## Component sources and licenses
MIGRO-owned components are released under Apache-2.0. The shared core includes frozen components from [BAAI/bge-small-en-v1.5](https://huggingface.co/BAAI/bge-small-en-v1.5) under MIT and the input embeddings/tokenizer from [google/flan-t5-small](https://huggingface.co/google/flan-t5-small) under Apache-2.0. Their notices and licenses accompany this repository.
See LICENSE, NOTICE, THIRD_PARTY_NOTICES.md and PROVENANCE.json for the existing component attribution and source revisions.
## Citation
~~~bibtex
@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}
}
~~~