사전 요구 사항 이 가이드는 LangSmith, Persistence, 그리고 Cross-thread persistence 개념에 대한 이해를 전제로 합니다.
LangSmith는 checkpoints (thread 상태)와 cross-thread memories (store items)를 모두 유지합니다. langgraph.json에서 Time-to-Live (TTL) 정책을 구성하여 이 데이터의 수명 주기를 자동으로 관리하고 무한정 축적되는 것을 방지할 수 있습니다.

​
Checkpoint TTL 구성하기

Checkpoint는 대화 thread의 상태를 캡처합니다. TTL을 설정하면 오래된 checkpoint와 thread가 자동으로 삭제됩니다. langgraph.json 파일에 checkpointer.ttl 구성을 추가하세요: 
{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "sweep_interval_minutes": 60,
      "default_ttl": 43200
    }
  }
}
  • strategy: 만료 시 수행되는 작업을 지정합니다. 현재는 "delete"만 지원되며, 만료 시 thread의 모든 checkpoint를 삭제합니다.
  • sweep_interval_minutes: 시스템이 만료된 checkpoint를 확인하는 주기를 분 단위로 정의합니다.
  • default_ttl: thread(및 해당 checkpoint)의 기본 수명을 분 단위로 설정합니다(예: 43200분 = 30일). 이 구성이 배포된 후 생성된 checkpoint에만 적용되며, 기존 checkpoint/thread는 변경되지 않습니다. 오래된 데이터를 지우려면 명시적으로 삭제해야 합니다.

​
Store Item TTL 구성하기

Store item은 cross-thread 데이터 지속성을 허용합니다. Store item에 대한 TTL을 구성하면 오래된 데이터를 제거하여 메모리를 관리하는 데 도움이 됩니다. langgraph.json 파일에 store.ttl 구성을 추가하세요: 
{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "store": {
    "ttl": {
      "refresh_on_read": true,
      "sweep_interval_minutes": 120,
      "default_ttl": 10080
    }
  }
}
  • refresh_on_read: (선택 사항, 기본값 true) true인 경우, get 또는 search를 통해 item에 접근하면 만료 타이머가 재설정됩니다. false인 경우, TTL은 put에서만 갱신됩니다.
  • sweep_interval_minutes: (선택 사항) 시스템이 만료된 item을 확인하는 주기를 분 단위로 정의합니다. 생략하면 sweeping이 발생하지 않습니다.
  • default_ttl: (선택 사항) store item의 기본 수명을 분 단위로 설정합니다(예: 10080분 = 7일). 이 구성이 배포된 후 생성된 item에만 적용되며, 기존 item은 변경되지 않습니다. 오래된 item을 지워야 하는 경우 수동으로 삭제해야 합니다. 생략하면 기본적으로 item이 만료되지 않습니다.

​
TTL 구성 결합하기

동일한 langgraph.json 파일에서 checkpoint와 store item 모두에 대한 TTL을 구성하여 각 데이터 유형에 대해 서로 다른 정책을 설정할 수 있습니다. 다음은 예시입니다: 
{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "sweep_interval_minutes": 60,
      "default_ttl": 43200
    }
  },
  "store": {
    "ttl": {
      "refresh_on_read": true,
      "sweep_interval_minutes": 120,
      "default_ttl": 10080
    }
  }
}

​
Runtime 재정의

langgraph.json의 기본 store.ttl 설정은 get, put, search와 같은 SDK 메서드 호출에서 특정 TTL 값을 제공하여 runtime에 재정의할 수 있습니다.

​
배포 프로세스

langgraph.json에서 TTL을 구성한 후, 변경 사항을 적용하려면 LangGraph 애플리케이션을 배포하거나 재시작하세요. 로컬 개발에는 langgraph dev를, Docker 배포에는 langgraph up을 사용하세요. 다른 구성 가능한 옵션에 대한 자세한 내용은 langgraph.json CLI reference를 참조하세요.
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.
⌘I