세션을 외부 저장소에 유지하기

세션 기록을 S3, Redis 또는 자신의 백엔드로 미러링하여 모든 호스트에서 세션을 재개할 수 있습니다.

기본적으로 SDK는 세션 기록을 로컬 파일 시스템의 ~/.claude/projects/ 아래 JSONL 파일로 작성합니다. SessionStore 어댑터를 사용하면 이러한 기록을 S3, Redis 또는 데이터베이스와 같은 자신의 백엔드로 미러링할 수 있으므로 한 호스트에서 생성된 세션을 다른 호스트에서 재개할 수 있습니다.

세션 저장소를 사용하는 일반적인 이유:

• 다중 호스트 배포. 서버리스 함수, 자동 확장 워커 및 CI 러너는 파일 시스템을 공유하지 않습니다. 공유 저장소를 사용하면 모든 복제본이 모든 세션을 재개할 수 있습니다.
• 내구성. 로컬 컨테이너는 임시적입니다. S3 또는 데이터베이스로 지원되는 저장소는 재시작 및 재배포를 견딥니다.
• 규정 준수 및 감사. 이미 관리하는 저장소에 기록을 유지하고, 자신의 보존 규칙, 암호화 및 접근 제어를 적용합니다.

`SessionStore` 인터페이스

SessionStore는 두 개의 필수 메서드 append와 load, 그리고 세 개의 선택적 메서드를 가진 객체입니다. SDK는 쿼리 중에 기록 항목을 작성하기 위해 append를 호출하고 재개를 위해 이를 다시 읽기 위해 load를 호출합니다.

// Exported from @anthropic-ai/claude-agent-sdk as
// SessionStore, SessionKey, SessionStoreEntry.

type SessionKey = {
projectKey: string;
sessionId: string;
subpath?: string;
};

type SessionStore = {
// Required
append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void>;
load(key: SessionKey): Promise<SessionStoreEntry[] | null>;

// Optional
listSessions?(
projectKey: string,
): Promise<Array<{ sessionId: string; mtime: number }>>;
delete?(key: SessionKey): Promise<void>;
listSubkeys?(key: {
projectKey: string;
sessionId: string;
}): Promise<string[]>;
};

# Exported from claude_agent_sdk as
# SessionStore, SessionKey, SessionStoreEntry.

class SessionKey(TypedDict):
project_key: str
session_id: str
subpath: NotRequired[str]

class SessionStore(Protocol):
# Required
async def append(
self, key: SessionKey, entries: list[SessionStoreEntry]
) -> None: ...
async def load(self, key: SessionKey) -> list[SessionStoreEntry] | None: ...

# Optional — omit or raise NotImplementedError
async def list_sessions(
self, project_key: str
) -> list[SessionStoreListEntry]: ...
async def delete(self, key: SessionKey) -> None: ...
async def list_subkeys(self, key: SessionListSubkeysKey) -> list[str]: ...

SessionKey는 하나의 기록을 주소 지정합니다. projectKey는 작업 디렉토리의 안정적이고 파일 시스템에 안전한 인코딩이고, sessionId는 세션 UUID이며, subpath는 항목이 하위 에이전트 기록 또는 사이드카 파일이 아닌 주 대화에 속할 때 설정됩니다. subpath를 불투명한 키 접미사로 취급합니다. 예를 들어 subagents/agent-<id>와 같이 온디스크 레이아웃을 따릅니다. subpath가 정의되지 않으면 키는 주 기록을 참조합니다.

빠른 시작

SDK는 개발 및 테스트를 위해 InMemorySessionStore를 제공합니다. 아래 예제는 저장소가 연결된 쿼리를 실행하고, 결과 메시지에서 세션 ID를 캡처한 다음, 두 번째 query() 호출에서 저장소에서 재개합니다. 두 번째 호출은 동일한 저장소 인스턴스와 resume을 전달하므로 SDK는 로컬 파일 시스템 대신 저장소에서 기록을 로드합니다:

