Skip to content

Commit 6d764f9

Browse files
hiaskyhiasky
authored
Feat/chat api en docs (#1742)
* docs: add English translation for Chat API reference * docs: add English translations for Message API reference
1 parent 537b3a5 commit 6d764f9

4 files changed

Lines changed: 305 additions & 0 deletions

File tree

‎docs/en/open_source/open_source_api/chat/chat.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: Chat
3+
desc: An integrated RAG closed-loop API covering retrieval, generation, and storage. Supports MemCube-based personalized responses and automatic memory persistence.
4+
---
5+
6+
:::note
7+
For a complete list of API fields, formats, and other details, see the [Chat API Reference](/api_docs/chat/chat).
8+
:::
9+
10+
**API Paths**:
11+
* **Full Response**: `POST /product/chat/complete`
12+
* **Streaming Response (SSE)**: `POST /product/chat/stream`
13+
14+
**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.
15+
16+
17+
## 1. Core Architecture: ChatHandler Orchestration Flow
18+
19+
1. **Memory Retrieval**: Calls **SearchHandler** against `readable_cube_ids` to extract relevant facts, preferences, and tool context from isolated Cubes.
20+
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.
21+
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.
22+
23+
## 2. Key API Parameters
24+
25+
### 2.1 Identity & Context
26+
| Parameter | Type | Required | Description |
27+
| :--- | :--- | :--- | :--- |
28+
| **`query`** | `str` | Yes | The user's current question or input. |
29+
| **`user_id`** | `str` | Yes | Unique user identifier, used for authentication and data isolation. |
30+
| `history` | `list` | No | Short-term conversation history to maintain coherence within the current session. |
31+
| `session_id` | `str` | No | Session ID. Acts as a "soft signal" to boost recall weight of related memories within this session. |
32+
33+
### 2.2 MemCube Read/Write Control
34+
| Parameter | Type | Default | Description |
35+
| :--- | :--- | :--- | :--- |
36+
| **`readable_cube_ids`** | `list` | - | **Read:** List of memory Cubes allowed for retrieval (can span personal and public libraries). |
37+
| **`writable_cube_ids`** | `list` | - | **Write:** Target Cube list where auto-generated memories should be stored after the conversation. |
38+
| **`add_message_on_answer`** | `bool` | `true` | Whether to enable automatic write-back. Recommended to keep memory continuously updated. |
39+
40+
### 2.3 Algorithm & Model Configuration
41+
| Parameter | Type | Default | Description |
42+
| :--- | :--- | :--- | :--- |
43+
| `mode` | `str` | `fast` | Retrieval mode: `fast`, `fine`, or `mixture`. |
44+
| `model_name_or_path` | `str` | - | Specifies the LLM model name or path to use. |
45+
| `system_prompt` | `str` | - | Overrides the default system prompt. |
46+
| `temperature` | `float` | - | Sampling temperature, controlling the creativity of generated text. |
47+
| `threshold` | `float` | `0.5` | Relevance threshold for memory recall. Memories scoring below this value are discarded. |
48+
49+
## 3. How It Works
50+
51+
MemOS provides two response modes to choose from:
52+
53+
### 3.1 Full Response (`/complete`)
54+
* **Behavior**: Waits for the model to generate the full output, then returns it as a single JSON response.
55+
* **Use Cases**: Non-interactive tasks, backend logic processing, or simple applications with low real-time requirements.
56+
57+
### 3.2 Streaming Response (`/stream`)
58+
* **Behavior**: Uses the **Server-Sent Events (SSE)** protocol to push tokens in real time.
59+
* **Use Cases**: Chatbots, intelligent assistants, and other UI interactions that require a typewriter-style streaming effect.
60+
61+
## 4. Quick Start
62+
63+
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:
64+
65+
```python
66+
from memos.api.client import MemOSClient
67+
68+
client = MemOSClient(api_key="...", base_url="...")
69+
70+
# Initiate a chat request
71+
res = client.chat(
72+
user_id="dev_user_01",
73+
query="Based on my previous preferences, recommend an R language data cleaning workflow",
74+
readable_cube_ids=["private_cube_01", "public_kb_r_lang"], # Read: personal preferences + public knowledge base
75+
writable_cube_ids=["private_cube_01"], # Write: persist to personal space
76+
add_message_on_answer=True, # Enable automatic memory write-back
77+
mode="fine" # Use fine-grained retrieval mode
78+
)
79+
80+
if res:
81+
print(f"AI Response: {res.data}")
82+
```
83+
84+
85+
:::note
86+
**Developer Tip:**
87+
To debug in the `Playground` environment, use the dedicated debug streaming endpoint /product/chat/stream/playground.
88+
:::

‎docs/en/open_source/open_source_api/message/feedback.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: Add Feedback
3+
desc: Submit user feedback on LLM responses to help MemOS correct, optimize, or delete inaccurate memories in real time.
4+
---
5+
6+
7+
**API Path**: `POST /product/feedback`
8+
**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.
9+
10+
## 1. Core Mechanism: Memory Correction Loop
11+
12+
**FeedbackHandler** provides more fine-grained control logic than the standard add API:
13+
14+
* **Precise Correction**: By providing `retrieved_memory_ids`, the system can directly target specific retrieved results for correction, avoiding collateral changes to other memories.
15+
* **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").
16+
* **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.
17+
18+
## 2. Key API Parameters
19+
20+
| Parameter | Type | Required | Default | Description |
21+
| :--- | :--- | :--- | :--- | :--- |
22+
| **`user_id`** | `str` | Yes | - | Unique user identifier. |
23+
| **`history`** | `list` | Yes | - | Recent conversation history, used to provide context for the feedback. |
24+
| **`feedback_content`** | `str` | Yes | - | **Core:** The user's feedback text content. |
25+
| **`writable_cube_ids`**| `list` | No | - | Target Cube list where memory corrections should be applied. |
26+
| `retrieved_memory_ids` | `list` | No | - | Optional. List of specific memory IDs from the last retrieval that need to be corrected. |
27+
| `async_mode` | `str` | No | `async` | Processing mode: `async` (background processing) or `sync` (real-time processing with wait). |
28+
| `corrected_answer` | `bool` | No | `false` | Whether the system should return a corrected answer after revising the memories. |
29+
| `info` | `dict` | No | - | Additional metadata. |
30+
31+
## 3. How It Works
32+
33+
1. **Conflict Detection**: After receiving feedback, `FeedbackHandler` compares `history` against existing memory facts in `writable_cube_ids`.
34+
2. **Locate & Update**:
35+
* If `retrieved_memory_ids` is provided, the corresponding nodes are updated directly.
36+
* 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.
37+
3. **Weight Adjustment**: For ambiguous feedback, the system adjusts the `confidence` or reliability level of specific memory entries.
38+
4. **Async Production**: In `async` mode, the correction logic is executed asynchronously by `MemScheduler`, and the API immediately returns a `task_id`.
39+
40+
## 4. Quick Start
41+
42+
```python
43+
from memos.api.client import MemOSClient
44+
45+
client = MemOSClient(api_key="...", base_url="...")
46+
47+
# Scenario: Correct the AI's mistaken memory about the user's occupation
48+
res = client.add_feedback(
49+
user_id="dev_user_01",
50+
feedback_content="I am no longer on a diet and don't need to control my food intake anymore.",
51+
history=[
52+
{"role": "assistant", "content": "You're on a diet — have you been controlling your calorie intake recently?"},
53+
{"role": "user", "content": "I'm not on a diet anymore..."}
54+
],
55+
writable_cube_ids=["private_cube_01"],
56+
# Specify the exact mistaken memory ID for precise correction
57+
retrieved_memory_ids=["mem_id_old_job_123"],
58+
corrected_answer=True # Ask the AI to respond again based on the updated facts
59+
)
60+
61+
if res and res.code == 200:
62+
print(f"Correction progress: {res.message}")
63+
if res.data:
64+
print(f"Corrected response: {res.data}")
65+
```
66+
67+
68+
## 5. Use Cases
69+
### 5.1 Correcting Incorrect AI Inferences
70+
**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.
71+
### 5.2 Updating Outdated User Preferences
72+
**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.
73+
74+
::note
75+
If the feedback involves a public knowledge base, make sure the current user has write permission for that Cube.
76+
::

‎docs/en/open_source/open_source_api/message/get_message.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: Get Messages
3+
desc: Retrieve the raw user-assistant conversation history for a specified session. Used for building chat UIs or extracting original context.
4+
---
5+
6+
::warning
7+
**[Click here for the API Reference](/api_docs/message/get_message)**
8+
<br>
9+
<br>
10+
11+
**This article focuses on functional explanations of the open-source project. For detailed API fields and constraints, please click the link above.**
12+
::
13+
14+
**API Path**: `POST /product/get/message`
15+
**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.
16+
17+
## 1. Memory vs. Message
18+
19+
When developing, please distinguish between these two data types:
20+
* **Get Memory (`/get_memory`)**: Returns system-processed **fact and preference summaries** (e.g., "The user prefers R language for visualization").
21+
* **Get Message (`/get_message`)**: Returns the **raw conversation text** (e.g., "I've been learning R recently, recommend a visualization package").
22+
23+
## 2. Key API Parameters
24+
25+
| Parameter | Type | Required | Default | Description |
26+
| :--- | :--- | :--- | :--- | :--- |
27+
| `user_id` | `str` | Yes | - | Unique user identifier associated with the messages to retrieve. |
28+
| `conversation_id` | `str` | No | `None` | Unique identifier for the specified conversation. |
29+
| `message_limit_number` | `int` | No | `6` | Limits the number of returned messages. Recommended maximum is 50. |
30+
| `conversation_limit_number`| `int` | No | `6` | Limits the number of returned conversation histories. |
31+
| `source` | `str` | No | `None` | Identifies the source channel of the messages. |
32+
33+
## 3. How It Works
34+
35+
1. **Locate Session**: The system retrieves message records belonging to the user and conversation from the underlying storage based on the provided `conversation_id`.
36+
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.
37+
3. **Security Isolation**: All requests pass through `RequestContextMiddleware`, which strictly validates `user_id` ownership to prevent unauthorized access.
38+
39+
## 4. Quick Start
40+
41+
Use the built-in `MemOSClient` from the open-source edition to quickly pull conversation history:
42+
43+
```python
44+
from memos.api.client import MemOSClient
45+
46+
# Initialize the client
47+
client = MemOSClient(
48+
api_key="YOUR_LOCAL_API_KEY",
49+
base_url="http://localhost:8000/product"
50+
)
51+
52+
# Retrieve the last 10 messages from a specified conversation
53+
res = client.get_message(
54+
user_id="memos_user_123",
55+
conversation_id="conv_r_study_001",
56+
message_limit_number=10
57+
)
58+
59+
if res and res.code == 200:
60+
# Iterate over the returned message list
61+
for msg in res.data:
62+
print(f"[{msg['role']}]: {msg['content']}")
63+
```
64+
65+
## 5. Use Cases
66+
### 5.1 Chat UI History Loading
67+
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.
68+
69+
### 5.2 External Model Context Injection
70+
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.
71+
72+
### 5.3 Message Retrospective Analysis
73+
You can periodically export raw conversation records to evaluate AI response quality or analyze users' underlying intentions.

‎docs/en/open_source/open_source_api/message/get_suggestion_queries.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: Get Suggestion Queries
3+
desc: Automatically generate 3 follow-up conversation suggestions based on the current dialogue context or recent memories within a Cube.
4+
---
5+
6+
# Get Suggestion Queries
7+
8+
**API Path**: `POST /product/suggestions`
9+
**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.
10+
11+
## 1. Core Mechanism: Dual-Mode Generation Strategy
12+
13+
**SuggestionHandler** supports two flexible generation modes depending on the input parameters:
14+
15+
* **Context-based Instant Suggestions**:
16+
* **Trigger**: `message` (conversation records) is provided in the request.
17+
* **Logic**: The system analyzes the recent conversation content and generates 3 follow-up questions closely related to the current topic.
18+
* **Memory-based Discovery Suggestions**:
19+
* **Trigger**: No `message` is provided.
20+
* **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.
21+
22+
23+
24+
## 2. Key API Parameters
25+
26+
| Parameter | Type | Required | Default | Description |
27+
| :--- | :--- | :--- | :--- | :--- |
28+
| **`user_id`** | `str` | Yes | - | Unique user identifier. |
29+
| **`mem_cube_id`** | `str` | Yes | - | **Core parameter:** Specifies the memory space on which to base the suggestion generation. |
30+
| **`language`** | `str` | No | `zh` | Language for generated suggestions: `zh` (Chinese) or `en` (English). |
31+
| `message` | `list/str`| No | - | Current conversation context. If provided, context-based suggestions are generated. |
32+
33+
## 3. How It Works (SuggestionHandler)
34+
35+
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.
36+
2. **Template Matching**: The system automatically switches between built-in Chinese and English prompt templates based on the `language` parameter.
37+
3. **Model Inference**: The LLM is called to reason over the background material, ensuring the 3 generated questions are both logical and thought-provoking.
38+
4. **Formatted Output**: Suggested questions are returned as an array for easy frontend rendering as clickable buttons.
39+
40+
## 4. Quick Start
41+
42+
Use the SDK to get Chinese-language suggestions for the current conversation:
43+
44+
```python
45+
from memos.api.client import MemOSClient
46+
47+
client = MemOSClient(api_key="...", base_url="...")
48+
49+
# Scenario: Generate suggestions based on a recent conversation about "R language"
50+
res = client.get_suggestions(
51+
user_id="dev_user_01",
52+
mem_cube_id="private_cube_01",
53+
language="zh",
54+
message=[
55+
{"role": "user", "content": "I want to learn R language visualization."},
56+
{"role": "assistant", "content": "I recommend learning the ggplot2 package — it's the core tool for R language visualization."}
57+
]
58+
)
59+
60+
if res and res.code == 200:
61+
# Example output: ["How do I install ggplot2?", "What are some classic ggplot2 tutorials?", "What other visualization packages does R have?"]
62+
print(f"Suggested questions: {res.data}")
63+
```
64+
65+
## 5. Suggested Use Cases
66+
**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.
67+
68+
**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.

0 commit comments

Comments
 (0)