Merge remote-tracking branch 'upstream/dev' into dev

Author: tangg555

README.md

@@ -3,8 +3,6 @@
 MemOS is an open-source **Agent Memory framework** that empowers AI agents with **long-term memory, personality consistency, and contextual recall**. It enables agents to **remember past interactions**, **learn over time**, and **build evolving identities** across sessions.
 
 Designed for **AI companions, role-playing NPCs, and multi-agent systems**, MemOS provides a unified API for **memory representation, retrieval, and update** — making it the foundation for next-generation **memory-augmented AI agents**.
-
-🆕 **MemOS 2.0** introduces **knowledge base system**, **multi-modal memory** (images & documents), **tool memory** for Agent optimization, **memory feedback mechanism** for precise control, and **enterprise-grade architecture** with Redis Streams scheduler and advanced DB optimizations.
 <div align="center">
   <a href="https://memos.openmem.net/">
     <img src="https://statics.memtensor.com.cn/memos/memos-banner.gif" alt="MemOS Banner">
@@ -117,98 +115,8 @@ showcasing its capabilities in **information extraction**, **temporal and cross-
     - **Textual Memory**: For storing and retrieving unstructured or structured text knowledge.
     - **Activation Memory**: Caches key-value pairs (`KVCacheMemory`) to accelerate LLM inference and context reuse.
     - **Parametric Memory**: Stores model adaptation parameters (e.g., LoRA weights).
-    - **Tool Memory** 🆕: Records Agent tool call trajectories and experiences to improve planning capabilities.
-- **📚 Knowledge Base System** 🆕: Build multi-dimensional knowledge bases with automatic document/URL parsing, splitting, and cross-project sharing capabilities.
-- **🔧 Memory Controllability** 🆕:
-    - **Feedback Mechanism**: Use `add_feedback` API to correct, supplement, or replace existing memories with natural language.
-    - **Precise Deletion**: Delete specific memories by User ID or Memory ID via API or MCP tools.
-- **👁️ Multi-Modal Support** 🆕: Support for image understanding and memory, including chart parsing in documents.
-- **⚡ Advanced Architecture**:
-    - **DB Optimization**: Enhanced connection management and batch insertion for high-concurrency scenarios.
-    - **Advanced Retrieval**: Custom tag and info field filtering with complex logical operations.
-    - **Redis Streams Scheduler**: Multi-level queue architecture with intelligent orchestration for fair multi-tenant scheduling.
-    - **Stream & Non-Stream Chat**: Ready-to-use streaming and non-streaming chat interfaces.
 - **🔌 Extensible**: Easily extend and customize memory modules, data sources, and LLM integrations.
-- **🏂 Lightweight Deployment** 🆕: Support for quick mode and complete mode deployment options.
-
-## 🚀 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
-```
-
-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
-```
-
-### Local SDK
-Here's a quick example of how to create a **`MemCube`**, load it from a directory, access its memories, and save it.
-
-```python
-from memos.mem_cube.general import GeneralMemCube
-
-# Initialize a MemCube from a local directory
-mem_cube = GeneralMemCube.init_from_dir("examples/data/mem_cube_2")
-
-# Access and print all memories
-print("--- Textual Memories ---")
-for item in mem_cube.text_mem.get_all():
-    print(item)
-
-print("\n--- Activation Memories ---")
-for item in mem_cube.act_mem.get_all():
-    print(item)
-
-# Save the MemCube to a new directory
-mem_cube.dump("tmp/mem_cube")
-```
-
-**`MOS`** (Memory Operating System) is a higher-level orchestration layer that manages multiple MemCubes and provides a unified API for memory operations. Here's a quick example of how to use MOS:
-
-```python
-from memos.configs.mem_os import MOSConfig
-from memos.mem_os.main import MOS
-
-
-# init MOS
-mos_config = MOSConfig.from_json_file("examples/data/config/simple_memos_config.json")
-memory = MOS(mos_config)
-
-# create user
-user_id = "b41a34d5-5cae-4b46-8c49-d03794d206f5"
-memory.create_user(user_id=user_id)
-
-# register cube for user
-memory.register_mem_cube("examples/data/mem_cube_2", user_id=user_id)
-
-# add memory for user
-memory.add(
-    messages=[
-        {"role": "user", "content": "I like playing football."},
-        {"role": "assistant", "content": "I like playing football too."},
-    ],
-    user_id=user_id,
-)
-
-# Later, when you want to retrieve memory for user
-retrieved_memories = memory.search(query="What do you like?", user_id=user_id)
-# output text_memories: I like playing football, act_memories, para_memories
-print(f"text_memories: {retrieved_memories['text_mem']}")
-```
-
-For more detailed examples, please check out the [`examples`](./examples) directory.
 
 ## 📦 Installation
 
