AI 에이전트 대화 기록 외부 저장 — 이어받으면 로컬 사본이 지워집니다

AI 에이전트를 서버 여러 대에 올려 돌리면 곧바로 걸리는 문제가 있습니다. 대화 기록이 각자의 디스크에 쌓여서, 다른 기계에서는 이어받을 수가 없거든요. 그래서 기록을 내 저장소에 두는 기능이 따로 있습니다. 공식 문서를 읽어보니 "대체"가 아니라 "복사"인 게 핵심이고, 저장소에서 이어받은 실행만 로컬 사본이 지워집니다. 이 차이를 모르면 어느 쪽이 진짜 기록인지 헷갈려요. 정리했습니다.

📌 30초 요약

• ★★항상 로컬에 먼저 씁니다 — 내 저장소는 복사본입니다.
• ★이어받은 실행만 로컬이 지워집니다 — 그때는 내 것이 유일본.
• ★작업 폴더가 다르면 못 이어받습니다.
• ⚠️ 저장이 실패해도 세션은 안 멈춥니다 — 그 묶음만 버립니다.
• 재시도 때문에 같은 항목이 두 번 갈 수 있습니다.
• 보관 기간은 전적으로 내 책임입니다 — 알아서 안 지웁니다.

밖에 저장하는 게 아니라 복사본입니다

구조부터 정확히 알아야 합니다. 에이전트는 언제나 자기 디스크에 먼저 기록을 쓰고, 그 묶음을 그대로 내 저장소에 한 번 더 넘깁니다. 그러니까 내 저장소는 원본을 대신하는 곳이 아니라 거울이에요. 흔히 "외부 저장소로 옮긴다"고 생각하는데 그게 아닙니다.

그런데 어느 쪽이 살아남는지가 시작 방식에 따라 갈립니다. 새로 시작했거나 저장소에 그 세션이 없어서 그냥 돌아간 경우엔 로컬 기록이 남고 내 저장소는 사본을 받습니다. 반대로 저장소에서 기록을 받아와 이어붙인 실행은, 끝날 때 로컬 사본이 삭제됩니다. 그 경우엔 내 저장소가 유일한 사본이 되는 거죠.

⚠️ 시작할 때 바로 튕겨내는 조합 둘

거울 구조라서 로컬 기록을 끄는 설정과는 같이 쓸 수 없습니다. 베낄 원본이 없어지니까요. 파일을 되돌릴 수 있게 백업해두는 기능과도 충돌합니다 — 그쪽은 백업을 로컬에 바로 쓰는데 그건 거울에 안 실리거든요. 둘 중 하나라도 저장소와 함께 켜면 시작하자마자 오류를 냅니다. 그리고 새 세션이 로컬에 아무것도 안 남기길 원한다면 설정 폴더를 임시 폴더로 돌리면 되는데, 그 폴더에 로그인 정보가 없으면 "로그인 안 됨"으로 실패하니 인증 파일을 먼저 옮겨두거나 열쇠를 환경에 직접 넣어야 합니다.

작업 폴더가 다르면 못 이어받습니다

기록을 찾는 열쇠가 세 조각입니다 — 작업 폴더를 안전한 글자로 바꾼 이름, 세션 번호, 그리고 곁가지 여부. 여기서 첫 조각이 함정이에요. 작업 폴더가 열쇠에 들어가 있으니, 이어받으려면 원래 실행과 같은 작업 폴더에서 돌려야 합니다. 서버가 달라도 되지만 폴더 구조는 맞아야 하는 거죠.

경로가 매번 달라지는 환경이라면 그 이름을 내가 직접 정해 고정할 수 있습니다. 다만 목록을 읽거나 지우는 독립 기능들은 그 설정을 안 보고 프로그램 전체의 환경만 읽으니, 같은 이름을 바깥쪽 환경에도 함께 넣어야 합니다. 백엔드를 붙여 데이터를 쌓는 흐름에 익숙하다면, 여기서도 "어느 열쇠로 찾느냐"가 전부라는 게 금방 와닿을 겁니다.

저장소에 그 세션이 없을 때	어떻게 되나
번호를 찍어 이어받기	로컬 기록으로 이어받습니다 — 평소와 동일
"직전 것 이어서" (한쪽 언어)	새 세션으로 시작합니다
"직전 것 이어서" (다른 쪽 언어)	가장 최근 로컬 세션을 이어갑니다
목록 기능을 안 만들었을 때	"직전 것 이어서"가 예외를 냅니다

표의 둘째·셋째 줄이 특히 얄궂습니다. 같은 "직전 것 이어서"인데 언어에 따라 하나는 새로 시작하고 하나는 로컬을 이어갑니다. 저장소가 비었을 때만 갈리는 차이라, 평소엔 안 보이다가 저장소가 잠깐 빈 순간에 튀어나와요. 인증 처리도 언어별로 달라서, 한쪽은 설정 파일까지 임시 폴더로 복사해 주지만 다른 쪽은 로그인 정보만 복사합니다. 그래서 설정 파일에 인증을 걸어둔 앱은 이어받을 때 "로그인 안 됨"으로 실패할 수 있습니다.

저장이 실패해도 세션은 안 멈춥니다

내 저장소가 잠깐 죽어도 에이전트는 계속 돕니다. 어차피 로컬에 먼저 쓰니까요. 실패하면 짧게 쉬었다 두 번 더, 합쳐서 세 번까지 시도하고, 그래도 안 되면 기록을 남기고 그 묶음을 버린 뒤 그냥 진행합니다. 대신 흐름에 "거울 쓰기 실패"라는 알림이 한 줄 섞여 나오니, 데이터가 새는 걸 알아채려면 이걸 지켜봐야 합니다.

