AI 에이전트에 필요한 건 기억보다 문서일까

AI 코딩 에이전트에 필요한 것은 대화를 더 오래 기억하는 장치가 아니라, 프로젝트의 현재 상태를 설명하는 문서라는 주장이 나왔다. 글쓴이는 기존 메모리 플러그인이 과거 대화를 잘게 나눠 저장한 뒤 관련 있어 보이는 조각을 다시 붙이는 데 집중한다고 지적한다. 대신 에이전트가 작업 전에 문서를 읽고 작업 후에 고치도록 하는 오픈소스 플러그인 오퍼레이터 메모리(Operator Memory)를 공개했다. 해커뉴스(Hacker News) 토론에서는 문서도 낡을 수 있고, 에이전트가 읽거나 지시를 따르지 않으면 같은 문제가 반복된다는 반론이 나왔다.

핵심요약

  • 글쓴이는 대화 기록을 검색해 붙이는 메모리 플러그인이 프로젝트의 현재 상태와 설계 이유를 전달하기에는 부족하다고 주장한다.
  • 유사도 검색은 질문과 가까운 기록을 찾지만, 그 기록이 최신인지 또는 중요한 맥락이 빠졌는지 판단하지 못한다.
  • 문서 기반 방식에서는 에이전트가 작업 전에 지침·사양·결정을 읽고, 작업을 마친 뒤 바뀐 내용을 반영한다.
  • 오퍼레이터 메모리는 이 작업공간을 마크다운 파일로 만들어 사람이 읽고 수정하며 팀과 공유할 수 있게 했다.
  • 토론에서는 문서의 노후화, 지시를 실제로 따르게 하는 방법, 여러 에이전트가 함께 쓰는 환경이 쟁점으로 떠올랐다.

대화에서 뽑은 조각을 다시 붙이는 방식

글쓴이가 비판하는 메모리 플러그인은 에이전트와 주고받은 대화를 재료로 삼는다. 대화 기록을 분석해 짧은 ‘기억’ 조각을 만들고, 이를 벡터 데이터베이스(텍스트를 수치 표현으로 바꿔 비슷한 내용을 찾는 저장소)에 넣는다. 새 요청이 들어오면 가장 비슷한 조각 다섯 개를 프롬프트에 붙이고, 부족하면 에이전트가 저장소를 더 검색하게 한다. 글쓴이는 이 과정을 프로젝트를 이해시키는 일이 아니라 적당한 기록이 검색 결과에 걸리기를 기다리는 일로 본다.

사용자가 에이전트에 기대하는 지식은 과거 대화의 문장 몇 개보다 넓다. 기능이 코드 어디에 있는지, 왜 그런 방식으로 만들었는지, 사용자와 무엇을 합의했는지 알아야 다음 작업을 이어갈 수 있다. 그런데 짧은 기록이 검색됐다는 사실만으로는 그 결정이 내려진 이유나 지금도 유효한 제약이 함께 전달되지 않는다. 글쓴이가 보기에 문제는 에이전트가 과거를 덜 기억한다는 데 있지 않고, 현재 프로젝트를 설명할 자료가 없다는 데 있다.

기억을 다듬는 기능이 늘어도

글쓴이는 메모리 도구들이 기본적인 검색 방식에 여러 기능을 더해 왔다고 설명한다. 일부는 요약된 조각뿐 아니라 과거 대화 원문까지 검색하게 하고, 일부는 단기·장기 기억을 나눠 보관한다. 백그라운드에서 기록을 검토하거나 병합하고 중복을 제거하는 방식도 있다. 밤사이 기억을 다시 쓰거나 대화 맥락을 계속 압축하는 기능, 검색 결과의 순위를 다시 매기는 기능도 글에 등장한다.

이런 기능은 기록을 더 많이 다루거나 검색 결과를 더 정교하게 고르는 데 초점을 맞춘다. 글쓴이는 그 과정에서 토큰을 추가로 쓰면서도 과거 기록을 저장하고 다시 불러온다는 전제는 그대로 남는다고 지적한다. 기록을 정리하는 절차가 복잡해질수록 어떤 내용이 최종적으로 에이전트에게 전달됐는지 살펴보기도 어려워진다. 검색의 정교함과 프로젝트에 대한 정확한 이해를 같은 것으로 취급해서는 안 된다는 주장이다.

가까운 기록이 맞는 기록은 아니다

