Merge pull request #367 from abbyzhou02/v2

docs: sync memory module docs English version

Author: CaralHsi

content/cn/open_source/modules/memories/naive_textual_memory.md

@@ -1,13 +1,12 @@
 ---
 title: "NaiveTextMemory: 简单明文记忆"
-desc: "MemOS 中最轻量级的记忆模块，专为快速原型开发和简单场景设计。无需向量数据库，使用关键词匹配即可快速检索。"
+desc: "MemOS 中最轻量级的记忆模块，专为快速原型开发和简单场景设计。无需向量数据库，使用关键词匹配即可快速检索。让我们用最简单的方式开始使用 MemOS 记忆系统！
+`NaiveTextMemory` 是一个基于内存的明文记忆模块，将记忆存储在内存列表中，使用关键词匹配进行检索。它是学习 MemOS 的最佳起点，也适用于演示、测试和小规模应用。"
+
 ---
 
-# NaiveTextMemory: 简单明文记忆
 
-让我们用最简单的方式开始使用 MemOS 记忆系统！
 
-`NaiveTextMemory` 是一个轻量级、基于内存的明文记忆模块，将记忆存储在内存列表中，使用关键词匹配进行检索。它是学习 MemOS 的最佳起点，也适用于演示、测试和小规模应用。
 
 ## 目录
 
@@ -144,7 +143,7 @@ memory = NaiveTextMemory(config: NaiveTextMemoryConfig)
 
 
 
-::alert{type="info"}
+::note
 **示例对比**<br>
 查询："猫咪" <br>
 - **关键词匹配**：只匹配包含"猫"、"猫咪"的记忆<br>

content/cn/open_source/modules/memories/tree_textual_memory.md

@@ -1,12 +1,13 @@
 ---
 title: "TreeTextMemory: 分层结构的明文记忆"
----
-
-让我们在MemOS中构建你的第一个**基于图的、树形明文记忆**！
+desc: "让我们在MemOS中构建你的第一个**基于图的、树形明文记忆**！
 
 **TreeTextMemory** 支持以结构化方式组织、关联并检索记忆，同时保留丰富的上下文信息与良好的可解释性。
 
-MemOS当前使用[Neo4j](/open_source/modules/memories/neo4j_graph_db)作为后端，未来计划支持更多图数据库。
+MemOS当前使用[Neo4j](/open_source/modules/memories/neo4j_graph_db)作为后端，未来计划支持更多图数据库。"
+---
+
+
 
 ## 目录
 

content/cn/open_source/open_source_api/chat/chat.md

