From 33fad2b8e06ac43a964d3ab62025173f5e3c85eb Mon Sep 17 00:00:00 2001 From: daken Date: Sat, 6 Jun 2026 22:38:05 +0800 Subject: [PATCH 1/2] [doc] Support TTL on ShortTermMemory in User Documentation --- .../docs/development/memory/overview.md | 1 + .../memory/sensory_and_short_term_memory.md | 57 ++++++++++++++++++- 2 files changed, 57 insertions(+), 1 deletion(-) diff --git a/docs/content/docs/development/memory/overview.md b/docs/content/docs/development/memory/overview.md index 65f8817ab..b44515a73 100644 --- a/docs/content/docs/development/memory/overview.md +++ b/docs/content/docs/development/memory/overview.md @@ -57,6 +57,7 @@ For more details, see [Sensory & Short-term Memory]({{< ref "docs/development/me * **Characteristics**: * The lifecycle of the stored data can across multiple runs. * Complete original data retrieval. + * Supports optional automatic expiration and cleanup. For more details, see [Sensory & Short-Term Memory]({{< ref "docs/development/memory/sensory_and_short_term_memory" >}}). diff --git a/docs/content/docs/development/memory/sensory_and_short_term_memory.md b/docs/content/docs/development/memory/sensory_and_short_term_memory.md index 5eb73a9e5..d086dc4d6 100644 --- a/docs/content/docs/development/memory/sensory_and_short_term_memory.md +++ b/docs/content/docs/development/memory/sensory_and_short_term_memory.md @@ -252,8 +252,11 @@ public static void secondAction(Event event, RunnerContext ctx) throws Exception {{< /tab >}} {{< /tabs >}} + ## Auto-Cleanup Behavior +### Sensory Memory + Sensory Memory is automatically cleared by the framework after each agent run completes. This cleanup happens: - **When**: After the agent run finishes processing all events trigger by one input event. @@ -263,4 +266,56 @@ Sensory Memory is automatically cleared by the framework after each agent run co {{< hint info >}} During execution, sensory memory data is checkpointed by Flink for fault tolerance. However, once the run completes, all sensory memory is cleared and will not be available in subsequent runs. -{{< /hint >}} \ No newline at end of file +{{< /hint >}} + +### Short-Term Memory + +Short-term memory can be configured with a time-to-live (TTL) so that older state expires automatically. This is useful for agents that may run for a long time: if the agent only needs recent memories, expiring historical data directly keeps the stored state focused on the latest context and avoids retaining stale information. + +Set `short-term-memory.state-ttl.ms` to a value greater than 0 in milliseconds to enable TTL. You can also configure how the TTL is refreshed and whether expired state can be returned before Flink cleans it up: + +- `short-term-memory.state-ttl.update-type`: controls whether TTL is refreshed on create/write or on read/write. +- `short-term-memory.state-ttl.visibility`: controls whether expired memory is never returned or may be returned if it has not been cleaned up yet. + +{{< tabs "Short-Term Memory TTL Configuration" >}} + +{{< tab "Python" >}} +```python +from flink_agents.api.core_options import ( + AgentExecutionOptions, + ShortTermMemoryTtlUpdate, + ShortTermMemoryTtlVisibility, +) +from flink_agents.api.execution_environment import AgentsExecutionEnvironment + +agents_env = AgentsExecutionEnvironment.get_execution_environment(env=env) +agents_config = agents_env.get_config() + +agents_config.set(AgentExecutionOptions.SHORT_TERM_MEMORY_STATE_TTL_MS, 60_000) +agents_config.set( + AgentExecutionOptions.SHORT_TERM_MEMORY_STATE_TTL_UPDATE_TYPE, + ShortTermMemoryTtlUpdate.ON_READ_AND_WRITE, +) +agents_config.set( + AgentExecutionOptions.SHORT_TERM_MEMORY_STATE_TTL_VISIBILITY, + ShortTermMemoryTtlVisibility.NEVER_RETURN_EXPIRED, +) +``` +{{< /tab >}} + +{{< tab "Java" >}} +```java +AgentsExecutionEnvironment agentsEnv = AgentsExecutionEnvironment.getExecutionEnvironment(env); +AgentConfiguration agentsConfig = (AgentConfiguration) agentsEnv.getConfig(); + +agentsConfig.set(AgentExecutionOptions.SHORT_TERM_MEMORY_STATE_TTL_MS, 60_000L); +agentsConfig.set( + AgentExecutionOptions.SHORT_TERM_MEMORY_STATE_TTL_UPDATE_TYPE, + ShortTermMemoryTtlUpdate.ON_READ_AND_WRITE); +agentsConfig.set( + AgentExecutionOptions.SHORT_TERM_MEMORY_STATE_TTL_VISIBILITY, + ShortTermMemoryTtlVisibility.NEVER_RETURN_EXPIRED); +``` +{{< /tab >}} + +{{< /tabs >}} From 9ced154d46f3c1d153ecc1b0a9918c81f5efd7f9 Mon Sep 17 00:00:00 2001 From: daken Date: Sat, 6 Jun 2026 23:17:32 +0800 Subject: [PATCH 2/2] [doc] Add configuration doc --- docs/content/docs/operations/configuration.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/content/docs/operations/configuration.md b/docs/content/docs/operations/configuration.md index ac9fab55e..36b899111 100644 --- a/docs/content/docs/operations/configuration.md +++ b/docs/content/docs/operations/configuration.md @@ -146,7 +146,9 @@ Here is the list of all built-in core configuration options. | `event-log.standard.max-string-length` | 2000 | int | At `STANDARD` level, strings in the event payload longer than this are truncated. Has no effect at `VERBOSE`. | | `event-log.standard.max-array-elements` | 20 | int | At `STANDARD` level, arrays in the event payload with more than this many elements are truncated. Has no effect at `VERBOSE`. | | `event-log.standard.max-depth` | 5 | int | At `STANDARD` level, objects nested deeper than this are summarized. Has no effect at `VERBOSE`. | - +| `short-term-memory.state-ttl.ms` | 0 | long | Time-to-live for short-term memory state in milliseconds. Set to a value greater than 0 to enable TTL; 0 disables it. | +| `short-term-memory.state-ttl.update-type` | `ON_READ_AND_WRITE` | ShortTermMemoryTtlUpdate | Update policy for short-term memory TTL. Only applies when `short-term-memory.state-ttl.ms` is greater than 0. Valid values: `ON_CREATE_AND_WRITE`, `ON_READ_AND_WRITE`. | +| `short-term-memory.state-ttl.visibility` | `NEVER_RETURN_EXPIRED` | ShortTermMemoryTtlVisibility | Visibility policy for expired short-term memory state. Only applies when `short-term-memory.state-ttl.ms` is greater than 0. Valid values: `NEVER_RETURN_EXPIRED`, `RETURN_EXPIRED_IF_NOT_CLEANED_UP`. | ### Action State Store