This is an automated email from the ASF dual-hosted git repository.
wenjin272 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/flink-agents.git
The following commit(s) were added to refs/heads/main by this push:
new da62dcb3 [doc] Support TTL on ShortTermMemory in User Documentation
(#784)
da62dcb3 is described below
commit da62dcb32f7b86fe8aa4ad7b7974a6c53119b5fc
Author: daken <[email protected]>
AuthorDate: Mon Jun 8 11:02:36 2026 +0800
[doc] Support TTL on ShortTermMemory in User Documentation (#784)
Co-authored-by: daken <[email protected]>
---
docs/content/docs/development/memory/overview.md | 1 +
.../memory/sensory_and_short_term_memory.md | 57 +++++++++++++++++++++-
docs/content/docs/operations/configuration.md | 4 +-
3 files changed, 60 insertions(+), 2 deletions(-)
diff --git a/docs/content/docs/development/memory/overview.md
b/docs/content/docs/development/memory/overview.md
index 65f8817a..b44515a7 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 5eb73a9e..d086dc4d 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 >}}
diff --git a/docs/content/docs/operations/configuration.md
b/docs/content/docs/operations/configuration.md
index ac9fab55..36b89911 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
