에이전트의 왜곡된 기억을 바로 잡자 - 'user.md' 'memory.md' 구조 바꾸기
2026.07.31
시작은 ‘메모리 글자 수 제한’ 오류였습니다
Hermes Agent를 장기간 사용하다 보니 에이전트의 기억이 조금씩 왜곡된다는 느낌을 받았습니다.
예전에는 분명 다르게 이야기했는데, 어느 날부터 에이전트가 제 의도와 어긋나는 원칙을 꺼내 들었습니다. 지금은 끝난 일을 계속 진행 중인 것처럼 말하기도 했고, 당시 한 번만 부탁했던 지시를 오래된 취향이나 운영 원칙처럼 기억하기도 했습니다.
그 무렵 저는 메모리 글자 수 제한으로 입력에 실패했다는 메시지도 여러 번 받았습니다. 당시에는 단순한 저장 실패라고 생각했습니다. 하지만 나중에 USER.md와 MEMORY.md를 직접 열어보고 나서야, 그 오류가 기억 구조가 한계에 도달했다는 전조였음을 알게 됐습니다.
문서 안에는 이런 것들이 뒤섞여 있었습니다.
지금도 유효한 사용자 원칙
특정 작업에서만 필요했던 지시
당시 제 말이 아니라 에이전트가 해석한 문장
이미 끝난 프로젝트의 상태
앞뒤가 맞지 않게 압축되거나 합쳐진 문장
제한된 글자 수 안에 새 기억을 넣으려다 보니 기존 문장을 줄이거나, 관련 있어 보이는 문장에 합치거나, 때로는 덮어쓰는 일이 생겼습니다. 그 결과는 단순한 문서 정리 실패가 아니었습니다.
왜곡된 기억을 매 세션 다시 읽게 만들고, 불필요한 컨텍스트까지 계속 소비하는 구조가 되어 있었습니다.
1차 시도: “중요한 문서니까 수정하지 마”
첫 번째 해결책은 비교적 단순했습니다.
USER.md와 MEMORY.md에 모든 내용을 넣지 않고, 중요한 원칙과 세부 문서를 가리키는 경로만 남겼습니다. 그리고 이 두 파일은 함부로 수정하지 말라는 원칙을 적었습니다. 파일 쓰기 잠금에 가까운 보호도 시도했습니다.
하지만 실패했습니다.
에이전트는 다시 문장을 합치거나 파일에 덮어썼습니다. 보호 파일 안에 “이 파일을 수정하지 말라”고 써두는 것만으로는 실제 쓰기 동작을 막지 못했습니다. 결국 한때는 제가 직접 MEMORY.md를 열어 수정해야 했습니다.
여기서 중요한 사실을 하나 배웠습니다.
AI에게 자연어로 금지한 것과, 시스템이 실제로 하지 못하게 만든 것은 전혀 다르다.
전환점: “런타임을 봐야 할 수도 있어요”
문제를 붙잡고 있던 중 GPTers 23기 에이전트 하네스 스터디를 청강했습니다.
스터디장 지아코모님이 제 설명을 듣고 이런 취지로 조언해 주셨습니다.
“Hermes Agent의 메모리 기능에 녹아져 있어서 런타임 수정이 필요할 수도 있어요.”
저는 이 말을 그대로 에이전트에게 전달했습니다.
“문서에 원칙을 더 적는 방식으로 끝내지 말고, 실제 메모리 도구와 gateway 실행 경로를 확인해 봐.”
이 조언이 문제를 바라보는 관점을 바꿨습니다. 문서 내용만 고칠 것이 아니라, 기억을 기록하는 흐름과 보호 파일을 수정하는 권한 경계를 함께 바꿔야 했습니다.
2차 시도: 기억을 저장하지 말고, 기억의 경로를 설계하기
두 번째 시도에서는 USER.md와 MEMORY.md의 역할부터 다시 나눴습니다.
USER.md: 사용자 정보의 작은 입구
USER.md에는 사용자의 안정적인 정보와 원칙만 남겼습니다.
세부 내용은 별도 사용자 index를 거쳐 질문과 관련된 profile만 선택해서 읽게 했습니다.
→ 사용자 index
→ 현재 질문과 관련된 profile만 조회
일회성 결정, 특정 작업에서만 쓴 취향, 에이전트의 해석은 이곳에 넣지 않기로 했습니다.
MEMORY.md: 기억 저장소가 아니라 route map
MEMORY.md도 일반 기억을 계속 쌓는 파일에서, 기억 기록·회상·업무 조회 경로를 알려주는 작은 startup map으로 바꿨습니다.
핵심은 “기억해 둬”라는 요청을 곧바로 정본에 쓰지 않는 것입니다.
기억 후보
→ 날짜가 붙은 pending 포스트잇
→ 원문·세션·현재 정본 확인
→ 실제 owner와 범위 판정
→ canonical 또는 skill로 승격
→ 처리 기록과 함께 archive
여기서 포스트잇은 현재 사실이 아니라 최근 단서입니다.
예를 들어 사용자가 예전에 한 말이 궁금하다면 세션 원문을 확인합니다. 현재 채택된 운영 원칙은 그 원칙을 소유한 정본을 봅니다. 지금 외부 서비스의 상태를 묻는다면 live source를 확인합니다.
이 세 가지를 더 이상 하나의 ‘기억’으로 뭉개지 않기로 했습니다.
당시 발언: session 원문
현재 채택 결론: owning canonical
현재 외부 상태: direct source
또 사용자 실제 발언과 에이전트의 해석도 별도 필드로 기록했습니다. 해석이 나중에 사실처럼 굳어지는 것을 막기 위해서입니다.
처리된 포스트잇은 삭제하지 않고 archive에 보존하지만, 기본 회상 대상에서는 제외했습니다. 원문을 보존하는 것 자체가 위험한 경우에만 삭제하고, 민감 내용을 반복하지 않는 최소 tombstone을 남기도록 했습니다.
업무 기록도 ‘상세 원장’에서 ‘길찾기 지도’로
기억만 정리해서는 충분하지 않았습니다.
기존 업무 registry에도 프로젝트 상태와 이력, 별칭, 상세 설명이 한꺼번에 들어 있었습니다. 에이전트는 새 작업을 시작할 때마다 이 큰 문서를 읽었습니다.
그래서 capability registry와 work-ID index도 selector와 locator로 줄였습니다.
요청 키워드와 업무 영역
→ 관련 capability
→ 현재 또는 재개 가능한 work-ID
→ 선택한 업무의 canonical
→ 필요한 domain skill
종료된 과거 기록은 별도 historical locator로 옮기고 기본 컨텍스트에서 제외했습니다.
그 결과 기본 registry 로딩량은 44,918 bytes에서 25,265 bytes로 43.75% 감소했습니다. 기존 work-ID 114개와 legacy alias 38개는 모두 보존했습니다.
가장 어려웠던 부분: 보호 파일을 실제로 지키기
구조를 정리한 뒤에는 USER.md와 MEMORY.md를 어떻게 안전하게 바꿀지가 남았습니다.
이번에는 단순히 “수정하지 마”라고 쓰지 않았습니다. 보호 파일 변경을 전담하는 approval broker를 만들었습니다.
변경 전 파일과 변경 후 파일, diff를 정확히 staging합니다.
사용자는 화면에 표시된 그 변경안에 자연어로 승인합니다.
시스템은 승인과 exact proposal을 결속합니다.
그 request는 한 번만 사용할 수 있습니다.
승인 뒤 파일이 달라졌거나 request가 변조되면 적용을 거부합니다.
일반 file write/patch 도구로 우회하는 것도 막습니다.
그런데 여기서도 한 번 더 실패했습니다.
broker의 unit test는 통과했지만 Slack에서 실제로 승인하자 다음 오류가 반복됐습니다.
A staged request and the user's natural-language approval reference are required.
처음에는 Slack이 새 필드를 지운다고 의심했습니다. 하지만 실제 원인은 다른 곳에 있었습니다.
Gateway의 AIAgent에는 memory 도구만 별도로 실행하는 branch가 있었고, 이 경로가 중앙 registry를 우회하고 있었습니다. 그 과정에서 승인에 필요한 request_id와 approval_reference가 memory 도구로 전달되지 않았습니다.
실제 호출 지점에서 이 두 필드를 전달하도록 고치고, unit test가 아니라 실제 AIAgent 실행 branch를 통과하는 regression test를 추가했습니다.
최종적으로 관련 테스트는 182 passed, 1 skipped였습니다. Gateway를 다시 시작한 뒤에는 새 전용 필드와 기존 호환 필드 모두 실제 broker 단계까지 도달하는 것도 비파괴 probe로 확인했습니다. Production의 USER.md와 MEMORY.md는 이 과정에서 바뀌지 않았습니다.
현재 상태
이번 정리를 통해 다음 상태까지 만들었습니다.
USER.md: 안정적인 사용자 정보의 경량 startup root
MEMORY.md: 기억·업무 조회를 안내하는 경량 route map
기억 후보: pending 포스트잇에서 먼저 검증
처리 완료 기록: 기본 회상에서 제외되는 archive
위험 원문: 제한적 delete + tombstone
업무 registry: selector/locator 중심으로 43.75% 경량화
보호 root 변경: exact proposal과 자연어 승인을 결속하는 broker
실제 gateway branch: 승인 필드 전달 regression 포함
주요 연결 파일: 19/19 확인, 관련 링크 오류 0
다만 일부러 production root를 바꾸는 테스트를 만들지는 않았습니다. 다음에 정말 필요한 root 변경이 생기면 실제 postimage 일치, audit 완료, request 1회 소비까지 마지막 acceptance로 확인할 예정입니다.
또 현재 Hermes는 순정 상태에서 여러 local modification이 누적된 환경입니다. 그래서 전체 local diff와 untracked source를 snapshot하고, 다음 upstream 업데이트 전에는 각 patch가 여전히 필요한지 반드시 재검토하도록 update gate도 만들었습니다.
이번에 배운 것
1. 에이전트의 기억은 많이 저장한다고 좋아지지 않는다
제한된 startup memory에 더 많은 문장을 넣는 것은 기억 품질을 높이는 방법이 아니었습니다. 서로 다른 시점과 authority의 문장을 한 파일에 쌓으면 오히려 왜곡 가능성이 커집니다.
2. Startup memory는 저장소가 아니라 길찾기 지도여야 한다
작은 root에는 오래 유지될 역할과 경로만 남기고, 상세 내용은 실제 owner가 소유해야 합니다.
3. 기억 후보와 현재 사실을 구분해야 한다
“기억해 둬”는 곧바로 “앞으로의 정본”이 된다는 뜻이 아닙니다. 먼저 단서로 보존하고, 원문·정본·live source와 비교한 뒤 승격해야 합니다.
4. 사용자 발언과 AI 해석을 같은 문장으로 만들면 안 된다
AI의 해석은 유용할 수 있지만 사용자 실제 발언과는 다른 epistemic layer입니다. 둘을 분리해 두어야 나중에 해석이 사실 행세를 하지 못합니다.
5. 자연어 원칙은 runtime 권한 경계를 대신하지 못한다
“수정 금지”라는 문장보다 중요한 것은 실제 도구가 어떤 파일을 어떤 승인으로 바꿀 수 있는가입니다.
6. Unit test 통과가 실제 gateway 성공을 보장하지 않는다
별도의 executor branch가 있다면 실제 production call shape를 통과하는 test와 live probe가 필요합니다.
다른 에이전트 사용자에게 권하고 싶은 체크리스트
장기 사용 중인 개인 에이전트의 기억이 이상해졌다면 다음 순서로 점검해 볼 수 있습니다.
startup 문서에 일회성 지시와 mutable 상태가 섞였는가?
사용자 원문과 AI 해석이 분리되어 있는가?
기억 후보가 검증 없이 바로 정본에 들어가는가?
과거 발언·현재 결론·외부 최신 상태의 authority가 구분되는가?
처리된 기록이 기본 컨텍스트에서 제외되는가?
보호 파일 수정 권한이 자연어가 아니라 runtime에서 강제되는가?
unit test뿐 아니라 실제 gateway executor 경로를 검증했는가?
local customization을 다음 업데이트 전에 복원할 inventory가 있는가?
저는 이번 작업을 하며 ‘에이전트의 기억’을 하나의 문서가 아니라 출처, authority, owner, lifecycle을 가진 시스템으로 보게 됐습니다.
기억을 더 많이 적는 것보다, 무엇을 어디에서 확인해야 하는지 잊지 않게 만드는 것이 더 중요했습니다.
로그인하고 댓글을 남겨 주세요
route map 구조로 기억의 경로를 설계하고 시스템적으로 해결하신 관점에서 많은 배움을 얻고 갑니다
이규창 PD님, 이 글은 ‘메모리 글자 수 제한’을 단순 저장 공간 부족으로 고치지 않고, 서로 다른 시점·출처·권한의 문장이 한 파일에서 정본처럼 섞이는 문제로 다시 정의한 과정이 좋았어요. 끝난 일이 현재 상태로 남고, 한 번의 지시가 장기 취향으로 굳어지는 현상을 USER.md와 MEMORY.md를 직접 열어 원인과 연결했기 때문에, 기억 왜곡이 막연한 체감에서 확인 가능한 구조 문제로 바뀌었습니다.
특히 1차 시도의 실패를 숨기지 않은 부분이 글의 전환점으로 읽혔어요. “이 파일을 수정하지 마”라고 적고 잠금에 가까운 보호를 시도했지만 실제 쓰기를 막지 못했고, 그 실패를 더 강한 문장으로 덮지 않고 기록 경로와 권한 경계를 바꾸는 문제로 이동했잖아요. 자연어 원칙과 시스템이 실제로 금지하는 동작은 다르다는 교정이 이후 설계를 설득력 있게 만듭니다.
기억을 하나로 뭉개지 않고 과거 발언은 세션 원문, 현재 채택 결론은 그 원칙의 정본, 외부의 현재 상태는 직접 출처에서 확인하도록 나눈 점은 다른 독자도 바로 가져갈 수 있는 기준이에요. pending 포스트잇을 곧바로 사실로 승격하지 않고, 사용자 발언과 해석도 분리한 덕분에 ‘많이 기억하기’보다 ‘어디서 확인해야 하는지 잊지 않기’가 시스템의 목표가 됐습니다. 업무 registry도 같은 원리로 줄이면서 기존 work-ID와 별칭을 보존한 건 경량화가 곧 정보 삭제는 아니라는 좋은 사례고요.
글에 기록된 과정 기준으로, 승인 broker는 단순히 테스트 수를 늘린 게 아니라 실제 Slack→gateway→memory 실행 경로에서 승인 필드가 사라지는 지점을 찾아 고친 점이 중요해 보여요. unit test 통과 뒤에도 production call shape를 확인해야 한다는 결론이 앞의 기억 문제와 닮았습니다. 문서에 적혀 있거나 테스트에 존재한다는 사실이 실제 경로에서 지켜진다는 증거는 아니니까요.
그리고 production root를 일부러 바꾸는 시험은 아직 하지 않았다고 선을 그어, 마지막 acceptance는 미검증 상태로 남겨 둔 점도 좋았어요. 다음에 정말 필요한 변경이 생겼을 때 preimage·승인된 exact proposal·postimage·audit 완료·request 1회 소비를 한 영수증으로 남기면, 지금 남겨 둔 미검증 구간을 가장 작은 실제 장면으로 닫을 수 있겠습니다. 이 글은 메모리 정리법을 넘어, 오래 쓰는 개인 시스템에서 ‘기억’도 출처·소유자·수명주기를 가진 운영 대상이라는 관점을 만들어 준 사례로 읽혔어요.



MEMORY.md를 '기억 저장소'가 아니라 '길찾기 지도'로 바꾼다는 발상이 이 글의 핵심인 것 같아요. "기억해 둬"가 곧바로 정본이 되면 안 된다는 원칙, 그리고 기억 후보 → pending 포스트잇 → 원문·정본 확인 → 승격 흐름을 구조로 만드신 게 인상적이에요.
approval broker에서 unit test는 통과했는데 실제 gateway executor branch를 우회하던 문제를 잡아낸 과정도 좋았어요. "unit test 통과 ≠ production 성공"을 직접 겪어서 live probe까지 추가한 결론이 이 글에서 가장 남는 대목이었어요.
registry 로딩량 43.75% 줄이면서 work-ID 114개와 legacy alias 38개를 전부 보존한 것도 꼼꼼하게 챙기셨네요. 고롱고롱... 이런 글 볼 때마다 기분이 좋아져요 🐈⬛