AI 메모리 저장소가 세션당 240k 토큰까지 커졌습니다. 제가 잘못한 점은 다음과 같습니다.

2025년 12월에 저는 Context Bank라는 작은 CLI 도구를 출시했습니다. 아이디어는 간단했고, 여전히 옳다고 생각합니다. AI 코딩 에이전트의 프로젝트 메모리를 리포지토리 내 .ai/ 폴더 아래 일반 마크다운 파일로 유지하고 git에 커밋하는 것입니다. 모든 도구(Claude Code, Codex, Cursor, Copilot, Gemini CLI)가 이를 읽고, 모든 팀원이 접근할 수 있으며, 도구를 전환해도 살아남습니다.

핵심 메시지는 "토큰 절약: 매 세션마다 프로젝트를 재설명하는 것을 멈추세요"였습니다.

8개월 후, 저 자신의 프로젝트에서 에이전트는 모든 작업을 시작하기 전에 최대 ~241k 토큰의 메모리를 읽고 있었습니다. 이 글은 어떻게 그런 일이 발생했는지, 그리고 제가 무엇을 변경했는지에 대한 내용입니다.

제가 작성한 계약서

v1이 생성한 AGENTS.md에는 다음과 같이 적혀 있었습니다:

필수 사항: 모든 작업 후, 반드시 다음 .ai/ 파일을 업데이트해야 합니다:
1. active-context.md - 현재 상태, 최근 변경 사항, 다음 단계.
2. roadmap.md - 완료된 기능은 [x]로 표시하고, 계획 중인 기능을 추가합니다.
...

그리고 rules.md는 에이전트에게 어떤 작업을 시작하기 전에 rules.md, active-context.md, 그리고 roadmap.md를 읽으라고 지시했습니다.

세 개의 파일을 시작할 때 읽고, 네 개의 파일을 끝낼 때 작성합니다. 모든 작업마다 말입니다.

에이전트들이 실제로 한 일

그들은 복종했습니다. 그것이 바로 전체 문제입니다.

"모든 작업 후 active-context.md를 업데이트하라"는 지시는 현재 작업에 대한 짧은 메모를 생성하지 않습니다. 대신 일기장을 만듭니다. 각 작업마다 "최근 변경 사항"을 추가하고, 아무도 이전 내용을 삭제하지 않으며, 에이전트가 가장 먼저 읽게 되는 파일은 프로젝트 시작 이후의 모든 세션 기록이 됩니다. 상태 마커는 작성만 되고 절대 지워지지 않습니다 (제 은행 중 하나는 이미 git에 있는 작업에 대해 여전히 "아직 커밋되지 않았음"이라고 표시했습니다). roadmap.md는 지금까지 완료된 모든 체크박스를 축적합니다.

다음은 제가 진행했던 네 개의 실제 프로젝트가, 해당 은행의 복사본을 기준으로 측정된 모습입니다 (토큰은 문자 수 / 4로 추정).

왜 이런 일이 발생하는가 (Why it happens)

사후적으로 명확해진 세 가지 점:

1. 추가(Appending)는 에이전트가 할 수 있는 가장 저렴한 편집이다. 파일 업데이트를 요청받으면, 에이전트는 줄을 추가한다. 재작성하거나 삭제하는 것은 위험하게 느껴지기 때문에 거의 일어나지 않는다.
2. '모든 작업 후(After every task)'는 메모리를 로그로 만든다. 대부분의 작업은 프로젝트의 현재 초점, 로드맵 또는 아키텍처를 변경하지 않는다. 그럼에도 불구하고 업데이트를 강제하면 노이즈가 발생한다.
3. Git 자체가 이미 로그이다. Diff, 커밋 메시지 및 파일 기록은 이미 무엇이 변경되었는지 기록하고 있다. 이것을 마크다운으로 복사하는 것은 매 세션마다 로드되는 한 곳에 중복을 일으킨다.

Cline의 Memory Bank 패턴도 같은 형태(

• 적게 읽기(Read little). 매 세션마다 rules.md(스택 및 규칙)와 active-context.md(현재 작업, 약 80줄)만 읽습니다. 계획 시에는 roadmap.md를, 구조가 중요할 때는 architecture.md를 읽습니다.
• 이력은 불러오는 것이 아니라 검색합니다(History is searched, not preloaded). story.md는 미래의 에이전트가 git으로부터 복구할 수 없는 희귀한 결정을 담고 있습니다. 에이전트는 과거 결정이 필요할 때 이를 grep 합니다.
• 적게 쓰기(Write less). 초점이 변경되었을 때만 active-context.md를 업데이트합니다. story.md에는 실제 결정에 대해서만 추가합니다. git이 이미 알고 있는 내용은 절대 작성하지 않습니다.
• 캡(Caps)과 이를 측정하는 도구. 각 파일에는 크기 제한(size cap)이 있습니다. context-bank doctor는 용량 초과 파일을, 남겨진 v1 명령어와 오래된 마커를 보고합니다.
• 아무것도 잃지 않고 정리하기(Clean up without losing anything). context-bank compact는 오버플로우 내용을 .ai/archive/로 이동시킵니다(복사본이며, 절대 삭제되지 않음). context-bank migrate는 v1 은행을 재작성하거나 Cline Memory Bank를 새 계약으로 변환합니다.

v3: 결정당 하나의 파일 (one file per decision)

v2도 오직 성장만 하는 단일 파일(story.md)이 있었습니다. 검색하는 방식이라 하더라도, 수백 개의 항목을 가진 단일 파일은 grep하기 어렵고, v2의 compact는 용량 제한을 지키기 위해 오래된 항목들을 아카이브로 잘라내야 했습니다.

v3에서는 이를 .ai/story/로 대체했습니다. 이곳에는 결정당 하나의 작은 파일이 있으며, 날짜와 제목으로 이름이 지정됩니다(2026-06-08-no-i18n-turkish-ui-english-code.md). 에이전트는 폴더를 나열하거나 grep하여 필요한 결정만 열어봅니다. 새로운 결정은 새 파일로, 오래된 결정은 수정되지 않으므로 이력(history)이 diff에서 변동하지 않습니다. 각 파일에는 자체적인 용량 제한이 있으며, migrate는 기존의 story.md(및 이전 compact가 아카이브한 모든 내용)를 항목을 누락시키지 않고 이 파일들로 분할합니다.

3.0.0 버전에서 migrate --compact를 거치기 전과 후의 동일한 은행(Same banks, same three files, before and after migrate --compact with 3.0.0):

이제 매 세션마다 rules.md와 active-context.md (23k 토큰)만 읽습니다. 네 개의 뱅크(banks) 기록은 각각 457, 167, 130, 66개의 결정 파일이 되었으며, 이 중 어느 것도 에이전트가 검색하려고 할 때까지 로드되지 않습니다.

AI 메모리를 마크다운에 보관할 경우

어떤 도구를 사용하든 저에게 효과적이었던 것들입니다:

• 매 세션마다 무엇이 로드되는지 측정하세요. 그 숫자를 모른다면, 아마도 증가하고 있을 가능성이 높습니다.
• '현재(current)'와 '기록(history)'을 분리하세요. 현재 작업은 재작성되고; 기록은 검색됩니다.
• 에이전트에게 모든 작업 후에 메모리를 업데이트하도록 요청하지 마세요. 다음에 필요할 무언가가 변경되었을 때 업데이트하도록 요청하세요.
• Git에 보관하세요. 저장소(repo)에 존재하는 메모리는 PR에서 검토되고, 팀과 공유되며, 도구 전반에 걸쳐 작동합니다. 사용자별 도구 메모리는 그렇지 않습니다.

사용해 보기

npx context-bank doctor            # 기존 뱅크 측정
npx context-bank migrate --compact # v1, v2 또는 Cline Memory Bank -> v3
npx context-bank init              # 새 프로젝트

Claude Code 플러그인도 있습니다 (계약 조건을 가르치고, 조용한 세션 시작 건강 검진을 수행하며, /context-bank:doctor, :compact, :init 기능을 제공하는 스킬):

claude plugin marketplace add kadiresen/context-bank
claude plugin install context-bank@context-bank

솔직히 주의할 점: 이 수치들은 제가 진행한 프로젝트의 것이며, 캐릭터 / 4는 토크나이저 카운트가 아닌 추정치입니다. compact 기능은 휴리스틱(heuristic)적입니다: active-context.md의 현재 초점 및 다음 단계 섹션을 유지하므로 결과를 자세히 살펴봐야 합니다. 결정 파일들은 원래 문구를 유지하며; 제목에 날짜가 없는 항목들은 migrate 후 빠르게 확인해야 합니다. architecture.md는 자동으로 압축되지 않습니다. 만약 이 파일이 용량을 초과하면, 현재 형태로 재작성할 수 있도록 사람(또는 감독하는 에이전트)의 도움이 필요합니다.

출처: MIT: https://github.com/kadiresen/context-bank