From 05ef0658e8c178adcb5a36077c6d58de217640ae Mon Sep 17 00:00:00 2001 From: Binks Riverton Date: Sun, 14 Jun 2026 08:48:04 +0800 Subject: [PATCH] docs: align Quick Start examples with MemOSClient signatures and add EN translations Fix the Chat and Message API reference docs where Quick Start code examples used parameters not present in the actual MemOSClient: - chat/chat.md: replace readable_cube_ids/writable_cube_ids/mode with conversation_id/knowledgebase_ids to match client.chat() signature - message/feedback.md: replace history/writable_cube_ids/retrieved_memory_ids/ corrected_answer with conversation_id to match client.add_feedback() - message/get_suggestion_queries.md: replace MemOSClient.get_suggestions() (method does not exist) with raw HTTP POST request; remove duplicate H1 heading Also add English translations for all four files under docs/en/. --- .../open_source/open_source_api/chat/chat.md | 8 +- .../open_source_api/message/feedback.md | 17 +--- .../message/get_suggestion_queries.md | 38 ++++---- .../open_source/open_source_api/chat/chat.md | 88 +++++++++++++++++++ .../open_source_api/message/feedback.md | 67 ++++++++++++++ .../open_source_api/message/get_message.md | 73 +++++++++++++++ .../message/get_suggestion_queries.md | 68 ++++++++++++++ 7 files changed, 323 insertions(+), 36 deletions(-) create mode 100644 docs/en/open_source/open_source_api/chat/chat.md create mode 100644 docs/en/open_source/open_source_api/message/feedback.md create mode 100644 docs/en/open_source/open_source_api/message/get_message.md create mode 100644 docs/en/open_source/open_source_api/message/get_suggestion_queries.md diff --git a/docs/cn/open_source/open_source_api/chat/chat.md b/docs/cn/open_source/open_source_api/chat/chat.md index 990e0f8a7..3d014c611 100644 --- a/docs/cn/open_source/open_source_api/chat/chat.md +++ b/docs/cn/open_source/open_source_api/chat/chat.md @@ -68,11 +68,11 @@ client = MemOSClient(api_key="...", base_url="...") # 发起对话请求 res = client.chat( user_id="dev_user_01", + conversation_id="conv_r_study_001", 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" # 使用精细检索模式 + knowledgebase_ids=["kb_r_lang"], # 检索 R 语言公共知识库 + add_message_on_answer=True, # 开启自动记忆回写 + temperature=0.7 ) if res: diff --git a/docs/cn/open_source/open_source_api/message/feedback.md b/docs/cn/open_source/open_source_api/message/feedback.md index eaa73d72d..e356818d3 100644 --- a/docs/cn/open_source/open_source_api/message/feedback.md +++ b/docs/cn/open_source/open_source_api/message/feedback.md @@ -46,24 +46,15 @@ from memos.api.client import MemOSClient client = MemOSClient(api_key="...", base_url="...") -# 场景：修正 AI 关于用户职业的错误记忆 +# 场景：修正 AI 关于用户饮食偏好的错误记忆 res = client.add_feedback( user_id="dev_user_01", - feedback_content="我不再减肥了，现在不需要控制饮食。", - history=[ - {"role": "assistant", "content": "您正在减肥中，近期是否控制了摄入食物的热量？"}, - {"role": "user", "content": "我不再减肥了..."} - ], - writable_cube_ids=["private_cube_01"], - # 指定具体的错误记忆 ID，以实现精准打击 - retrieved_memory_ids=["mem_id_old_job_123"], - corrected_answer=True # 要求 AI 重新根据新事实回复我 + conversation_id="conv_diet_001", + feedback_content="我不再减肥了，现在不需要控制饮食。" ) if res and res.code == 200: - print(f"修正进度: {res.message}") - if res.data: - print(f"更正后的回复: {res.data}") + print(f"反馈已提交: {res.message}") ``` diff --git a/docs/cn/open_source/open_source_api/message/get_suggestion_queries.md b/docs/cn/open_source/open_source_api/message/get_suggestion_queries.md index 34bcbd1ee..71d26f2c9 100644 --- a/docs/cn/open_source/open_source_api/message/get_suggestion_queries.md +++ b/docs/cn/open_source/open_source_api/message/get_suggestion_queries.md @@ -3,8 +3,6 @@ title: 获取建议问题 (Get Suggestions) desc: 基于当前对话语境或 Cube 内的近期记忆，自动生成 3 条后续对话建议。 --- -# 获取建议问题 (Get Suggestion Queries) - **接口路径**：`POST /product/suggestions` **功能描述**：本接口用于实现“猜你想问”功能。系统会根据提供的对话上下文或目标 **MemCube** 中的近期记忆，通过大语言模型生成 3 个相关的建议问题，帮助用户延续对话。 @@ -41,27 +39,29 @@ desc: 基于当前对话语境或 Cube 内的近期记忆，自动生成 3 条 ## 4. 快速上手示例 -使用 SDK 获取针对当前对话的中文建议： +使用 HTTP 请求获取针对当前对话的中文建议： ```python -from memos.api.client import MemOSClient - -client = MemOSClient(api_key="...", base_url="...") - -# 场景：根据刚刚关于“R语言”的对话生成建议 -res = client.get_suggestions( - user_id="dev_user_01", - mem_cube_id="private_cube_01", - language="zh", - message=[ - {"role": "user", "content": "我想学习 R 语言的可视化。"}, - {"role": "assistant", "content": "推荐您学习 ggplot2 包，它是 R 语言可视化的核心工具。"} - ] +import requests + +# 场景：根据刚刚关于”R语言”的对话生成建议 +res = requests.post( + “http://localhost:8000/product/suggestions”, + json={ + “user_id”: “dev_user_01”, + “mem_cube_id”: “private_cube_01”, + “language”: “zh”, + “message”: [ + {“role”: “user”, “content”: “我想学习 R 语言的可视化。”}, + {“role”: “assistant”, “content”: “推荐您学习 ggplot2 包，它是 R 语言可视化的核心工具。”} + ] + } ) -if res and res.code == 200: - # 示例输出: ["如何安装 ggplot2？", "有哪些经典的 ggplot2 教程？", "R 语言还有哪些可视化包？"] - print(f"建议问题: {res.data}") +if res.status_code == 200: + data = res.json() + # 示例输出: [“如何安装 ggplot2？”, “有哪些经典的 ggplot2 教程？”, “R 语言还有哪些可视化包？”] + print(f”建议问题: {data['data']}”) ``` ## 5. 使用场景建议 diff --git a/docs/en/open_source/open_source_api/chat/chat.md b/docs/en/open_source/open_source_api/chat/chat.md new file mode 100644 index 000000000..602d8c93e --- /dev/null +++ b/docs/en/open_source/open_source_api/chat/chat.md @@ -0,0 +1,88 @@ +--- +title: Chat +desc: An integrated RAG closed-loop API covering retrieval, generation, and storage. Supports MemCube-based personalized responses and automatic memory persistence. +--- + +:::note +For a complete list of API fields, formats, and other details, see the [Chat API Reference](/api_docs/chat/chat). +::: + +**API Paths**: +* **Full Response**: `POST /product/chat/complete` +* **Streaming Response (SSE)**: `POST /product/chat/stream` + +**Description**: This API is the core business orchestration entry point of MemOS. It automatically retrieves relevant memories from the specified `readable_cube_ids`, generates a response based on the current context, and optionally writes the conversation result back to `writable_cube_ids`, enabling self-evolution of AI applications. + + +## 1. Core Architecture: ChatHandler Orchestration Flow + +1. **Memory Retrieval**: Calls **SearchHandler** against `readable_cube_ids` to extract relevant facts, preferences, and tool context from isolated Cubes. +2. **Context-Enhanced Generation**: Injects the retrieved memory fragments into the prompt and calls the specified LLM (via `model_name_or_path`) to generate a targeted response. +3. **Automatic Memory Loop (Storage)**: When `add_message_on_answer=true`, the system asynchronously calls **AddHandler** to store this conversation in the specified Cubes — no manual add calls required. + +## 2. Key API Parameters + +### 2.1 Identity & Context +| Parameter | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **`query`** | `str` | Yes | The user's current question or input. | +| **`user_id`** | `str` | Yes | Unique user identifier, used for authentication and data isolation. | +| `history` | `list` | No | Short-term conversation history to maintain coherence within the current session. | +| `session_id` | `str` | No | Session ID. Acts as a "soft signal" to boost recall weight of related memories within this session. | + +### 2.2 MemCube Read/Write Control +| Parameter | Type | Default | Description | +| :--- | :--- | :--- | :--- | +| **`readable_cube_ids`** | `list` | - | **Read:** List of memory Cubes allowed for retrieval (can span personal and public libraries). | +| **`writable_cube_ids`** | `list` | - | **Write:** Target Cube list where auto-generated memories should be stored after the conversation. | +| **`add_message_on_answer`** | `bool` | `true` | Whether to enable automatic write-back. Recommended to keep memory continuously updated. | + +### 2.3 Algorithm & Model Configuration +| Parameter | Type | Default | Description | +| :--- | :--- | :--- | :--- | +| `mode` | `str` | `fast` | Retrieval mode: `fast`, `fine`, or `mixture`. | +| `model_name_or_path` | `str` | - | Specifies the LLM model name or path to use. | +| `system_prompt` | `str` | - | Overrides the default system prompt. | +| `temperature` | `float` | - | Sampling temperature, controlling the creativity of generated text. | +| `threshold` | `float` | `0.5` | Relevance threshold for memory recall. Memories scoring below this value are discarded. | + +## 3. How It Works + +MemOS provides two response modes to choose from: + +### 3.1 Full Response (`/complete`) +* **Behavior**: Waits for the model to generate the full output, then returns it as a single JSON response. +* **Use Cases**: Non-interactive tasks, backend logic processing, or simple applications with low real-time requirements. + +### 3.2 Streaming Response (`/stream`) +* **Behavior**: Uses the **Server-Sent Events (SSE)** protocol to push tokens in real time. +* **Use Cases**: Chatbots, intelligent assistants, and other UI interactions that require a typewriter-style streaming effect. + +## 4. Quick Start + +We recommend using the built-in `MemOSClient` from the open-source edition. The following example shows how to ask for R language learning advice while leveraging memory: + +```python +from memos.api.client import MemOSClient + +client = MemOSClient(api_key="...", base_url="...") + +# Initiate a chat request +res = client.chat( + user_id="dev_user_01", + conversation_id="conv_r_study_001", + query="Based on my previous preferences, recommend an R language data cleaning workflow", + knowledgebase_ids=["kb_r_lang"], # Retrieve from the public R language knowledge base + add_message_on_answer=True, # Enable automatic memory write-back + temperature=0.7 +) + +if res: + print(f"AI Response: {res.data}") +``` + + +:::note +**Developer Tip:** +To debug in the `Playground` environment, use the dedicated debug streaming endpoint /product/chat/stream/playground. +::: diff --git a/docs/en/open_source/open_source_api/message/feedback.md b/docs/en/open_source/open_source_api/message/feedback.md new file mode 100644 index 000000000..96d346125 --- /dev/null +++ b/docs/en/open_source/open_source_api/message/feedback.md @@ -0,0 +1,67 @@ +--- +title: Add Feedback +desc: Submit user feedback on LLM responses to help MemOS correct, optimize, or delete inaccurate memories in real time. +--- + + +**API Path**: `POST /product/feedback` +**Description**: This API processes user feedback on AI responses or memory content. By analyzing `feedback_content`, the system can automatically locate and modify incorrect facts stored in **MemCube**, or adjust memory weights based on positive/negative user feedback. + +## 1. Core Mechanism: Memory Correction Loop + +**FeedbackHandler** provides more fine-grained control logic than the standard add API: + +* **Precise Correction**: By providing `retrieved_memory_ids`, the system can directly target specific retrieved results for correction, avoiding collateral changes to other memories. +* **Context Analysis**: Combined with `history` (conversation history), the system understands the real intent behind the feedback (e.g., "You got it wrong, my current company is A, not B"). +* **Result Echo**: When `corrected_answer=true`, the API attempts to return a corrected response based on the newly updated facts after processing the memory correction. + +## 2. Key API Parameters + +| Parameter | Type | Required | Default | Description | +| :--- | :--- | :--- | :--- | :--- | +| **`user_id`** | `str` | Yes | - | Unique user identifier. | +| **`history`** | `list` | Yes | - | Recent conversation history, used to provide context for the feedback. | +| **`feedback_content`** | `str` | Yes | - | **Core:** The user's feedback text content. | +| **`writable_cube_ids`**| `list` | No | - | Target Cube list where memory corrections should be applied. | +| `retrieved_memory_ids` | `list` | No | - | Optional. List of specific memory IDs from the last retrieval that need to be corrected. | +| `async_mode` | `str` | No | `async` | Processing mode: `async` (background processing) or `sync` (real-time processing with wait). | +| `corrected_answer` | `bool` | No | `false` | Whether the system should return a corrected answer after revising the memories. | +| `info` | `dict` | No | - | Additional metadata. | + +## 3. How It Works + +1. **Conflict Detection**: After receiving feedback, `FeedbackHandler` compares `history` against existing memory facts in `writable_cube_ids`. +2. **Locate & Update**: + * If `retrieved_memory_ids` is provided, the corresponding nodes are updated directly. + * If no IDs are provided, the system uses semantic matching to find the most relevant outdated memories and either overwrites or marks them as invalid. +3. **Weight Adjustment**: For ambiguous feedback, the system adjusts the `confidence` or reliability level of specific memory entries. +4. **Async Production**: In `async` mode, the correction logic is executed asynchronously by `MemScheduler`, and the API immediately returns a `task_id`. + +## 4. Quick Start + +```python +from memos.api.client import MemOSClient + +client = MemOSClient(api_key="...", base_url="...") + +# Scenario: Correct the AI's mistaken memory about the user's diet preference +res = client.add_feedback( + user_id="dev_user_01", + conversation_id="conv_diet_001", + feedback_content="I am no longer on a diet and don't need to control my food intake anymore." +) + +if res and res.code == 200: + print(f"Feedback submitted: {res.message}") +``` + + +## 5. Use Cases +### 5.1 Correcting Incorrect AI Inferences +**Human intervention**: Provide a "correct" button in the admin panel. When an admin finds an incorrectly extracted memory entry, call this API to manually correct it. +### 5.2 Updating Outdated User Preferences +**Real-time user correction**: In the chat UI, if the user says something like "you remembered wrong" or "that's not right", automatically trigger this API with `is_feedback=True` to clean up memories in real time. + +::note +If the feedback involves a public knowledge base, make sure the current user has write permission for that Cube. +:: diff --git a/docs/en/open_source/open_source_api/message/get_message.md b/docs/en/open_source/open_source_api/message/get_message.md new file mode 100644 index 000000000..c4993a68f --- /dev/null +++ b/docs/en/open_source/open_source_api/message/get_message.md @@ -0,0 +1,73 @@ +--- +title: Get Messages +desc: Retrieve the raw user-assistant conversation history for a specified session. Used for building chat UIs or extracting original context. +--- + +::warning +**[Click here for the API Reference](/api_docs/message/get_message)** +
+
+ +**This article focuses on functional explanations of the open-source project. For detailed API fields and constraints, please click the link above.** +:: + +**API Path**: `POST /product/get/message` +**Description**: This API retrieves the raw user-assistant conversation records for a specified session. Unlike the "memory" API which returns summary information, this API returns unprocessed raw text — making it the core interface for building chat history review functionality. + +## 1. Memory vs. Message + +When developing, please distinguish between these two data types: +* **Get Memory (`/get_memory`)**: Returns system-processed **fact and preference summaries** (e.g., "The user prefers R language for visualization"). +* **Get Message (`/get_message`)**: Returns the **raw conversation text** (e.g., "I've been learning R recently, recommend a visualization package"). + +## 2. Key API Parameters + +| Parameter | Type | Required | Default | Description | +| :--- | :--- | :--- | :--- | :--- | +| `user_id` | `str` | Yes | - | Unique user identifier associated with the messages to retrieve. | +| `conversation_id` | `str` | No | `None` | Unique identifier for the specified conversation. | +| `message_limit_number` | `int` | No | `6` | Limits the number of returned messages. Recommended maximum is 50. | +| `conversation_limit_number`| `int` | No | `6` | Limits the number of returned conversation histories. | +| `source` | `str` | No | `None` | Identifies the source channel of the messages. | + +## 3. How It Works + +1. **Locate Session**: The system retrieves message records belonging to the user and conversation from the underlying storage based on the provided `conversation_id`. +2. **Slicing**: Based on the `message_limit_number` parameter, the system fetches the specified count in reverse chronological order, ensuring the most recent messages are returned. +3. **Security Isolation**: All requests pass through `RequestContextMiddleware`, which strictly validates `user_id` ownership to prevent unauthorized access. + +## 4. Quick Start + +Use the built-in `MemOSClient` from the open-source edition to quickly pull conversation history: + +```python +from memos.api.client import MemOSClient + +# Initialize the client +client = MemOSClient( + api_key="YOUR_LOCAL_API_KEY", + base_url="http://localhost:8000/product" +) + +# Retrieve the last 10 messages from a specified conversation +res = client.get_message( + user_id="memos_user_123", + conversation_id="conv_r_study_001", + message_limit_number=10 +) + +if res and res.code == 200: + # Iterate over the returned message list + for msg in res.data: + print(f"[{msg['role']}]: {msg['content']}") +``` + +## 5. Use Cases +### 5.1 Chat UI History Loading +When a user clicks into a historical conversation, call this API to restore the chat session. We recommend combining it with `message_limit_number` for paginated loading to improve frontend performance. + +### 5.2 External Model Context Injection +If you are using custom LLM logic (outside of MemOS's built-in chat API), you can retrieve the raw conversation history through this API and manually append it to your model's `messages` array. + +### 5.3 Message Retrospective Analysis +You can periodically export raw conversation records to evaluate AI response quality or analyze users' underlying intentions. diff --git a/docs/en/open_source/open_source_api/message/get_suggestion_queries.md b/docs/en/open_source/open_source_api/message/get_suggestion_queries.md new file mode 100644 index 000000000..2cafab44f --- /dev/null +++ b/docs/en/open_source/open_source_api/message/get_suggestion_queries.md @@ -0,0 +1,68 @@ +--- +title: Get Suggestion Queries +desc: Automatically generate 3 follow-up conversation suggestions based on the current dialogue context or recent memories within a Cube. +--- + +**API Path**: `POST /product/suggestions` +**Description**: This API implements the "Guess What You Want to Ask" feature. Based on the provided conversation context or recent memories in the target **MemCube**, the system uses a large language model to generate 3 relevant suggested questions, helping users continue the conversation. + +## 1. Core Mechanism: Dual-Mode Generation Strategy + +**SuggestionHandler** supports two flexible generation modes depending on the input parameters: + +* **Context-based Instant Suggestions**: + * **Trigger**: `message` (conversation records) is provided in the request. + * **Logic**: The system analyzes the recent conversation content and generates 3 follow-up questions closely related to the current topic. +* **Memory-based Discovery Suggestions**: + * **Trigger**: No `message` is provided. + * **Logic**: The system retrieves "recent memories" from the memory space specified by `mem_cube_id` and generates heuristic questions related to the user's recent life and work activities. + + + +## 2. Key API Parameters + +| Parameter | Type | Required | Default | Description | +| :--- | :--- | :--- | :--- | :--- | +| **`user_id`** | `str` | Yes | - | Unique user identifier. | +| **`mem_cube_id`** | `str` | Yes | - | **Core parameter:** Specifies the memory space on which to base the suggestion generation. | +| **`language`** | `str` | No | `zh` | Language for generated suggestions: `zh` (Chinese) or `en` (English). | +| `message` | `list/str`| No | - | Current conversation context. If provided, context-based suggestions are generated. | + +## 3. How It Works (SuggestionHandler) + +1. **Context Detection**: `SuggestionHandler` first checks the `message` field. If present, it extracts the conversation essence; if empty, it falls back to the underlying `MemCube` for recent activity. +2. **Template Matching**: The system automatically switches between built-in Chinese and English prompt templates based on the `language` parameter. +3. **Model Inference**: The LLM is called to reason over the background material, ensuring the 3 generated questions are both logical and thought-provoking. +4. **Formatted Output**: Suggested questions are returned as an array for easy frontend rendering as clickable buttons. + +## 4. Quick Start + +Use an HTTP request to get Chinese-language suggestions for the current conversation: + +```python +import requests + +# Scenario: Generate suggestions based on a recent conversation about "R language" +res = requests.post( + "http://localhost:8000/product/suggestions", + json={ + "user_id": "dev_user_01", + "mem_cube_id": "private_cube_01", + "language": "zh", + "message": [ + {"role": "user", "content": "I want to learn R language visualization."}, + {"role": "assistant", "content": "I recommend learning the ggplot2 package — it's the core tool for R language visualization."} + ] + } +) + +if res.status_code == 200: + data = res.json() + # Example output: ["How do I install ggplot2?", "What are some classic ggplot2 tutorials?", "What other visualization packages does R have?"] + print(f"Suggested questions: {data['data']}") +``` + +## 5. Suggested Use Cases +**Conversation Guidance**: After the AI finishes replying to the user, automatically call this API to display suggestion buttons below the reply, guiding the user to explore the topic further. + +**Cold Start Activation**: When a user enters a new session and has not yet spoken, use the "memory-based mode" to surface past topics the user may be interested in, breaking the silence.