유사도 검색의 첫 번째 한계는 질문과 기록이 얼마나 가까운지만 따진다는 점이다. 임베딩(텍스트의 의미를 검색 가능한 수치로 나타낸 표현) 공간에서 가까운 조각을 찾더라도, 그 내용이 정확한지 또는 가장 최근 결정인지는 알 수 없다. 필요한 기록이 저장소에 아예 없는지도 검색 순위만으로는 드러나지 않는다. 결과가 관련 있어 보여도 작업에 필요한 정보가 모두 갖춰졌다고 볼 수 없는 이유다.

기록을 짧은 조각으로 나누는 과정에서도 정보가 빠진다. 어떤 구현을 택했는지는 남아 있어도 다른 선택지를 버린 이유나 당시의 작업 환경은 빠질 수 있다. 글쓴이는 설계 동기와 시행착오까지 알아야 판단할 수 있는 상황에서 이런 단편적 기록이 충분하지 않다고 본다. 에이전트가 검색 도구를 직접 쓸 수 있더라도, 빠진 정보를 스스로 알아채지 못하면 추가로 무엇을 찾아야 할지도 정하기 어렵다.

코드가 바뀐 뒤에도 남는 과거

프로젝트의 코드는 계속 바뀌지만 저장된 대화는 과거의 상태를 가리킨다. 글쓴이는 인증 기능에 관한 기록이 수백 개 쌓였다면 어느 설명이 현재 코드와 맞는지 가려야 한다고 예를 든다. 기록을 많이 모았다는 사실은 최신 상태를 잘 설명한다는 보장이 아니다. 오히려 오래된 구현과 새로운 결정을 구분하지 못하면 과거의 합의를 현재의 지시처럼 받아들일 수 있다.

저장소를 사람이 점검하기 어렵다는 문제도 있다. 글쓴이는 SQLite에 임베딩이 1만 개 들어 있는 상황을 들어, 어떤 기억이 존재하고 무엇이 낡았는지 파악하기 어렵다고 말한다. 한 번도 검색되지 않은 기록이나 틀렸는데 계속 에이전트의 답변에 영향을 주는 기록을 찾기도 쉽지 않다. 검색 결과가 잘못됐을 때 개별 기록을 확인하는 일과 저장소 전체의 상태를 관리하는 일은 서로 다른 과제다.

회의 기록 대신 정리된 설명

글쓴이는 사람들이 오래전 회의를 처음부터 다시 보며 기능의 제약을 확인하지는 않는다고 말한다. 회의와 작업을 거쳐 정리된 기록을 읽고, 이후 결정이 달라졌다면 그 기록을 고쳐 쓴다는 것이다. 에이전트에게도 방대한 과거 대화에서 결정의 조각을 재구성시키기보다, 현재 작업에 쓸 설명을 주자는 제안이다. 기록의 목적을 모든 발언의 보존에서 다음 작업에 필요한 지식의 정리로 바꾸는 셈이다.

이 구분은 AI로 제품과 기능을 빠르게 만드는 상황에서 더 중요하다는 것이 글쓴이의 판단이다. 글쓴이는 코드를 충분히 읽거나 이해하지 않은 채 결과물을 만들어 내는 일이 가능해지면서 문서가 뒷전으로 밀리기 쉽다고 지적한다. 그러나 작업 속도가 빠를수록 새로 들어온 에이전트가 무엇을 전제로 판단해야 하는지 알려줄 자료도 필요하다. 대화 기록을 계속 쌓는 방식만으로는 그런 설명을 읽기 좋은 형태로 유지하기 어렵다는 주장이다.

AGENTS.md 한 장을 넘어서

AGENTS.md는 에이전트가 코드베이스에 들어올 때 기본 지침을 읽게 하려는 파일이다. 글쓴이는 이런 파일이 도움이 되지만, 프로젝트 문서가 사실상 그 한 장뿐이라면 충분하지 않다고 본다. 코드 리뷰가 어떻게 진행되는지, 사용자와 논의한 사양이 무엇인지, 낯선 라이브러리나 API를 조사하며 무엇을 확인했는지는 성격이 다른 정보다. 이 모든 내용을 하나의 긴 지침에 넣기보다 각각의 문서로 정리하고 찾아갈 수 있게 해야 한다는 것이다.

글쓴이가 구상한 작업공간에는 지침, 사양, 설계 결정, 조사 결과와 색인이 들어간다. 에이전트는 작업을 시작할 때 색인과 관련 문서를 참고해 해당 작업의 맥락을 얻는다. 예를 들어 기능을 바꾸는 작업이라면 기존 사양과 결정 이유를 먼저 읽고, 다른 라이브러리를 다루는 작업이라면 앞서 정리한 조사 내용을 활용할 수 있다. 문서는 에이전트만을 위한 숨은 저장소가 아니라 사람이 열어 내용을 확인하고 바로잡을 수 있는 파일이다.

작업 전에는 읽고, 끝난 뒤에는 고친다

문서 기반 방식에서 중요한 것은 파일을 만들어 두는 것만이 아니다. 글쓴이는 에이전트가 요청을 받고 결과물을 만든 뒤 맥락을 잊는 흐름을, 문서를 참고하고 작업한 다음 문서를 갱신하는 흐름으로 바꾸자고 제안한다. 작업 전에 읽는 과정은 과거 결정을 재구성하는 시간을 줄이고, 작업 후에 고치는 과정은 다음 세션에 낡은 설명이 남지 않게 하려는 것이다. 읽기와 갱신이 한 작업의 일부로 묶여야 문서가 계속 쓸 만한 상태를 유지한다.

갱신 시점에도 이유가 있다. 작업을 막 마쳤을 때는 무엇을 바꿨고 어떤 문서가 그 영향을 받는지 아직 맥락 속에서 살펴볼 수 있다. 글쓴이는 이때 오래된 설명을 고치고 빠진 문서를 새로 쓰도록 에이전트에 맡긴다. 다만 이 순환은 에이전트가 관련 문서를 제대로 찾고 변경 사항을 정확히 적는다는 전제에서만 작동한다. 해커뉴스에서 나온 반론 역시 문서라는 형식보다 이 과정의 신뢰성에 집중됐다.

내부 폴더에서 오퍼레이터 메모리까지

글쓴이는 AI로 프로그래밍을 시작했을 때 세션이 바뀌어도 이전 작업을 이어갈 방법이 필요했다고 설명한다. 처음에는 프로젝트 안에 internal/ 폴더를 만들고 에이전트에게 사양, 계획, 색인을 적도록 했다. 작업 전에 적절한 문서와 색인을 읽고 끝난 뒤 갱신하라는 지시도 함께 뒀다. 이 규칙이 점차 정리돼 오퍼레이터 메모리라는 플러그인으로 발전했고, 글쓴이는 이를 1년 넘게 자신의 프로젝트에서 사용했다고 밝혔다.

오퍼레이터 메모리는 지침과 사양, 조사 결과, 색인을 마크다운 문서로 보관하는 ‘문서 작업공간’을 제공한다. 글쓴이는 벡터 데이터베이스나 임베딩을 사용하지 않고, 백그라운드에서 기억을 요약하거나 다시 쓰는 구성요소도 두지 않았다고 소개한다. 에이전트는 작업 전에 관련 문서를 참고하고, 끝난 뒤에는 낡은 문서를 손보거나 필요한 문서를 추가한다. 파일을 사람이 읽고 수정하며 커밋해 팀과 공유할 수 있다는 점이 글쓴이가 내세우는 차이다.

커뮤니티 의견

한 사용자는 코드 자체가 문서이며, 별도의 메모리 체계나 방대한 마크다운 파일은 오히려 에이전트의 맥락을 어지럽힌다고 했다. 자신도 설계와 결정에 관한 문서를 많이 남겼지만, 시간이 지나 낡은 문서가 문제를 일으켰다고 설명했다. 문서를 코드에 맞춰 다시 정리해도 에이전트가 혼란스러워졌다는 경험이다. 답글에서는 예외적인 설계 이유만 코드와 테스트 안에 남기는 편이 낫다는 의견이 나왔다.

다른 사용자는 글쓴이가 지적한 문제들이 문서 기반 방식에도 적용된다고 반박했다. 에이전트가 무엇을 모르는지 몰라 검색하지 못한다면, 처음부터 어떤 문서를 읽어야 하는지도 알아내기 어렵다는 것이다. 문서 역시 낡으며, 에이전트가 이를 갱신하는 작업은 글쓴이가 비판한 기억 정리 기능과 닮았다고 지적했다. 다만 공개된 플러그인에는 각 문서의 내용과 읽을 시점을 알려주는 목록이 있어, 에이전트가 아무 단서 없이 파일을 고르는 구조는 아니라고 덧붙였다.

