From 14f59d616373042d662dd809332a865c702e1712 Mon Sep 17 00:00:00 2001 From: Elvis <1693372324@qq.com> Date: Wed, 24 Dec 2025 21:05:40 +0800 Subject: [PATCH 1/2] fix: update README.md --- README.md | 129 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 78 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 634b38dec..2f5422095 100644 --- a/README.md +++ b/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.
MemOS Banner @@ -117,19 +115,7 @@ 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 @@ -153,62 +139,103 @@ pip install -r ./docker/requirements.txt 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. +### 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 -from memos.mem_cube.general import GeneralMemCube +# 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}") +``` -# Initialize a MemCube from a local directory -mem_cube = GeneralMemCube.init_from_dir("examples/data/mem_cube_2") +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 -# Access and print all memories -print("--- Textual Memories ---") -for item in mem_cube.text_mem.get_all(): - print(item) +# Initialize the client using the API Key +client = MemOSClient(api_key="YOUR_API_KEY") -print("\n--- Activation Memories ---") -for item in mem_cube.act_mem.get_all(): - print(item) +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) -# Save the MemCube to a new directory -mem_cube.dump("tmp/mem_cube") +print(f"result: {res}") ``` -**`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: - +This interface is used to delete the memory of specified users and supports batch deletion. ```python -from memos.configs.mem_os import MOSConfig -from memos.mem_os.main import MOS +# 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}") +``` -# init MOS -mos_config = MOSConfig.from_json_file("examples/data/config/simple_memos_config.json") -memory = MOS(mos_config) +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 -# create user -user_id = "b41a34d5-5cae-4b46-8c49-d03794d206f5" -memory.create_user(user_id=user_id) +# Initialize the client using the API Key +client = MemOSClient(api_key="YOUR_API_KEY") -# register cube for user -memory.register_mem_cube("examples/data/mem_cube_2", user_id=user_id) +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"] -# add memory for user -memory.add( - messages=[ - {"role": "user", "content": "I like playing football."}, - {"role": "assistant", "content": "I like playing football too."}, - ], +res = client.add_feedback( user_id=user_id, + conversation_id=conversation_id, + feedback_content=feedback_content, + allow_knowledgebase_ids=allow_knowledgebase_ids ) -# 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']}") +print(f"result: {res}") ``` -For more detailed examples, please check out the [`examples`](./examples) directory. +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}") +``` ## 📦 Installation From 17b944bc8170b80a4b27733c89c35c06d8d28b7b Mon Sep 17 00:00:00 2001 From: Elvis <1693372324@qq.com> Date: Thu, 25 Dec 2025 10:57:15 +0800 Subject: [PATCH 2/2] fix: update README.md --- README.md | 100 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 51 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 2f5422095..29a50c1da 100644 --- a/README.md +++ b/README.md @@ -117,6 +117,57 @@ showcasing its capabilities in **information extraction**, **temporal and cross- - **Parametric Memory**: Stores model adaptation parameters (e.g., LoRA weights). - **🔌 Extensible**: Easily extend and customize memory modules, data sources, and LLM integrations. + +## 📦 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 + +To download example code, data and configurations, run the following command: + +```bash +memos download_examples +``` + + ## 🚀 Getting Started ### ⭐️ MemOS online API @@ -237,55 +288,6 @@ res = client.create_knowledgebase( print(f"result: {res}") ``` -## 📦 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 - -To download example code, data and configurations, run the following command: - -```bash -memos download_examples -``` - ## 💬 Community & Support Join our community to ask questions, share your projects, and connect with other developers.