[Doc] Introduce Mem0 based Long-Term Memory by matrixsparse · Pull Request #637 · apache/flink-agents

matrixsparse · 2026-04-20T19:34:28Z

What is the purpose of the change

Add documentation for Mem0-based Long-Term Memory integration, as described in #621.

Brief change log

Add docs/content/docs/development/memory/mem0_long_term_memory.md
- Overview and prerequisites for Mem0 integration
- Mem0LongTermMemory implementation example (extending BaseLongTermMemory)
- Agent usage examples with correct Flink Agents Python API
- Configuration options (vector store, LLM, embedder) and multi-provider support
- Advanced features: multi-user isolation, memory categories, async operations
- Best practices and known limitations

Does this pull request potentially affect one of the following parts

Dependencies
The public API
Integration tests
Documentation

Documentation

Does this pull request introduce a new feature? (yes, Mem0 LTM docs)
If yes, how is the feature documented? (docs)

matrixsparse · 2026-04-29T19:54:40Z

@wenjin272 PTAL, thanks!

wenjin272

Hi, @matrixsparse, Ty for your work.

I believe the document itself is comprehensive and accurate; however, I think some content does not need to be exposed to users. Therefore, I mainly left comments suggesting the removal of certain parts.

Additionally, #647 has been merged. You can now attach Java sample code.

wenjin272 · 2026-05-08T06:03:34Z

+1. **Install Mem0 Python SDK**:
+   ```bash
+   pip install mem0ai
+   ```


mem0ai is a dependency of flink-agents and will be installed automatically when install flink-agents, so there's no need to install it separately.

wenjin272 · 2026-05-08T06:05:35Z

+agents_config = env.get_config()
+
+# Set job identifier (maps to Mem0 user_id)
+agents_config.set(AgentConfigOptions.JOB_IDENTIFIER, "my_job")


I think it would be worth mentioning here that if the user does not configure it, the Flink job ID will be used by default.

wenjin272 · 2026-05-08T06:08:17Z

+
+### Getting a Memory Set
+
+Unlike the VectorStore-based LTM, Mem0 does not require explicit `get_or_create_memory_set` with capacity and compaction config — simply call `get_memory_set`:


Similarly, there is no need to mention VectorStore-based LTM here.

wenjin272 · 2026-05-08T06:18:51Z

+
+## Architecture
+
+The integration uses a three-layer adapter pattern. `Mem0LongTermMemory` orchestrates a Mem0 `Memory` instance, and three adapters (`FlinkAgentsLLM`, `FlinkAgentsEmbedding`, `FlinkAgentsMem0VectorStore`) bridge Flink Agents resources (ChatModel, EmbeddingModel, VectorStore) to Mem0's factory system under the `flink_agents` provider. See [Adapter Mechanism](#adapter-mechanism-advanced) for details.


This document is primarily a user guide. Since these adapters are internal implementations of Mem0LongTermMemory, I do not think they need to be introduced to users.

wenjin272 · 2026-05-08T06:19:39Z