또 다른 사용자는 지침을 어디에 적느냐보다 실제로 따르게 하는 방법이 중요하다고 말했다. JSON을 처리할 때 파이썬 스크립트 대신 jq를 쓰라고 해도 에이전트가 계속 임시 파이썬 코드를 작성한다는 경험을 들었다. 답글에서는 잘못된 응답을 감지하는 훅을 만들고, 이후 같은 문제가 나타나면 에이전트에게 피드백을 주는 도구가 소개됐다. 문서에 적힌 규칙을 읽는 일과 그 규칙을 실행 과정에서 지키는 일은 다르다는 지적이다.

문서와 기억의 유효기간을 관리해야 한다는 의견도 나왔다. 시스템 이전 중에만 중요한 주의사항은 이전이 끝난 뒤에도 같은 무게로 남아 있어서는 안 된다는 것이다. 이 사용자는 여러 사람이 서로 다른 답변 방식을 선호할 때 사실과 개인별 선호를 구분할 필요도 있다고 봤다. 서버에서 여러 에이전트가 동시에 일하는 환경에는 모두가 수정할 단일 파일시스템을 전제한 방식이 맞지 않을 수 있다고 덧붙였다.

문서 활용에 동의하면서도 에이전트 전용 문서를 따로 늘릴 필요는 없다는 사용자도 있었다. 기여 안내, 코딩 표준, README, 아키텍처 문서, 커밋 메시지와 GitHub 이슈에 적힌 사양을 에이전트가 활용하게 한다는 설명이다. 답글에서는 AI가 만든 문서가 장황하고 초점이 흐려지기 쉽다는 경험이 공유됐다. 중요한 내용만 사람이 직접 적으면 에이전트가 읽어야 할 맥락도 줄일 수 있다는 의견이다.

한 사용자는 문서보다 결정적인 피드백을 더 강조했다. 규칙을 어긴 코드에 대해 어떻게 고쳐야 하는지 설명하는 린트 오류를 제공하는 방식을 시험했고 좋은 결과를 얻었다는 것이다. 이어지는 논의에서는 일반적인 규칙 몇 개에 그치지 말고 프로젝트 고유의 코드 문제도 감지해야 한다는 요구가 나왔다. 에이전트가 문서의 지시를 놓치더라도 실행 과정에서 이를 다시 알려주는 장치가 필요하다는 관점이다.

실제로 프로젝트마다 문서 폴더를 운영한다는 사용자는 진행 중인 계획과 완료된 계획을 나눠 관리한다고 했다. 낡거나 끝난 문서는 보관 폴더로 옮기고, 에이전트에게는 현재 문서를 읽되 보관 자료는 평소 작업에서 제외하도록 지시한다. 보관 자료는 버리지 않고 코드가 과거의 설계 의도에서 얼마나 멀어졌는지 점검할 때 다시 쓴다. 이는 문서를 계속 쌓기보다 현재 자료와 이력을 구분하는 방식이다.

뒤이어 한 사용자는 메모리 플러그인의 문제가 과거를 기록한다는 행위 자체는 아니라고 지적했다. 회의 뒤에 메모를 남기듯 중요한 내용을 추려 적는 일은 도움이 되지만, 발언마다 기록을 만들어 수천 개의 조각을 쌓으면 관리 부담이 커진다는 것이다. 이 사용자는 최종 상태뿐 아니라 결정에 이른 과정도 남기려면 설계 결정 기록이 유용할 수 있다고 봤다. 답글에서는 에이전트가 작성한 사양에 요청하지 않은 추측이 섞일 수 있으므로 사람의 승인이 필요하다는 경고가 나왔다.

핵심통찰

이 논쟁은 에이전트가 과거를 얼마나 많이 저장하느냐보다, 다음 작업에 쓸 설명을 어떻게 골라 최신 상태로 유지하느냐에 관한 것이다. 마크다운 문서는 사람이 내용을 읽고 고칠 수 있어 검색 조각보다 점검하기 쉽지만, 파일이 많아지면 낡은 결정도 함께 늘어날 수 있다. 앞으로 살펴볼 것은 에이전트가 필요한 문서를 실제로 찾고 읽는지, 코드 변경을 정확히 반영하는지, 문서의 규칙을 어겼을 때 바로잡을 피드백을 받는지다.


원본: Agents Don’t Need Memory. They Need Documentation.

토론: Hacker News