HUST-AI-HYZ/MemoryAgentBench

Yuanzhe Hu, Yu Wang, Julian McAuley.

이 프로젝트는 메모리 능력을 갖춘 에이전트(agents)를 벤치마킹합니다. 환경을 설정하고 의존성(dependencies)을 설치하려면 아래 단계를 따르세요.

평가를 위한 네 가지 핵심 역량:

정확한 검색 (Accurate Retrieval, AR)

테스트 시간 학습 (Test-Time Learning, TTL)

장기 이해 (Long-Range Understanding, LRU)

갈등 해결 (Conflict Resolution, CR)

우리는 이전의 벤치마크와 데이터셋으로부터 데이터를 수집하고 재구성했습니다. 모든 데이터는 AI 어시스턴트와의 일상적인 대화와 마찬가지로 실제 다회차 상호작용(multi-turn interaction) 시나리오를 시뮬레이션하기 위해 청크(chunks) 단위로 분할되었습니다. 또한, 우리는 EventQA와 FactConsolidation이라는 두 개의 데이터셋을 새롭게 구축했습니다.

특히, 팀은 "한 번 주입하고 여러 번 쿼리한다(inject once, query multiple times)"는 설계 철학을 채택했습니다. 즉, 하나의 긴 텍스트가 여러 질문에 대응하도록 하여 평가 효율성을 크게 향상시켰습니다.

(2026년 5월) 우리 벤치마크에 GPT-5-Mini 모델에 대한 결과를 추가했습니다. OpenReview 링크.

🔥 에이전트 작업에서의 에이전트 메모리(agentic memory) 평가에 관한 우리의 새로운 연구인 MemoryArena를 확인해 보세요. ICML 2026에 채택되었습니다!

(2026년 1월 26일) 우리의 논문이 제14회 국제 학습 표현 컨퍼런스 (ICLR 2026)에 채택되었습니다. 현재의 벤치마크를 개선할 예정입니다.

(2025년 9월 28일)

논문의 새 버전을 게시합니다. -
(2025년 8월 5일)

더 나은 사용을 위해 template.py를 최적화했습니다. -
(2025년 7월 22일)

Readme.md를 업데이트하고 longmemeval 및 infbench_sum에 대한 코드를 릴리스했습니다. 이들은 gpt-4o를 판사(judge)로 사용하여 평가하는 데 필요합니다. 코드 내의 uuid를 qa_pair_id로 변경했습니다. Hugging Face 데이터셋을 약간 업데이트했습니다.

(2025년 7월 7일) 주요 실험을 재현하기 위한 코드를 릴리스했습니다.

• TODO 리스트 ✍️ .

[x] 장기 이해 (Long Range Understanding, LRU)의 새로운 데이터셋.

🌟 더 자세한 내용(데이터셋 수집 등)이 곧 공개될 예정입니다! 🌟

재현성을 위해 전용 conda 환경을 사용하는 것을 권장합니다:

conda create --name MABench python=3.10.16

pip install torch
pip install -r requirements.txt
pip install "numpy<2"

현재 hipporag 버전이 패키지 버전 간의 충돌을 일으킬 수 있으므로, requirements.txt에 hipporag를 포함하지 않았습니다. 대신 hipporag를 사용하는 별도의 환경을 생성할 수 있습니다.

requirements.txt를 설치한 후 패키지 관련 오류가 발생하면, cognee 및 letta에 부족한 패키지를 추가로 설치해 보시기 바랍니다.

pip install letta
pip uninstall letta
pip install cognee
...

이 프로젝트를 사용하려면 처리된 데이터 파일을 다운로드하여 올바른 디렉토리에 배치해야 합니다.

HuggingFace 데이터셋 링크입니다. 코드를 직접 실행하면 자동으로 다운로드됩니다.

영화 추천 (Movie Recommendation) 태스크를 위한 entity2id.json 파일을 잊지 마세요.

이 프로젝트를 실행하려면 프로젝트 루트의 .env 파일에 API 키와 모델 설정을 구성해야 합니다.

.env 파일을 생성하고, 플레이스홀더 값을 실제 API 키로 교체하여 다음 내용을 추가하세요:

OPENAI_API_KEY= ###your_openai_api_key

LLM_MODEL=gpt-4o-mini
LLM_API_KEY= ###your_api_key

Anthropic_API_KEY= ###your_anthropic_api
Google_API_KEY= ###your_google_api

벤치마킹 에이전트 (benchmarking agent)를 평가하려면 다음 단계를 따르세요:

다음 예시 명령어를 사용하여 평가를 실행할 수 있습니다:

bash bash_files/eniac/run_memagent_longcontext.sh

--agent_config: 에이전트/모델 설정 파일의 경로입니다.
--dataset_config: 데이터셋 설정 파일의 경로입니다.

bash bash_files/eniac/run_memagent_rag_agents.sh

bash bash_files/eniac/run_memagent_rag_agents_chunksize.sh

hipporag (2.0.0a3)는 openai==1.58.1을 요구하며, 이로 인해 동일한 환경에서 최신 OpenAI 모델들을 사용하지 못할 수도 있음을 유의하세요.

다음 예시 파이썬 파일들을 사용하여 평가를 실행할 수 있으며, 설정(configs)도 함께 설정해야 합니다:

python llm_based_eval/longmem_qa_evaluate.py

python llm_based_eval/summarization_evaluate.py

저희 논문에서 "정확도 (accuracy)"는 약어로 사용되며, 작업에 따라 JSON 출력의 substring_exact_match 또는 exact_match 중 하나에 매핑됩니다. 전체 지표-데이터셋 매핑은 다음과 같습니다:

카테고리	데이터셋 (Dataset(s))	지표 (Metric)	JSON 필드
정확한 검색 (Accurate Retrieval)	event_qa, ruler_qa1, ruler_qa2	정확도 (Accuracy)	substring_exact_match
...

참고: exact_match의 경우, 파싱이 엄격합니다. 예를 들어, 정답 라벨(ground-truth label)이 "43"인데 모델이 "label: 43"을 반환하면 오답으로 처리됩니다. 벤치마크를 귀하의 파이프라인 (pipeline)에 맞게 조정할 때는 유연한 파싱을 권장합니다.

RULER, InfBench, HELMET 및 LongmemEval의 오픈 소스 코드와 데이터셋에 감사드립니다.

본 저장소가 귀하의 연구에 유용했다면 다음 논문을 인용해 주시면 감사하겠습니다:

@inproceedings{
 hu2026evaluating,
 title={Evaluating Memory in {LLM} Agents via Incremental Multi-Turn Interactions},
 ...