+Flink Agents provides built-in support for [Mem0](https://github.com/mem0ai/mem0) as a Long-Term Memory backend. Mem0 is an intelligent memory layer for AI agents that provides automatic memory extraction, consolidation, and semantic retrieval.
+
+{{< hint info >}}
+Mem0 replaces the previous VectorStore-based Long-Term Memory implementation since Flink Agents 0.3.0.


I believe there is no need to mention VectorStore-based LTM here, as flink-agents is still in beta and does not guarantee API compatibility. Additionally, VectorStore-based LTM has not been around for long and has no active users. Mentioning it might only increase the cognitive load for users.

wenjin272 · 2026-05-08T06:25:25Z

+    memory_set.add(items=f"User said: {event.input}")
+
+    # Search — only returns memories for the current key
+    results = memory_set.search(query=event.input, limit=10)


It is necessary to explain the importance of context isolation to users, but providing code examples may not be needed, as the code itself does not intuitively demonstrate this isolation.

The introduction to scope was already covered in the previous section on MemorySet; I suggest moving that explanation here.

wenjin272 · 2026-05-08T06:29:21Z

+4. **Monitor token usage**: Mem0 makes two LLM calls per `add` operation (fact extraction + memory update), which impacts cost
+5. **Choose appropriate vector store**: Use Chroma for development, Elasticsearch/OpenSearch for production
+
+## Limitations


I think the Best Practices and Limitations section is not necessary.

wenjin272 · 2026-05-08T06:36:09Z

@@ -0,0 +1,434 @@
+---
+title: Mem0-based Long-Term Memory


I think we can just replace the original Long-Term Memory section rather than add a new section. Since the content in Long-Term Memory section is invalid.

Even if we support backends other than mem0 in the future, I believe the API and functionality of Long-Term Memory will remain unchanged. We only need to document the configuration methods and characteristics of each backend within the Long-Term Memory section.

wenjin272 · 2026-05-08T07:14:20Z

+
+## Overview
+
+Flink Agents provides built-in support for [Mem0](https://github.com/mem0ai/mem0) as a Long-Term Memory backend. Mem0 is an intelligent memory layer for AI agents that provides automatic memory extraction, consolidation, and semantic retrieval.


After we move the content of this document to the original Long-Term Memory section, the Overview section can be consolidated. My proposal is as follows:

Provide an introduction to Flink-Agents Long-Term Memory. 

Explain that Long-Term Memory currently supports only the mem0 backend, and give a brief overview of how mem0 works.

matrixsparse · 2026-05-08T08:00:56Z

Thanks! Will remove the flagged sections and add Java sample code.

Add documentation for integrating Mem0 as a Long-Term Memory backend in Flink Agents, including: - Mem0 overview, concepts, and prerequisites - BaseLongTermMemory implementation example - Agent usage examples with correct API - Configuration options for multiple LLM providers - Multi-user memory management and async operations - Best practices and limitations Closes apache#621

wenjin272

Overall looks good to me, just one comment. PTAL @xintongsong.

wenjin272 · 2026-05-09T09:35:24Z

-{{< tabs "Compaction Config" >}}
+This means you can safely use the same memory set name across different partitions — each partition will only access its own memories.
+
+## Metadata Filtering


Shall we move this section to Operaions? Introducing operation-level content after the sections on Usage in Agent and Context Isolation feels somewhat unnatural.

Done. Moved "Metadata Filtering" into the Operations section as a subsection.

@action

- Consolidate mem0_long_term_memory.md into long_term_memory.md - Remove Architecture, Best Practices, Limitations sections - Remove pip install instruction (mem0ai is auto-installed) - Add JOB_IDENTIFIER default behavior hint - Move scope explanation to Context Isolation section - Add Java code examples based on PR apache#647 - Fix @action/@action usage to match framework convention - Use Event base type with fromEvent()/from_event() pattern

wenjin272

LGTM

github-actions Bot added doc-label-missing The Bot applies this label either because none or multiple labels were provided. fixVersion/0.3.0 The feature or bug should be implemented/fixed in the 0.3.0 version. priority/major Default priority of the PR or issue. labels Apr 20, 2026

wenjin272 added doc-included Your PR already contains the necessary documentation updates. and removed doc-label-missing The Bot applies this label either because none or multiple labels were provided. labels Apr 21, 2026

matrixsparse force-pushed the feature/mem0-long-term-memory-docs branch from 6664d89 to 67e8693 Compare April 29, 2026 19:45

wenjin272 reviewed May 8, 2026

View reviewed changes

matrixsparse force-pushed the feature/mem0-long-term-memory-docs branch from 67e8693 to b00a1d2 Compare May 8, 2026 21:11

wenjin272 reviewed May 9, 2026

View reviewed changes

matrixsparse force-pushed the feature/mem0-long-term-memory-docs branch from b00a1d2 to cd59350 Compare May 9, 2026 12:12

wenjin272 approved these changes May 11, 2026

View reviewed changes

wenjin272 merged commit df89798 into apache:main May 11, 2026
45 of 46 checks passed


		### Getting a Memory Set

		Unlike the VectorStore-based LTM, Mem0 does not require explicit `get_or_create_memory_set` with capacity and compaction config — simply call `get_memory_set`:


		## Architecture

		The integration uses a three-layer adapter pattern. `Mem0LongTermMemory` orchestrates a Mem0 `Memory` instance, and three adapters (`FlinkAgentsLLM`, `FlinkAgentsEmbedding`, `FlinkAgentsMem0VectorStore`) bridge Flink Agents resources (ChatModel, EmbeddingModel, VectorStore) to Mem0's factory system under the `flink_agents` provider. See [Adapter Mechanism](#adapter-mechanism-advanced) for details.


		## Overview

		Flink Agents provides built-in support for [Mem0](https://github.com/mem0ai/mem0) as a Long-Term Memory backend. Mem0 is an intelligent memory layer for AI agents that provides automatic memory extraction, consolidation, and semantic retrieval.

Uh oh!

Conversation

matrixsparse commented Apr 20, 2026

What is the purpose of the change

Brief change log

Does this pull request potentially affect one of the following parts

Documentation

Uh oh!

matrixsparse commented Apr 29, 2026

Uh oh!

wenjin272 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matrixsparse commented May 8, 2026

Uh oh!

wenjin272 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wenjin272 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

wenjin272 left a comment •

edited

Loading