From 90b3da59595d67fbe18ba93a97e1a16d37f6f7a9 Mon Sep 17 00:00:00 2001
From: William FH <13333726+hinthornw@users.noreply.github.com>
Date: Tue, 1 Apr 2025 22:54:31 -0700
Subject: [PATCH] TTL How-to (#4129)

Signed-off-by: William Fu-Hinthorn <13333726+hinthornw@users.noreply.github.com>
---
 docs/docs/how-tos/index.md             |   1 +
 docs/docs/how-tos/ttl/configure_ttl.md | 102 +++++++++++++++++++++++++
 docs/mkdocs.yml                        |   3 +
 3 files changed, 106 insertions(+)
 create mode 100644 docs/docs/how-tos/ttl/configure_ttl.md

diff --git a/docs/docs/how-tos/index.md b/docs/docs/how-tos/index.md
index 8421001a6..b5e840be7 100644
--- a/docs/docs/how-tos/index.md
+++ b/docs/docs/how-tos/index.md
@@ -206,6 +206,7 @@ LangGraph applications can be deployed using LangGraph Cloud, which provides a r
 - [How to deploy to LangGraph cloud](../cloud/deployment/cloud.md)
 - [How to deploy to a self-hosted environment](./deploy-self-hosted.md)
 - [How to interact with the deployment using RemoteGraph](./use-remote-graph.md)
+- [How to add TTLs to your LangGraph application](./ttl/configure_ttl.md)
 
 ### Authentication & Access Control
 
diff --git a/docs/docs/how-tos/ttl/configure_ttl.md b/docs/docs/how-tos/ttl/configure_ttl.md
new file mode 100644
index 000000000..4ae3d769b
--- /dev/null
+++ b/docs/docs/how-tos/ttl/configure_ttl.md
@@ -0,0 +1,102 @@
+# How to add TTLs to your LangGraph application
+
+!!! tip "Prerequisites"
+
+    This guide assumes familiarity with the [LangGraph Platform](../../concepts/index.md#langgraph-platform), [Persistence](../../concepts/persistence.md), and [Cross-thread persistence](../../concepts/store.md) concepts.
+
+???+ note "LangGraph platform only"
+    
+    TTLs are only supported for LangGraph platform deployments. This guide does not apply to LangGraph OSS.
+
+The LangGraph Platform persists both [checkpoints](../../concepts/persistence.md#checkpoints) (thread state) and [cross-thread memories](../../concepts/persistence.md#memory-store) (store items). Configure Time-to-Live (TTL) policies in `langgraph.json` to automatically manage the lifecycle of this data, preventing indefinite accumulation.
+
+## Configuring Checkpoint TTL
+
+Checkpoints capture the state of conversation threads. Setting a TTL ensures old checkpoints and threads are automatically deleted.
+
+Add a `checkpointer.ttl` configuration to your `langgraph.json` file:
+
+```json
+{
+  "dependencies": ["."],
+  "graphs": {
+    "agent": "./agent.py:graph"
+  },
+  "checkpointer": {
+    "ttl": {
+      "strategy": "delete",
+      "sweep_interval_minutes": 60,
+      "default_ttl": 43200 
+    }
+  }
+}
+```
+
+*   `strategy`: Specifies the action taken on expiration. Currently, only `"delete"` is supported, which deletes all checkpoints in the thread upon expiration.
+*   `sweep_interval_minutes`: Defines how often, in minutes, the system checks for expired checkpoints.
+*   `default_ttl`: Sets the default lifespan of checkpoints in minutes (e.g., 43200 minutes = 30 days).
+
+## 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:
+
+```json
+{
+  "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). 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:
+
+```json
+{
+  "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 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.
+
+
+See the [langgraph.json CLI reference](../../../cloud/reference/cli.md) for more details on the other configurable options.
+
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 2e6388980..893a3e669 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -204,6 +204,9 @@ nav:
                 - cloud/deployment/cloud.md
                 - how-tos/deploy-self-hosted.md
                 - how-tos/use-remote-graph.md
+                - how-tos/ttl/configure_ttl.md
+            - Data Management:
+                - how-tos/ttl/configure_ttl.md
             - Authentication & Access Control:
                 - Authentication & Access Control: how-tos#authentication-access-control
                 - cloud/how-tos/auth/custom_auth_new.md