영속성 제어

영속성에는 기능 플래그가 없습니다. 무엇을 영속화할지는 백엔드가 제공하는 상태 저장소로 결정하며, 저장소별로 백엔드를 조합합니다. 워크플로에 필요한 저장소만 제공합니다.

인스턴스 간 뮤텍스가 필요합니까? 아래의 잠금을 참조하세요.

명명된 형태(권장)

타입	필수 저장소	용도
ChatTranscriptStores / ChatTranscriptPersistence	messages (선택 사항인 runs/interrupts/metadata)	withPersistence / reconstructChat의 기본 형태
ChatPersistenceStores / ChatPersistence	messages + runs + interrupts + metadata	패키지로 제공되는 백엔드 (memoryPersistence, Drizzle, Prisma, D1)
ChatWithInterruptsStores / ChatWithInterruptsPersistence	messages + runs + interrupts	metadata가 필요하지 않은 HITL

공개 희소 AIPersistenceStores export는 없으므로, 명명된 형태나 사용자 지정 맵을 위한 AIPersistence<{ messages: MessageStore, … }>를 사용합니다. defineAIPersistence / composePersistence는 타입 추론을 통해 희소 맵도 계속 허용합니다.

각 상태 저장소가 제공하는 내용

요구 사항	저장소
신뢰할 수 있는 서버 트랜스크립트	messages (withPersistence / reconstructChat에 필수)
실행 상태 및 사용량	runs (ChatPersistence에 필수이며, interrupts가 설정되면 필수)
영속적인 승인 또는 사람의 입력	interrupts (runs 필요)
앱 또는 통합 체크포인트	metadata (항상 선택 사항)

withPersistence(persistence)는 존재하는 저장소를 검사합니다. 저장소의 존재 여부가 선택 사항인 채팅 기능을 선택하는 방식입니다.

진입점 요구 사항

진입점	형태	참고
withPersistence	ChatTranscriptStores 기본 형태	interrupts ⇒ runs
reconstructChat	ChatTranscriptStores	runs / interrupts가 있으면 응답을 보강합니다
패키지로 제공되는 *Persistence()	ChatPersistence	messages + runs (+ interrupts + metadata)
defineAIPersistence / composePersistence	추론에 따른 희소 형태	결과에는 명명된 형태를 권장합니다

저장소 조합 및 재정의

composePersistence는 먼저 기본 백엔드를 받고, 두 번째로 overrides 객체를 받습니다. 다음 예제에서는 메모리 내 참조 백엔드에서 시작해 사용자 지정 interrupts / runs 저장소로 교체합니다:

import { composePersistence, memoryPersistence } from '@tanstack/ai-persistence'
// Your own store implementations of the InterruptStore / RunStore contracts.
import { interruptStore, runStore } from './stores'

const persistence = composePersistence(memoryPersistence(), {
  overrides: {
    interrupts: interruptStore,
    runs: runStore,
  },
})

각 재정의는 독립적입니다:

재정의 값	결과
키를 생략함	기본 저장소를 상속합니다.
undefined	기본 저장소를 상속합니다.
저장소 객체	해당 저장소만 교체합니다.
false	해당 저장소를 제거합니다.

import { composePersistence, memoryPersistence } from '@tanstack/ai-persistence'

// Drop metadata; the resulting type has no `metadata` key.
const withoutMetadata = composePersistence(memoryPersistence(), {
  overrides: { metadata: false },
})

알 수 없는 저장소 이름은 타입 검사를 통과하지 못하며, 타입이 지정되지 않은 JavaScript에서 값이 전달되는 경우 런타임에서도 거부됩니다.

유효한 저장소 조합

• withPersistence에는 messages가 필요합니다.
• interrupts에는 runs가 필요합니다. 인터럽트 레코드는 하나의 실행 범위에 속합니다.
• withGenerationPersistence에는 generationRuns가 필요합니다.
• 이식 가능한 샌드박스 스냅샷에는 동일한 persistence 객체에 messages, artifacts, blobs가 필요합니다. 다시 로드한 후에도 파일 유지를 참조하세요.

조합하지 않고 부분 백엔드를 직접 정의하려면 defineAIPersistence({ stores: { ... } })를 사용하고 보유한 저장소만 전달합니다. 저장소 계약은 저장소 참조를 참조하세요.

잠금 (조정)

잠금은 인스턴스 간 작업을 조정하는 분산 뮤텍스입니다. 잠금은 @tanstack/ai/locks에 있으며, withPersistence와 함께 withLocks를 사용해 독립적인 미들웨어로 적용합니다. 전체 가이드는 잠금을 참조하세요.

import { withLocks, InMemoryLockStore } from '@tanstack/ai/locks'
import { withPersistence, memoryPersistence } from '@tanstack/ai-persistence'

const middleware = [
  withPersistence(memoryPersistence()),
  withLocks(new InMemoryLockStore()), // multi-instance: distributed LockStore
]