docs(open_source_api): add EN translation of all open-source REST API docs

content/en/open_source/open_source_api/chat/chat.md

@@ -0,0 +1,80 @@
+---
+title: Chat
+desc: "An end-to-end RAG loop integrating retrieval, generation, and storage — supporting personalized responses with MemCube and automatic memory crystallization."
+---
+
+:::note
+For a complete reference of API fields and formats, see the [Chat API Documentation](/api_docs/chat/chat).
+:::
+
+**Endpoints**:
+* **Complete Response**: `POST /product/chat/complete`
+* **Streaming Response (SSE)**: `POST /product/chat/stream`
+
+**Description**: The core business orchestration entry point of MemOS. It automatically recalls relevant memories from specified `readable_cube_ids`, generates contextual responses, and optionally writes conversation results back to `writable_cube_ids` for continuous AI self-evolution.
+
+## 1. Core Architecture: ChatHandler Orchestration
+
+1. **Memory Retrieval**: Calls **SearchHandler** based on `readable_cube_ids` to extract relevant facts, preferences, and tool context from isolated Cubes.
+2. **Context-Augmented Generation**: Injects recalled memory fragments into the prompt, then calls the specified LLM (via `model_name_or_path`) to generate a targeted response.
+3. **Automatic Memory Loop**: If `add_message_on_answer=true`, the system calls **AddHandler** to asynchronously store the conversation in the specified Cubes — no manual add call required.
+
+## 2. Key Parameters
+
+### 2.1 Identity & Context
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **`query`** | `str` | Yes | The user's current question. |
+| **`user_id`** | `str` | Yes | Unique user identifier for auth and data isolation. |
+| `history` | `list` | No | Short-term conversation history for maintaining session coherence. |
+| `session_id` | `str` | No | Session ID. Acts as a "soft signal" to boost recall weight for in-session memories. |
+
+### 2.2 MemCube Read/Write Control
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| **`readable_cube_ids`** | `list` | - | **Read**: Memory Cubes allowed for retrieval (can span personal and shared Cubes). |
+| **`writable_cube_ids`** | `list` | - | **Write**: Target Cubes for auto-generated memories after conversation. |
+| **`add_message_on_answer`** | `bool` | `true` | Whether to enable auto-writeback. Recommended to keep enabled. |
+
+### 2.3 Algorithm & Model Configuration
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `mode` | `str` | `fast` | Retrieval mode: `fast`, `fine`, `mixture`. |
+| `model_name_or_path` | `str` | - | LLM model name or path. |
+| `system_prompt` | `str` | - | Override the default system prompt. |
+| `temperature` | `float` | - | Sampling temperature for controlling creativity. |
+| `threshold` | `float` | `0.5` | Relevance threshold — memories below this score are filtered out. |
+
+## 3. Response Modes
+
+### 3.1 Complete Response (`/complete`)
+* Returns the full JSON response after the model finishes generation.
+* Best for non-interactive tasks, background processing, or simple applications.
+
+### 3.2 Streaming Response (`/stream`)
+* Uses **Server-Sent Events (SSE)** to push tokens in real time.
+* Best for chatbots and assistants requiring typewriter-style UI feedback.
+
+## 4. Quick Start
+
+```python
+from memos.api.client import MemOSClient
+
+client = MemOSClient(api_key="...", base_url="...")
+
+res = client.chat(
+    user_id="dev_user_01",
+    query="Based on my preferences, suggest an R data cleaning workflow",
+    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 response: {res.data}")
+```
+
+:::note
+**Developer Tip**: For debugging in a Playground environment, use the dedicated stream endpoint `/product/chat/stream/playground`.
+:::

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

