← 목록으로

에이전트에게 필요한 것은 메모리가 아니라 문서다

• 에이전트가 프로젝트를 이해하려면 과거 대화 조각을 검색하는 메모리보다 프로젝트 문서가 필요함. 기능의 위치, 구현 이유, 합의 사항, 중요하게 여기는 기준을 함께 파악할 수 있어야 함
• 대화를 조각내 저장하고 프롬프트마다 유사한 항목을 주입하는 RAG 기반 메모리는 정보의 정확성, 최신성, 누락 여부를 보장하지 못함
• 검색 도구를 추가해도 에이전트는 자신이 무엇을 모르는지 알 수 없으며, 방대한 임베딩 저장소에서는 오래되거나 잘못된 정보가 동작에 영향을 주는지 점검하기 어려움
• AGENTS.md 하나를 넘어 지침, 명세, 결정 사항, 조사 결과, 색인을 담는 구조화된 문서 작업 공간이 필요함
• 작업 흐름을 프롬프트 → 참조 → 구현 → 갱신으로 바꾸면, 전체 맥락이 남아 있을 때 문서를 최신화하고 사람이 읽고 수정하고 공유할 수 있는 지식으로 유지할 수 있음

대화 검색과 프로젝트 이해의 차이

• 메모리 플러그인은 대화를 분석해 1,000개의 독립적인 조각을 벡터 데이터베이스에 넣고, 매 프롬프트에 가장 유사한 5개를 붙이는 방식으로 작동함
  • 에이전트가 혼란스러워하면 검색 도구로 추가 정보를 찾음
  • 그러나 필요한 것은 대화 조각의 유사성이 아니라 기능의 위치, 구현 이유, 합의 사항, 사용자 우선순위에 대한 이해임
• RAG 검색이 제대로 작동하더라도, 검색된 조각만으로 프로젝트 전체를 이해할 수 있는 것은 아님

복잡한 기능을 더해도 유지되는 RAG 구조

• 메모리 플러그인의 기본 구조는 세션 기록 분석 → 메모리 조각 생성 → RAG 데이터베이스 저장 → 상위 5개 검색 및 주입으로 이어짐
  • 추가 정보가 필요하면 에이전트가 데이터베이스를 검색함
• 일부 도구는 과거 대화 원문 검색이나 단기/장기 메모리 분류를 추가함
  • 백그라운드 데몬이 메모리를 검토, 병합, 중복 제거하기도 함
  • 밤새 메모리를 다시 쓰는 ‘Dreamers’, 지속적인 컨텍스트 압축, 재순위화 도구도 사용함
• 이런 부가 기능은 토큰을 더 소비하지만, 과거 조각을 저장하고 검색하는 기본 구조의 문제를 해결하지 못함

회상 기반 메모리의 다섯 가지 문제

• 유사성은 정확성이 아님: 임베딩 공간에서 두 조각이 얼마나 가까운지만으로 순위를 정하므로, 어느 정보가 맞고 최신인지, 무엇이 빠졌는지 알 수 없음
• 맥락이 잘려 나감: 제한된 크기의 RAG 조각에는 주변 맥락, 동기, 교훈, 환경을 모두 담을 수 없음
• 과거를 사실로 취급함: 코드베이스는 매일 바뀌는데, 과거 대화나 벡터 데이터베이스의 인증 관련 조각 500개가 각각 얼마나 정확한지는 불분명함
• 모르는 것을 검색할 수 없음: 검색 도구가 있어도 에이전트는 자신이 무엇을 모르는지 모르므로 언제 도구를 써야 할지 알기 어려움
• 저장소를 점검하기 어려움: SQLite에 임베딩 10,000개가 있을 때 어떤 메모리가 존재하는지, 무엇이 오래됐거나 한 번도 검색되지 않았는지, 잘못된 정보가 동작에 영향을 주는지 확인하기 어려움

과거를 더 잘 회상하는 대신 지식을 기록하기

• 회상 기반 접근은 망각을 문제로 보고, 더 많이 수집하고 더 잘 색인하고 더 똑똑하게 검색하는 것을 해결책으로 삼음
• 사람은 기능의 제약 조건을 확인하려고 3년 전 회의를 다시 보는 대신 기록을 작성하고 참조함
  • 에이전트도 과거 1,000만 토큰의 대화를 뒤져 사건의 조각을 재구성하기보다 문서 기반 메모리를 활용해야 함
• AI로 코드를 읽거나 이해하지 않은 채 제품과 기능, 저품질 결과물을 빠르게 만들어내는 환경에서는 문서화가 뒷전으로 밀리기 쉽지만 오히려 더 중요해짐

AGENTS.md에서 구조화된 문서 작업 공간으로

• AGENTS.md 는 에이전트가 아무 맥락 없이 코드베이스에 진입하지 않도록 돕지만, 프로젝트의 유일한 문서인 경우가 많으며 파일 하나로는 부족함
• 에이전트에는 별도 요청 없이 지침, 명세, 결정 사항, 조사 결과, 색인을 기록할 수 있는 구조화된 작업 공간이 필요함
  • 코드 리뷰 절차를 담은 지침을 유지함
  • 사용자와 논의한 내용을 명세로 기록함
  • 익숙하지 않은 라이브러리나 API 조사 결과를 재사용할 수 있게 보관함
• 작업 전에는 관련 문서를 읽어 충분한 맥락을 확보하고, 작업 후에는 전체 상황이 컨텍스트에 남아 있을 때 오래된 문서를 고치고 필요한 문서를 추가함
• 에이전트의 반복 흐름을 프롬프트 → 구현 → 망각에서 프롬프트 → 참조 → 구현 → 갱신으로 바꿈
  • 메모리는 에이전트에 덧붙이는 RAG 데이터베이스가 아니라 읽고 수정하고 공유하는 작업 공간이 됨

Operator Memory로 구현한 문서 기반 메모리

• Operator Memory는 internal/ 폴더에 명세, 계획, 색인을 기록하고 작업 전후로 읽고 갱신하도록 한 지침에서 출발함
  • 이 지침이 정식 체계를 거쳐 플러그인으로 발전했으며, 개발자는 1년 넘게 이 체계를 사용하고 모든 프로젝트에서 플러그인을 정기적으로 활용함
• Operator Memory는 지침, 명세, 조사 결과, 색인을 보관하는 Markdown 기반 지식 공간을 제공하는 무료 오픈소스 도구임
  • 작업 전 관련 문서를 참조하고, 작업 후 오래된 문서를 수정하며 빠진 문서를 추가함
• 벡터 데이터베이스와 임베딩을 사용하지 않으며, 요약기, 큐레이터, 갱신기, Dreamers 같은 토큰 소비형 백그라운드 데몬이나 블랙박스 검색도 없음
• 모든 지식은 일반 Markdown 문서이므로 사람이 읽고 수정하고 커밋하고 팀과 공유할 수 있음