에이전트와 긴 작업을 하다 보면 답답한 순간이 옵니다. 어제 세션에서 분명히 '이 방법은 실패했다'고 알려줬는데, 오늘 새 세션에서 에이전트가 같은 방법을 다시 시도합니다. 에이전트에게 이전 세션의 기억이 없기 때문입니다. 이 문제를 해결하는 것이 대화 밖 메모리입니다.
에이전트 메모리의 종류
| 종류 | 위치 | 지속성 | 용도 |
|---|---|---|---|
| 컨텍스트 창 | 모델 내부 | 세션 중에만 | 현재 대화, 즉각적인 맥락 |
| 외부 파일 | 파일시스템 | 영구 | 작업 상태, 결정 기록, 다음 단계 |
| 데이터베이스 | DB 서버 | 영구 | 구조화된 데이터, 대규모 기억 |
| 임베딩/벡터DB | 벡터 저장소 | 영구 | 의미 검색, 지식 베이스 |
핵심 메모리 파일 3종 세트
3종 메모리 파일 구성
- loop-state.md: 현재 루프의 실시간 상태. 지금 반복 몇 번째인지, 마지막으로 무엇을 했는지, 다음에 뭘 해야 하는지를 기록합니다.
- decision-log.md: 왜 이런 접근을 선택했는지, 어떤 대안을 고려했는지, 무엇이 실패했는지를 기록합니다. 시행착오의 역사입니다.
- verification-log.md: 각 반복에서 실행한 검증 명령과 그 결과(통과/실패, 오류 내용)를 기록합니다. 나중에 어디서 막혔는지 추적할 수 있습니다.
loop-state.md 예시
# 루프 상태 파일
생성: 2026-06-28 14:30
마지막 업데이트: 2026-06-28 16:45
## 현재 목표
TypeScript 타입 오류를 89개에서 0개로 줄이기
## 진행 상황
- [x] 반복 1: 타입 오류 목록 파악 (89개 확인)
- [x] 반복 2: auth/ 폴더 수정 완료 (89 -> 62개)
- [x] 반복 3: api/ 폴더 수정 완료 (62 -> 31개)
- [ ] 반복 4: components/ 폴더 수정 (진행 중)
## 다음 단계
- components/UserCard.tsx의 any 타입 제거
- components/DataTable.tsx의 제네릭 타입 추가
## 실패한 접근법
- Zod 스키마 자동 추론: 순환 참조 오류 발생, 포기새 세션에서 이어받기
새 세션을 시작할 때 에이전트에게 loop-state.md를 먼저 읽도록 지시하면, 마치 어제 작업을 계속 하는 것처럼 이어갈 수 있습니다. 하네스가 자동으로 이 파일을 컨텍스트 초반에 주입하도록 설계하면 더욱 매끄럽습니다.
메모리와 컨텍스트 창의 균형
외부 파일에 모든 것을 다 기록한다고 해서 그것을 전부 컨텍스트 창에 넣어야 한다는 의미는 아닙니다. 현재 작업과 직접 관련 있는 부분만 선택적으로 주입합니다. 긴 결정 로그라면 최근 5번의 결정만, 긴 오류 목록이라면 현재 집중하는 파일의 오류만 넣습니다.
세션 시작 메모리 로드 프롬프트
작업을 시작하기 전에 다음 파일들을 순서대로 읽고,
내용을 파악한 후 현재 상태를 요약해 줘:
1. tasks/loop-state.md - 현재 진행 상황
2. tasks/decision-log.md - 지금까지의 결정과 실패 기록
3. tasks/verification-log.md - 마지막 검증 결과
요약 후 '다음에 해야 할 작업'과 '피해야 할 접근법'을 알려줘.
그런 다음 작업을 시작해.loop-state.md는 항상 에이전트가 직접 업데이트하도록 하세요. '이 반복이 끝나면 loop-state.md의 진행 상황을 업데이트하라'는 지시를 루프의 마지막 단계로 넣으면 자동으로 관리됩니다.
메모리 파일에 민감한 정보(API 키, 개인정보, 인증 토큰)를 절대 저장하지 마세요. 이 파일들은 보통 git에 커밋되거나 로그에 남을 수 있습니다. 환경변수와 시크릿 관리 도구를 따로 사용하세요.