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.