Skip to main content
前提条件 本指南假设您已熟悉 LangSmith、持久化 以及 跨线程持久化 的概念。
LangSmith 会持久化 检查点（线程状态）和 跨线程记忆（存储项）。您可以在 langgraph.json 中配置生存时间（TTL）策略来自动管理这些数据的生命周期，防止无限累积。

​
配置线程和检查点 TTL

检查点记录了对话线程的状态。设置 TTL 可确保旧的检查点和线程元数据被自动删除。 在您的 langgraph.json 文件中添加 checkpointer.ttl 配置： 
{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "sweep_interval_minutes": 60,
      "default_ttl": 43200
    }
  }
}
  • strategy: 指定过期时采取的操作。
    • "delete": TTL 过期时删除整个线程及其所有关联的运行和检查点数据。
    • "keep_latest": 保留线程和最新的检查点，但删除后续运行不需要的旧检查点数据。
  • sweep_interval_minutes: 定义系统检查过期检查点的频率（以分钟为单位）。
  • default_ttl: 设置线程（及对应检查点）的默认生存时间（以分钟为单位，例如 43200 分钟 = 30 天）。仅适用于此配置部署后创建的检查点；现有的检查点/线程不会更改。要清除旧数据，请显式删除。

​
配置存储项 TTL

存储项支持跨线程数据持久化。为存储项配置 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 访问项会重置其过期计时器。如果为 false，TTL 仅在 put 时刷新。
  • sweep_interval_minutes: （可选）定义系统检查过期项的频率（以分钟为单位）。如果省略，则不进行清理。
  • default_ttl: （可选）设置存储项的默认生存时间（以分钟为单位，例如 10080 分钟 = 7 天）。仅适用于此配置部署后创建的项；现有项不会更改。如果需要清除旧项，请手动删除。如果省略，项默认不会过期。

​
组合 TTL 配置

您可以在同一个 langgraph.json 文件中为检查点和存储项配置 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
    }
  }
}

​
配置每线程 TTL

您可以 按线程应用 TTL 配置。 
thread = await client.threads.create(
    ttl={
        "strategy": "delete",
        "ttl": 43200  # 30 天，以分钟为单位
    }
)
线程级 TTL 也会删除所有关联的检查点。因此，您可以设置线程级 TTL，而无需再为检查点单独设置 TTL。

​
运行时覆盖

langgraph.json 中的默认 store.ttl 设置可以在运行时被覆盖，方法是在 SDK 方法调用（如 get、put 和 search）中提供特定的 TTL 值。

​
部署流程

在 langgraph.json 中配置 TTL 后，部署或重启您的 LangGraph 应用以使更改生效。本地开发请使用 langgraph dev，Docker 部署请使用 langgraph up。 有关其他可配置选项的详细信息，请参阅 LangGraph CLI 参考页面。
Edit this page on GitHub or file an issue.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.