@@ -0,0 +1,86 @@
+---
+title: 对话
+desc: 集成“检索、生成、存储”全链路的 RAG 闭环接口，支持基于 MemCube 的个性化回复与记忆自动沉淀。
+---
+
+:::note
+有关API字段、格式等信息的完整列表，详见[Chat 接口文档](/api_docs/chat/chat)。
+:::
+
+**接口路径**：
+* **全量响应**：`POST /product/chat/complete`
+* **流式响应 (SSE)**：`POST /product/chat/stream`
+
+**功能描述**：本接口是 MemOS 的核心业务编排入口。它能够自动从指定的 `readable_cube_ids` 中召回相关记忆，结合当前语境生成回复，并可选地将对话结果自动回写至 `writable_cube_ids` 中，实现 AI 应用的自我进化。
+
+
+## 1. 核心架构：ChatHandler 编排流程
+
+1. **记忆检索 (Retrieval)**：根据 `readable_cube_ids` 调用 **SearchHandler**，从隔离的 Cube 中提取相关的事实、偏好及工具背景。
+2. **上下文增强生成 (Generation)**：将检索到的记忆片段注入 Prompt，调用指定的 LLM（通过 `model_name_or_path`）生成针对性回复。
+3. **记忆自动闭环 (Storage)**：若开启 `add_message_on_answer=true`，系统会调用 **AddHandler** 将本次对话异步存入指定的 Cube，无需开发者手动调用添加接口。
+## 2. 关键接口参数
+
+### 2.1 身份与语境
+| 参数名 | 类型 | 必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| **`query`** | `str` | 是 | 用户当前的提问内容。 |
+| **`user_id`** | `str` | 是 | 用户唯一标识，用于鉴权与数据隔离。 |
+| `history` | `list` | 否 | 短期历史对话记录，用于维持当前会话的连贯性。 |
+| `session_id` | `str` | 否 | 会话 ID。作为“软信号”提升该会话内相关记忆的召回权重。 |
+
+### 2.2 MemCube 读写控制
+| 参数名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| **`readable_cube_ids`** | `list` | - | **读：** 允许检索的记忆 Cube 列表（可跨个人库与公共库）。 |
+| **`writable_cube_ids`** | `list` | - | **写：** 对话完成后，自动生成的记忆应存入的目标 Cube 列表。 |
+| **`add_message_on_answer`** | `bool` | `true` | 是否开启自动回写。建议开启以维持记忆的持续更新。 |
+
+### 2.3 算法与模型配置
+| 参数名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `mode` | `str` | `fast` | 检索模式：`fast` (快速), `fine` (精细), `mixture` (混合)。 |
+| `model_name_or_path` | `str` | - | 指定使用的 LLM 模型名称或路径。 |
+| `system_prompt` | `str` | - | 覆盖默认的系统提示词。 |
+| `temperature` | `float` | - | 采样温度，控制生成文本的创造性。 |
+| `threshold` | `float` | `0.5` | 记忆召回的相关性阈值，低于该值的记忆将被剔除。 |
+
+## 3. 工作原理
+
+MemOS提供两种响应模式可供选型：
+### 3.1 全量响应 (`/complete`)
+* **特点**：等待模型生成全部内容后一次性返回 JSON。
+* **场景**：非交互式任务、后台逻辑处理、或对实时性要求较低的简单应用。
+
+### 3.2 流式响应 (`/stream`)
+* **特点**：采用 **Server-Sent Events (SSE)** 协议，实时推送 Token。
+* **场景**：聊天机器人、智能助手等需要即时打字机反馈效果的 UI 交互。
+
+## 4. 快速上手
+
+推荐使用开源版内置的 `MemOSClient` 进行调用。以下示例展示了如何询问关于 R 语言学习的建议，并利用记忆功能：
+
+```python
+from memos.api.client import MemOSClient
+
+client = MemOSClient(api_key="...", base_url="...")
+
+# 发起对话请求
+res = client.chat(
+    user_id="dev_user_01",
+    query="根据我之前的偏好，推荐一套 R 语言数据清理方案",
+    readable_cube_ids=["private_cube_01", "public_kb_r_lang"], # 读：个人偏好+公共库
+    writable_cube_ids=["private_cube_01"],                      # 写：沉淀至个人空间
+    add_message_on_answer=True,                                 # 开启自动记忆回写
+    mode="fine"                                                 # 使用精细检索模式
+)
+
+if res:
+    print(f"AI 回复内容: {res.data}")
+```
+
+
+:::note
+**开发者提示：**
+若需要针对 `Playground` 环境进行调试，请访问专用的调试流接口 /product/chat/stream/playground 。
+:::

content/cn/open_source/open_source_api/core/add_memory.md

