SubtleMemory: 장기 지평 AI 에이전트의 미세 관계 기억 판별을 위한 벤치마크

개요 | 데이터 | 데이터 구성 | 평가 | 통합 가이드 | 결과 | 인용

장시간 작동하는 어시스턴트는 사용자, 작업 또는 외부 사실에 대한 많은 유사한 기억들을 축적합니다. 이러한 기억들은 서로 보완할 수도 있고, 다른 상황에서만 적용될 수도 있으며, 혹은 직접적으로 충돌할 수도 있습니다. SubtleMemory는 메모리 시스템이 단순히 고립된 사실을 회상하는 것을 넘어, 이러한 미세 관계를 보존하고 사용하는지 테스트합니다.

SubtleMemory는 10개의 페르소나 수준 히스토리, 1,090개의 관계 제어 의미 변형 세트, 그리고 1,522개의 평가 인스턴스를 포함합니다. 각 인스턴스는 타겟 관련 기억들 간의 관계에 따라 답이 결정되는 다운스트림 질문을 요구합니다.

2026-08-21: SubtleMemory가 EMNLP 2026 Findings에 채택되었습니다!2026-06-05: arXiv preprint이 온라인으로 공개되었습니다: https://arxiv.org/abs/2606.05761**2026-06-04:** 프로젝트 페이지가 온라인으로 공개되었습니다: https://yummytanmo.github.io/SubtleMemory/**Path | 목적 |data/subtlememory/ | 생성된 벤치마크 데이터로, persona_0부터 persona_9까지 구성되어 있습니다. |construction/ | 사용자 관련, 사용자 비관련 및 병합된 벤치마크 데이터를 위한 데이터 구축 워크플로우입니다. |evaluation/cli.py | 단계별(staged) 벤치마크 실행을 위한 메인 진입점입니다. |evaluation/config/datasets/ | subtlememory.yaml을 포함한 데이터셋 설정 파일들입니다. |evaluation/config/systems/ | 호스팅된 API, 네이티브 시스템, OpenClaw 플러그인 및 베이스라인을 위한 메모리 시스템 설정 파일들입니다. |evaluation/src/adapters/ | 메모리 시스템 및 베이스라인을 위한 어댑터 구현체들입니다. |evaluation/src/core/stages/ | 추가(add), 최종화(finalize), 검색(search), 답변(answer) 및 평가(evaluate) 단계 구현체들입니다. |assets/ | 데이터 구축 다이어그램을 포함한 논문 및 README 에셋들입니다. |site/ | 프로젝트 페이지 소스 코드입니다. |

Python 3.10 이상 버전을 사용하세요. 리포지토리 루트에서 다음 명령어를 실행합니다:

uv sync
cp env.template .env

.env 파일을 편집하여 평가하고자 하는 시스템이나 데이터 구축에 필요한 자격 증명(credentials)을 추가해야 합니다. 일반적인 변수에는 다음과 같은 것들이 포함됩니다:

ANSWER_LLM_API_KEY,
ANSWER_LLM_BASE_URL,
ANSWER_LLM_MODEL

JUDGE_LLM_API_KEY,
JUDGE_LLM_BASE_URL,
JUDGE_LLM_MODEL

GENERATION_BASE_URL,
GENERATION_API_KEY

FILTER_BASE_URL,
FILTER_API_KEY

• 메모리 백엔드 자격 증명(credentials) (예: MEM0_API_KEY, MEMOS_KEY, EVERMEMOS_API_KEY, ZEP_API_KEY) 및 OpenClaw, MIRIX, MetaClaw, A-Mem, MemoBase에 대한 로컬 런타임 경로가 포함됩니다.

생성된 SubtleMemory 벤치마크 데이터는 Hugging Face에서 이용 가능합니다:

• 데이터셋 페이지: Yummytanmo/SubtleMemory
• 벤치 인스턴스 뷰어: bench_instances/persona_0
• 히스토리 세션 뷰어: history_sessions/persona_0

Hugging Face 릴리스는 리포지토리 데이터 레이아웃을 유지하며 persona_0부터 persona_9까지 노출합니다.

데이터셋 분할(splits) 형태로 제공됩니다. 이 데이터는 벤치마크 케이스와 QA 인스턴스를 위한 bench_instances 구성과, 시간 순서에 따른 대화 세션(chronological conversation sessions)을 위한 history_sessions 구성을 포함합니다.