@@ -0,0 +1,68 @@
+---
+title: Add Memory
+desc: "The core production endpoint of MemOS. Leverages MemCube isolation to support personal memory, knowledge bases, and multi-tenant async memory production."
+---
+
+**Endpoint**: `POST /product/add`
+**Description**: The primary entry point for storing unstructured data. It accepts conversation lists, plain text, or metadata and transforms raw data into structured memory fragments. The open-source edition uses **MemCube** for physical memory isolation and dynamic organization.
+
+## 1. Core Mechanism: MemCube Isolation
+
+Understanding MemCube is essential for effective API usage:
+
+* **Isolation Unit**: A MemCube is the atomic unit of memory production. Cubes are fully independent — deduplication and conflict resolution happen only within a single Cube.
+* **Flexible Mapping**:
+    * **Personal Mode**: Pass `user_id` as `writable_cube_ids` to create a private memory space.
+    * **Knowledge Base Mode**: Pass a knowledge base identifier (QID) as `writable_cube_ids` to store content into that knowledge base.
+* **Multi-target Writes**: The API supports writing to multiple Cubes simultaneously for cross-domain synchronization.
+
+## 2. Key Parameters
+
+| Parameter | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| **`user_id`** | `str` | Yes | - | Unique user identifier for permission validation. |
+| **`messages`** | `list/str` | Yes | - | Message list or plain text content to store. |
+| **`writable_cube_ids`** | `list[str]` | Yes | - | **Core**: Target Cube IDs for writing. |
+| **`async_mode`** | `str` | No | `async` | Processing mode: `async` (background queue) or `sync` (blocking). |
+| **`is_feedback`** | `bool` | No | `false` | If `true`, routes to the feedback handler for memory correction. |
+| `session_id` | `str` | No | `default` | Session identifier for conversation context tracking. |
+| `custom_tags` | `list[str]` | No | - | Custom tags for subsequent search filtering. |
+| `info` | `dict` | No | - | Extended metadata. All key-value pairs support filter-based retrieval. |
+| `mode` | `str` | No | - | Effective only when `async_mode='sync'`: `fast` or `fine`. |
+
+## 3. How It Works (Component & Handler)
+
+When a request arrives, the **AddHandler** orchestrates core components:
+
+1. **Multimodal Parsing**: `MemReader` converts `messages` into internal memory objects.
+2. **Feedback Routing**: If `is_feedback=True`, the handler extracts the tail of the conversation as feedback and corrects existing memories instead of generating new facts.
+3. **Async Dispatch**: In `async` mode, `MemScheduler` pushes the task into a queue and the API returns a `task_id` immediately.
+4. **Internal Organization**: The algorithm performs deduplication and fusion within the target Cube to optimize memory quality.
+
+## 4. Quick Start
+
+Use the `MemOSClient` SDK for standardized calls:
+
+```python
+from memos.api.client import MemOSClient
+
+client = MemOSClient(api_key="...", base_url="...")
+
+# Scenario 1: Add memory for a personal user
+client.add_message(
+    user_id="sde_dev_01",
+    writable_cube_ids=["user_01_private"],
+    messages=[{"role": "user", "content": "I'm learning ggplot2 in R."}],
+    async_mode="async",
+    custom_tags=["Programming", "R"]
+)
+
+# Scenario 2: Import content into a knowledge base with feedback
+client.add_message(
+    user_id="admin_01",
+    writable_cube_ids=["kb_finance_2026"],
+    messages="The 2026 financial audit process has been updated. Please see attachment.",
+    is_feedback=True,
+    info={"source": "Internal_Portal"}
+)
+```

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