import { query, InMemorySessionStore } from "@anthropic-ai/claude-agent-sdk";

const store = new InMemorySessionStore();

let sessionId: string | undefined;
for await (const message of query({
prompt: "List the TypeScript files under src/",
options: { sessionStore: store },
})) {
if (message.type === "result") {
sessionId = message.session_id;
}
}

// Resume from the store. The agent has full context from the first call.
for await (const message of query({
prompt: "Summarize what those files do",
options: { sessionStore: store, resume: sessionId },
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

import asyncio
from claude_agent_sdk import (
ClaudeAgentOptions,
InMemorySessionStore,
ResultMessage,
query,
)

store = InMemorySessionStore()


async def main():
session_id = None
async for message in query(
prompt="List the Python files under src/",
options=ClaudeAgentOptions(session_store=store),
):
if isinstance(message, ResultMessage):
session_id = message.session_id

# Resume from the store. The agent has full context from the first call.
async for message in query(
prompt="Summarize what those files do",
options=ClaudeAgentOptions(session_store=store, resume=session_id),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)


asyncio.run(main())

두 번째 쿼리는 첫 번째 쿼리의 파일 요약을 출력하며, 이는 에이전트가 저장소에서 전체 컨텍스트와 함께 재개되었음을 보여줍니다.

자신의 어댑터 작성하기

백엔드에 대해 append와 load를 구현합니다. 저장소에 대해 listSessions(), deleteSession() 및 하위 에이전트 재개가 작동하도록 하려면 listSessions, delete 및 listSubkeys를 추가합니다.

append에 전달된 항목은 SessionStoreEntry로 입력됩니다({ type: string; ... } 객체). 이를 불투명한 JSON 안전 값으로 취급합니다: 순서대로 유지하고 load에서 동일한 순서로 반환합니다. load는 추가된 항목과 깊이 같은 항목을 반환해야 합니다. 바이트 같은 직렬화는 필요하지 않으므로 Postgres jsonb와 같이 객체 키를 재정렬하는 백엔드는 괜찮습니다.

참조 구현

TypeScript SDK 저장소에는 examples/session-stores/ 아래 S3, Redis 및 Postgres용 실행 가능한 참조 어댑터가 포함되어 있습니다. 이들은 npm에 게시되지 않습니다. 필요한 src/ 파일을 프로젝트에 복사하고 해당 백엔드 클라이언트를 설치합니다.

각 어댑터는 사전 구성된 클라이언트 인스턴스를 사용하므로 자격 증명, TLS, 지역 및 풀링을 제어합니다. 예를 들어 S3의 경우:

import { query } from "@anthropic-ai/claude-agent-sdk";
import { S3Client } from "@aws-sdk/client-s3";
import { S3SessionStore } from "./S3SessionStore"; // copied from examples/session-stores/s3

const store = new S3SessionStore({
  bucket: "my-claude-sessions",
  prefix: "transcripts",
  client: new S3Client({ region: "us-east-1" }),
});

for await (const message of query({
  prompt: "Hello!",
  options: { sessionStore: store },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

// Later, possibly on a different host:
for await (const message of query({
  prompt: "Continue where we left off",
  options: { sessionStore: store, resume: "previous-session-id" },
})) {
  // ...
}

어댑터 검증하기

두 SDK 모두 append, load 및 선택적 메서드가 만족해야 하는 동작 계약을 주장하는 적합성 제품군을 제공합니다. 선택적 메서드에 대한 테스트는 해당 메서드가 구현되지 않으면 자동으로 건너뜁니다.

TypeScript에서 예제 디렉토리의 shared/conformance.ts를 테스트 제품군에 복사합니다. Python에서는 제품군이 패키지에 포함됩니다:

import pytest
from claude_agent_sdk.testing import run_session_store_conformance


@pytest.mark.asyncio
async def test_my_store_conformance():
    await run_session_store_conformance(MyRedisStore)

동작 참고 사항

이중 쓰기 아키텍처

저장소는 미러이지 대체가 아닙니다. Claude Code 서브프로세스는 항상 로컬 디스크에 먼저 쓰고, SDK는 각 배치를 append()로 전달합니다. 로컬 복사본을 임시적으로 만들려면 options.env의 임시 디렉토리에 CLAUDE_CONFIG_DIR을 가리킵니다. 미러는 로컬 쓰기에 따라 달라지므로 sessionStore는 persistSession: false와 결합할 수 없습니다. 둘 다 설정하면 SDK는 예외를 발생시킵니다. 또한 enableFileCheckpointing과 결합할 수 없습니다. 파일 기록 백업 블롭은 로컬 디스크에 직접 작성되고 저장소로 미러링되지 않기 때문입니다.

미러 쓰기는 최선의 노력입니다

append()가 거부하거나 시간 초과되면 오류가 기록되고, { type: "system", subtype: "mirror_error" } 메시지가 반복자로 내보내지며, 쿼리가 계속됩니다. 로컬 기록은 이미 디스크에 내구적이므로 저장소 중단은 에이전트를 중단하거나 로컬에서 데이터를 손실하지 않습니다. 실패한 배치는 재시도되지 않으므로 저장소 데이터 손실을 감지해야 하는 경우 mirror_error를 모니터링합니다.

`getSessionMessages`는 압축 후 체인을 반환합니다

getSessionMessages({ sessionStore })는 에이전트가 재개할 때 볼 수 있는 연결된 메시지 체인을 반환합니다. 자동 압축 후 이전 턴은 요약으로 대체되므로 저장소에 503개의 원본 항목을 보유한 세션은 getSessionMessages에서 18개의 메시지를 반환할 수 있습니다. 압축 전 턴 및 메타데이터 항목을 포함한 전체 원본 기록의 경우 store.load(key)를 직접 호출합니다.

`forkSession`은 바이트 복사가 아닙니다

forkSession({ sessionStore })는 원본 항목을 읽고, 모든 sessionId 필드를 다시 작성하고 메시지 UUID를 재매핑한 다음, 변환된 항목을 새 키 아래에 추가합니다. 어댑터 수준 복사 또는 CopyObject 바로 가기는 여전히 이전 세션 ID를 참조하는 기록을 생성하므로 SDK는 이를 사용하지 않습니다.

하위 에이전트 기록

하위 에이전트 기록은 subpath: "subagents/agent-<id>" 아래에 미러링됩니다. listSubagents({ sessionStore })는 어댑터가 listSubkeys를 구현해야 합니다. getSubagentMessages({ sessionStore })는 사용 가능할 때 이를 사용하지만 정의되지 않으면 직접 하위 경로로 폴백합니다. 재개도 listSubkeys를 호출하여 하위 에이전트 파일을 복원합니다. 이것이 없으면 주 기록만 구체화됩니다.

보존

SDK는 자체적으로 저장소에서 삭제하지 않습니다. 보존은 어댑터의 책임입니다: TTL, S3 수명 주기 정책 또는 규정 준수 요구 사항에 따른 예약된 정리를 구현합니다. CLAUDE_CONFIG_DIR 아래의 로컬 기록은 cleanupPeriodDays 설정에 의해 독립적으로 정리됩니다.

지원 대상

다음 SDK 함수는 sessionStore 옵션을 수락하고 제공될 때 로컬 파일 시스템 대신 저장소에 대해 작동합니다:

• query()
• startup()
• listSessions()
• getSessionInfo()
• getSessionMessages()
• renameSession()
• tagSession()
• deleteSession()
• forkSession()
• listSubagents()
• getSubagentMessages()

관련 리소스

• 세션 작업하기: 사용자 정의 저장소 없이 계속, 재개 및 포크
• SDK 호스팅하기: 다중 호스트 환경을 위한 배포 패턴
• TypeScript Options: 전체 옵션 참조
• examples/session-stores/: 실행 가능한 S3, Redis 및 Postgres 참조 어댑터