from datasets import load_dataset
bench_p0 = load_dataset(
"Yummytanmo/SubtleMemory",
...

동일한 데이터는 다음 리포지토리에서도 확인할 수 있습니다:

data/subtlememory/
persona_0/
bench_instances.json
...

각 페르소나 번들(persona bundle)에는 관계 레이블(relation labels), 출처 사실(source facts), 대상 세션 ID(target session IDs), 정답(correct answers), 오답(incorrect answers)을 포함하는 시간 순서 대화 기록 세션과 벤치마크 인스턴스가 담겨 있습니다. 평가 로더(evaluation loader)는 이러한 번들을 스테이징 파이프라인(staged pipeline)에서 사용되는 LoCoMo 스타일의 런타임 형식으로 변환합니다.

평가를 위해 생성된 벤치 데이터를 다음 평가 데이터 위치로 복사하십시오:

mkdir -p evaluation/data/subtlememory
rsync -a data/subtlememory/ evaluation/data/subtlememory/

SubtleMemory는 오픈 소스 시드 데이터(seed data)에서 시작하여 페르소나 범위의 벤치마크 번들로 끝나는 스테이징 구성 파이프라인을 통해 구축되었습니다.

고해상도 PDF: assets/data_construction.pdf

구성 워크플로우는 다섯 단계를 따릅니다:

• 의미론적 시드 데이터(semantic seed data) 선택 및 정규화.
• 관계 제어형 의미 변이체(relation-controlled semantic variants) 생성.
• 변이체를 암묵적이고 자연스러운 다중 턴 세션(multi-turn sessions)에 임베딩.
• 평가 인스턴스 및 QA 타겟 구성.
• 시간 순서 사용자 기록과 최종 벤치 번들 조립.

주요 구성 진입점은 다음과 같습니다:

uv run python construction/user-related/main.py build
uv run python construction/user-unrelated/main.py generate-to-filter
uv run python construction/user-unrelated/main.py filter
...

구성 워크플로우, 예상 중간 경로(expected intermediate paths), 상세 프롬프트 및 데이터 흐름 문서 링크는 construction/README.md를 참조하십시오.

evaluation/data/subtlememory로 데이터를 복사한 후,
작은 스모크 슬라이스(smoke slice)를 실행합니다:

uv run python -m evaluation.cli \
--dataset subtlememory \
--system mem0 \
...

완료된 실행을 검증하십시오:

uv run python -m evaluation.validate_run
--output-dir evaluation/results/subtlememory-mem0-mem0-smoke/subtlememory-mem0-mem0-smoke-api

구성된 시스템에 대한 전체 단계별 파이프라인을 실행합니다:

uv run python -m evaluation.cli \
--dataset subtlememory \
--system memos \
...

데이터 수집(ingestion)이 완료된 후의 후반부 단계만 실행합니다:

uv run python -m evaluation.cli \
--dataset subtlememory \
--system memos \
...

주요 리더보드와 종합 벤치마크 결과는 프로젝트 페이지에서 확인할 수 있습니다:

표준 api 모드는 메모리 시스템이 일반 검색 API를 통해 증거(evidence)를 검색하도록 요청합니다. 반면, readback 모드는 질문의 출처(provenance), 특히 session_ids를 사용하여 대상 세션에서 작성된 메모리 객체를 읽어옵니다. Readback은 선택적인 진단 지원 기능이며, 이를 구현하지 않아도 일반 api 모드에서 메모리 시스템을 벤치마크할 수 있습니다.

api mode: query -> provider search API -> answer -> evaluate
readback mode: session_ids -> stored memory objects -> answer -> evaluate

시스템이 add와 finalize를 수행하도록 먼저 api를 실행합니다:

uv run python -m evaluation.cli \
--dataset subtlememory \
--system memos \
...

그런 다음 동일한 add/finalize 아티팩트를 재사용하면서 readback을 실행합니다:

uv run python -m evaluation.cli \
--dataset subtlememory \
--system memos \
...

Readback 관련 세부 정보는 readback_search_readback.jsonl에 저장되며, 여기에는 질문별로 세션 ID, 상태(status), 읽어온 객체(read objects), 오류(errors)가 한 행씩 기록됩니다.

새로운 메모리 시스템을 추가하고 벤치마크하려면 상세 평가 통합 가이드(detailed evaluation integration guide)를 참조하십시오. 여기에는 시스템 YAML, 어댑터 계약(adapter contract), api 대 선택적 readback에 대한 설명이 포함되어 있습니다.

검색 모드(search modes), 레지스트리(registry)
배선(wiring), 아티팩트 기대치(artifact expectations), 검증 흐름(validation flow) 및 Mem0 작동 예제.

각 실행은 evaluation/results/ 아래에 모드별 아티팩트 디렉터리를 작성합니다.

중요 파일 목록:

이 파이프라인은 체크포인트를 작성하여 중단된 실행을 완료된 단계를 다시 수행하지 않고도 재개할 수 있게 합니다.

본 저장소는 EverOS 평가 프레임워크를 기반으로 각색되었습니다. SubtleMemory가 구축하는 기본 평가 파이프라인, 단계별 아티팩트 설계, 어댑터 추상화(adapter abstractions), 구성 주도 실험 워크플로우에 대해 EverOS에 감사드립니다.

SubtleMemory는 여러 오픈 소스 메모리 및 에이전트 시스템을 평가하고 통합합니다. 해당 어댑터를 사용할 때는 반드시 관련 상위 프로젝트의 인용과 라이선스를 따르십시오.

SubtleMemory가 유용하다고 생각되시면, 다음 논문을 인용해 주십시오:

@misc{wang2026subtlememory,
title = {SubtleMemory: A Benchmark for Fine-Grained Relational Memory Discrimination in Long-Horizon AI Agents},
author = {Wenxuan Wang and Haoyu Sun and Fukuan Hou and Mingyang Song and Weinan Zhang and Yu Cheng and Yang Yang},
...