@@ -0,0 +1,71 @@
+---
+title: 添加记忆 (Add Memory)
+desc: MemOS 的核心生产接口。通过 MemCube 隔离机制，实现个人记忆、知识库及多租户场景下的异步记忆生产。
+---
+
+**接口路径**：`POST /product/add`
+**功能描述**：这是系统存储非结构化数据的核心入口。它支持通过对话列表、纯文本或元数据，将原始数据转化为结构化的记忆片段。在开源版中，系统通过 **MemCube** 实现记忆的物理隔离与动态组织。
+
+## 1. 核心机理：MemCube 与隔离
+
+在开源架构中，理解 MemCube 是高效使用接口的关键：
+
+* **隔离单元**：MemCube 是记忆生成的原子单位，Cube 之间完全独立，系统仅在单个 Cube 内部进行去重和冲突解决。
+* **灵活映射**：
+    * **个人模式**：将 `user_id` 作为 `writable_cube_ids` 传入，即建立个人私有记忆。
+    * **知识库模式**：将知识库的唯一标识（QID）作为 `writable_cube_ids` 传入，内容即存入该知识库。
+* **多目标写入**：接口支持同时向多个 Cube 写入记忆，实现跨域同步。
+
+
+## 2. 关键接口参数
+
+核心参数定义如下：
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- | :--- |
+| **`user_id`** | `str` | 是 | - | 用户唯一标识符，用于权限校验。 |
+| **`messages`** | `list/str`| 是 | - | 待存储的消息列表或纯文本内容。 |
+| **`writable_cube_ids`** | `list[str]`| 是 | - | **核心参数**：指定写入的目标 Cube ID 列表。 |
+| **`async_mode`** | `str` | 否 | `async` | 处理模式：`async` (后台队列处理) 或 `sync` (当前请求阻塞)。 |
+| **`is_feedback`** | `bool` | 否 | `false` | 若为 `true`，系统将自动路由至反馈处理器执行记忆更正。 |
+| `session_id` | `str` | 否 | `default` | 会话标识符，用于追踪对话上下文。 |
+| `custom_tags` | `list[str]`| 否 | - | 自定义标签，可作为后续搜索时的过滤条件。 |
+| `info` | `dict` | 否 | - | 扩展元数据。其中的所有键值对均支持后续过滤检索。 |
+| `mode` | `str` | 否 | - | 仅在 `async_mode='sync'` 时生效，可选 `fast` (快速) 或 `fine` (精细)。 |
+
+## 3. 工作原理 (Component & Handler)
+
+当请求到达后端时，系统由 **AddHandler** 调度核心组件执行以下逻辑：
+
+1. **多模态解析**：由 `MemReader` 组件将 `messages` 转化为内部记忆对象。
+2. **反馈路由**：若 `is_feedback=True`，Handler 会提取对话末尾作为反馈，直接修正已有记忆，不生成新事实。
+3. **异步分发**：若为 `async` 模式，`MemScheduler` 将任务推入任务队列，接口立即返回 `task_id`。
+4. **内部组织**：算法在目标 Cube 内执行组织逻辑，通过去重和融合优化记忆质量。
+
+## 4. 快速上手示例
+
+推荐使用 `MemOSClient` SDK 进行标准化调用：
+
+```python
+from memos.api.client import MemOSClient
+
+# 初始化客户端
+client = MemOSClient(api_key="...", base_url="...")
+
+# 场景一：为个人用户添加记忆
+client.add_message(
+    user_id="sde_dev_01",
+    writable_cube_ids=["user_01_private"], 
+    messages=[{"role": "user", "content": "我正在学习 R 语言的 ggplot2。"}],
+    async_mode="async",
+    custom_tags=["Programming", "R"]
+)
+# 场景二：往知识库导入内容并开启反馈
+client.add_message(
+    user_id="admin_01",
+    writable_cube_ids=["kb_finance_2026"],
+    messages="2026年财务审计流程已更新，请参考附件。",
+    is_feedback=True, # 标记为反馈以更正旧版流程
+    info={"source": "Internal_Portal"}
+)
+```

content/cn/open_source/open_source_api/core/delete_memory.md

@@ -0,0 +1,62 @@
+---
+title: 删除记忆 (Delete Memory)
+desc: 从指定的 MemCube 中永久移除记忆条目、关联文件或符合特定过滤条件的记忆集合。
+---
+
+**接口路径**：`POST /product/delete_memory`
+**功能描述**：本接口用于维护记忆库的准确性与合规性。当用户要求遗忘特定信息、数据过时或需要清理特定的上传文件时，可以通过此接口在向量数据库与图数据库中同步执行物理删除。
+
+## 1. 核心机理：Cube 级物理清理
+
+在开源版中，删除操作遵循严格的 **MemCube** 隔离逻辑：
+
+* **作用域限制**：通过 `writable_cube_ids` 参数，删除操作被严格锁定在指定的记忆体中，绝不会误删其他 Cube 的内容。
+* **多维删除**：支持按 **记忆 ID**（精确）、**文件 ID**（关联删除）以及 **Filter 过滤器**（条件逻辑）三种维度并发执行清理。
+* **原子性同步**：删除操作由 **MemoryHandler** 触发，确保底层向量索引与图数据库中的实体节点同步移除，防止召回“幻觉”。
+
+
+
+## 2. 关键接口参数
+核心参数定义如下：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| **`writable_cube_ids`** | `list[str]` | 是 | 指定执行删除操作的目标 Cube 列表。 |
+| **`memory_ids`** | `list[str]` | 否 | 待删除的记忆唯一标识符列表。 |
+| **`file_ids`** | `list[str]` | 否 | 待删除的原始文件标识符列表，将同步清理该文件产生的全部记忆。 |
+| **`filter`** | `object` | 否 | 逻辑过滤器。支持按标签、元信息或时间戳批量删除符合条件的记忆。 |
+
+## 3. 工作原理 (MemoryHandler)
+
+1. **权限与路由**：系统通过 `user_id` 校验操作权限，并将请求路由至 **MemoryHandler**。
+2. **定位存储**：根据 `writable_cube_ids` 定位底层的 **naive_mem_cube** 组件。
+3. **分发清理任务**：
+    * **按 ID 清理**：直接根据 UUID 在主数据库和向量库中执行记录抹除。
+    * **按 Filter 清理**：先检索出符合条件的记忆 ID 集合，再执行批量物理移除。
+4. **状态反馈**：操作完成后返回成功状态，相关内容将立即从 [**检索接口**](./search_memory.md) 的召回范围中消失。
+
+## 4. 快速上手示例
+
+使用 `MemOSClient` 执行不同维度的删除操作：
+
+```python
+# 初始化客户端
+client = MemOSClient(api_key="...", base_url="...")
+
+# 场景一：精确删除单条已知的错误记忆
+client.delete_memory(
+    writable_cube_ids=["user_01_private"],
+    memory_ids=["2f40be8f-736c-4a5f-aada-9489037769e0"]
+)
+
+# 场景二：批量清理某一特定标签下的所有过时记忆
+client.delete_memory(
+    writable_cube_ids=["kb_finance_2026"],
+    filter={"tags": {"contains": "deprecated_policy"}}
+)
+```
+## 5. 注意事项
+
+不可恢复性：删除操作是物理删除。一旦执行成功，该记忆将无法再通过检索接口召回。
+
+文件关联性：通过 `file_ids` 删除时，系统会自动溯源并清理该文件解析出的事实记忆和摘要。

