How to add TTLs to your application ↗

Documentation Index#

Fetch the complete documentation index at: https://docs.langchain.com/llms.txt Use this file to discover all available pages before exploring further.

Prerequisites This guide assumes familiarity with LangSmith, Persistence, and Cross-thread persistence concepts.

LangSmith persists both checkpoints (thread state) and cross-thread memories (store items). You can configure Time-to-Live (TTL) policies in langgraph.json to manage the lifecycle of this data automatically, preventing indefinite accumulation.

Configuring thread and checkpoint TTL#

Checkpoints capture the state of conversation threads. Setting a TTL ensures old checkpoints and thread metadata are automatically deleted.

Add a checkpointer.ttl configuration to your langgraph.json file:

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "sweep_interval_minutes": 60,
      "default_ttl": 43200
    }
  }
}

• strategy: Specifies the action taken on expiration.
  • "delete": Removes the entire thread including all associated run and checkpoint data when the TTL expires.
  • "keep_latest": Retains the thread and latest checkpoint, but deletes older checkpoint data that subsequent runs won’t need.
• sweep_interval_minutes: Defines how often, in minutes, the system checks for expired checkpoints.
• default_ttl: Sets the default lifespan of threads (and corresponding checkpoints) in minutes (e.g., 43200 minutes = 30 days). Applies only to checkpoints created after this configuration is deployed; existing checkpoints/threads are not changed. To clear older data, delete it explicitly.

Configuring store item TTL#

Store items allow cross-thread data persistence. Configuring TTL for store items helps manage memory by removing stale data.

Add a store.ttl configuration to your langgraph.json file:

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "store": {
    "ttl": {
      "refresh_on_read": true,
      "sweep_interval_minutes": 120,
      "default_ttl": 10080
    }
  }
}

• refresh_on_read: (Optional, default true) If true, accessing an item via get or search resets its expiration timer. If false, TTL only refreshes on put.
• sweep_interval_minutes: (Optional) Defines how often, in minutes, the system checks for expired items. If omitted, no sweeping occurs.
• default_ttl: (Optional) Sets the default lifespan of store items in minutes (e.g., 10080 minutes = 7 days). Applies only to items created after this configuration is deployed; existing items are not changed. If you need to clear older items, delete them manually. If omitted, items do not expire by default.

Combining TTL configurations#

You can configure TTLs for both checkpoints and store items in the same langgraph.json file to set different policies for each data type. Here is an example:

{
  "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
    }
  }
}

Configure per-thread TTL#

You can apply TTL configurations per-thread.

thread = await client.threads.create(
    ttl={
        "strategy": "delete",
        "ttl": 43200  # 30 days in minutes
    }
)

Thread-level TTLs will also delete all associated checkpoints. As a result, you can set a thread-level TTL and avoid setting a separate TTL for checkpoints.

Runtime overrides#

The default store.ttl settings from langgraph.json can be overridden at runtime by providing specific TTL values in SDK method calls like get, put, and search.

Deployment process#

After configuring TTLs in langgraph.json, deploy or restart your LangGraph application for the changes to take effect. Use langgraph dev for local development or langgraph up for Docker deployment.

For details on other configurable options, refer to the LangGraph CLI reference page.

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.