@@ -0,0 +1,57 @@
+---
+title: Delete Memory
+desc: "Permanently remove memory entries, associated files, or memory sets matching specific filter conditions from a designated MemCube."
+---
+
+**Endpoint**: `POST /product/delete_memory`
+**Description**: Maintains memory store accuracy and compliance. When a user requests information erasure, data becomes stale, or uploaded files need cleanup, this endpoint performs synchronized physical deletion across both vector databases and graph databases.
+
+## 1. Core Mechanism: Cube-level Physical Cleanup
+
+In the open-source edition, deletion follows strict **MemCube** isolation:
+
+* **Scope Restriction**: Deletion is locked to the Cubes specified via `writable_cube_ids` — content in other Cubes is never affected.
+* **Multi-dimensional Deletion**: Supports concurrent cleanup by **memory ID** (precise), **file ID** (cascading), and **filter** (conditional logic).
+* **Atomic Synchronization**: Triggered by **MemoryHandler**, ensuring both vector index entries and graph database entity nodes are removed simultaneously, preventing recall of "phantom" memories.
+
+## 2. Key Parameters
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **`writable_cube_ids`** | `list[str]` | Yes | Target Cube IDs for the deletion operation. |
+| **`memory_ids`** | `list[str]` | No | List of memory UUIDs to delete. |
+| **`file_ids`** | `list[str]` | No | List of original file IDs — all memories derived from these files will also be removed. |
+| **`filter`** | `object` | No | Logical filter. Supports batch deletion by tags, metadata, or timestamps. |
+
+## 3. How It Works (MemoryHandler)
+
+1. **Permission & Routing**: Validates permissions via `user_id` and routes to **MemoryHandler**.
+2. **Locate Storage**: Identifies the underlying **naive_mem_cube** components from `writable_cube_ids`.
+3. **Dispatch Cleanup**:
+    * **By ID**: Directly erases records from the primary database and vector store.
+    * **By Filter**: First retrieves matching memory IDs, then performs bulk physical removal.
+4. **Status Feedback**: Returns success status — affected content immediately disappears from [**Search**](./search_memory.md) results.
+
+## 4. Quick Start
+
+```python
+client = MemOSClient(api_key="...", base_url="...")
+
+# Scenario 1: Delete a single known incorrect memory
+client.delete_memory(
+    writable_cube_ids=["user_01_private"],
+    memory_ids=["2f40be8f-736c-4a5f-aada-9489037769e0"]
+)
+
+# Scenario 2: Batch cleanup all memories with a specific tag
+client.delete_memory(
+    writable_cube_ids=["kb_finance_2026"],
+    filter={"tags": {"contains": "deprecated_policy"}}
+)
+```
+
+## 5. Important Notes
+
+**Irreversibility**: Deletion is physical. Once successful, the memory cannot be recalled via the search API.
+
+**File Cascading**: When deleting by `file_ids`, the system automatically traces and removes all fact memories and summaries derived from those files.

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