content/cn/open_source/open_source_api/core/get_memory.md

@@ -0,0 +1,81 @@
+---
+title: 获取记忆 (Get Memories)
+desc: 分页查询或全量导出指定 Cube 中的记忆集合，支持按类型过滤及子图提取。
+---
+
+**接口路径**：
+* **分页查询**：`POST /product/get_memory`
+* **全量导出**：`POST /product/get_all`
+
+**功能描述**：用于列出或导出指定 **MemCube** 中的记忆资产。通过这两个接口，您可以获取系统生成的原始记忆片段、用户偏好或工具使用记录，支持分页展示与结构化导出。
+
+## 1. 核心机理：分页 vs. 全量导出
+
+在开源版中，系统通过 **MemoryHandler** 提供了两种不同的集合访问模式：
+
+* **业务分页模式 (`/get_memory`)**：
+    * **设计初衷**：为前端 UI 列表设计。支持 `page` 和 `page_size` 参数。
+    * **特性**：默认包含偏好记忆（`include_preference`），支持轻量级的数据加载。
+* **全量导出模式 (`/get_all`)**：
+    * **设计初衷**：为数据迁移或复杂关系分析设计。
+    * **核心能力**：支持传入 `search_query` 提取相关的**子图（Subgraph）**，或按 `memory_type`（文本/动作/参数）导出全量数据。
+
+
+## 2. 关键接口参数
+
+### 2.1 分页查询参数 (`/get_memory`)
+
+| 参数名 | 类型 | 必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| **`mem_cube_id`** | `str` | 是 | 目标 MemCube ID。 |
+| **`user_id`** | `str` | 否 | 用户唯一标识符。 |
+| **`page`** | `int` | 否 | 页码（从 1 开始）。若设为 `None` 则尝试全量导出。 |
+| **`page_size`** | `int` | 否 | 每页条目数。 |
+| `include_preference` | `bool` | 否 | 是否包含偏好记忆。 |
+
+### 2.2 全量/子图导出参数 (`/get_all`)
+
+| 参数名 | 类型 | 必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| **`user_id`** | `str` | 是 | 用户 ID。 |
+| **`memory_type`** | `str` | 是 | 记忆类型：`text_mem`, `act_mem`, `para_mem`。 |
+| `mem_cube_ids` | `list` | 否 | 待导出的 Cube ID 列表。 |
+| `search_query` | `str` | 否 | 若提供，将基于此查询召回并返回相关的记忆子图。 |
+
+## 3. 快速上手示例
+
+### 3.1 前端分页展示 (SDK 调用)
+
+```python
+# 获取第一页，每页 10 条记忆
+res = client.get_memory(
+    user_id="sde_dev_01",
+    mem_cube_id="cube_research_01",
+    page=1,
+    page_size=10
+)
+
+for mem in res.data:
+    print(f"[{mem['type']}] {mem['memory_value']}")
+```
+### 3.2 导出特定的事实记忆子图
+```python
+# 提取与“R 语言”相关的全部事实记忆
+res = client.get_all(
+    user_id="sde_dev_01",
+    memory_type="text_mem",
+    search_query="R language visualization"
+)
+```
+
+## 4. 响应结构说明
+接口返回标准的业务响应，其中 data 包含记忆对象数组。每条记忆通常包含以下核心字段：
+
+`id`: 记忆唯一标识，用于执行 获取详情 或 删除 操作。
+
+`memory_value`: 经过算法加工后的记忆文本。
+
+`tags`: 关联的自定义标签。
+
+::note
+开发者提示： 如果您已知记忆 ID 并希望查看其完整的元数据（如 confidence 或 usage 记录），请使用`获取记忆详情`（Get_ memory_by_id）接口。 :::