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 参考页面。
将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。
在 GitHub 上编辑此页面 或 提交问题。