(flink-agents) branch main updated: [docs] Fix memory examples and clarify long-term memory isolation (#794) (#816)

[we...@apache.org]

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 cb657971 [docs] Fix memory examples and clarify long-term memory isolation (#794) (#816)
cb657971 is described below

commit cb65797130838f64390052ba7d09cd093d33b670
Author: Wenjin Xie <16...@users.noreply.github.com>
AuthorDate: Tue Jun 9 10:58:41 2026 +0800

    [docs] Fix memory examples and clarify long-term memory isolation (#794) (#816)
    
    * [docs] Fix memory examples and clarify long-term memory isolation (#794)
    
    - Soften LTM context isolation wording: isolation is keyed on
      String.valueOf(key.hashCode()), so hash collisions may share a context.
    - Document the Java+Mem0 Flink version prerequisite that throws at startup.
    - Rename "Complete Example" to "Usage Snippet" and note these are action
      fragments, not standalone agents; link to the Workflow Agent Quickstart.
    - Fix Java example: getInput() returns Object, wrap with String.valueOf.
    - Fix MemoryRef#resolve cast: resolve returns MemoryObject, read getValue().
    
    Co-Authored-By: Claude Opus 4.8 (1M context) <no...@anthropic.com>
---
 docs/content/docs/development/memory/long_term_memory.md   | 14 ++++++++++----
 .../development/memory/sensory_and_short_term_memory.md    |  2 +-
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/docs/content/docs/development/memory/long_term_memory.md b/docs/content/docs/development/memory/long_term_memory.md
index b2475fc0..eeb4c79d 100644
--- a/docs/content/docs/development/memory/long_term_memory.md
+++ b/docs/content/docs/development/memory/long_term_memory.md
@@ -35,6 +35,8 @@ Declare the following resources in your agent plan:
 - An [EmbeddingModel]({{< ref "docs/development/embedding_models" >}}) for vector generation
 - A [VectorStore]({{< ref "docs/development/vector_stores" >}}) for persistent storage
 
+> **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` or higher; otherwise it throws at startup. Either upgrade Flink or use the Python API.
+
 ## Configuration
 
 Mem0 Long-Term Memory is enabled by setting three configuration options:
@@ -444,9 +446,11 @@ results = memorySet.search(
 
 ## Usage in Agent
 
-### Complete Example
+### Usage Snippet
+
+The snippets below show how to read from and write to Long-Term Memory inside an action.
 
-{{< tabs "Complete Example" >}}
+{{< tabs "Usage Snippet" >}}
 
 {{< tab "Python" >}}
 
@@ -501,7 +505,7 @@ agents_config.set(LongTermMemoryOptions.Mem0.VECTOR_STORE, "my_vector_store")
 public static void processEvent(Event event, RunnerContext ctx) throws Exception {
     InputEvent inputEvent = InputEvent.fromEvent(event);
     BaseLongTermMemory ltm = ctx.getLongTermMemory();
-    String userQuery = inputEvent.getInput();
+    String userQuery = String.valueOf(inputEvent.getInput());
 
     // Get memory set
     MemorySet memorySet = ltm.getMemorySet("assistant_memories");
@@ -536,4 +540,6 @@ The isolation hierarchy works as follows:
 - **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
 
-This means you can safely use the same memory set name across different partitions — each partition will only access its own memories.
+This means you can reuse the same memory set name across different partitions, and each partition will normally access only its own memories.
+
+> **Note:** Partition-level isolation is currently derived from the hash of the partition key (`String.valueOf(key.hashCode())`) rather than the full original key. Distinct keys whose hashes collide may therefore share the same memory context. Avoid relying on isolation as a strict security boundary; if collision-free isolation is required, encode a unique identifier into the memory set name.
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 d086dc4d..f3aa3810 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
@@ -245,7 +245,7 @@ public static void secondAction(Event event, RunnerContext ctx) throws Exception
                                                      .get(myEvent.getValue())
                                                      .getValue();
     // or
-    processedData = (ProcessedData) myEvent.getValue().resolve(ctx);
+    processedData = (ProcessedData) myEvent.getValue().resolve(ctx).getValue();
     ...
 }
 ```