@@ -259,6 +167,127 @@ To download example code, data and configurations, run the following command:
 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
+```
+
+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
+```
+
+### Interface SDK
+#### Here is a quick example showing how to create all interface SDK
+
+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.
+```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")
+
+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."},
+  {"role": "user", "content": "I'll choose 7 Days"},
+  {"role": "assistant", "content": "Okay, ask me if you have any other questions."}
+]
+user_id = "memos_user_123"
+conversation_id = "0610"
+res = client.add_message(messages=messages, user_id=user_id, conversation_id=conversation_id)
+
+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'.
+```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"
+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."
+
+res = client.create_knowledgebase(
+    knowledgebase_name=knowledgebase_name,
+    knowledgebase_description=knowledgebase_description
+)
+print(f"result: {res}")
+```
+
 ## 💬 Community & Support
 
 Join our community to ask questions, share your projects, and connect with other developers.

docker/.env.example

@@ -20,7 +20,7 @@ MOS_TOP_K=50
 ## Chat LLM (main dialogue)
 MOS_CHAT_MODEL=gpt-4o-mini
 MOS_CHAT_TEMPERATURE=0.8
-MOS_MAX_TOKENS=8000
+MOS_MAX_TOKENS=2048
 MOS_TOP_P=0.9
 MOS_CHAT_MODEL_PROVIDER=openai             # openai | huggingface | vllm
 MOS_MODEL_SCHEMA=memos.configs.llm.VLLMLLMConfig  # vllm only: config class path; keep default unless you extend it
@@ -51,9 +51,18 @@ MOS_RERANKER_HEADERS_EXTRA=               # extra headers, JSON string, e.g. {"A
 MOS_RERANKER_STRATEGY=single_turn
 MOS_RERANK_SOURCE=                        # optional rerank scope, e.g., history/stream/custom
 
+
+# External Services (for evaluation scripts)
+ZEP_API_KEY=your_zep_api_key_here
+MEM0_API_KEY=your_mem0_api_key_here
+MODEL=gpt-4o-mini
+EMBEDDING_MODEL=nomic-embed-text:latest
+
 ## Internet search & preference memory
 ENABLE_INTERNET=false
 BOCHA_API_KEY=                             # required if ENABLE_INTERNET=true
+XINYU_API_KEY=
+XINYU_SEARCH_ENGINE_ID=
 SEARCH_MODE=fast                          # fast | fine | mixture
 FAST_GRAPH=false
 BM25_CALL=false
@@ -90,7 +99,9 @@ NEO4J_URI=bolt://localhost:7687           # required when backend=neo4j*
 NEO4J_USER=neo4j                          # required when backend=neo4j*
 NEO4J_PASSWORD=12345678                   # required when backend=neo4j*
 NEO4J_DB_NAME=neo4j                       # required for shared-db mode
-MOS_NEO4J_SHARED_DB=false
+MOS_NEO4J_SHARED_DB=true                  # if true, all users share one DB; if false, each user gets their own DB
+NEO4J_AUTO_CREATE=false                   # [IMPORTANT] set to false for Neo4j Community Edition
+NEO4J_USE_MULTI_DB=false                  # alternative to MOS_NEO4J_SHARED_DB (logic is inverse)
 QDRANT_HOST=localhost
 QDRANT_PORT=6333
 # For Qdrant Cloud / remote endpoint (takes priority if set):
@@ -121,6 +132,7 @@ POLAR_DB_USER=root
 POLAR_DB_PASSWORD=123456
 POLAR_DB_DB_NAME=shared_memos_db
 POLAR_DB_USE_MULTI_DB=false
+POLARDB_POOL_MAX_CONN=100
 
 ## Redis (scheduler queue) — fill only if you want scheduler queues in Redis; otherwise in-memory queue is used
 REDIS_HOST=localhost                      # global Redis endpoint (preferred over MEMSCHEDULER_*)
@@ -170,3 +182,11 @@ OSS_PUBLIC_BASE_URL=
 ## SDK / external client
 MEMOS_API_KEY=
 MEMOS_BASE_URL=https://memos.memtensor.cn/api/openmem/v1
+
+CHAT_MODEL_LIST='[{
+  "backend": "deepseek",
+  "api_base": "http://localhost:1234",
+  "api_key": "your-api-key",
+  "model_name_or_path": "deepseek-r1",
+  "support_models": ["deepseek-r1"]
+}]'

docker/Dockerfile

@@ -32,4 +32,4 @@ ENV PYTHONPATH=/app/src
 EXPOSE 8000
 
 # Start the docker
-CMD ["uvicorn", "memos.api.product_api:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
+CMD ["uvicorn", "memos.api.server_api:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]