From d2275a67277eda683a2690c5c98f122c593efdd5 Mon Sep 17 00:00:00 2001 From: William FH <13333726+hinthornw@users.noreply.github.com> Date: Tue, 1 Apr 2025 22:21:55 -0700 Subject: [PATCH] Update cli.md to mention ttl (#4128) Signed-off-by: William Fu-Hinthorn <13333726+hinthornw@users.noreply.github.com> --- docs/docs/cloud/reference/cli.md | 66 ++++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 4 deletions(-) diff --git a/docs/docs/cloud/reference/cli.md b/docs/docs/cloud/reference/cli.md index aa4c3fd43..e1ddec38f 100644 --- a/docs/docs/cloud/reference/cli.md +++ b/docs/docs/cloud/reference/cli.md @@ -29,7 +29,7 @@ The LangGraph command line interface includes commands to build and run a LangGr ## Configuration File {#configuration-file} -The LangGraph CLI requires a JSON configuration file with the following keys: +The LangGraph CLI requires a JSON configuration file that follows this [schema](https://raw.githubusercontent.com/langchain-ai/langgraph/refs/heads/main/libs/cli/schemas/schema.json). It contains the following properties:

Note

@@ -46,11 +46,12 @@ The LangGraph CLI requires a JSON configuration file with the following keys: | `graphs` | **Required**. Mapping from graph ID to path where the compiled graph or a function that makes a graph is defined. Example: | | `auth` | _(Added in v0.0.11)_ Auth configuration containing the path to your authentication handler. Example: `./your_package/auth.py:auth`, where `auth` is an instance of `langgraph_sdk.Auth`. See [authentication guide](../../concepts/auth.md) for details. | | `env` | Path to `.env` file or a mapping from environment variable to its value. | - | `store` | Configuration for adding semantic search to the BaseStore. Contains the following fields: | + | `store` | Configuration for adding semantic search and/or time-to-live (TTL) to the BaseStore. Contains the following fields: | | `python_version` | `3.11`, `3.12`, or `3.13`. Defaults to `3.11`. | | `node_version` | Specify `node_version: 20` to use LangGraph.js. | | `pip_config_file` | Path to `pip` config file. | | `dockerfile_lines` | Array of additional lines to add to Dockerfile following the import from parent image. | + | `checkpointer` | Configuration for the checkpointer. Contains a `ttl` field which is an object with the following keys: | | `http` | HTTP server configuration with the following fields: | === "JS" @@ -59,9 +60,10 @@ The LangGraph CLI requires a JSON configuration file with the following keys: | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `graphs` | **Required**. Mapping from graph ID to path where the compiled graph or a function that makes a graph is defined. Example: | | `env` | Path to `.env` file or a mapping from environment variable to its value. | - | `store` | Configuration for adding semantic search to the BaseStore. Contains the following fields: | + | `store` | Configuration for adding semantic search and/or time-to-live (TTL) to the BaseStore. Contains the following fields: | | `node_version` | Specify `node_version: 20` to use LangGraph.js. | | `dockerfile_lines` | Array of additional lines to add to Dockerfile following the import from parent image. | + | `checkpointer` | Configuration for the checkpointer. Contains a `ttl` field which is an object with the following keys: | ### Examples @@ -82,7 +84,7 @@ The LangGraph CLI requires a JSON configuration file with the following keys: All deployments come with a DB-backed BaseStore. Adding an "index" configuration to your `langgraph.json` will enable [semantic search](../deployment/semantic_search.md) within the BaseStore of your deployment. - The `fields` configuration determines which parts of your documents to embed: + The `index.fields` configuration determines which parts of your documents to embed: - If omitted or set to `["$"]`, the entire document will be embedded - To embed specific fields, use JSON path notation: `["metadata.title", "content.text"]` @@ -171,6 +173,62 @@ The LangGraph CLI requires a JSON configuration file with the following keys: See the [authentication conceptual guide](../../concepts/auth.md) for details, and the [setting up custom authentication](../../tutorials/auth/getting_started.md) guide for a practical walk through of the process. + #### Configuring Store Item Time-to-Live (TTL) + + You can configure default data expiration for items/memories in the BaseStore using the `store.ttl` key. This determines how long items are retained after they are last accessed (with reads potentially refreshing the timer based on `refresh_on_read`). Note that these defaults can be overwritten on a per-call basis by modifying the corresponding arguments in `get`, `search`, etc. + + The `ttl` configuration is an object containing optional fields: + + - `refresh_on_read`: If `true` (the default), accessing an item via `get` or `search` resets its expiration timer. Set to `false` to only refresh TTL on writes (`put`). + - `default_ttl`: The default lifespan of an item in **minutes**. If not set, items do not expire by default. + - `sweep_interval_minutes`: How frequently (in minutes) the system should run a background process to delete expired items. If not set, sweeping does not occur automatically. + + Here is an example enabling a 7-day TTL (10080 minutes), refreshing on reads, and sweeping every hour: + + ```json + { + "dependencies": ["."], + "graphs": { + "memory_agent": "./agent/graph.py:graph" + }, + "store": { + "ttl": { + "refresh_on_read": true, + "sweep_interval_minutes": 60, + "default_ttl": 10080 + } + } + } + ``` + + #### Configuring Checkpoint Time-to-Live (TTL) + + You can configure the time-to-live (TTL) for checkpoints using the `checkpointer` key. This determines how long checkpoint data is retained before being automatically handled according to the specified strategy (e.g., deletion). The `ttl` configuration is an object containing: + + - `strategy`: The action to take on expired checkpoints (currently `"delete"` is the only accepted option). + - `sweep_interval_minutes`: How frequently (in minutes) the system checks for expired checkpoints. + - `default_ttl`: The default lifespan of a checkpoint in **minutes**. + + Here's an example setting a default TTL of 30 days (43200 minutes): + + ```json + { + "dependencies": ["."], + "graphs": { + "chat": "./chat/graph.py:graph" + }, + "checkpointer": { + "ttl": { + "strategy": "delete", + "sweep_interval_minutes": 10, + "default_ttl": 43200 + } + } + } + ``` + + In this example, checkpoints older than 30 days will be deleted, and the check runs every 10 minutes. + === "JS"