@@ -0,0 +1,80 @@
+---
+title: Get Memories
+desc: "Paginated query or full export of memory collections from a specified Cube, with support for type filtering and subgraph extraction."
+---
+
+**Endpoints**:
+* **Paginated Query**: `POST /product/get_memory`
+* **Full Export**: `POST /product/get_all`
+
+**Description**: List or export memory assets from a specified **MemCube**. These endpoints provide access to raw memory fragments, user preferences, and tool usage records, supporting paginated display and structured exports.
+
+## 1. Core Mechanism: Paginated vs. Full Export
+
+The system provides two access modes via **MemoryHandler**:
+
+* **Business Pagination (`/get_memory`)**:
+    * Designed for frontend UI lists. Supports `page` and `page_size` parameters.
+    * Includes preference memories by default (`include_preference`), enabling lightweight data loading.
+* **Full Export (`/get_all`)**:
+    * Designed for data migration or complex relationship analysis.
+    * Supports `search_query` for extracting related **subgraphs**, or full export by `memory_type` (text/action/parameter).
+
+## 2. Key Parameters
+
+### 2.1 Paginated Query (`/get_memory`)
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **`mem_cube_id`** | `str` | Yes | Target MemCube ID. |
+| **`user_id`** | `str` | No | Unique user identifier. |
+| **`page`** | `int` | No | Page number (starting from 1). Set to `None` for full export. |
+| **`page_size`** | `int` | No | Items per page. |
+| `include_preference` | `bool` | No | Whether to include preference memories. |
+
+### 2.2 Full / Subgraph Export (`/get_all`)
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **`user_id`** | `str` | Yes | User ID. |
+| **`memory_type`** | `str` | Yes | Memory type: `text_mem`, `act_mem`, `para_mem`. |
+| `mem_cube_ids` | `list` | No | Cube IDs to export. |
+| `search_query` | `str` | No | If provided, recalls and returns a related memory subgraph. |
+
+## 3. Quick Start
+
+### 3.1 Frontend Paginated Display
+
+```python
+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 Export a Fact Memory Subgraph
+
+```python
+res = client.get_all(
+    user_id="sde_dev_01",
+    memory_type="text_mem",
+    search_query="R language visualization"
+)
+```
+
+## 4. Response Structure
+
+The response `data` contains an array of memory objects. Each memory typically includes:
+
+* `id`: Unique memory identifier — use with [**Get Detail**](./get_memory_by_id.md) or [**Delete**](./delete_memory.md).
+* `memory_value`: Algorithmically processed memory text.
+* `tags`: Associated custom tags.
+
+:::note
+**Developer Tip**: If you already know a memory ID and want to see its full metadata (confidence, usage records, etc.), use the [**Get Memory Detail**](./get_memory_by_id.md) endpoint.
+:::

content/en/open_source/open_source_api/core/get_memory_by_id.md

@@ -0,0 +1,53 @@
+---
+title: Get Memory Detail
+desc: "Retrieve full metadata for a single memory via its unique ID, including confidence score, background context, and usage history."
+---
+
+**Endpoint**: `GET /product/get_memory/{memory_id}`
+**Description**: Retrieve all underlying details for a single memory entry. Unlike search endpoints that return summary information, this endpoint exposes lifecycle data (vector sync status, AI extraction context) — essential for system management and troubleshooting.
+
+## 1. Why Get Memory Detail?
+
+* **Metadata Inspection**: View the AI's `confidence` score and `background` reasoning when it extracted this memory.
+* **Lifecycle Verification**: Confirm whether `vector_sync` succeeded and check `updated_at` timestamps.
+* **Usage Tracking**: Review `usage` records showing which sessions recalled this memory for generation.
+
+## 2. Key Parameters
+
+This endpoint uses standard RESTful path parameters:
+
+| Parameter | Location | Type | Required | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| **`memory_id`** | Path | `str` | Yes | Memory UUID. Obtain from [**Get Memories**](./get_memory.md) or [**Search**](./search_memory.md) results. |
+
+## 3. How It Works (MemoryHandler)
+
+1. **Direct Query**: **MemoryHandler** bypasses business orchestration, interacting directly with the underlying **naive_mem_cube** component.
+2. **Data Completion**: Pulls the complete `metadata` dictionary from the persistent store — no semantic truncation is applied.
+
+## 4. Response Data
+
+The response `data` object contains these core fields:
+
+| Field | Description |
+| :--- | :--- |
+| **`id`** | Unique memory identifier. |
+| **`memory`** | Memory text content, typically with annotations (e.g., `[user opinion]`). |
+| **`metadata.confidence`** | AI extraction confidence score (0.0–1.0). |
+| **`metadata.type`** | Memory classification: `fact`, `preference`, etc. |
+| **`metadata.background`** | Detailed AI explanation of why this memory was extracted and its context. |
+| **`metadata.usage`** | List of historical timestamps and contexts where this memory was used by the model. |
+| **`metadata.vector_sync`** | Vector database sync status, typically `success`. |
+
+## 5. Quick Start
+
+```python
+mem_id = "2f40be8f-736c-4a5f-aada-9489037769e0"
+
+res = client.get_memory_by_id(memory_id=mem_id)
+
+if res and res.code == 200:
+    metadata = res.data.get('metadata', {})
+    print(f"Background: {metadata.get('background')}")
+    print(f"Sync status: {metadata.get('vector_sync')}")
+```