dataset/
- 🧪 Contains all datasets used in our experiments, along with the official splits for training, validation, and testing.
EMA/
- 🧠 Houses the core implementation of EMA and MemDecider, including all scripts, pipelines, and utility functions.
- 🚀 Please first refer to the Quick Start section below to complete environment and path configuration. More detailed descriptions can be found in the README.md file under the EMA directory.
EMA.yaml
- 🛠️ The Conda environment configuration adapted for running the code.
This repository provides the official implementation of Episodic Memory Agent (EMA) — a unified, human-inspired framework that equips Large Language Models (LLMs) with efficient long-term memory and stable conversational consistency through episodic memory modeling ✨.
By rethinking what information is worth remembering and when it should be written into memory, EMA aims to address the challenges faced by existing LLMs in long-horizon, multi-turn interaction scenarios.
At its core, EMA is built upon two simple ideas:
- 🧩 Context Abstraction
Compressing raw dialogue streams into compact and meaningful Episodic Memory Units (EMUs). - 🧹 Smart Filtering
Leveraging MemDecider, a lightweight and plug-and-play decision module, to block irrelevant or low-value information before it is written into long-term memory, thereby preventing memory pollution.
-
⚡ High Efficiency
Reduces token consumption by an average of 11.48% while maintaining competitive performance. -
🔌 Plug-and-Play Design
MemDecider can be seamlessly integrated into existing memory-augmented frameworks with minimal engineering overhead. -
🎯 Robust Conversational Consistency
Preserves personalization and contextual coherence even in complex, long-running dialogues.
The core module of this project, EMA, supports the following use cases:
- 🔁 Reproduction of the complete training pipeline
- 📊 Reproduction of experimental results with consistent and verifiable settings
- ⚙️ Batch training and evaluation with automatic result saving, suitable for large-scale experiments
-
📌 The EMA/ directory provides rich and well-documented examples, which can be directly used as references or templates ✨
-
📖 For detailed usage instructions and configuration options, please refer to:
EMA/README.MD
This section provides a concise and practical guide to help you quickly get started with EMA 🚀.
The EMA/ directory serves as the main execution entry for all experiments and pipelines.
Before running the code, please complete the following two configuration steps.
We provide a ready-to-use Conda environment configuration file.
Create and activate the environment using EMA.yaml:
conda env create -f EMA.yaml
conda activate EMA
EMA depends on several resources, including:
- Pretrained model weights
- Backbone language models
- Datasets and caches
To simplify configuration, all paths are centralized in EMA/hardcoded_paths.yaml and can be configured in a one-time, automated manner.
Follow these steps:
- Open hardcoded_paths.yaml
- Replace the placeholder paths with your local paths
- Run the following script to apply the updates:
python inject_yaml_paths_to_code.py
After completing these steps, you can directly run EMA experiments from the EMA/ directory.
Use test.py to run experiments, and eval.py to perform evaluation.
For detailed explanations of each script and component, please refer to EMA/README.md.
Large Language Models (LLMs) demonstrate remarkable capabilities in generation and reasoning, yet they continue to face challenges in long-term memory retention and multi-turn conversational consistency.
Most existing memory-augmented approaches indiscriminately store full dialogue histories, resulting in severe information redundancy and increased inference latency ⏱️.
Inspired by episodic memory in human cognition, we propose Episodic Memory Agent (EMA), a unified framework that abstracts conversational context into concise Episodic Memory Units (EMUs).
To further enhance memory quality and efficiency, we introduce MemDecider, a filtering decision module that selectively determines whether incoming information should be stored.
Within EMA, EMUs are systematically organized and retrieved to support response generation, while MemDecider proactively reduces noise and unnecessary memory growth.
Experiments on two widely adopted benchmarks demonstrate that EMA achieves competitive performance, and that MemDecider reduces token consumption of other methods by an average of 11.48% while preserving their effectiveness.
Notably, MemDecider is a fully plug-and-play module that can be integrated into diverse memory frameworks and consistently enhances their overall efficiency and robustness 🌟.
Instead of storing raw dialogue logs, EMA encodes interactions as EMUs — structured, high-level abstractions of conversational events that focus on what truly matters 🧠.
A pioneering upstream memory gatekeeper 🚪.
MemDecider evaluates the importance of incoming information and decides whether it deserves admission into long-term memory, effectively suppressing noise, reducing API costs, and keeping memory lean and informative.