Merge pull request #598 from kartik-mem0/feat/mem0-memory-store

feat: add Mem0 memory integration with config, implementation, docs, tests, and dependency

Author: NA-Wen

docs/user_guide/en/modules/memory.md

@@ -32,12 +32,23 @@ memory:
         model: text-embedding-3-small
 ```
 
+### Mem0 Memory Config
+```yaml
+memory:
+  - name: agent_memory
+    type: mem0
+    config:
+      api_key: ${MEM0_API_KEY}
+      agent_id: my-agent
+```
+
 ## 3. Built-in Store Comparison
 | Type | Path | Highlights | Best for |
 | --- | --- | --- | --- |
 | `simple` | `node/agent/memory/simple_memory.py` | Optional disk persistence (JSON) after runs; FAISS + semantic rerank; read/write capable. | Small conversation history, prototypes. |
 | `file` | `node/agent/memory/file_memory.py` | Chunks files/dirs into a vector index, read-only, auto rebuilds when files change. | Knowledge bases, doc QA. |
 | `blackboard` | `node/agent/memory/blackboard_memory.py` | Lightweight append-only log trimmed by time/count; no vector search. | Broadcast boards, pipeline debugging. |
+| `mem0` | `node/agent/memory/mem0_memory.py` | Cloud-managed by Mem0; semantic search + graph relationships; no local embeddings or persistence needed. Requires `mem0ai` package. | Production memory, cross-session persistence, multi-agent memory sharing. |
 
 All stores register through `register_memory_store()` so summaries show up in UI via `MemoryStoreConfig.field_specs()`.
 
@@ -98,6 +109,14 @@ This schema lets multimodal outputs flow into Memory/Thinking modules without ex
 - **Retrieval** – Returns the latest `top_k` entries ordered by time.
 - **Write** – `update()` appends the latest snapshot (input/output blocks, attachments, previews). No embeddings are generated, so retrieval is purely recency-based.
 
+### 5.4 Mem0Memory
+- **Config** – Requires `api_key` (from [app.mem0.ai](https://app.mem0.ai)). Optional `user_id`, `agent_id`, `org_id`, `project_id` for scoping.
+- **Entity scoping**: `user_id` and `agent_id` are independent dimensions — both can be included simultaneously in `add()` and `search()` calls. When both are configured, retrieval uses an OR filter (`{"OR": [{"user_id": ...}, {"agent_id": ...}]}`) to search across both scopes. Writes include both IDs when available.
+- **Retrieval** – Uses Mem0's server-side semantic search. Supports `top_k` and `similarity_threshold` via `MemoryAttachmentConfig`.
+- **Write** – `update()` sends only user input to Mem0 via the SDK (as `role: "user"` messages). Assistant output is excluded to prevent noise memories from the LLM's responses being extracted as facts.
+- **Persistence** – Fully cloud-managed. `load()` and `save()` are no-ops. Memories persist across runs and sessions automatically.
+- **Dependencies** – Requires `mem0ai` package (`pip install mem0ai`).
+
 ## 6. EmbeddingConfig Notes
 - Fields: `provider`, `model`, `api_key`, `base_url`, `params`.
 - `provider=openai` uses the official client; override `base_url` for compatibility layers.

docs/user_guide/zh/modules/memory.md

@@ -32,12 +32,23 @@ memory:
         model: text-embedding-3-small
 ```
 
+### Mem0 Memory 配置
+```yaml
+memory:
+  - name: agent_memory
+    type: mem0
+    config:
+      api_key: ${MEM0_API_KEY}
+      agent_id: my-agent
+```
+
 ## 3. 内置 Memory Store 对比
 | 类型 | 路径 | 特点 | 适用场景 |
 | --- | --- | --- | --- |
 | `simple` | `node/agent/memory/simple_memory.py` | 运行结束后可选择落盘（JSON）；使用向量搜索（FAISS）+语义重打分；支持读写 | 小规模对话记忆、快速原型 |
 | `file` | `node/agent/memory/file_memory.py` | 将指定文件/目录切片为向量索引，只读；自动检测文件变更并更新索引 | 知识库、文档问答 |
 | `blackboard` | `node/agent/memory/blackboard_memory.py` | 轻量附加日志，按时间/条数裁剪；不依赖向量检索 | 简易广播板、流水线调试 |
+| `mem0` | `node/agent/memory/mem0_memory.py` | 由 Mem0 云端托管；支持语义搜索 + 图关系；无需本地 embedding 或持久化。需安装 `mem0ai` 包。 | 生产级记忆、跨会话持久化、多 Agent 记忆共享 |
 
 > 所有内置 store 都会在 `register_memory_store()` 中注册，摘要可通过 `MemoryStoreConfig.field_specs()` 在 UI 中展示。
 
@@ -100,6 +111,14 @@ nodes:
 - **检索**：直接返回最近 `top_k` 条，按时间排序。
 - **写入**：`update()` 以 append 方式存储最新的输入/输出 snapshot（文本 + 块 + 附件信息），不生成向量，适合事件流或人工批注。
 
