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 8d2df12e1 [docs] Correct memory documentation (#1307)
8d2df12e1 is described below
commit 8d2df12e16ba7588ade6493976e217988336e615
Author: Yi Zhang <[email protected]>
AuthorDate: Thu Oct 22 10:40:25 2026 +0800
[docs] Correct memory documentation (#1307)
Generated-by: Codex Desktop 0.158.0-alpha.2.1 (GPT-6)
---
.../docs/development/memory/long_term_memory.md | 26 +++++++++++------
docs/content/docs/development/memory/overview.md | 14 ++++-----
.../memory/sensory_and_short_term_memory.md | 33 ++++++++++------------
3 files changed, 39 insertions(+), 34 deletions(-)
diff --git a/docs/content/docs/development/memory/long_term_memory.md
b/docs/content/docs/development/memory/long_term_memory.md
index 3f39325a6..591adb7d0 100644
--- a/docs/content/docs/development/memory/long_term_memory.md
+++ b/docs/content/docs/development/memory/long_term_memory.md
@@ -31,9 +31,14 @@ Long-Term Memory currently supports the
[Mem0](https://github.com/mem0ai/mem0) b
## Prerequisites
Declare the following resources in your agent plan:
+
- A [ChatModel]({{< ref "docs/development/calling-llms/chat-models" >}}) for
memory extraction and management
- An [EmbeddingModel]({{< ref
"docs/development/vector-search/embedding_models" >}}) for vector generation
-- A [VectorStore]({{< ref "docs/development/vector-search/vector_stores" >}})
for persistent storage
+- A [VectorStore]({{< ref "docs/development/vector-search/vector_stores" >}})
that supports collection management (`CollectionManageableVectorStore`) for
persistent storage
+
+See [Manage collections]({{< ref
"docs/development/vector-search/vector_stores#manage-collections" >}}) for the
built-in providers that support collection management.
+
+Mem0 Long-Term Memory uses the Python runtime with both the Java and Python
APIs. Follow [Setup]({{< ref "docs/get-started/setup" >}}) to install the
Python package and configure `PYTHONPATH`.
> **Java prerequisite:** Mem0 invokes the chat and embedding models on its own
> thread executor, which relies on the async-friendly pemja fix. When Mem0
> Long-Term Memory is configured together with Java actions, the runtime
> requires a Flink version of `1.20.5`, `2.0.2`, `2.1.3`, `2.2.1`, `2.3.0` or
> higher; otherwise it throws at startup. Either upgrade Flink or use the
> Python API.
@@ -116,7 +121,7 @@ agentsConfig.set(
{{< /tabs >}}
{{< hint info >}}
-If `JOB_IDENTIFIER` is not configured, the Flink job ID will be used by
default.
+If `JOB_IDENTIFIER` is not configured, the Flink JobID is used. Restoring the
agent's state from a checkpoint or savepoint retains the previous identifier,
preserving access to the same long-term memories.
{{< /hint >}}
## Data Model
@@ -149,6 +154,7 @@ A named collection of memory items. Memory sets provide
logical grouping and iso
```python
from flink_agents.api.decorators import action
from flink_agents.api.events.event import InputEvent, Event
+from flink_agents.api.events.event_type import EventType
from flink_agents.api.runner_context import RunnerContext
@action(EventType.InputEvent)
@@ -259,10 +265,10 @@ items = memory_set.get(ids="mem_123abc")
# Get multiple items by IDs
items = memory_set.get(ids=["mem_123abc", "mem_456def"])
-# Get all items
+# Get up to 100 items using the default limit
all_items = memory_set.get()
-# Get with metadata filter
+# Get up to 100 items with a metadata filter using the default limit
work_items = memory_set.get(filters={"category": "work"})
# Access item properties
@@ -285,10 +291,10 @@ List<MemorySetItem> items =
memorySet.get(List.of("item_id_1"), null, null);
// Get multiple items by IDs
items = memorySet.get(List.of("item_id_1", "item_id_2"), null, null);
-// Get all items
+// Get up to 100 items using the default limit
List<MemorySetItem> allItems = memorySet.get(null, null, null);
-// Get with metadata filter
+// Get up to 100 items with a metadata filter using the default limit
List<MemorySetItem> workItems = memorySet.get(null, Map.of("category",
"work"), null);
// Access item properties
@@ -469,7 +475,7 @@ results = memorySet.search(
### Usage Snippet
-The snippets below show how to read from and write to Long-Term Memory inside
an action.
+The snippets below show how to read from and write to Long-Term Memory inside
an action. They assume the configured resources are already registered;
resource declarations and job setup are omitted.
{{< tabs "Usage Snippet" >}}
@@ -478,14 +484,16 @@ The snippets below show how to read from and write to
Long-Term Memory inside an
```python
from pyflink.datastream import StreamExecutionEnvironment
+from flink_agents.api.agents.agent import Agent
from flink_agents.api.decorators import action
from flink_agents.api.execution_environment import AgentsExecutionEnvironment
from flink_agents.api.core_options import AgentConfigOptions
from flink_agents.api.events.event import InputEvent, OutputEvent, Event
+from flink_agents.api.events.event_type import EventType
from flink_agents.api.memory.long_term_memory import LongTermMemoryOptions
from flink_agents.api.runner_context import RunnerContext
-class PersonalizedAssistant:
+class PersonalizedAssistant(Agent):
@action(EventType.InputEvent)
@staticmethod
@@ -560,7 +568,7 @@ public static void processEvent(Event event, RunnerContext
ctx) throws Exception
Long-Term Memory automatically provides context isolation through Flink's
keyed partition model. Each keyed partition normally maintains its own isolated
set of memories.
The isolation hierarchy works as follows:
-- **Job-level** (`JOB_IDENTIFIER`): Separates memories between different Flink
jobs
+- **Job-level** (`JOB_IDENTIFIER`): Separates memories by job identifier
- **Partition-level** (keyed partition key): Separates memories between
different keys within the same job
- **Set-level** (memory set name): Separates memories between different
logical categories within the same partition
diff --git a/docs/content/docs/development/memory/overview.md
b/docs/content/docs/development/memory/overview.md
index b44515a73..fa8c7f7e2 100644
--- a/docs/content/docs/development/memory/overview.md
+++ b/docs/content/docs/development/memory/overview.md
@@ -28,7 +28,7 @@ Memory is a system that remembers information about previous
interactions. Memor
It underpins long-horizon reasoning, continual adaptation, and effective
interaction with complex
environments.<sup>[1](https://arxiv.org/pdf/2512.13564)</sup>
-We propose a distributed memory system for flink-agents that mirrors human
cognitive processes. The solution implements four memory types: Sensory Memory,
Short-term Memory, Long-term Memory and Knowledge, based on their visibility,
retention and derivation.
+We propose a distributed memory system for flink-agents that mirrors human
cognitive processes. The solution defines four memory types: Sensory Memory,
Short-Term Memory, Long-Term Memory and Knowledge, based on their visibility,
retention and derivation. Knowledge is not supported yet.
## Memory Types
@@ -48,14 +48,14 @@ Flink Agents classifies memory types based on visibility,
retention and derivati
* **Use Case**: Store temporary data generated during the agent execution
which is only needed for a single run. For example, tool call context, or the
data users want to pass to other agent actions.
* **Characteristics**: Isolation between agent runs, which means the memory
will be automatically cleaned up by the framework when an agent run is
completed.
-For more details, see [Sensory & Short-term Memory]({{< ref
"docs/development/memory/sensory_and_short_term_memory" >}}).
+For more details, see [Sensory & Short-Term Memory]({{< ref
"docs/development/memory/sensory_and_short_term_memory" >}}).
### Short-Term Memory
* **Use Case**: Store data generated during the agent execution.
- * Compared to sensory memory, the lifecycle of stored data can across
multiple runs.
- * Compared to long-term memory, user need retrieve all the original data
they have written to the memory.
+ * Compared to sensory memory, the lifecycle of stored data can span multiple
runs.
+ * Compared to long-term memory, users need to retrieve all the original data
they have written to the memory.
* **Characteristics**:
- * The lifecycle of the stored data can across multiple runs.
+ * The lifecycle of the stored data can span multiple runs.
* Complete original data retrieval.
* Supports optional automatic expiration and cleanup.
@@ -63,7 +63,7 @@ For more details, see [Sensory & Short-Term Memory]({{< ref
"docs/development/me
### Long-Term Memory
* **Use Case**: Store data generated during the agent execution, but compared
to short-term memory,
-the data may expand rapidly as the agent execution, which requires compaction
to provide concise and highly related context.
+the data may expand rapidly as the agent executes, requiring compaction to
provide concise and highly related context.
* **Characteristics**:
* Support for compacting similar items.
* Support for semantic search.
@@ -80,4 +80,4 @@ For more details, see [Long-Term Memory]({{< ref
"docs/development/memory/long_t
| **Storage** | Flink State | Flink
State | External Vector Store
|
| **Access Pattern** | Key-Value / Nested Objects |
Key-Value / Nested Objects | Semantic Search
|
| **Use Case** | Temporary execution states of an agent run | Exact
information shared across multiple runs | Large, compactable and searchable
information |
-| **Types of Contents** | Any primitive/object | Any
primitive/object | String, ChatMessage
|
\ No newline at end of file
+| **Types of Contents** | Java: Flink-serializable values; Python: [supported
built-in values]({{< ref
"docs/development/memory/sensory_and_short_term_memory#supported-value-types"
>}}) | Java: Flink-serializable values; Python: [supported built-in values]({{<
ref
"docs/development/memory/sensory_and_short_term_memory#supported-value-types"
>}}) | String |
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 a3e3e9ed4..1994898a5 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
@@ -27,7 +27,7 @@ under the License.
Sensory memory is a temporary storage mechanism in Flink Agents designed for
data that only needs to persist during a single agent run.
-Sensory memory will be auto cleaned after an agent run finished, which means
isolation between agent runs. It provides a convenient way to store
intermediate results, tool call contexts, and other temporary data without the
overhead of persistence across multiple runs.
+Sensory memory is automatically cleared after an agent run finishes, which
provides isolation between agent runs. It provides a convenient way to store
intermediate results, tool call contexts, and other temporary data without the
overhead of persistence across multiple runs.
### Short-Term Memory
@@ -44,7 +44,7 @@ through a previously obtained `MemoryObject`. See
Sensory Memory is ideal for:
- **Intermediate results and temporary information** which will be used later
by other actions in the same agent run.
-- **Passing data through multiple actions**, reduce unnecessary data copy and
serialization.
+- **Passing data through multiple actions**, reducing unnecessary data copying
and serialization.
{{< hint warning >}}
Do not use Sensory Memory for data that needs to persist across multiple agent
runs. Use Short-Term Memory or [Long-Term Memory]({{< ref
"docs/development/memory/long_term_memory" >}}) instead.
@@ -54,10 +54,10 @@ Do not use Sensory Memory for data that needs to persist
across multiple agent r
Short-Term Memory is ideal for:
- **Persistent Data**: Data needs to persist across multiple runs.
-- **Complete original data retrieval**: User want to retrieve the exact same
data they have written to memory.
+- **Complete original data retrieval**: Users want to retrieve the exact same
data they have written to memory.
{{< hint warning >}}
-Short-Term Memory is designed for complete original data retrival. For use
case that need get the concise and highly related context, consider using
[Long-Term Memory]({{< ref "docs/development/memory/long_term_memory" >}})
instead.
+Short-Term Memory is designed for complete original data retrieval. For use
cases that need concise and highly related context, consider using [Long-Term
Memory]({{< ref "docs/development/memory/long_term_memory" >}}) instead.
{{< /hint >}}
## Data Types & Operations
@@ -66,25 +66,25 @@ Sensory memory and short-term memory have the same data
types and operations. Th
### MemoryObject
-The root of the sensory memory and short-term memory is `MemoryObject`. User
can use it to store a series of key-value pairs.
+Sensory memory and short-term memory each have a root `MemoryObject`, which
users can use to store a series of key-value pairs.
### Supported Value Types
-The key of the pairs stored in `MemoryObject` must be a string. The supported
value types differ between Java and Python.
+Keys stored in a `MemoryObject` must be strings. The supported value types
differ between Java and Python.
**Java** supports a broad set of types:
- **Primitive Types**: integer, float, boolean, string
- **Collections**: list, map
- **Java POJOs**: See [Flink
POJOs](https://nightlies.apache.org/flink/flink-docs-master/docs/dev/datastream/fault-tolerance/serialization/types_serialization/#pojos)
for details.
-- **General Class Types**: Any objects that can be serialized by kryo. See
[General Class
Types](https://nightlies.apache.org/flink/flink-docs-master/docs/dev/datastream/fault-tolerance/serialization/types_serialization/#general-class-types)
for details.
-- **Memory Object**: The value can also be a `MemoryObject`, which means users
can store nested objects.
+- **General Class Types**: Any objects that can be serialized by Kryo. See
[General Class
Types](https://nightlies.apache.org/flink/flink-docs-master/docs/dev/datastream/fault-tolerance/serialization/types_serialization/#general-class-types)
for details.
**Python** is restricted to recursively *checkpoint-stable* values:
- **Primitive Types**: `None`, `bool`, `int`, `float`, `str`, `bytes`
- **Collections**: `list`, and `dict` with `str` keys (values are recursively
validated)
-- **Memory Object**: A nested `MemoryObject` created via `new_object()`.
+
+**Nested objects:** A `MemoryObject` is not a value passed to `set()`. Create
nested object nodes with `new_object()` in Python or `newObject()` in Java, and
then write their fields.
Anything else — Pydantic models, `uuid.UUID`, `Enum`, custom classes, `tuple`,
`set`, `bytearray`, or a `dict` with non-`str` keys — is **rejected by `set()`
with a `TypeError`**. Exact `bytes` is supported (it converts to a native Java
`byte[]`), but `bytearray` and `bytes` subclasses are not — Pemja wraps them as
non-checkpoint-stable objects rather than materializing a `byte[]`.
@@ -154,10 +154,6 @@ public static void processEvent(Event event, RunnerContext
ctx) throws Exception
{{< /tabs >}}
-{{< hint info >}}
-Unlike other types, user should use `new_object` to write a `MemoryObject`.
-{{< /hint >}}
-
#### Nested Object
There are two ways to access fields of a nested object. Users can choose
whichever they like.
@@ -216,9 +212,10 @@ age = (int) memory.get("user.age").getValue();
#### When to use
-`MemoryRef` is useful for passing data across multiple actions via memory. We
recommend user to use `MemoryRef` for large data in events rather than original
data. It can bring follow benefit:
-* **Reduce the event payload size**: The size of `MemoryRef` is usually
typically smaller than that of the original data. Events are widely used in
Flink Agents - action orchestration, observability and fault tolerance, etc.
Therefore, reducing the event size can help avoid unnecessary overheads.
-* **Avoid unnecessary data copy & SerDe**: When traveling through actions,
only the reference of data needs to be copied and serialized.
+`MemoryRef` is useful for passing data across multiple actions via memory. For
large data, use a `MemoryRef` in events rather than the original data. It
provides the following benefits:
+
+* **Reduce the event payload size**: The size of a `MemoryRef` is typically
smaller than that of the original data. Events are widely used in Flink Agents
for action orchestration, observability, and fault tolerance. Therefore,
reducing event size can help avoid unnecessary overhead.
+* **Avoid unnecessary data copy & SerDe**: Only a reference to the data needs
to be copied and serialized between actions.
{{< tabs "Memory Reference" >}}
@@ -281,7 +278,7 @@ public static void secondAction(Event event, RunnerContext
ctx) throws Exception
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.
+- **When**: After the agent run finishes processing all events triggered by
one input event.
- **What**: All data stored in sensory memory is cleared.
- **Why**: Isolation across agent runs.
- **Framework Responsibility**: The framework handles cleanup automatically;
no user action required.
@@ -332,7 +329,7 @@ agents_config.set(
{{< tab "Java" >}}
```java
AgentsExecutionEnvironment agentsEnv =
AgentsExecutionEnvironment.getExecutionEnvironment(env);
-AgentConfiguration agentsConfig = (AgentConfiguration) agentsEnv.getConfig();
+Configuration agentsConfig = agentsEnv.getConfig();
agentsConfig.set(AgentExecutionOptions.SHORT_TERM_MEMORY_STATE_TTL_MS,
60_000L);
agentsConfig.set(
