Main zhq readme (#794)

fridayL · web-flow · commit d42ec55affc9 · 2025-12-26T20:20:45.000+08:00
## Description  Summary: (summary) Fix: #(issue) Docs Issue/PR: (docs-issue-or-pr-link) Reviewer: @(reviewer) ## Checklist: - [ ] I have performed a self-review of my own code | 我已自行检查了自己的代码 - [ ] I have commented my code in hard-to-understand areas | 我已在难以理解的地方对代码进行了注释 - [ ] I have added tests that prove my fix is effective or that my feature works | 我已添加测试以证明我的修复有效或功能正常 - [ ] I have created related documentation issue/PR in [MemOS-Docs](https://github.com/MemTensor/MemOS-Docs) (if applicable) | 我已在 [MemOS-Docs](https://github.com/MemTensor/MemOS-Docs) 中创建了相关的文档 issue/PR（如果适用） - [ ] I have linked the issue to this PR (if applicable) | 我已将 issue 链接到此 PR（如果适用） - [ ] I have mentioned the person who will review this PR | 我已提及将审查此 PR 的人
diff --git a/README.md b/README.md
@@ -131,88 +131,32 @@ showcasing its capabilities in **information extraction**, **temporal and cross-
 - **🔌 Extensible**: Easily extend and customize memory modules, data sources, and LLM integrations.
 - **🏂 Lightweight Deployment** 🆕: Support for quick mode and complete mode deployment options.
 
-## 📦 Installation
 
-### Install via pip
-
-```bash
-pip install MemoryOS
-```
-
-### Optional Dependencies
-
-MemOS provides several optional dependency groups for different features. You can install them based on your needs.
-
-| Feature               | Package Name              |
-| --------------------- | ------------------------- |
-| Tree Memory           | `MemoryOS[tree-mem]`      |
-| Memory Reader         | `MemoryOS[mem-reader]`    |
-| Memory Scheduler      | `MemoryOS[mem-scheduler]` |
-
-Example installation commands:
-
-```bash
-pip install MemoryOS[tree-mem]
-pip install MemoryOS[tree-mem,mem-reader]
-pip install MemoryOS[mem-scheduler]
-pip install MemoryOS[tree-mem,mem-reader,mem-scheduler]
-```
-
-### External Dependencies
-
-#### Ollama Support
-
-To use MemOS with [Ollama](https://ollama.com/), first install the Ollama CLI:
-
-```bash
-curl -fsSL https://ollama.com/install.sh | sh
-```
-
-#### Transformers Support
-
-To use functionalities based on the `transformers` library, ensure you have [PyTorch](https://pytorch.org/get-started/locally/) installed (CUDA version recommended for GPU acceleration).
-
-#### Download Examples
+## 🚀 Quickstart Guide
 
-To download example code, data and configurations, run the following command:
+### Get API Key
+  - Sign up and get started on[`MemOS dashboard`](https://memos-dashboard.openmem.net/cn/quickstart/?source=landing)
+  - Open the API Keys Console in the MemOS dashboard and copy the API Key into the initialization code
 
-```bash
-memos download_examples
-```
-
-## 🚀 Getting Started
-
-### ⭐️ MemOS online API
-The easiest way to use MemOS. Equip your agent with memory **in minutes**!
-
-Sign up and get started on[`MemOS dashboard`](https://memos-dashboard.openmem.net/cn/quickstart/?source=landing).
-
-
-### Self-Hosted Server
-1. Get the repository.
-```bash
-git clone https://github.com/MemTensor/MemOS.git
-cd MemOS
-pip install -r ./docker/requirements.txt
-```
+### Install via pip
 
-2. Configure `docker/.env.example` and copy to `MemOS/.env`
-3. Start the service.
 ```bash
-uvicorn memos.api.server_api:app --host 0.0.0.0 --port 8001 --workers 8
+pip install MemoryOS -U
 ```
 
-### Interface SDK
-#### Here is a quick example showing how to create interface SDK
+### Basic Usage
 
-This interface is used to add messages, supporting multiple types of content and batch additions. MemOS will automatically parse the messages and handle memory for reference in subsequent conversations.
+- Initialize MemOS client with API Key to start sending requests
 ```python
 # Please make sure MemoS is installed (pip install MemoryOS -U)
 from memos.api.client import MemOSClient
 
 # Initialize the client using the API Key
 client = MemOSClient(api_key="YOUR_API_KEY")
+```
 
+- This API allows you to add one or more messages to a specific conversation. As illustrated in the examples bellow, you can add messages in real time during a user-assistant interaction, import historical messages in bulk, or enrich the conversation with user preferences and behavior data. All added messages are transformed into memories by MemOS, enabling their retrieval in future conversations to support chat history management, user behavior tracking, and personalized interactions.
+```python
 messages = [
   {"role": "user", "content": "I have planned to travel to Guangzhou during the summer vacation. What chain hotels are available for accommodation?"},
   {"role": "assistant", "content": "You can consider [7 Days, All Seasons, Hilton], and so on."},
@@ -226,79 +170,89 @@ res = client.add_message(messages=messages, user_id=user_id, conversation_id=con
 print(f"result: {res}")
 ```
 
-This interface is used to retrieve the memories of a specified user, returning the memory fragments most relevant to the input query for Agent use. The recalled memory fragments include 'factual memory', 'preference memory', and 'tool memory'.
+- This API allows you to query a user’s memory and returns the fragments most relevant to the input. These can serve as references for the model when generating responses. As shown in the examples bellow, You can retrieve memory in real time during a user’s conversation with the AI, or perform a global search across their entire memory to create user profiles or support personalized recommendations, improving both dialogue coherence and personalization.
+In the latest update, in addition to “Fact Memory”, the system now supports “Preference Memory”, enabling LLM to respond in a way that better understands the user.
 ```python
-# Please make sure MemoS is installed (pip install MemoryOS -U)
-from memos.api.client import MemOSClient
-
-# Initialize the client using the API Key
-client = MemOSClient(api_key="YOUR_API_KEY")
-
 query = "I want to go out to play during National Day. Can you recommend a city I haven't been to and a hotel brand I haven't stayed at?"
 user_id = "memos_user_123"
-conversation_id = "0928"
+conversation_id = "0610"
 res = client.search_memory(query=query, user_id=user_id, conversation_id=conversation_id)
 
 print(f"result: {res}")
 ```
 
-This interface is used to delete the memory of specified users and supports batch deletion.
-```python
-# Please make sure MemoS is installed (pip install MemoryOS -U)
-from memos.api.client import MemOSClient
-
-# Initialize the client using the API Key
-client = MemOSClient(api_key="YOUR_API_KEY")
-
-user_ids = ["memos_user_123"]
-# Replace with the memory ID
-memory_ids = ["6b23b583-f4c4-4a8f-b345-58d0c48fea04"]
-res = client.delete_memory(user_ids=user_ids, memory_ids=memory_ids)
-
-print(f"result: {res}")
-```
-
-This interface is used to add feedback to messages in the current session, allowing MemOS to correct its memory based on user feedback.
-```python
-# Please make sure MemoS is installed (pip install MemoryOS -U)
-from memos.api.client import MemOSClient
-
-# Initialize the client using the API Key
-client = MemOSClient(api_key="YOUR_API_KEY")
-
-user_id = "memos_user_123"
-conversation_id = "memos_feedback_conv"
-feedback_content = "No, let's change it now to a meal allowance of 150 yuan per day and a lodging subsidy of 700 yuan per day for first-tier cities; for second- and third-tier cities, it remains the same as before."
-# Replace with the knowledgebase ID
-allow_knowledgebase_ids = ["basee5ec9050-c964-484f-abf1-ce3e8e2aa5b7"]
-
-res = client.add_feedback(
-    user_id=user_id,
-    conversation_id=conversation_id,
-    feedback_content=feedback_content,
-    allow_knowledgebase_ids=allow_knowledgebase_ids
-)
-
-print(f"result: {res}")
-```
-
-This interface is used to create a knowledgebase associated with a project
-```python
-# Please make sure MemoS is installed (pip install MemoryOS -U)
-from memos.api.client import MemOSClient
-
-# Initialize the client using the API Key
-client = MemOSClient(api_key="YOUR_API_KEY")
-
-knowledgebase_name = "Financial Reimbursement Knowledge Base"
-knowledgebase_description = "A compilation of all knowledge related to the company's financial reimbursements."
+### Self-Hosted Server
+1. Get the repository.
+    ```bash
+    git clone https://github.com/MemTensor/MemOS.git
+    cd MemOS
+    pip install -r ./docker/requirements.txt
+    ```
+2. Configure `docker/.env.example` and copy to `MemOS/.env`
+ - The `OPENAI_API_KEY`,`MOS_EMBEDDER_API_KEY`,`MEMRADER_API_KEY` and others can be applied for through [`BaiLian`](https://bailian.console.aliyun.com/?spm=a2c4g.11186623.0.0.2f2165b08fRk4l&tab=api#/api).
+ - Fill in the corresponding configuration in the `MemOS/.env` file.
+3. Start the service.
 
-res = client.create_knowledgebase(
-    knowledgebase_name=knowledgebase_name,
-    knowledgebase_description=knowledgebase_description
-)
-print(f"result: {res}")
-```
+- Launch via Docker
+  ###### Tips: Please ensure that Docker Compose is installed successfully and that you have navigated to the docker directory (via `cd docker`) before executing the following command.
+  ```bash
+  # Enter docker directory
+  docker compose up
+  ```
+  ##### If you prefer to deploy using Docker, please refer to the [`Docker Reference`](https://docs.openmem.net/open_source/getting_started/rest_api_server/#method-1-docker-use-repository-dependency-package-imagestart-recommended-use).
+
+- Launch via the uvicorn command line interface (CLI)
+  ###### Tips: Please ensure that Neo4j and Qdrant are running before executing the following command.
+  ```bash
+  uvicorn memos.api.server_api:app --host 0.0.0.0 --port 8001 --workers 1
+  ```
+  ##### For detailed integration steps, see the [`CLI Reference`](https://docs.openmem.net/open_source/getting_started/rest_api_server/#method-3client-install-with-CLI).
+
+
+
+Example
+  - Add User Message
+    ```python
+    import requests
+    import json
+    
+    data = {
+        "user_id": "8736b16e-1d20-4163-980b-a5063c3facdc",
+        "mem_cube_id": "b32d0977-435d-4828-a86f-4f47f8b55bca",
+        "messages": [
+            {
+                "role": "user",
+                "content": "I like strawberry"
+            }
+        ],
+        "async_mode": "sync"
+    }
+    headers = {
+        "Content-Type": "application/json"
+    }
+    url = "http://localhost:8000/product/add"
+    
+    res = requests.post(url=url, headers=headers, data=json.dumps(data))
+    print(f"result: {res.json()}")
+    ```
+  - Search User Memory
+    ```python
+    import requests
+    import json
+    
+    data = {
+        "query": "What do I like",
+        "user_id": "8736b16e-1d20-4163-980b-a5063c3facdc",
+        "mem_cube_id": "b32d0977-435d-4828-a86f-4f47f8b55bca"
+    }
+    headers = {
+        "Content-Type": "application/json"
+    }
+    url = "http://localhost:8000/product/search"
+    
+    res = requests.post(url=url, headers=headers, data=json.dumps(data))
+    print(f"result: {res.json()}")
+    ```
 
 ## 💬 Community & Support
 
diff --git a/src/memos/api/config.py b/src/memos/api/config.py
@@ -201,7 +201,7 @@ def init(cls) -> None:
         sk = os.getenv("SK")
 
         if not (server_addr and data_id and ak and sk):
-            logger.warning("❌ missing NACOS_SERVER_ADDR / AK / SK / DATA_ID")
+            logger.warning("missing NACOS_SERVER_ADDR / AK / SK / DATA_ID")
             return
 
         base_url = f"http://{server_addr}/nacos/v1/cs/configs"
