🚀 Quick Start · 🏗️ How It Works · 📦 Repository · 📄 Citation
📑 Table of contents
- [2026-10-26]: 🗂️ As the project grew beyond text-only memory, the implementation moved from LightMem into this standalone StructMem repository.
- [2026-10-24]: 🖼️ StructMem now supports multimodal memory.
- [2026-04-24]: 🎉🎉🎉 StructMem: Structured Memory for Long-Horizon Behavior in LLMs has been accepted by ACL 2026!
StructMem builds memories around events instead of isolated flat facts. Its text implementation combines event-level factual and relational extraction with temporal anchoring and cross-event summarization. The multimodal implementation extends the same direction to ordered text and image evidence with persistent, user-isolated retrieval.
| Implementation | Best for | Entry point |
|---|---|---|
| 📝 Text | Long-horizon conversation memory and LoCoMo experiments | text/ |
| 🖼️ Multimodal | Text/image evidence storage and retrieval as a service | multimodal/ |
cd text
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'The canonical Python package namespace is structmem:
from structmem.memory.structmem import StructMemoryRead the method guide in text/StructMem.md and the LoCoMo workflow in text/experiments/locomo/readme.md.
cd multimodal
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
export MEMORY_API_KEY='change-me'
python -m uvicorn service.multimodal:app --host 127.0.0.1 --port 18084The service exposes interactive API documentation at http://127.0.0.1:18084/docs.
Configure remote encoders or optional local models using the variables documented in multimodal/.env.example and multimodal/SERVICE.md.
- Event extraction preserves factual components, relational components, and temporal bindings.
- Hierarchical consolidation connects related events within a time window and stores cross-event summaries alongside detailed memories.
- Scoped retrieval combines the resulting memories for long-horizon question answering.
- Ingestion stores original text and image evidence with ordered metadata.
- Encoding supports remote multimodal embeddings, optional local CLIP, and lexical matching.
- Evidence retrieval combines the available signals and returns source evidence with user isolation and persistent SQLite storage.
StructMem/
├── text/ # Original text-only StructMem implementation
│ ├── src/structmem/ # Canonical Python package namespace
│ ├── experiments/ # LoCoMo construction and evaluation scripts
│ └── StructMem.md # Method guide and examples
├── multimodal/ # Standalone multimodal memory service
│ ├── service/ # FastAPI application and retrieval modules
│ ├── tests/ # Synthetic, credential-free tests
│ └── SERVICE.md # API limits and configuration details
└── README.md
Datasets, credentials, model weights, runtime databases, generated memories, and benchmark outputs stay outside the repository.
Run the multimodal unit tests with synthetic content and mocked encoders:
cd multimodal
python -m pytest -qThe text project contains the LoCoMo construction and search scripts.
Their dataset paths, model endpoints, and output directories are supplied by the user; see text/experiments/locomo/readme.md.
Published or development scores should always include the exact dataset split, model, evaluator, and retrieval configuration.
Please cite the StructMem paper if you use the code or ideas in your work:
@misc{xu2026structmem,
title={StructMem: Structured Memory for Long-Horizon Behavior in LLMs},
year={2026},
eprint={2604.21748},
archivePrefix={arXiv},
primaryClass={cs.CL},
url={https://arxiv.org/abs/2604.21748}
}
The implementations are released under the MIT License.
See text/LICENSE and multimodal/LICENSE.