에이전트에게 필요한 것은 메모리가 아니라 문서다: RAG 회상의 다섯 가지 함정
한눈에 보는 핵심
AI 코딩 에이전트에 "메모리"를 붙이는 시도가 유행입니다. 과거 대화를 잘게 쪼개 벡터 DB에 넣고, 매 프롬프트마다 유사한 조각 몇 개를 주입하는 방식이죠. 하지만 이 글의 주장은 분명합니다. 에이전트가 프로젝트를 이해하기 위해 필요한 것은 과거 대화의 회상이 아니라, 사람이 읽고 수정할 수 있는 프로젝트 문서라는 것입니다.
에이전트가 실제로 알아야 하는 건 이런 것들입니다.
- 기능이 어디에 있는지
- 왜 그렇게 구현했는지
- 팀이 무엇에 합의했는지
- 사용자가 중요하게 여기는 기준은 무엇인지
대화 조각 간의 코사인 유사도는 이 질문들에 답해주지 않습니다.
대화 검색 ≠ 프로젝트 이해
전형적인 메모리 플러그인의 동작 방식을 따라가 봅시다.
- 세션 기록을 분석한다
- 메모리 조각을 생성한다 (예: 1,000개의 독립적인 조각)
- RAG 데이터베이스에 저장한다
- 매 프롬프트마다 가장 유사한 상위 5개를 붙인다
- 에이전트가 혼란스러워하면 검색 도구로 추가 정보를 찾는다
여기에 복잡한 기능을 계속 얹을 수도 있습니다. 과거 대화 원문 검색, 단기/장기 메모리 분류, 백그라운드 데몬을 돌려 메모리를 검토·병합·중복 제거하기, 밤새 메모리를 다시 쓰는 'Dreamers', 지속적인 컨텍스트 압축, 재순위화(re-ranking) 도구까지요.
문제는 이 부가 기능들이 토큰은 더 쓰면서도 기본 구조의 결함은 건드리지 못한다는 점입니다. '과거 조각을 저장하고 유사도로 꺼내 쓴다'는 전제 자체가 흔들리기 때문입니다.
회상 기반 메모리의 다섯 가지 문제
1. 유사성은 정확성이 아니다
임베딩 공간에서 두 조각이 가깝다는 사실만으로 순위를 정합니다. 어느 정보가 맞는지, 최신인지, 무엇이 빠졌는지는 알 수 없습니다.
2. 맥락이 잘려 나간다
조각 크기는 제한되어 있습니다. 주변 맥락, 그렇게 결정한 동기, 시행착오에서 얻은 교훈, 실행 환경을 한 조각에 모두 담을 수 없습니다.
3. 과거를 사실로 취급한다
코드베이스는 매일 바뀝니다. 벡터 DB에 인증 관련 조각이 500개 쌓여 있을 때, 각각이 지금도 유효한지는 아무도 모릅니다.
4. 모르는 것은 검색할 수 없다
검색 도구를 쥐여줘도, 에이전트는 자신이 무엇을 모르는지 모릅니다. 그래서 언제 도구를 써야 할지도 판단하기 어렵습니다.
5. 저장소를 점검하기 어렵다
SQLite에 임베딩 10,000개가 들어 있다면, 어떤 메모리가 존재하는지, 무엇이 오래됐거나 한 번도 검색되지 않았는지, 잘못된 정보가 동작에 영향을 주고 있는지 확인할 방법이 사실상 없습니다.
더 잘 회상하는 대신, 기록을 남기자
회상 기반 접근은 망각을 문제로 보고 더 많이 수집하고, 더 잘 색인하고, 더 똑똑하게 검색하는 것을 해법으로 삼습니다.
그런데 사람은 그렇게 일하지 않습니다. 어떤 기능의 제약 조건을 확인하려고 3년 전 회의를 다시 재생해 보는 사람은 없습니다. 대신 기록을 작성하고 참조합니다. 에이전트도 1,000만 토큰짜리 과거 대화를 뒤져 사건을 재구성하기보다 문서 기반 메모리를 활용하는 쪽이 자연스럽습니다.
AI로 코드를 깊이 읽거나 이해하지 않은 채 제품과 기능을 빠르게 쏟아내는 환경에서는 문서화가 뒷전으로 밀리기 쉽습니다. 하지만 바로 그래서 문서화가 더 중요해집니다.
AGENTS.md 하나로는 부족하다
AGENTS.md는 에이전트가 아무 맥락 없이 코드베이스에 들어오는 상황을 막아줍니다. 하지만 많은 프로젝트에서 이 파일이 유일한 문서이고, 파일 하나가 담을 수 있는 양에는 한계가 있습니다.
필요한 것은 에이전트가 별도 요청 없이도 기록을 남길 수 있는 구조화된 문서 작업 공간입니다.
- 지침(instructions) — 예: 코드 리뷰 절차
- 명세(specs) — 사용자와 논의한 내용을 그대로 기록
- 결정 사항(decisions) — 왜 이 방향을 택했는지
- 조사 결과(research) — 익숙하지 않은 라이브러리나 API를 조사한 내용을 재사용 가능하게 보관
- 색인(index) — 어디에 무엇이 있는지
작업 흐름을 바꾸기
기존: 프롬프트 → 구현 → 망각
개선: 프롬프트 → 참조 → 구현 → 갱신
작업 전에는 관련 문서를 읽어 충분한 맥락을 확보하고, 작업 후에는 전체 상황이 아직 컨텍스트에 남아 있는 동안 오래된 문서를 고치고 빠진 문서를 추가합니다. 이렇게 하면 메모리는 에이전트에 덧붙이는 RAG 데이터베이스가 아니라, 읽고 수정하고 공유하는 작업 공간이 됩니다.
실제 구현: Operator Memory
글의 저자는 이 아이디어를 Operator Memory라는 도구로 구현했습니다.
시작은 소박했습니다. internal/ 폴더에 명세·계획·색인을 기록하고 작업 전후로 읽고 갱신하라는 지침 한 장이었죠. 이것이 정식 체계로 다듬어지고 플러그인으로 발전했으며, 저자는 1년 넘게 이 방식을 사용하면서 모든 프로젝트에서 플러그인을 정기적으로 활용하고 있다고 합니다.
특징을 정리하면:
- 지침, 명세, 조사 결과, 색인을 보관하는 Markdown 기반 지식 공간
- 작업 전 관련 문서를 참조하고, 작업 후 오래된 문서를 수정하고 빠진 문서를 추가
- 벡터 데이터베이스와 임베딩을 사용하지 않음
- 요약기, 큐레이터, 갱신기, Dreamers 같은 토큰 소비형 백그라운드 데몬이 없음
- 블랙박스 검색이 없음
- 모든 지식이 일반 Markdown이므로 사람이 읽고, 수정하고, 커밋하고, 팀과 공유할 수 있음
- 무료 오픈소스
정리하며
이 글의 통찰은 기술 선택의 문제를 넘어섭니다. 에이전트 메모리를 '검색 문제'로 보면 끝없이 인프라를 쌓게 되지만, '기록 문제'로 보면 해법은 의외로 단순해집니다. 바로 사람이 읽을 수 있는 문서죠.
부수 효과도 분명합니다. 에이전트를 위해 작성한 문서는 동료 개발자에게도, 그리고 6개월 뒤의 나에게도 그대로 유용합니다. 벡터 DB에 묻힌 임베딩 1만 개는 그렇지 않습니다.
지금 당신의 프로젝트에 AGENTS.md 한 장만 있다면, 명세와 결정 기록을 담을 폴더 하나를 더 만드는 것부터 시작해 보는 건 어떨까요?