+### 5.4 Mem0Memory
+- **配置**：必须提供 `api_key`（从 [app.mem0.ai](https://app.mem0.ai) 获取）。可选参数 `user_id`、`agent_id`、`org_id`、`project_id` 用于记忆范围控制。
+- **实体范围**：`user_id` 和 `agent_id` 是独立的维度，可在 `add()` 和 `search()` 调用中同时使用。若同时配置，检索时使用 OR 过滤器（`{"OR": [{"user_id": ...}, {"agent_id": ...}]}`）在一次 API 调用中搜索两个范围。写入时两个 ID 同时包含。
+- **检索**：使用 Mem0 服务端语义搜索。通过 `MemoryAttachmentConfig` 中的 `top_k` 和 `similarity_threshold` 控制。
+- **写入**：`update()` 仅将用户输入（`role: "user"` 消息）发送至 Mem0。不包含 Agent 输出，以避免 LLM 响应中的内容被提取为噪声记忆。
+- **持久化**：完全由云端托管。`load()` 和 `save()` 为空操作（no-op）。记忆在不同运行和会话间自动持久化。
+- **依赖**：需安装 `mem0ai` 包（`pip install mem0ai`）。
+
 ## 6. EmbeddingConfig 提示
 - 字段：`provider`, `model`, `api_key`, `base_url`, `params`。
 - `provider=openai` 时使用 `openai.OpenAI` 客户端，可配置 `base_url` 以兼容兼容层。

entity/configs/__init__.py

@@ -10,6 +10,7 @@
     EmbeddingConfig,
     FileMemoryConfig,
     FileSourceConfig,
+    Mem0MemoryConfig,
     MemoryAttachmentConfig,
     MemoryStoreConfig,
     SimpleMemoryConfig,
@@ -43,6 +44,7 @@
     "FunctionToolConfig",
     "GraphDefinition",
     "HumanConfig",
+    "Mem0MemoryConfig",
     "MemoryAttachmentConfig",
     "MemoryStoreConfig",
     "McpLocalConfig",

entity/configs/node/memory.py

@@ -279,6 +279,75 @@ def from_dict(cls, data: Mapping[str, Any], *, path: str) -> "BlackboardMemoryCo
     }
 
 
+@dataclass
+class Mem0MemoryConfig(BaseConfig):
+    """Configuration for Mem0 managed memory service."""
+
+    api_key: str = ""
+    org_id: str | None = None
+    project_id: str | None = None
+    user_id: str | None = None
+    agent_id: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any], *, path: str) -> "Mem0MemoryConfig":
+        mapping = require_mapping(data, path)
+        api_key = require_str(mapping, "api_key", path)
+        org_id = optional_str(mapping, "org_id", path)
+        project_id = optional_str(mapping, "project_id", path)
+        user_id = optional_str(mapping, "user_id", path)
+        agent_id = optional_str(mapping, "agent_id", path)
+        return cls(
+            api_key=api_key,
+            org_id=org_id,
+            project_id=project_id,
+            user_id=user_id,
+            agent_id=agent_id,
+            path=path,
+        )
+
+    FIELD_SPECS = {
+        "api_key": ConfigFieldSpec(
+            name="api_key",
+            display_name="Mem0 API Key",
+            type_hint="str",
+            required=True,
+            description="Mem0 API key (get one from app.mem0.ai)",
+            default="${MEM0_API_KEY}",
+        ),
+        "org_id": ConfigFieldSpec(
+            name="org_id",
+            display_name="Organization ID",
+            type_hint="str",
+            required=False,
+            description="Mem0 organization ID for scoping",
+            advance=True,
+        ),
+        "project_id": ConfigFieldSpec(
+            name="project_id",
+            display_name="Project ID",
+            type_hint="str",
+            required=False,
+            description="Mem0 project ID for scoping",
+            advance=True,
+        ),
+        "user_id": ConfigFieldSpec(
+            name="user_id",
+            display_name="User ID",
+            type_hint="str",
+            required=False,
+            description="User ID for user-scoped memories. Mutually exclusive with agent_id in API calls.",
+        ),
+        "agent_id": ConfigFieldSpec(
+            name="agent_id",
+            display_name="Agent ID",
+            type_hint="str",
+            required=False,
+            description="Agent ID for agent-scoped memories. Mutually exclusive with user_id in API calls.",
+        ),
+    }
+
+
 @dataclass
 class MemoryStoreConfig(BaseConfig):
     name: str

pyproject.toml

@@ -39,6 +39,7 @@ dependencies = [
     "filelock>=3.20.1",
     "markdown>=3.10",
     "xhtml2pdf>=0.2.17",
+    "mem0ai>=1.0.9",
 ]
 
 [build-system]

runtime/node/agent/memory/builtin_stores.py

@@ -3,6 +3,7 @@
 from entity.configs.node.memory import (
     BlackboardMemoryConfig,
     FileMemoryConfig,
+    Mem0MemoryConfig,
     SimpleMemoryConfig,
     MemoryStoreConfig,
 )
@@ -34,6 +35,19 @@
 )
 
 
+def _create_mem0_memory(store):
+    from runtime.node.agent.memory.mem0_memory import Mem0Memory
+    return Mem0Memory(store)
+
+
+register_memory_store(
+    "mem0",
+    config_cls=Mem0MemoryConfig,
+    factory=_create_mem0_memory,
+    summary="Mem0 managed memory with semantic search and graph relationships",
+)
+
+
 class MemoryFactory:
     @staticmethod
     def create_memory(store: MemoryStoreConfig) -> MemoryBase: