몇 주 전에 내 에이전트를 위해 세션 간 메모리 시스템을 구축했다. 이 시스템은 어떤 비자명한 작업을 수행하기 전에 네 개의 마크다운 파일을 읽는다: 알려진 문제와 그 해결책에 대한 bugs.md, 왜 그렇게 만들어졌는지에 대한 결정 사항을 담은 decisions.md, 사용자 이름, 엔드포인트, 스코프, 실행 명령어 등을 위한 key_facts.md, 그리고 작업 기록으로서의 issues.md이다. 이 시스템은 내가 만들고자 했던 문제를 해결했다: 에이전트가 세션 간에 모든 것을 잊어버리고 이미 내린 결정을 재논쟁하는 문제였다. 문제가 해결되었다.

그런 다음 지난주, 나는 새로운 OSS 기여를 위해 GitHub 토큰을 설정하도록 요청했고, 에이전트는 나에게 자신 있게 말했다:

• bugs.md: 서사(narrative) 형식으로 작성하며, 사건별로 한 항목씩 기록하고 날짜를 명시함.
• key_facts.md: 참고 자료(reference)이며, 현재 상태 요약본(current-state summary)을 담는 것이 목적임.
• decisions.md: ADRs(Architecture Decision Records) 형식으로 작성되며, 설계상 추가만 가능하도록(append-only) 되어 있음 (결정 사항에는 적절하지만, 사실 정보에는 부적절함).
• issues.md: 작업 기록부(work log)임.

워크플로우 범위의 사건은 bugs.md에 작성되었는데, 이는 CLAUDE.md의 프로토콜이 오류가 발생하면 그곳을 먼저 검색하도록(

그리고 더 중요한 프로토콜 변경 사항은 다음과 같습니다: bugs.md 항목이 key_facts.md에 요약된 사실을 수정할 경우, key_facts.md의 해당 줄이 '나중에'가 아니라 같은 자리에서 업데이트됩니다. 제가 기억하는 것을 믿지 못해서가 아닙니다 — 이 시스템의 핵심은 제가 기억할 필요가 없다는 것입니다 — 하지만 요약 파일이 에이전트가 가장 먼저 읽고 권위 있는 것으로 취급하기 때문입니다. 만약 수정 사항이 서술형 로그에만 존재한다면, 그것은 작업을 수행하기 전에 사고 기록을 순차적으로 읽는 사람에게만 도움이 될 뿐이며, 그런 사람은 아무도 없습니다. 참고 파일(reference file)이야말로 오래됨(staleness)이 실제로 비용을 발생시키는 곳입니다. 왜냐하면 그곳은 원본 기록 대신 읽도록 설계된 유일한 장소이기 때문입니다.

유사한 시스템을 구축하는 사람에게 해주고 싶은 말

만약 에이전트에게 메모리 파일(프로젝트 노트, 위키, CLAUDE.md 등)을 제공한다면, 그것을 정신적으로 두 가지 범주로 나누고 다르게 취급해야 합니다:

• 추가 전용의 서술형/날짜 기록 (사고 로그, ADRs(Architectural Decision Records), 작업 로그). 이들은 오래되어도 괜찮습니다. 즉, 오래된 항목들이 영원히 사실을 유지하는 것이 아니라 — 그것은 무엇이 일어났는지에 대한 기록일 뿐, 지금 현재에 대한 주장이 아니기 때문입니다.
• 현재 상태 요약본 (범위 목록, 엔드포인트 테이블, '이렇게 실행하기'). 이들은 모든 줄에 암묵적인 '현재 시점(as of now)'이 붙어 있으며, 그 '지금'이 실제로 지금임을 강제하는 것은 아무것도 없습니다.

실패 모드는 카테고리 1에 있는 것이 아닙니다. 아무도 오래된 버그 보고서가 오래된 날짜를 가지고 있다는 사실에 혼란스러워하지 않습니다. 문제는 카테고리 2입니다. 왜냐하면 요약 파일은 어제 업데이트되었든 6주 전에 업데이트되었든 동일하게 자신감 있고 시대를 초월한(timeless) 어조로 읽히기 때문이며, '여전히 참임'과 '참이었음' 사이에 시각적인 차이가 없기 때문입니다. 만약 에이전트가 오래된 요약 라인을 새로운 라인과 완전히 똑같이 취급한다면—같은 글꼴, 같은 확신, 문장 자체에 타임스탬프의 부재라는 점에서—당신은 자신이 말했던 모든 것에 대해 완벽하게 정직하면서도 당신을 오도할 수 있는 시스템을 구축한 것입니다. 해결책은 더 많은 메모리가 아닙니다. 요약 파일의 최신 상태를 누군가의 명시적인 임무로 만드는 것이며, 그것은 그 파일을 무효화(invalidate)했던 수정 작업과 같은 자리에서 이루어져야 합니다.