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

TL;DR Highlight

RAG 메모리 플러그인 대신 Markdown 문서 '두뇌'를 읽고 고치게 하자는 주장

Who Should Read

코딩 에이전트가 세션마다 프로젝트 맥락을 잊어 메모리 플러그인을 고민하는 개발자

Core Mechanics

메모리 플러그인은 전부 RAG 구조다
- 세션 기록에서 스니펫을 뽑아 RAG(검색 기반 주입) DB에 넣는다.
- 매 프롬프트마다 상위 5개를 붙이고, 더 필요하면 검색 도구를 준다.
회상 방식에는 문제 5가지가 있다
- 유사도로만 순위를 매겨 어느 것이 맞고 최신인지 알 수 없다.
- 스니펫에는 맥락이 빠지고, 과거를 사실로 취급하며, 모르는 건 검색조차 못 하고, 저장소 감사도 어렵다.
해법은 구조화된 문서 '두뇌'다
- 지시·스펙·리서치·매핑을 담은 작업 공간을 에이전트가 작업 전에 읽고 작업 후에 갱신한다.
- 저자는 internal/ 폴더에서 시작해 Operator Memory 플러그인으로 발전시켰다.
코드에 없는 것만 문서화한다
- 요구사항, 결정, 제약, 매핑, 재사용 리서치, 표준을 적는다.
- 안 적으면 매 세션 80k 토큰어치 탐색으로 의도를 역추정하게 된다.
카탈로그로 필요한 문서만 연다
- 세션 시작 때 문서별 설명과 열람 시점이 적힌 가벼운 카탈로그만 주입한다.
- 코드베이스도 인덱스와 하위 인덱스를 만들어 ls·grep 반복을 줄인다.

Community Reactions

문서도 낡는다는 반론
- 프로젝트에 결정 문서를 잔뜩 쌓았다가 낡아서 오히려 LLM이 헷갈렸다는 경험이 있었다.
- 문서 정합성을 맞추는 세션을 해도 혼란이 계속됐다고 한다.
같은 약점이 문서에도 있다는 지적
- 모르는 걸 검색 못 한다는 비판이 인덱스 방식에도 적용된다는 의견이 있었다.
- 다만 GitHub를 보면 카탈로그와 read_if 조건이 잘 짜여 있어 글보다 낫다는 평도 있었다.
토큰 비용과 수명 문제 경험담
- 비슷한 시스템을 만들었더니 문서가 늘수록 읽기·갱신 비용으로 작은 작업의 토큰이 부풀었다는 경험이 있었다.
- 마이그레이션 같은 시한부 정보나 선호 대 사실 구분, 서버형 에이전트에는 안 맞는다는 의견도 있었다.
각자의 대안 구조
- docs 폴더에 계획을 쌓고 낡은 건 archive로 옮기는 방식이 잘 된다는 경험이 있었다.
- README.md를 폴더별로 두거나, 에러 메시지에 해결법을 담은 lint 규칙을 쓰자는 의견도 있었다.
검증이 없다는 비판
- 성능 평가 없이 주장만 한다며 evals를 요구하는 의견이 있었다.
- 홍보성 글이라는 평과, 이미 Karpathy의 LLM Wiki 패턴이라는 지적도 있었다.

How to Apply

프로젝트에 docs 인덱스 파일 만들기
- 오늘 docs/INDEX.md에 문서별 한 줄 설명과 '언제 열지'를 적어라.
- AGENTS.md에 세션 시작 시 이 인덱스만 읽으라고 지시하라.
작업 후 문서 갱신 규칙 넣기
- AGENTS.md에 작업을 끝내면 바뀐 사실을 해당 문서에서 덧붙이지 말고 고쳐 쓰라고 적어라.
- 코드에서 알 수 있는 내용은 적지 말라고 명시하라.
문서 변경을 PR 리뷰에 포함하기
- 에이전트가 만든 문서 diff를 코드와 함께 리뷰하라.
- 비대해진 문서는 분리하거나 통합하라고 직접 요청하라.
낡은 문서는 archive로 분리하기
- 끝난 계획과 handoff 문서는 archive 폴더로 옮겨라.
- 에이전트에게 archive는 읽지 말라고 지시하라.

Try It

복사해서 바로 해보기

# Claude Code 또는 코딩 에이전트 세션에 붙여넣기 (원문 방법의 간이 버전)

너는 이 저장소의 문서 '두뇌'를 관리한다. 규칙:
1. 작업 전 docs/INDEX.md를 읽고, 설명과 열람 조건이 맞는 문서만 연다.
2. 코드로 알 수 있는 내용은 적지 않는다. 요구사항, 결정과 이유, 제약, 재사용할 리서치만 적는다.
3. 작업이 끝나면 전체 맥락이 남아 있을 때 관련 문서를 직접 갱신한다. 사실이 바뀌면 덧붙이지 말고 해당 문장을 고쳐 쓴다.
4. 문서가 길어지거나 범위를 벗어나면 분리하거나 통합한다.
5. INDEX.md에는 문서마다 '무엇을 다루는지'와 'read_if: 언제 열지'를 한 줄씩 유지한다.

지금 할 일: {{작업 내용}}

먼저 docs/INDEX.md가 없으면 만들고, 현재 코드에서 코드만으로는 알 수 없는 결정과 제약을 후보로 제안해 줘.

이어서 해 볼 것: 작업이 끝난 뒤 git diff docs/ 로 문서 변경을 코드처럼 리뷰해 보기

Terminology

RAG질문과 비슷한 조각을 검색해 프롬프트에 끼워 넣는 방식이다. 도서관에서 비슷한 책 몇 권을 뽑아 책상에 올려주는 셈이다.

AGENTS.md에이전트가 코드베이스에 들어가기 전에 읽는 지침 파일이다. 신입에게 주는 한 장짜리 온보딩 메모와 비슷하다.

하네스(harness)Claude Code, Codex처럼 모델을 감싸 도구와 루프를 제공하는 실행 환경이다.

Operator Memory글쓴이가 만든 오픈소스 플러그인이다. 작업 전 문서 조회와 작업 후 갱신을 에이전트 루프의 단계로 강제한다.

ADR아키텍처 결정 기록이다. 왜 그렇게 정했는지 남겨두는 회의록 같은 문서다.