여기서 두 가지를 챙겨야 합니다. 첫째, 시간 초과로 끝난 요청은 재시도하지 않습니다 — 원래 요청이 늦게라도 도착했을 수 있어서예요. 둘째, 재시도 때문에 이미 들어간 항목이 다시 올 수 있으니 받는 쪽에서 항목 고유값으로 중복을 걸러야 합니다. 그리고 무서운 대목 하나 — 저장소에서 이어받아 돌던 실행에서 묶음이 버려지면, 실행이 끝나는 순간 그 부분은 어디에도 안 남습니다. 로컬 사본이 지워지니까요.

✅ 동시에 쓰면 요약 파일에서 부딪힙니다

목록을 빠르게 보여주려고 세션마다 요약을 곁에 하나씩 유지하는 구조인데, 같은 세션에 대해 쓰기가 동시에 들어오면 이 요약 파일에서 경합이 납니다. 문서는 읽고-합치고-쓰는 과정을 하나로 묶어 직렬화하라고 합니다 — 거래로 묶든, 비교 후 교체를 쓰든, 세션별 잠금을 걸든. 합치는 계산 자체는 부작용이 없으니 문제는 순서뿐입니다. 그리고 곁가지 대화의 묶음은 본 세션 요약에 섞으면 안 됩니다. 여러 AI를 나눠 지휘하는 구성이라면 이 경합이 실제로 자주 일어납니다.

안 만들면 조용히 못 하는 것들

필수는 쓰기와 읽기 둘뿐이고 나머지 넷은 선택입니다. 그런데 안 만들면 딸려서 못 쓰게 되는 기능이 각각 있어요. 곁가지 대화를 찾아주는 기능을 빼면 이어받을 때 본 대화만 복원되고 곁가지는 안 살아납니다. 지우기를 빼면 삭제 요청이 아무 일도 안 하고 통과합니다 — 쌓기만 하는 저장소에는 오히려 맞는 동작이죠.

지우기를 만들 거라면 조건이 붙습니다. 본 열쇠를 지울 때 곁가지 전부와 요약 항목까지 함께 지워야 해요. 안 그러면 지운 세션이 목록에 계속 나타납니다. 그리고 알아둘 것 — 이 기능은 내 저장소에서 절대 스스로 지우지 않습니다. 보관 기간은 전적으로 내 몫이고, 저장소에서 이어받은 실행은 로컬에 아무것도 안 남기니 내 보관 정책이 유일한 정책이 됩니다.

마지막으로 읽어올 때의 착시 둘. 메시지를 가져오는 기능은 "압축이 끝난 뒤의 사슬"을 돌려줍니다 — 자동 요약이 한 번 돌면 앞부분이 요약으로 대체되므로, 저장소에 원본 항목이 수백 개여도 돌아오는 메시지는 수십 개일 수 있어요. 원본 전체가 필요하면 저장소를 직접 읽어야 합니다. 그리고 복제는 바이트 복사가 아닙니다 — 세션 번호와 메시지 식별자를 전부 새로 써서 넣습니다. 저장소 차원의 복사 지름길을 쓰면 옛 번호를 가리키는 기록이 만들어집니다.

자주 묻는 질문 (FAQ)

Q. 어떤 저장소를 붙일 수 있나요?

쓰기와 읽기만 구현하면 됩니다. 공식 저장소에 클라우드 객체 저장소·인메모리 캐시·관계형 데이터베이스 세 가지 예제가 실려 있는데, 패키지로 배포되진 않아서 파일을 복사해 쓰라고 안내합니다. 개발·시험용 메모리 저장소는 기본 제공되고요.

Q. 넣은 그대로 돌려줘야 하나요?

순서는 지켜야 하지만 글자 단위로 같을 필요는 없습니다. 내용이 같으면 됩니다. 그래서 키 순서를 바꿔 저장하는 데이터베이스도 괜찮다고 문서가 명시해요. 내용물은 열어보지 말고 통째로 보관하면 됩니다.

Q. 내가 만든 게 제대로 동작하는지 확인할 방법이 있나요?

두 언어 모두 규격 검사 묶음을 제공합니다. 안 만든 선택 기능의 검사는 알아서 건너뜁니다. 단, 검사들이 같은 열쇠를 재사용하니 매번 빈 저장소로 시작하도록 만들어 넘겨야 합니다.

Q. 목록을 빨리 보여주려면요?

요약을 따로 유지하는 기능을 만들면 한 번의 호출로 전체 목록을 읽습니다. 안 만들면 세션 목록을 가져온 뒤 하나씩 다 읽어들이는 방식으로 되돌아가요. 요약은 쓰기가 일어날 때 같이 갱신하고, 시각은 목록이 내주는 것과 같은 시계를 써야 합니다.

✨ 정리하면

이 기능의 성격은 "기록을 옮기는 것"이 아니라 "복사본을 하나 더 두는 것"입니다. 그래서 평소엔 저장소가 죽어도 아무 일 없지만, 저장소에서 이어받은 실행에서는 내 저장소가 유일한 사본이 됩니다. 작업 폴더를 맞추고, 중복을 걸러내고, 보관 기간은 직접 정하세요. 사내 인프라에서 세션을 굴릴 때의 함정은 운영 편에, 비용과 권한 설계는 AI 지출 관리 허브에 정리해 두었습니다.

출처: Claude Agent SDK 공식 문서 「세션을 외부 저장소에 보관하기」 (2026-08-31 열람). 일부 동작은 SDK 버전과 언어에 따라 다르며, 세부 절차는 변경될 수 있습니다.