From a79f1f5f8cc0e13a9fdf1d421bbfc7cac96e121b Mon Sep 17 00:00:00 2001 From: abby Date: Tue, 27 Jan 2026 14:22:16 -0500 Subject: [PATCH 1/4] docs: sync memory module docs English version --- .../modules/memories/naive_textual_memory.md | 9 +++---- .../modules/memories/tree_textual_memory.md | 9 ++++--- .../memories/general_textual_memory.md | 18 +++++++++++-- .../modules/memories/naive_textual_memory.md | 27 +++++-------------- .../modules/memories/neo4j_graph_db.md | 2 +- .../open_source/modules/memories/overview.md | 13 +++++---- .../modules/memories/polardb_graph_db.md | 4 +-- .../memories/preference_textual_memory.md | 7 +++-- .../modules/memories/tree_textual_memory.md | 12 ++++----- 9 files changed, 49 insertions(+), 52 deletions(-) diff --git a/content/cn/open_source/modules/memories/naive_textual_memory.md b/content/cn/open_source/modules/memories/naive_textual_memory.md index 699ac068..779863af 100644 --- a/content/cn/open_source/modules/memories/naive_textual_memory.md +++ b/content/cn/open_source/modules/memories/naive_textual_memory.md @@ -1,13 +1,12 @@ --- title: "NaiveTextMemory: 简单明文记忆" -desc: "MemOS 中最轻量级的记忆模块，专为快速原型开发和简单场景设计。无需向量数据库，使用关键词匹配即可快速检索。" +desc: "MemOS 中最轻量级的记忆模块，专为快速原型开发和简单场景设计。无需向量数据库，使用关键词匹配即可快速检索。让我们用最简单的方式开始使用 MemOS 记忆系统！ +`NaiveTextMemory` 是一个基于内存的明文记忆模块，将记忆存储在内存列表中，使用关键词匹配进行检索。它是学习 MemOS 的最佳起点，也适用于演示、测试和小规模应用。" + --- -# NaiveTextMemory: 简单明文记忆 -让我们用最简单的方式开始使用 MemOS 记忆系统！ -`NaiveTextMemory` 是一个轻量级、基于内存的明文记忆模块，将记忆存储在内存列表中，使用关键词匹配进行检索。它是学习 MemOS 的最佳起点，也适用于演示、测试和小规模应用。 ## 目录 @@ -144,7 +143,7 @@ memory = NaiveTextMemory(config: NaiveTextMemoryConfig) -::alert{type="info"} +::note **示例对比**
查询："猫咪"
- **关键词匹配**：只匹配包含"猫"、"猫咪"的记忆
diff --git a/content/cn/open_source/modules/memories/tree_textual_memory.md b/content/cn/open_source/modules/memories/tree_textual_memory.md index 9eed3db9..8b8e42ed 100644 --- a/content/cn/open_source/modules/memories/tree_textual_memory.md +++ b/content/cn/open_source/modules/memories/tree_textual_memory.md @@ -1,12 +1,13 @@ --- title: "TreeTextMemory: 分层结构的明文记忆" ---- - -让我们在MemOS中构建你的第一个**基于图的、树形明文记忆**！ +desc: "让我们在MemOS中构建你的第一个**基于图的、树形明文记忆**！ **TreeTextMemory** 支持以结构化方式组织、关联并检索记忆，同时保留丰富的上下文信息与良好的可解释性。 -MemOS当前使用[Neo4j](/open_source/modules/memories/neo4j_graph_db)作为后端，未来计划支持更多图数据库。 +MemOS当前使用[Neo4j](/open_source/modules/memories/neo4j_graph_db)作为后端，未来计划支持更多图数据库。" +--- + + ## 目录 diff --git a/content/en/open_source/modules/memories/general_textual_memory.md b/content/en/open_source/modules/memories/general_textual_memory.md index 97376bb5..a495a7d7 100644 --- a/content/en/open_source/modules/memories/general_textual_memory.md +++ b/content/en/open_source/modules/memories/general_textual_memory.md @@ -42,6 +42,20 @@ Each memory is represented as a `TextualMemoryItem`: All values are validated. Invalid values will raise errors. +### Search Mechanism +Unlike NaiveTextMemory, which relies on keyword matching, GeneralTextMemory utilizes vector-based semantic search. + +## Algorithm Comparison + +| Feature | Keyword Matching | Vector Semantic Search | +| ------------------ | ---------------------------------- | ------------------------------------------ | +| **Semantic Understanding** | ❌ Doesn't understand synonyms | ✅ Understands similar concepts | +| **Resource Usage** | ✅ Extremely low | ⚠️ Requires embedding model and vector DB | +| **Execution Speed** | ✅ Fast (O(n)) | ⚠️ Slower (indexing + querying) | +| **Suitable Scale** | < 1K memories | 10K - 100K memories | +| **Predictability** | ✅ Intuitive results | ⚠️ Black box model + + ## API Summary (`GeneralTextMemory`) ### Initialization @@ -112,13 +126,13 @@ m.dump("tmp/mem") m.load("tmp/mem") ``` -::alert{type="info"} +::note **Extension: Internet Retrieval**
GeneralTextMemory can be combined with Internet Retrieval to extract content from web pages and add to memory.
View example: [Retrieve Memories from the Internet](./tree_textual_memory#retrieve-memories-from-the-internet-optional) :: -::alert{type="info"} +::note **Advanced: Using MultiModal Reader**
For processing images, URLs, or files within conversations, see the comprehensive MultiModal Reader examples.
View documentation: [Using MultiModalStructMemReader](./tree_textual_memory#using-multimodalstructmemreader-advanced) diff --git a/content/en/open_source/modules/memories/naive_textual_memory.md b/content/en/open_source/modules/memories/naive_textual_memory.md index 81fa9fdf..6993f7a7 100644 --- a/content/en/open_source/modules/memories/naive_textual_memory.md +++ b/content/en/open_source/modules/memories/naive_textual_memory.md @@ -3,11 +3,9 @@ title: "NaiveTextMemory: Simple Plain Text Memory" desc: "The most lightweight memory module in MemOS, designed for rapid prototyping and simple scenarios. No vector database required—quickly retrieve memories using keyword matching." --- -# NaiveTextMemory: Simple Plain Text Memory +Let's get started with the MemOS memory system in the simplest way possible! -Let's start using the MemOS memory system in the simplest way possible! - -**NaiveTextMemory** is a lightweight, in-memory plain text memory module that stores memories in a memory list and uses keyword matching for retrieval. It's the best starting point for learning MemOS and is suitable for demos, testing, and small-scale applications. +NaiveTextMemory is a lightweight, memory-based, plain-text memory module. It stores memories in an in-memory list and retrieves them using keyword matching. It is the perfect starting point for learning MemOS, as well as an ideal choice for demos, testing, and small-scale applications. ## Table of Contents @@ -62,7 +60,7 @@ By the end of this guide, you will be able to: - Keyword search scenarios (queries directly match memories) :: -::alert{type="warning"} +::note **Performance Tip**
When memory count exceeds 1000, it's recommended to upgrade to [GeneralTextMemory](/open_source/modules/memories/general_textual_memory), which uses vector search for better performance. :: @@ -139,19 +137,8 @@ Sort all memories by match count in descending order #### Step 4: Return Results Return the top-k memories as search results -:: - -**Algorithm Comparison** - -| Feature | Keyword Matching (NaiveTextMemory) | Vector Semantic Search (GeneralTextMemory) | -| ------------------ | ---------------------------------- | ------------------------------------------ | -| **Semantic Understanding** | ❌ Doesn't understand synonyms | ✅ Understands similar concepts | -| **Resource Usage** | ✅ Extremely low | ⚠️ Requires embedding model and vector DB | -| **Execution Speed** | ✅ Fast (O(n)) | ⚠️ Slower (indexing + querying) | -| **Suitable Scale** | < 1K memories | 10K - 100K memories | -| **Predictability** | ✅ Intuitive results | ⚠️ Black box model | -::alert{type="info"} +::note **Example Comparison**
Query: "cat"
- **Keyword Matching**: Only matches memories containing "cat"
@@ -238,7 +225,7 @@ memory.add(memories) print(f"✓ Added {len(memories)} memories") ``` -::alert{type="info"} +::note **Advanced: Using MultiModal Reader**
If you need to process multimodal content such as images, URLs, or files, use `MultiModalStructMemReader`.
View complete example: [Using MultiModalStructMemReader (Advanced)](./tree_textual_memory#using-multimodalstructmemreader-advanced) @@ -332,7 +319,7 @@ if memories: # memory.delete_all() ``` -::alert{type="info"} +::note **Extension: Internet Retrieval**
NaiveTextMemory focuses on local memory management. For retrieving information from the internet and adding it to your memory store, see:
[Retrieve Memories from the Internet (Optional)](./tree_textual_memory#retrieve-memories-from-the-internet-optional) @@ -367,7 +354,7 @@ When calling `dump(dir)`, the system saves memories to: Use `load(dir)` to fully restore all memory data. -::alert{type="warning"} +::note **Important Note**
Memories are stored in memory and will be lost after process restart. Remember to call `dump()` regularly to save data! :: diff --git a/content/en/open_source/modules/memories/neo4j_graph_db.md b/content/en/open_source/modules/memories/neo4j_graph_db.md index 455f8078..9478f253 100644 --- a/content/en/open_source/modules/memories/neo4j_graph_db.md +++ b/content/en/open_source/modules/memories/neo4j_graph_db.md @@ -185,4 +185,4 @@ You can add support for any other graph engine (e.g., **TigerGraph**, **DGraph** * `GraphDBConfigFactory.backend_to_class` * `GraphStoreFactory.backend_to_class` -See `src/memos/graph_dbs/neo4j.py` as a reference implementation. +See `src/memos/graph_dbs/neo4j.py` as a reference for implementation. diff --git a/content/en/open_source/modules/memories/overview.md b/content/en/open_source/modules/memories/overview.md index 35ab4e47..a90e7d67 100644 --- a/content/en/open_source/modules/memories/overview.md +++ b/content/en/open_source/modules/memories/overview.md @@ -3,19 +3,18 @@ title: "Memory Modules Overview" desc: "Complete guide to MemOS memory systems - from lightweight text memory to advanced graph structures, choose the right memory module for your needs" --- -# Memory Modules Overview -MemOS provides a rich set of memory modules to meet various needs from rapid prototyping to production environments. This guide helps you quickly find the most suitable memory solution. +The Memory Module provides Agents with essential long-term memory capabilities. Instead of acting as a static database, it mimics human cognitive processes by automatically extracting, organizing, and linking information. Choosing different memory modules allows you to customize and enhance your Agent's skills. ## 🎯 Quick Selection Guide ::alert{type="info"} **Not sure which to choose?** Follow this decision tree: -- 🚀 **Quick testing/demo** → [NaiveTextMemory](#naivetextmemory-simple-textual-memory) -- 📝 **General text memory** → [GeneralTextMemory](#generaltextmemory-general-purpose-textual-memory) -- 👤 **User preference management** → [PreferenceTextMemory](#preferencetextmemory-preference-memory) -- 🌳 **Structured knowledge graph** → [TreeTextMemory](#treetextmemory-hierarchical-structured-memory) -- ⚡ **Inference acceleration** → [KVCacheMemory](#kvcachememory-activation-memory) +- 🚀 **Quick testing/demo**: Get started easily with no additional software → [NaiveTextMemory](#naivetextmemory-simple-textual-memory) +- 📝 **General text memory**: Retain chat history or massive documents with semantic search capabilities → [GeneralTextMemory](#generaltextmemory-general-purpose-textual-memory) +- 👤 **User preference management**：Specifically designed for building and managing user profiles → [PreferenceTextMemory](#preferencetextmemory-preference-memory) +- 🌳 **Structured knowledge graph**: Ideal for data with complex logical relationships and interconnections → [TreeTextMemory](#treetextmemory-hierarchical-structured-memory) +- ⚡ **Inference acceleration**: Optimized for high-traffic scenarios to ensure stable and rapid responses → [KVCacheMemory](#kvcachememory-activation-memory) :: --- diff --git a/content/en/open_source/modules/memories/polardb_graph_db.md b/content/en/open_source/modules/memories/polardb_graph_db.md index c61599a3..8c288cef 100644 --- a/content/en/open_source/modules/memories/polardb_graph_db.md +++ b/content/en/open_source/modules/memories/polardb_graph_db.md @@ -1,11 +1,9 @@ --- title: "PolarDB Graph Database" -desc: "Configuration and usage of PolarDB graph database in the MemOS framework" +desc: "Configuration and usage of PolarDB graph database in the MemOS framework. MemOS supports using **PolarDB** (based on Apache AGE extension) as a graph database backend for storing and retrieving knowledge graph-style memory data. PolarDB combines the powerful capabilities of PostgreSQL with the flexibility of graph databases, making it particularly suitable for scenarios requiring both relational and graph data queries." --- -# PolarDB Graph Database -MemOS supports using **PolarDB** (based on Apache AGE extension) as a graph database backend for storing and retrieving knowledge graph-style memory data. PolarDB combines the powerful capabilities of PostgreSQL with the flexibility of graph databases, making it particularly suitable for scenarios requiring both relational and graph data queries. ## Features diff --git a/content/en/open_source/modules/memories/preference_textual_memory.md b/content/en/open_source/modules/memories/preference_textual_memory.md index d16763fd..ab715be5 100644 --- a/content/en/open_source/modules/memories/preference_textual_memory.md +++ b/content/en/open_source/modules/memories/preference_textual_memory.md @@ -49,9 +49,8 @@ desc: "`PreferenceTextMemory` is a textual memory module in MemOS for storing an - Learning assistance systems (adapting to learning styles) :: -::alert{type="info"} -**Applicable Scenarios**
-When you need to build systems that can "remember" user preferences and provide personalized services accordingly, `PreferenceTextMemory` is the best choice. + +In conclusion, when you need to build systems that can "remember" user preferences and provide personalized services accordingly, `PreferenceTextMemory` is the best choice. :: ## Core Concepts and Workflow @@ -74,7 +73,7 @@ Preference memory can be divided into explicit preference memory and implicit pr - User frequently requests detailed explanations → prefers in-depth understanding - User mentions environmental topics multiple times → concerned about sustainable development -::alert{type="success"} +::note **Intelligent Extraction**
`PreferenceTextMemory` automatically extracts both explicit and implicit preferences from conversations using LLM, no manual annotation required! :: diff --git a/content/en/open_source/modules/memories/tree_textual_memory.md b/content/en/open_source/modules/memories/tree_textual_memory.md index 9bf430d7..10b0862e 100644 --- a/content/en/open_source/modules/memories/tree_textual_memory.md +++ b/content/en/open_source/modules/memories/tree_textual_memory.md @@ -1,12 +1,12 @@ --- title: "TreeTextMemory: Structured Hierarchical Textual Memory" ---- - -Let’s build your first **graph-based, tree-structured memory** in MemOS! +desc: "Let’s build your first **graph-based, tree-structured memory** in MemOS! **TreeTextMemory** helps you organize, link, and retrieve memories with rich context and explainability. -[Neo4j](/open_source/modules/memories/neo4j_graph_db) is the current backend, with support for additional graph stores planned in the future. +[Neo4j](/open_source/modules/memories/neo4j_graph_db) is the current backend, with support for additional graph stores planned in the future." +--- + ## Table of Contents @@ -309,7 +309,7 @@ for m_list in mixed_memories: print(f"✓ Extracted and added {len(mixed_memories)} memories from mixed content") ``` -::alert{type="info"} +::note **MultiModal Reader Advantages**
- **Smart Routing**: Automatically identifies content type (image/URL/file) and selects appropriate parser
- **Format Support**: Supports PDF, DOCX, Markdown, HTML, images, and more
@@ -318,7 +318,7 @@ print(f"✓ Extracted and added {len(mixed_memories)} memories from mixed conten - **Context Preservation**: Uses sliding window to maintain context continuity between chunks :: -::alert{type="tip"} +::note **Configuration Tips**
- Use the `direct_markdown_hostnames` parameter to specify which domains should return Markdown format
- Supports both `mode="fast"` and `mode="fine"` extraction modes; fine mode extracts more details
From de6fc96c1cf6953af4ec13e3dd279f432ee60dca Mon Sep 17 00:00:00 2001 From: abby Date: Wed, 4 Feb 2026 22:43:35 -0500 Subject: [PATCH 2/4] docs: add open_source_api --- .../open_source/open_source_api/chat/chat.md | 120 ++++ .../open_source_api/core/add_message.md | 248 +++++++++ .../open_source_api/core/delete_memory.md | 86 +++ .../open_source_api/core/get_memory.md | 77 +++ .../open_source_api/core/search_memory.md | 112 ++++ .../open_source_api/help/error_codes.md | 48 ++ .../open_source_api/message/add_feedback.md | 77 +++ .../open_source_api/message/get_message.md | 75 +++ .../open_source_api/message/get_status.md | 63 +++ .../open_source_api/start/configuration.md | 517 ++++++++++++++++++ .../open_source_api/start/overview.md | 58 ++ 11 files changed, 1481 insertions(+) create mode 100644 content/cn/open_source/open_source_api/chat/chat.md create mode 100644 content/cn/open_source/open_source_api/core/add_message.md create mode 100644 content/cn/open_source/open_source_api/core/delete_memory.md create mode 100644 content/cn/open_source/open_source_api/core/get_memory.md create mode 100644 content/cn/open_source/open_source_api/core/search_memory.md create mode 100644 content/cn/open_source/open_source_api/help/error_codes.md create mode 100644 content/cn/open_source/open_source_api/message/add_feedback.md create mode 100644 content/cn/open_source/open_source_api/message/get_message.md create mode 100644 content/cn/open_source/open_source_api/message/get_status.md create mode 100644 content/cn/open_source/open_source_api/start/configuration.md create mode 100644 content/cn/open_source/open_source_api/start/overview.md diff --git a/content/cn/open_source/open_source_api/chat/chat.md b/content/cn/open_source/open_source_api/chat/chat.md new file mode 100644 index 00000000..546a91b2 --- /dev/null +++ b/content/cn/open_source/open_source_api/chat/chat.md @@ -0,0 +1,120 @@ +--- +title: 对话 +desc: MemOS 提供的一站式对话接口，内置完整的记忆召回与自动管理能力，无需手动拼接上下文。 +--- + +:::note +有关 API 字段、格式等信息的完整列表，详见[Chat 接口文档](/api_docs/chat/chat)。 +::: + +**接口路径**：`POST /product/chat/complete` 或 `POST /product/chat/stream` +**功能描述**：这是 MemOS 最核心的端到端接口。它整合了“记忆检索”、“Prompt 自动拼装”与“大模型生成”全链路，让您的 AI 应用原生具备长期记忆。 + + + +## 1. 为什么使用 Chat 接口？ + +* **一体化对话能力**：仅需调用一个接口传入当前用户提问，即可获得结合了历史记忆的回答，无需自建复杂的 RAG 链路。 +* **记忆自动化循环**：通过 `add_message_on_answer` 参数，系统在回答的同时会自动加工并写入新记忆，形成闭环。 +* **持久“上下文”理解**：在跨轮次、跨天甚至跨会话中保持连贯，让模型持续“记住”用户的偏好。 + +## 2. 关键接口参数 + +基于开源版 `src/api/routers/client.py` 的实现，`chat` 接口包含丰富的配置项： + +### 核心参数 +| 参数名 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | +| `query` | `str` | 是 | 用户的当前提问内容。 | +| `user_id` | `str` | 是 | 用于识别用户身份并检索对应的私有记忆。 | +| `conversation_id` | `str` | 是 | 标识当前会话，用于维持短期对话连贯性。 | + +### 记忆与控制参数 +| 参数名 | 类型 | 默认值 | 说明 | +| :--- | :--- | :--- | :--- | +| `add_message_on_answer` | `bool` | `False` | **关键功能**：设为 `True` 时，回答完成后自动调用 `add_message` 将对话存入记忆。 | +| `include_preference` | `bool` | `True` | 是否在生成回答时参考用户的偏好记忆。 | +| `knowledgebase_ids` | `list` | `None` | 指定需要包含的知识库 ID 列表，实现 RAG 增强。 | +| `system_prompt` | `str` | `None` | 自定义系统级提示词，覆盖默认配置。 | +| `temperature` | `float` | `None` | 控制生成随机性（0.0-1.0）。 | + +## 3. 工作原理 + + + +1. **发起请求**：AI 应用调用 `chat` 接口，传入 `user_id`、`query` 等参数。 +2. **自动召回**：MemOS 异步并发从个人记忆空间及关联知识库中提取相关事实。 +3. **Prompt 拼装**：系统将用户记忆、系统指令与当前问题拼接为完整 Prompt。 +4. **模型回答**：调用指定的大模型生成回复，并返回给应用。 +5. **异步加工**：若开启 `add_message_on_answer`，系统在后台自动将本轮对话更新为记忆。 + +## 4. 快速上手 + +推荐使用开源版内置的 `MemOSClient` 进行调用。以下示例展示了如何询问关于 R 语言学习的建议，并利用记忆功能： + +```python +import os +from memos.api.client import MemOSClient + +# 初始化客户端，指向本地服务地址 +client = MemOSClient( + api_key="YOUR_LOCAL_API_KEY", + base_url="http://localhost:8000/product" +) + +# 发起对话：系统会自动查找用户之前关于“R语言”或“可视化”的记忆 +res = client.chat( + user_id="memos_user_123", + conversation_id="session_r_study", + query="我最近在学 R 语言，除了 ggplot2，还有什么推荐的数据可视化包吗？", + add_message_on_answer=True, # 自动存储本次对话为新记忆 + include_preference=True # 开启偏好召回 +) + +if res: + print(f"AI 建议: {res.data}") +``` + +## 5. 更多功能 + +除了一键复制上述快速开始代码，本接口还提供了丰富的其他可配置参数，您可以根据业务需求灵活调用 `chat` 接口。 + +### 5.1 筛选召回的记忆 + +通过以下参数，您可以实现精细化的记忆检索控制： + +| **功能** | **字段** | **说明** | +| :--- | :--- | :--- | +| **记忆过滤器** | `filter` | 支持传入 JSON 结构的逻辑条件，用于按标签、元信息或时间筛选记忆。 | +| **召回偏好记忆** | `include_preference` / `preference_limit_number` | 开启后，AI 会参考用户的隐性/显式偏好。 | +| **检索指定知识库** | `knowledgebase_ids` | 用于指定本次对话可访问的关联知识库范围。 | + +### 5.2 调整模型回答 + +您可以直接在请求中调整底层大模型的生成表现，或通过 `/configure` 接口进行全局设置。 + +| **功能** | **字段** | **说明 & 可选值** | +| :--- | :--- | :--- | +| **选定模型** | `model_name` | 指定使用的模型名称。开源版默认模型可在环境配置中通过 `MOS_CHAT_MODEL` 定义。 | +| **自定义指令** | `system_prompt` | 支持传入自定义系统提示词，覆盖默认的记忆安全协议指令。 | +| **流式回答控制** | `async_mode` | 对应接口 `/product/chat/stream`。开启后支持流式输出，提升交互体验。 | +| **温度系数** | `temperature` | 控制生成随机性。建议范围 0.0 - 2.0，默认值为 0.7。 | +| **候选词范围** | `top_p` | 控制生成时的采样范围。默认值为 0.95。 | +| **长度限制** | `max_tokens` | 限制单次回复的最大 Token 数。默认值为 8192。 | + + + +### 5.3 闭环记忆自动化 + +这是开源版的核心特色，支持在对话过程中自动完成记忆的维护： + +| **功能** | **字段** | **说明** | +| :--- | :--- | :--- | +| **自动生成记忆** | `add_message_on_answer` | 开启后（True），系统会自动将用户消息与模型回复处理为新记忆。 | +| **关联元信息** | `info` / `tags` | 为本次对话生成的记忆打上业务标签或存储自定义元数据。 | +| **实体关联** | `agent_id` / `app_id` | 将记忆关联到特定的 Agent 或应用，方便多应用间的数据隔离。 | + +:::note +**开发者提示：** +在开源版本中，所有默认参数均可在项目的 `DEFAULT_CONFIG` 中找到并进行初始化修改。 +::: \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/core/add_message.md b/content/cn/open_source/open_source_api/core/add_message.md new file mode 100644 index 00000000..1469767a --- /dev/null +++ b/content/cn/open_source/open_source_api/core/add_message.md @@ -0,0 +1,248 @@ +--- +title: 添加消息 +desc: MemOS 会将您通过接口提交的消息内容，自动处理并持久化为可检索、可召回的个人记忆。 +--- +::warning +**[直接看 API文档 点这里哦](/api_docs/core/add_message)** +
+
+ +**本文聚焦于开源项目的功能说明，详细接口字段及限制请点击上方文字链接查看** +:: + +**接口路径**：`POST /product/add` +**功能描述**：这是 MemOS 的核心生产接口。它支持通过对话列表、纯文本或元数据信息，将原始数据转化为结构化的记忆片段，实现 AI 应用的长期记忆能力。 + +## 1. 为什么记忆很重要？ + +在开源版 MemOS 中，添加消息是构建 AI “懂用户”能力的起点： +* **跨会话长期记忆**：能够实现跨会话的长期记忆，避免对话结束后信息丢失。 +* **个性化积累**：随着交互不断积累，让 AI 越来越“懂用户”。 +* **动态更新**：在会话过程中持续写入新信息，动态更新用户记忆。 +* **共享体验**：在您的多个应用或产品之间，共享同一用户的记忆，实现一致的用户体验。 + +## 2. 关键接口参数 + +根据开源代码 `src/api/routers/client.py` 的实现，该接口接受以下核心参数： + +### 核心标识 +| 参数名 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | +| `user_id` | `str` | 是 | 用于标识消息所属的唯一用户。 | +| `conversation_id` | `str` | 是 | 用于标识消息所属的唯一会话。 | +| `messages` | `list` | 是 | 对话内容列表，格式为 `[{"role": "user", "content": "..."}]`。 | + +### 扩展配置 +| 参数名 | 类型 | 默认值 | 说明 | +| :--- | :--- | :--- | :--- | +| `tags` | `list[str]` | `None` | 为当前消息添加自定义标签，用于后续记忆过滤。 | +| `async_mode` | `bool` | `True` | 控制添加消息后的处理方式。开启后系统将异步生产记忆。 | +| `info` | `dict` | `None` | 自定义元信息（如 `scene`, `biz_id`），支持后续高级过滤检索。 | +| `allow_public` | `bool` | `False` | 控制生成的记忆是否写入项目级公共记忆空间。 | + +## 3. 工作原理 + + + +当您通过 `POST /product/add` 提交请求后，系统内部将执行以下逻辑： +1. **请求校验**：通过 `RequestContextMiddleware` 校验请求来源及其身份有效性。 +2. **信息提取**：使用内部 LLM 从消息中提取事实、偏好等内容，处理为事实记忆、偏好记忆或工具记忆。 +3. **冲突解决**：系统会自动检查现有记忆是否有重复或矛盾，并完成更新。 +4. **记忆储存**：最终产生的记忆将使用向量数据库与图数据库储存。 + +## 4. 快速上手示例 + +您可以直接使用项目中封装的 `MemOSClient` 进行调用： + +```python +import os +from memos.api.client import MemOSClient + +# 初始化客户端 +# 默认 base_url 指向本地 8000 端口的 /product +client = MemOSClient( + api_key="YOUR_LOCAL_API_KEY", + base_url="http://localhost:8000/product" +) + +# 添加一组对话消息 +res = client.add_message( + user_id="memos_user_123", + conversation_id="conv_2026_01", + messages=[ + {"role": "user", "content": "我计划今年暑假去大连看海。"}, + {"role": "assistant", "content": "大连是个不错的选择，我会记得您的旅行计划。"} + ], + tags=["travel_plan"], + info={"priority": "high"} +) + +if res and res.code == 200: + print("✅ 记忆添加成功") +``` +## 5. 使用场景 + +### 5.1 实时导入对话 + +您可以在用户每次收到模型回复时，实时调用接口同步对话。MemOS 将在后端不断根据新的对话更新用户记忆。 + +```python +import os +from memos.api.client import MemOSClient + +# 初始化客户端，默认指向本地开发环境地址 +client = MemOSClient( + api_key="YOUR_LOCAL_API_KEY", + base_url="http://localhost:8001/product" +) + +def sync_chat_to_memos(user_id, conversation_id, messages): + # 调用开源版客户端封装的 add_message 方法 + res = client.add_message( + user_id=user_id, + conversation_id=conversation_id, + messages=messages, + async_mode=True # 实时同步建议使用异步模式，不阻塞主流程 + ) + + if res and res.code == 200: + print(f"✅ 记忆实时同步成功") + else: + print(f"❌ 同步失败") + +# 示例：同步一组实时生成的对话 +sync_chat_to_memos( + user_id="memos_user_123", + conversation_id="conv_realtime_001", + messages=[ + {"role": "user", "content": "我最近在自学 R 语言，对数据可视化很感兴趣。"}, + {"role": "assistant", "content": "这很棒！R 语言的 ggplot2 包是数据可视化的神器。"} + ] +) +``` +### 5.2 导入历史对话 +```python +如果您已经构建了 AI 对话应用，MemOS 支持批量导入已有聊天记录，帮助助手建立初始记忆。 + +# 示例历史对话数据格式 +history_messages = [ + {"role": "user", "content": "我喜欢吃辣的食物"}, + {"role": "assistant", "content": "明白啦，我记住了，你喜欢辣味的食物。"}, + {"role": "user", "content": "但我又不太喜欢重油的，比如麻辣火锅之类的"} +] + +# 批量导入建议关闭 async_mode 以确保导入顺序和完整性 +client.add_message( + user_id="memos_user_123", + conversation_id="history_import_01", + messages=history_messages, + async_mode=False +) +``` +这是为你整理的开源版 添加消息 (Add Message) 文档中“使用场景”与“更多功能”部分的 Markdown 源代码。 + +我已将示例代码从云服务的原始 requests 方式，修改为直接调用你提供的开源版 MemOSClient 方式，这更符合开源项目的使用习惯。 + +Markdown + +## 5. 使用场景 + +### 5.1 实时导入对话 + +您可以在用户每次收到模型回复时，实时调用接口同步对话。MemOS 将在后端不断根据新的对话更新用户记忆。 + +```python +import os +from memos.api.client import MemOSClient + +# 初始化客户端，默认指向本地开发环境地址 +client = MemOSClient( + api_key="YOUR_LOCAL_API_KEY", + base_url="http://localhost:8001/product" +) + +def sync_chat_to_memos(user_id, conversation_id, messages): + # 调用开源版客户端封装的 add_message 方法 + res = client.add_message( + user_id=user_id, + conversation_id=conversation_id, + messages=messages, + async_mode=True # 实时同步建议使用异步模式，不阻塞主流程 + ) + + if res and res.code == 200: + print(f"✅ 记忆实时同步成功") + else: + print(f"❌ 同步失败") + +# 示例：同步一组实时生成的对话 +sync_chat_to_memos( + user_id="memos_user_123", + conversation_id="conv_realtime_001", + messages=[ + {"role": "user", "content": "我最近在自学 R 语言，对数据可视化很感兴趣。"}, + {"role": "assistant", "content": "这很棒！R 语言的 ggplot2 包是数据可视化的神器。"} + ] +) +5.2 导入历史对话 +如果您已经构建了 AI 对话应用，MemOS 支持批量导入已有聊天记录，帮助助手建立初始记忆。 + +Python + +# 示例历史对话数据格式 +history_messages = [ + {"role": "user", "content": "我喜欢吃辣的食物"}, + {"role": "assistant", "content": "明白啦，我记住了，你喜欢辣味的食物。"}, + {"role": "user", "content": "但我又不太喜欢重油的，比如麻辣火锅之类的"} +] + +# 批量导入建议关闭 async_mode 以确保导入顺序和完整性 +client.add_message( + user_id="memos_user_123", + conversation_id="history_import_01", + messages=history_messages, + async_mode=False +) +``` +### 5.3 记录用户偏好或行为 +除了对话内容，用户的个人偏好、兴趣问卷等结构化数据也可以导入，作为记忆的一部分。 +```python +# 示例用户兴趣信息导入 +client.add_message( + user_id="memos_user_123", + conversation_id="user_profile_001", + messages=[ + { + "role": "user", + "content": """ + 喜欢的电影类型: 科幻, 动作 + 运动习惯: 跑步, 健身 + 饮食偏好: 偏爱辣, 健康饮食 + """ + } + ], + tags=["profile", "preference"] # 使用标签便于后续筛选 +) +``` +## 6. 更多功能 + +开源版 `add_message` 提供了丰富的配置参数，支持精细化的记忆管理与多维度的数据归属。 + +:::note +有关 API 字段定义及格式的完整列表，请参考 [Add Message 详细接口文档](/api_docs/core/add_message)。 +::: + +| **功能** | **字段** | **说明** | +| :--- | :--- | :--- | +| **关联实体** | `agent_id` / `app_id` | 将当前用户的对话消息关联到具体的 Agent 或应用 ID，便于后续按实体维度检索记忆。 | +| **消息列表** | `messages` | 核心对话内容列表。支持 `user` / `assistant` / `system` / `tool` 等角色。 | +| **处理模式** | `async_mode` | 默认为 `True`。开启后系统异步提取记忆并快速返回；关闭则接口会阻塞直至记忆生产完成。 | +| **自定义标签** | `tags` | 为消息添加自定义标签（如 `feedback`），用于后续记忆过滤及高级图召回。 | +| **扩展元信息** | `info` | 自定义键值对字典。建议使用 `biz_id` 或 `scene` 等已索引字段以获得更优的检索性能。 | +| **公共记忆** | `allow_public` | 默认为 `False`。若开启，该消息生成的记忆将共享给项目下的所有用户。 | +| **写入知识库** | `allow_knowledgebase_ids` | 控制生成的记忆是否同步写入指定的知识库 ID 列表中，实现记忆与知识库的联动。 | + +:::note +**开发者提示：** +在开源版 MemOS 中，所有的请求校验（如参数缺失）和业务异常均由 `APIExceptionHandler` 统一捕获，并返回标准化的错误响应格式。 +::: \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/core/delete_memory.md b/content/cn/open_source/open_source_api/core/delete_memory.md new file mode 100644 index 00000000..c8721b3b --- /dev/null +++ b/content/cn/open_source/open_source_api/core/delete_memory.md @@ -0,0 +1,86 @@ +--- +title: 删除记忆 +desc: 从 MemOS 删除记忆,支持批量删除。 +--- + +::warning +**[直接看 API文档 点这里哦](/api_docs/core/delete_memory)** +
+
+ +**本文聚焦于功能说明，详细接口字段及限制请点击上方文字链接查看** +:: + +**接口路径**：`POST /product/delete_memory` +**功能描述**：当某条记忆已过期、不再准确或根据用户隐私要求需要移除时，可以使用此接口从向量数据库与图数据库中永久删除指定的记忆内容。 + +## 1. 关键参数 + +* **记忆 ID 列表（memory\_ids[]）**：每条存储在 MemOS 中的记忆都对应一个唯一标识符，支持以列表形式传入，用于精确删除一条或多条指定记忆。 +根据开源代码 `src/api/routers/client.py` 的实现，删除操作需要以下两个核心列表参数： + +| 参数名 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | +| **用户 ID 列表 (`user_ids`)** | `list[str]` | 是 | 指定这些记忆所属的用户标识列表。 | +| **记忆 ID 列表 (`memory_ids`)** | `list[str]` | 是 | 每条记忆的唯一标识符列表。您可以通过检索接口获取此 ID。 | + +:::note +**如何获取待删除记忆的记忆ID** +
+
+在检索记忆（`search/memory`）和获取记忆（`get/memory`）时，返回结果中的每条记忆都包含唯一的 `id` 字段，作为该记忆的唯一标识符。
+当发现某条记忆已过期或不符合预期时，可直接取 `id`，并作为 `memory_ids[]` 参数传入 `delete/memory` 接口，即可删除对应的记忆条目。 +::: + + +## 2. 工作原理 + +1. **请求路由**：请求发送至 `server_api.py` 统一定义的路由入口。 +2. **逻辑校验**：系统通过 `_validate_required_params` 确保 `user_ids` 和 `memory_ids` 均不为空。 +3. **物理移除**：MemOS 会同步清理底层向量数据库中的向量索引，以及图数据库中的实体关联。 +4. **异常处理**：若删除过程中出现业务逻辑错误，将由 `APIExceptionHandler` 返回标准化的 400 或 500 响应。 + +## 3. 快速上手 + +推荐使用项目中封装的 `MemOSClient` 进行批量删除操作： + +```python +import os +from memos.api.client import MemOSClient + +# 初始化客户端 +client = MemOSClient( + api_key="YOUR_LOCAL_API_KEY", + base_url="http://localhost:8001/product" +) + +# 准备待删除的记忆信息 +target_users = ["memos_user_123"] +target_memories = [ + "4a50618f-797d-4c3b-b914-94d7d1246c8d", + "b210928a-1234-5678-90ab-cdef12345678" +] + +# 执行删除操作 +res = client.delete_memory( + user_ids=target_users, + memory_ids=target_memories +) + +if res and res.code == 200: + print("✅ 指定记忆已成功删除") + +``` + +::note + 想知道是否删除成功？ +一键复制上述代码并运行，再次[检索记忆](/memos_cloud/mem_operations/search_memory)，看看记忆是否删除成功？ +:: + +## 4. 注意事项 + +不可恢复性：删除操作是物理删除。一旦执行成功，该记忆将无法再通过检索接口召回。 + +批量效率：建议将需要删除的 ID 整合在一次请求中处理，以减少网络开销并利用后端的批量清理机制。 + +校验机制：开源版要求显式传入 `user_ids`，这为多租户或多用户场景下的数据安全提供了双重保障，防止误删其他用户的记忆。 \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/core/get_memory.md b/content/cn/open_source/open_source_api/core/get_memory.md new file mode 100644 index 00000000..3bc44ad7 --- /dev/null +++ b/content/cn/open_source/open_source_api/core/get_memory.md @@ -0,0 +1,77 @@ +--- +title: 获取记忆 +desc: 分页查询并列出指定用户的所有记忆内容，支持深度过滤与分类筛选。 +--- + +::warning +**[直接看 API文档 点这里哦](/api_docs/core/get_memory)** +
+
+ +**本文聚焦于开源项目的功能说明，详细接口字段及限制请点击上方文字链接查看** +:: + +**接口路径**：`POST /product/get_memory` +**功能描述**：与侧重于语义匹配的“检索”接口不同，“获取”接口主要用于管理目的。它允许开发者以分页的方式列出指定用户的所有记忆（事实、偏好及工具记忆），常用于构建用户记忆画像展示页或后台管理界面。 + +## 1. 为什么需要“获取”接口？ + +* **全局视图**：无需输入查询语句即可查看用户已有的全部记忆资产。 +* **分页管理**：支持 `page` 和 `size` 参数，能够高效处理拥有数千条记忆的高级用户数据。 +* **精确清理前置**：在执行删除操作前，通过此接口确认记忆的 `id`。 + +## 2. 关键参数说明 + + +| 参数名 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | +| **`user_id`** | `str` | 是 | 关联用户的唯一标识符。 | +| **`include_preference`** | `bool` | 否 | 是否返回偏好记忆（默认为 `True`）。 | +| **`page`** | `int` | 否 | 分页页码，默认从 `1` 开始。 | +| **`size`** | `int` | 否 | 每页返回的记忆条目数量（建议最大不超过 50）。 | +| **`filter`** | `dict` | 否 | 结构化过滤器。支持按 `create_time` 或自定义 `info` 字段精确锁定。 | + + + +## 3. 工作原理 + +1. **多级过滤**：系统根据提供的 `user_id` 定位私有存储空间。 +2. **分类聚合**：根据 `include_preference` 和 `include_tool_memory` 参数，从不同的存储索引中聚合数据。 +3. **分页切片**：利用 `page` 和 `size` 对聚合后的结果集进行切片处理，降低网络传输压力。 +4. **结果返回**：返回包含记忆 ID、内容、标签及创建时间的数据列表。 + +## 4. 快速上手示例 + +通过 `MemOSClient` 快速拉取用户的记忆列表： + +```python +from memos.api.client import MemOSClient + +# 初始化客户端 +client = MemOSClient( + api_key="YOUR_LOCAL_API_KEY", + base_url="http://localhost:8000/product" +) + +# 获取用户最近的 10 条记忆，包含偏好信息 +res = client.get_memory( + user_id="memos_user_123", + include_preference=True, + page=1, + size=10 +) + +if res and res.code == 200: + for memory in res.data.get('memory_detail_list', []): + print(f"ID: {memory['id']} | 内容: {memory['memory_value']}") +``` + +## 5. 使用场景 +### 5.1 构建用户画像看板 +展示“AI 对你的印象”或“已记住的偏好”。由于该接口支持分页，非常适合瀑布流或列表展示。 + +### 5.2 数据审计与纠偏 +您可以定期通过此接口扫描某个用户的记忆条目，配合过滤器查找是否存在过时的业务标签（如 custom_status='deprecated'），并利用删除记忆接口进行清理。 + +### 5.3 导出记忆资产 +支持将用户的记忆批量拉取并导出，方便进行离线分析或跨平台的数据迁移。 \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/core/search_memory.md b/content/cn/open_source/open_source_api/core/search_memory.md new file mode 100644 index 00000000..f1bfc637 --- /dev/null +++ b/content/cn/open_source/open_source_api/core/search_memory.md @@ -0,0 +1,112 @@ +--- +title: 检索记忆 +desc: 通过语义检索和过滤功能，MemOS召回相关记忆。 +--- + +::warning +**[直接看 API文档 点这里哦](/api_docs/core/search_memory)** +
+
+ +**本文聚焦于开源项目的功能说明，详细接口字段及限制请点击上方文字链接查看** +:: + +**接口路径**：`POST /product/search` +**功能描述**：当用户提出问题时，MemOS 会结合开发者预设的过滤条件，从海量记忆中召回最相关、最重要的片段。这些片段可作为大模型的上下文，显著提升回答的准确性与个性化程度。 + +## 1. 什么是检索记忆？ + +检索记忆是指系统根据用户当前的 `query`（查询内容），利用向量相似度匹配和逻辑过滤，从存储的“事实记忆”和“偏好记忆”中提取关键信息。 + +::note +** 为什么需要检索记忆？** +
+ +* **增强可靠性**：无需为模型手动构建复杂的上下文，直接获取经过验证的记忆片段。 +* **高度相关性**：通过过滤器（Filter）确保召回的内容始终贴合当前的业务语境。 +
+:: + +## 2. 关键接口参数 + +根据开源代码 `client.py` 的定义，检索接口支持以下参数： + +| 参数名 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | +| `query` | `str` | 是 | 检索的自然语言问题。系统将基于此内容进行语义匹配。 | +| `user_id` | `str` | 是 | 指定检索哪位用户的记忆库。 | +| `conversation_id` | `str` | 否 | 提供当前会话 ID 可增加该会话内记忆的权重，提升回复连贯性。 | +| `memory_limit_number` | `int` | 否 | 默认召回 6 条。限制返回的事实记忆数量。 | +| `filter` | `dict` | 否 | 基于 JSON 的逻辑条件，用于按标签、时间或元信息缩小范围。 | +| `include_preference` | `bool` | 否 | 是否同时召回该用户的偏好记忆（显式/隐式偏好）。 | + +## 3. 工作原理 + + + +1. **查询预处理**：MemOS 会对输入的 `query` 进行清理与语义增强，以提升向量检索的效果。 +2. **逻辑过滤**：结合 `filter` 参数中的运算符（如 `contains`, `gt` 等）初步筛选记忆范围。 +3. **语义检索**：基于嵌入（Embedding）向量，在向量数据库中寻找相似度最高的内容。 +4. **结果排序**：根据 `relativity`（相关性分数）和时间权重对记忆片段进行排序并返回。 + +## 4. 快速上手示例 + +使用开源版 `MemOSClient` 快速执行一次记忆检索： + +```python +from memos.api.client import MemOSClient + +# 初始化客户端 +client = MemOSClient( + api_key="YOUR_LOCAL_API_KEY", + base_url="http://localhost:8001/product" +) + +# 执行检索 +res = client.search_memory( + user_id="memos_user_123", + conversation_id="conv_2026_09", + query="我暑假想去旅游，根据我的偏好推荐个城市", + memory_limit_number=5, + include_preference=True # 同时获取用户的偏好，如“喜欢安静”、“偏好南方” +) + +if res: + # 打印召回的事实记忆 + for mem in res.memory_detail_list: + print(f"Key: {mem['memory_key']}, Value: {mem['memory_value']}") +``` + +## 5. 使用场景 + +### 5.1 增强对话上下文 +在与 AI 对话的过程中，您可以调用 MemOS 检索与当前用户发言最相关的记忆，并将其填充到大模型的回复提示词中。 +::note +`conversation_id`为非必填项，如填写可以帮助 MemOS 理解当前会话的上下文，提升本会话相关记忆的权重，使对话模型的回复内容更加连贯。 +:: + +### 5.2 用户整体画像分析 +不指定 `conversation_id` 且使用全局查询（如“我的兴趣关键词是什么？”），可以获取用户在所有会话中积累的属性特征，帮助生成个性化画像。 + +### 5.3 进阶过滤器检索 +您可以利用 `filter `字段实现复杂的筛选逻辑。例如：只搜索标签包含“学习计划”且创建时间晚于特定日期的记忆。 + +```python +# 示例：组合过滤器 +search_filter = { + "and": [ + {"tags": {"contains": "学习计划"}}, + {"create_time": {"gt": "2025-11-09"}} + ] +} +``` +## 6. 更多功能 + +::note + 有关 API 字段、格式等信息的完整列表，详见[Search Memory接口文档](/api_docs/core/search_memory)。 +:: +| **功能** | **相关字段** | **说明** | +| -------------- | --------------------------------------------------- | ------------------------------------------------------------ | +| 召回偏好记忆 | `include_preference`
 
`preference_limit_number` | 偏好记忆是 MemOS 基于用户历史消息分析生成的用户偏好信息。开启后，可在检索结果中召回用户偏好记忆。 | +| 召回工具记忆 | `include_tool_memory`
 
`tool_memory_limit_number` | 工具记忆是 MemOS 对已添加的工具调用信息进行分析后生成的记忆。开启后，可在检索结果中召回工具记忆，详见[工具调用](/memos_cloud/features/advanced/tool_calling)。 | +| 检索指定知识库 | `knowledgebase_ids` | 用于指定本次检索可访问的项目关联知识库范围。开发者可借此实现精细的权限控制，灵活定义不同终端用户可访问的知识库集合，详见[知识库](/memos_cloud/features/advanced/knowledge_base)。 | diff --git a/content/cn/open_source/open_source_api/help/error_codes.md b/content/cn/open_source/open_source_api/help/error_codes.md new file mode 100644 index 00000000..1aa94ca3 --- /dev/null +++ b/content/cn/open_source/open_source_api/help/error_codes.md @@ -0,0 +1,48 @@ +--- +title: 错误码 +--- + +| 错误码 | 含义 | 推荐解决方法 | +| :--- | :--- | :--- | +| **参数错误** | | | +| 40000 | 请求参数错误 | 检查参数名、类型及格式是否符合要求 | +| 40001 | 请求数据不存在 | 检查资源 ID（如 memory_id）是否正确 | +| 40002 | 必填参数不能为空 | 补充缺失的必填字段 | +| 40003 | 参数为空 | 检查传入的列表或对象是否为空 | +| 40006 | 不支持的类型 | 检查 type 字段取值 | +| 40007 | 不支持的文件类型 | 仅上传允许的格式（.pdf, .docx, .doc, .txt） | +| 40008 | Base64 内容非法 | 检查 Base64 字符串是否包含非法字符 | +| 40009 | Base64 格式非法 | 检查 Base64 编码格式是否正确 | +| 40010 | 用户 ID 过长 | user_id 长度不能超过 100 字符 | +| 40011 | 会话 ID 过长 | conversation_id 长度不能超过 100 字符 | +| 40020 | 项目 ID 非法 | 确认 Project ID 格式正确 | +| **认证与权限错误** | | | +| 40100 | 需要 API Key 认证 | 在 Header 中添加有效 API Key | +| 40130 | 需要 API Key 认证 | 在 Header 中添加有效 API Key | +| 40132 | API Key 无效或已过期 | 检查 API Key 状态或重新生成 | +| **配额与限流错误** | | | +| 40300 | 超过接口调用次数上限 | 获取更多额度 | +| 40301 | 超过请求 Token 调用上限 | 减少输入内容或获取更多额度 | +| 40302 | 超过响应 Token 调用上限 | 缩短预期输出或获取更多额度 | +| 40303 | 单次对话长度超过限制 | 缩减单次输入/输出长度 | +| 40304 | 账户总 API 调用次数耗尽 | 获取更多额度 | +| 40305 | 输入超过单次 Token 上限 | 缩减输入内容 | +| 40306 | 删除记忆鉴权失败 | 确认是否有权删除该记忆 | +| 40307 | 删除记忆不存在 | 检查 memory_id 是否有效 | +| 40308 | 删除记忆对应的用户不存在 | 检查 user_id 是否正确 | +| **系统与服务错误** | | | +| 50000 | 系统内部异常 | 服务器繁忙或出现异常，请联系支持 | +| 50002 | 操作失败 | 检查操作逻辑或稍后重试 | +| 50004 | 记忆服务暂时不可用 | 稍后重试记忆写入/获取操作 | +| 50005 | 搜索服务暂时不可用 | 稍后重试记忆搜索操作 | +| **知识库与操作错误** | | | +| 50103 | 文件数量超过限制 | 单次上传文件数量不超过20个 | +| 50104 | 单个文件大小超过限制 | 确保单个文件不超过 100MB | +| 50105 | 所有文件总大小超过限制 | 确保单次上传总大小不超过 300MB | +| 50107 | 文件上传格式不符合要求 | 检查并更换文件格式 | +| 50120 | 知识库不存在 | 确认知识库 ID 是否正确 | +| 50123 | 知识库不关联此项目 | 确认知识库是否已授权给当前项目 | +| 50131 | 任务不存在 | 检查 task_id 是否正确（常见于查询处理状态） | +| 50143 | 添加记忆失败 | 算法服务处理异常，请稍后重试 | +| 50144 | 添加消息失败 | 保存聊天历史记录失败 | +| 50145 | 保存反馈并写入记忆失败 | 反馈处理过程中出现异常 | \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/message/add_feedback.md b/content/cn/open_source/open_source_api/message/add_feedback.md new file mode 100644 index 00000000..e154fa51 --- /dev/null +++ b/content/cn/open_source/open_source_api/message/add_feedback.md @@ -0,0 +1,77 @@ +--- +title: 添加反馈 +desc: 提交用户对大模型回复的反馈内容，帮助 MemOS 实时更正、优化或删除不准确的记忆。 +--- + +::warning +**[直接看 API文档 点这里哦](/api_docs/message/get_status)** +
+
+ +**本文聚焦于开源项目的功能说明，详细接口字段及限制请点击上方文字链接查看** +:: + +**接口路径**：`POST /product/feedback` +**功能描述**：当您发现大模型的回答基于了错误的记忆，或者用户的偏好发生了变化时，可以通过此接口提交反馈。MemOS 会分析反馈内容，并据此调整存储在向量库和图数据库中的相关条目。 + +## 1. 为什么需要添加反馈？ + +* **记忆纠偏**：MemOS 能够基于用户的反馈更正已有记忆，解决信息过时或提取错误的问题。 +* **强化偏好**：通过正向或负向反馈，让 AI 更好地理解用户的隐性偏好。 +* **提升准确性**：反馈内容会作为后续记忆生产的参考，防止 AI 重复犯同样的错误。 + +## 2. 关键接口参数 +本接口接受以下参数： + +| 参数名 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | +| **`user_id`** | `str` | 是 | 反馈内容所关联的用户唯一标识符。 | +| **`conversation_id`** | `str` | 是 | 反馈内容所关联的会话唯一标识符。 | +| **`feedback_content`** | `str` | 是 | 反馈的文本内容（例如：“我不喜欢吃辣了”或“你记错我的名字了”）。 | +| `feedback_time` | `str` | 否 | 反馈发生的时间，支持结构化或自然语言描述。 | +| `agent_id` / `app_id` | `str` | 否 | 关联的 Agent 或应用标识，用于实现精细化的记忆隔离。 | +| `allow_public` | `bool` | 否 | 是否允许将由此反馈产生的修正记忆写入公共记忆库。 | + +## 3. 工作原理 + +1. **反馈接收**：系统接收到 `feedback_content` 后，结合当前 `conversation_id` 的语境进行解析。 +2. **冲突检测**：AI 会检查反馈内容是否与现有记忆库中的事实存在冲突。 +3. **记忆更正**：如果发现冲突，系统会更新原有的事实条目；如果是新信息，则作为补充记忆存入。 +4. **实时生效**：更正后的记忆在下一次调用 [**检索记忆**](./search_memory.md) 时即可被正确召回。 + +## 4. 快速上手示例 + +推荐使用项目中封装的 `MemOSClient` 提交反馈： + +```python +from memos.api.client import MemOSClient + +# 初始化客户端 +client = MemOSClient( + api_key="YOUR_LOCAL_API_KEY", + base_url="http://localhost:8000/product" +) + +# 提交反馈以更正记忆 +res = client.add_feedback( + user_id="memos_user_123", + conversation_id="conv_888", + feedback_content="我最近开始尝试清淡饮食了，不再喜欢重辣的食物。", + feedback_time="2026-02-04", + tags=["preference_update"] +) + +if res and res.code == 200: + print("✅ 反馈已接收，系统正在更正记忆...") +``` + + +## 5. 使用场景 +### 5.1 纠正 AI 的错误推断 +如果 AI 之前根据对话错误地总结了用户的名字或职业，用户可以直接反馈：“我的名字是 Grace，不是 Gray”。MemOS 会自动修正 `UserMemory` 中的相关条目。 + +### 5.2 更新过时的用户偏好 +用户的喜好会随时间改变。通过记录反馈（如饮食习惯、旅游倾向的变化），可以确保 AI 生成的建议始终符合用户现状。 + +### 5.3 跨实体记忆同步 +通过指定 `allow_knowledgebase_ids`，反馈产生的修正结果可以同步写入关联的知识库，让所有相关 Agent 都能获取到最新的信息。 \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/message/get_message.md b/content/cn/open_source/open_source_api/message/get_message.md new file mode 100644 index 00000000..5cfaeceb --- /dev/null +++ b/content/cn/open_source/open_source_api/message/get_message.md @@ -0,0 +1,75 @@ +--- +title: 获取消息 +desc: 获取指定会话中的用户与助手原始对话历史，用于构建聊天 UI 或提取原始语境。 +--- + +::warning +**[直接看 API文档 点这里哦](/api_docs/message/get_message)** +
+
+ +**本文聚焦于开源项目的功能说明，详细接口字段及限制请点击上方文字链接查看** +:: + +**接口路径**：`POST /product/get/message` +**功能描述**：该接口用于获取指定会话中用户与助手的原始对话记录。与返回摘要信息的“记忆”接口不同，此接口返回的是未经加工的原始文本，是构建聊天历史回溯功能的核心接口。 + +## 1. 记忆 (Memory) vs 消息 (Message) + +在开发过程中，请区分以下两类数据： +* **获取记忆 (`/get_memory`)**：返回的是系统处理后的**事实与偏好摘要**（例如：“用户喜欢 R 语言进行可视化”）。 +* **获取消息 (`/get_message`)**：返回的是**原始对话文本**（例如：“我最近在自学 R 语言，推荐个可视化包”）。 + +## 2. 关键接口参数 +本接口支持以下参数： + +| 参数名 | 类型 | 必填 | 默认值 | 说明 | +| :--- | :--- | :--- | :--- | :--- | +| `user_id` | `str` | 是 | - | 与获取消息关联的用户唯一标识符。 | +| `conversation_id` | `str` | 否 | `None` | 指定会话的唯一标识符。 | +| `message_limit_number` | `int` | 否 | `6` | 限制返回的消息条数，最大建议值为 50。 | +| `conversation_limit_number`| `int` | 否 | `6` | 限制返回的会话历史条数。 | +| `source` | `str` | 否 | `None` | 标识消息的来源渠道。 | + +## 3. 工作原理 + + +1. **定位会话**：系统根据提供的 `conversation_id` 在底层存储中检索属于该用户及会话的消息记录。 +2. **切片处理**：根据 `message_limit_number` 参数，系统从最新的消息开始倒序截取指定条数，确保返回的是最近的对话。 +3. **安全隔离**：所有请求均通过 `RequestContextMiddleware` 中间件，严格校验 `user_id` 的归属权，防止越权访问。 + +## 4. 快速上手示例 + +使用开源版内置的 `MemOSClient` 快速拉取对话历史： + +```python +from memos.api.client import MemOSClient + +# 初始化客户端 +client = MemOSClient( + api_key="YOUR_LOCAL_API_KEY", + base_url="http://localhost:8000/product" +) + +# 获取指定会话的最近 10 条对话记录 +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: + # 遍历返回的消息列表 + for msg in res.data: + print(f"[{msg['role']}]: {msg['content']}") +``` + +## 5. 使用场景 +### 5.1 聊天 UI 历史加载 +当用户点击进入某个历史会话时，调用此接口可恢复对话现场。建议结合 `message_limit_number` 实现分页加载，提升前端性能。 + +### 5.2 外部模型上下文注入 +如果您正在使用自定义的大模型逻辑（非 MemOS 内置 chat 接口），可以通过此接口获取原始对话历史，并将其手动拼接至模型的 messages 数组中。 + +### 5.3 消息回溯分析 +您可以定期导出原始对话记录，用于评估 AI 的回复质量或分析用户的潜在意图。 \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/message/get_status.md b/content/cn/open_source/open_source_api/message/get_status.md new file mode 100644 index 00000000..c8f5e7d1 --- /dev/null +++ b/content/cn/open_source/open_source_api/message/get_status.md @@ -0,0 +1,63 @@ +--- +title: 获取任务状态 +desc: 获取异步处理任务（如记忆生产、文档解析）的实时执行状态。 +--- + +::warning +**[直接看 API文档 点这里哦](/api_docs/message/get_status)** +
+
+ +**本文聚焦于开源项目的功能说明，详细接口字段及限制请点击上方文字链接查看** +:: +**接口路径**：`POST /product/get/status` +**功能描述**：MemOS 在处理复杂的记忆提取或大规模文档导入时，通常采用异步模式。本接口允许开发者通过任务 ID 查询后台任务的执行情况，确保记忆生产流程的透明化。 + +## 1. 为什么需要此接口？ + +* **异步追踪**：当 `add_message` 以 `async_mode=True` 调用时，接口会立即返回响应，而实际的记忆提取逻辑在后台运行。 +* **失败排查**：如果任务执行失败，可以通过此接口获取具体的错误原因。 +* **流程控制**：在构建复杂 Agent 时，确保记忆已成功“入库”后再执行后续的高级搜索操作。 + +## 2. 关键参数说明 + +根据开源代码 `client.py` 中的 `get_task_status` 方法定义，核心参数如下： + +| 参数名 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | +| **`task_id`** | `str` | 是 | 异步任务的唯一标识符。该 ID 通常在调用 `add_message` 或 `add_knowledgebase_file` 后获得。 | + +## 3. 工作原理 + +1. **状态查询**：系统根据 `task_id` 在内部任务队列中检索记录。 +2. **状态反馈**：返回当前任务的阶段（如 `pending`, `running`, `completed`, `failed`）。 +3. **数据一致性校验**：若状态为 `completed`，通常意味着向量数据库同步（`vector_sync`）已完成，该记忆即可被搜索召回。 + +## 4. 快速上手示例 + +推荐使用项目中封装的 `MemOSClient` 进行状态轮询： + +```python +from memos.api.client import MemOSClient +import time + +# 初始化客户端 +client = MemOSClient( + api_key="YOUR_LOCAL_API_KEY", + base_url="http://localhost:8001/product" +) + +# 假设您在添加消息时获得了一个 task_id +task_id = "async_task_123456789" + +# 轮询任务状态 +while True: + res = client.get_task_status(task_id=task_id) + if res and res.code == 200: + status = res.data.get('status') + print(f"当前任务状态: {status}") + + if status in ['completed', 'failed']: + break + + time.sleep(2) # 建议轮询间隔 2 秒 \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/start/configuration.md b/content/cn/open_source/open_source_api/start/configuration.md new file mode 100644 index 00000000..76d43c6e --- /dev/null +++ b/content/cn/open_source/open_source_api/start/configuration.md @@ -0,0 +1,517 @@ +--- +title: 项目配置 +desc: MemOS 开源版支持以 User 和 MemCube 为维度来管理资源、权限和数据隔离。您可以将一个 MemCube 视为一个独立的项目空间、一个 Agent 的专属数据库或一款 App 的存储后端。 +--- + + + +## 本地运行 + +### 1、本地下载 +```bash +# 将代码下载到本地文件夹下 +git clone https://github.com/MemTensor/MemOS +``` + +### 2、配置环境变量 +```bash +# 进入文件夹目录下 +cd MemOS +``` + +#### 在根目录中创建一个 `.env` 文件并设置你的环境变量。 +##### .env 快速模式配置如下，完整模式参考 .env.example。 + +```bash + +# OpenAI API 密钥 (需自定义配置) +OPENAI_API_KEY=sk-xxx +# OpenAI API 基础 URL +OPENAI_API_BASE=http://xxx:3000/v1 +# 默认模型名称 +MOS_CHAT_MODEL=qwen3-max + +# Memory Reader LLM 模型 +MEMRADER_MODEL=qwen3-max +# Memory Reader API 密钥 +MEMRADER_API_KEY=sk-xxx +# Memory Reader API 基础 URL +MEMRADER_API_BASE=http://xxx:3000/v1 + +# Embedder 模型名称 +MOS_EMBEDDER_MODEL=text-embedding-v4 +# 配置embedding backend 两种选择 ollama | universal_api +MOS_EMBEDDER_BACKEND=universal_api +# Embedder API 基础 URL +MOS_EMBEDDER_API_BASE=http://xxx:8081/v1 +# Embedder API 密钥 +MOS_EMBEDDER_API_KEY=xxx +# Embedding 向量维度 +EMBEDDING_DIMENSION=1024 +# Reranker 后端 (http_bge | etc.) +MOS_RERANKER_BACKEND=cosine_local + +# Neo4j 连接 URI +# 可选值: neo4j-community | neo4j | nebular | polardb +NEO4J_BACKEND=neo4j-community +# 当 backend=neo4j* 时必须 +NEO4J_URI=bolt://localhost:7687 +NEO4J_USER=neo4j +NEO4J_PASSWORD=12345678 +NEO4J_DB_NAME=neo4j +MOS_NEO4J_SHARED_DB=false + +# 是否使用 redis 的调度器 +DEFAULT_USE_REDIS_QUEUE=false + +# 启用聊天 API +ENABLE_CHAT_API=true +# 聊天模型列表 可以通过百炼申请. 模型可自选 +CHAT_MODEL_LIST=[{"backend": "qwen", "api_base": "https://xxx/v1", "api_key": "sk-xxx", "model_name_or_path": "qwen3-max", "extra_body": {"enable_thinking": true} ,"support_models": ["qwen3-max"]}] +``` + +### 3、以百炼为例自定义配置 + +```bash +# 可通过百炼平台申请 +# https://bailian.console.aliyun.com/?spm=a2c4g.11186623.0.0.2f2165b08fRk4l&tab=api#/api +# 申请成功后，获取API_KEY和BASE_URL，示例配置如下 + +# OpenAI API 密钥 (用百炼的API_KEY) +OPENAI_API_KEY=you_bailian_api_key +# OpenAI API 基础 URL +OPENAI_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1 +# 默认模型名称 +MOS_CHAT_MODEL=qwen3-max + +# Memory Reader LLM 模型 +MEMRADER_MODEL=qwen3-max +# Memory Reader API 密钥 (用百炼的API_KEY) +MEMRADER_API_KEY=you_bailian_api_key +# Memory Reader API 基础 URL +MEMRADER_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1 + +# Embedder模型名称可以参考下面链接 +# https://bailian.console.aliyun.com/?spm=a2c4g.11186623.0.0.2f2165b08fRk4l&tab=api#/api/?type=model&url=2846066 +MOS_EMBEDDER_MODEL=text-embedding-v4 +# 配置embedding backend 两种选择 ollama | universal_api +MOS_EMBEDDER_BACKEND=universal_api +# Embedder API 基础 URL +MOS_EMBEDDER_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1 +# Embedder API 密钥 (用百炼的API_KEY) +MOS_EMBEDDER_API_KEY=you_bailian_api_key +# Embedding 向量维度 +EMBEDDING_DIMENSION=1024 +# Reranker 后端 (http_bge | etc.) +MOS_RERANKER_BACKEND=cosine_local + +# Neo4j 连接 URI +# 可选值: neo4j-community | neo4j | nebular | polardb +NEO4J_BACKEND=neo4j-community +# 当 backend=neo4j* 时必须 +NEO4J_URI=bolt://localhost:7687 +NEO4J_USER=neo4j +NEO4J_PASSWORD=12345678 +NEO4J_DB_NAME=neo4j +MOS_NEO4J_SHARED_DB=false + +# 是否使用 redis 的调度器 +DEFAULT_USE_REDIS_QUEUE=false + +# 启用聊天 API +ENABLE_CHAT_API=true + +CHAT_MODEL_LIST=[{"backend": "qwen", "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1", "api_key": "you_bailian_api_key", "model_name_or_path": "qwen3-max-preview", "extra_body": {"enable_thinking": true} ,"support_models": ["qwen3-max-preview"]}] +``` +![MemOS bailian](https://cdn.memtensor.com.cn/img/get_key_url_by_bailian_compressed.png) +
百炼申请 API_KEY和 BASE_URL 示例
+ +配置docker/requirement.txt中依赖包的版本等（可忽略）。完整版可参考 requirements.txt。 + +### 4、启动docker +```bash + # 如果没有安装docker,请安装对应版本，下载地址如下： + https://www.docker.com/ + +# 安装完成之后，可通过客户端启动docker，或者通过命令行启动docker +# 通过命令行启动docker +sudo systemctl start docker + +# 安装完成后，查看docker状态 +docker ps + +# 查看docker镜像 （可不用） +docker images + +``` + + +### 方式一：Docker 使用仓库依赖包镜像启动(推荐使用) +::steps{level="4"} + +```bash +#进入docker目录下 +cd docker +``` + +#### 镜像包使用确认 +包含快速模式和完整模式，可区分使用精简包（区分arm和x86）和全量包（区分arm和x86） + +```bash + +● 精简包：简化体量过大的 nvidia相关等依赖，对镜像实现轻量化，使本地部署更加轻量快速。 +url: registry.cn-shanghai.aliyuncs.com/memtensor/memos-base:v1.0 +url: registry.cn-shanghai.aliyuncs.com/memtensor/memos-base-arm:v1.0 + +● 全量包：将 MemOS 全部依赖包打为镜像，可体验完整功能，通过配置 Dockerfile可直接构建启动。 +url: registry.cn-shanghai.aliyuncs.com/memtensor/memos-full-base:v1.0.0 +url: registry.cn-shanghai.aliyuncs.com/memtensor/memos-full-base-arm:v1.0.0 +``` +#### 配置Dockerfile文件 + +```bash +# 当前示例使用精简包 url +FROM registry.cn-shanghai.aliyuncs.com/memtensor/memos-base-arm:v1.0 + +WORKDIR /app + +ENV HF_ENDPOINT=https://hf-mirror.com + +ENV PYTHONPATH=/app/src + +COPY src/ ./src/ + +EXPOSE 8000 + +CMD ["uvicorn", "memos.api.server_api:app", "--host", "0.0.0.0", "--port", "8000", "--reload"] + +``` + +#### 构建并启动服务 ： +```bash +# 在docker目录下 +docker compose up +``` +![MemOS buildComposeupSuccess](https://cdn.memtensor.com.cn/img/memos_build_composeup_success_compressed.png) +
示例图片，端口按 docker 自定义的配置
+ +#### 通过 [http://localhost:8000/docs](http://localhost:8000/docs) 访问 API。 + +![MemOS Architecture](https://cdn.memtensor.com.cn/img/memos_run_server_success_compressed.png) + + +#### 测试用例 (添加用户记忆->查询用户记忆) 参考Docker Compose up测试用例 + +:: + + + +### 方式二：客户端install Docker Compose up +::steps{level="4"} +开发环境的 Docker Compose up 已预配置了 qdrant、neo4j。 +运行服务器需要环境变量 `OPENAI_API_KEY`。 + + +#### 进入docker文件夹 +```bash +# 当前文件夹下进入docker文件夹 +cd docker +``` + +#### 安装对应依赖模块 +```bash + +pip install --upgrade pip && pip install --no-cache-dir -r requirements.txt +# 使用阿里云源安装依赖 +pip install --upgrade pip && pip install --no-cache-dir -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ + +# command not found: pip 使用pip3 + + + +``` + + +#### 在docker目录下使用 Docker Compose Up启动容器(保证vpn正常连接)： + +```bash + +# 首次运行需要build +docker compose up --build +# 再次运行则不需要 +docker compose up + +``` + +#### 通过 [http://localhost:8000/docs](http://localhost:8000/docs) 访问 API。 + +#### 示例流程 + +##### (查询用户记忆（没有继续往后）->添加用户记忆->查询用户记忆) + +##### 添加用户记忆 http://localhost:8000/product/add (POST) +```bash +# 请求参数 +{ + "user_id": "8736b16e-1d20-4163-980b-a5063c3facdc", + "mem_cube_id": "b32d0977-435d-4828-a86f-4f47f8b55bca", + "async_mode": "async", + "messages": [ + { + "role": "user", + "content": "我喜欢草莓" + } + ] +} +# 响应 +{ + "code": 200, + "message": "Memory created successfully", + "data": null +} +``` + +##### 查询用户记忆 http://localhost:8000/product/search (POST) +```bash +# 请求参数 +{ + "query": "我喜欢什么", + "user_id": "8736b16e-1d20-4163-980b-a5063c3facdc", + "mem_cube_id": "b32d0977-435d-4828-a86f-4f47f8b55bca" +} + +# 响应 +{ + "code": 200, + "message": "Search completed successfully", + "data": { + "text_mem": [ + { + "cube_id": "7231eda8-6c57-4f6e-97ce-98b699eebb98", + "memories": [ + { + "id": "2f40be8f-736c-4a5f-aada-9489037769e0", + "memory": "[user观点]用户喜欢草莓。", + "metadata": { + "user_id": "de8215e3-3beb-4afc-9b64-ae594d62f1ea", + "session_id": "root_session", + "status": "activated", + "type": "fact", + "key": "用户对草莓的喜好", + "confidence": 0.99, + "source": null, + "tags": [ + "喜好", + "草莓" + ], + "visibility": null, + "updated_at": "2025-09-18T08:23:44.625479000+00:00", + "memory_type": "UserMemory", + "sources": [], + "embedding": [], + "created_at": "2025-09-18T08:23:44.625511000+00:00", + "usage": [ + "{ + \"time\": \"2025-09-18T08:24:17.759748\", + \"info\": { + \"user_id\": \"de8215e3-3beb-4afc-9b64-ae594d62f1ea\", + \"session_id\": \"root_session\" + } + }" + ], + "background": "用户表达了对草莓的喜好，显示出他们在饮食偏好上的倾向。", + "relativity": 0.6349761312470591, + "vector_sync": "success", + "ref_id": "[2f40be8f]", + "id": "2f40be8f-736c-4a5f-aada-9489037769e0", + "memory": "[user观点]用户喜欢草莓。" + }, + "ref_id": "[2f40be8f]" + } + ] + }, + ... + ], + "act_mem": [], + "para_mem": [] + } +} + +# 响应失败，原因排查 +# src/memos/api/config.py +# 检查get_neo4j_community_config方法中配置的"neo4j_vec_db"和"EMBEDDING_DIMENSION" +``` + + +#### 对服务器代码或库代码进行修改将自动重新加载服务器。 + + +:: + +### 方式三：客户端install 使用 CLI 命令 + +::steps{level="4"} + +#### 安装依赖 + +```bash +# pip install --upgrade pip && pip install --no-cache-dir -r ./docker/requirements.txt +# 使用阿里云源安装依赖 +pip install --no-cache-dir -r ./docker/requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ + + +``` + +#### 在终端中打开运行以下命令进行安装： + +```bash + +# 目前可能需要手动安装的包 这两个包需要找资源 +# neo4j.5.26.4.tar qdrant.v1.15.3.tar +docker load -i neo4j.5.26.4.tar +docker load -i qdrant.v1.15.3.tar +# 查看是否安装成功 +docker images +# 查看是否跑起来了 +docker ps -a + +# 若启动时出现ModuleNotFoundError: No module named 'memos'，是因为路径匹配有问题，请执行 +export PYTHONPATH=/you-file-absolute-path/MemOS/src + +# 根目录 + uvicorn memos.api.server_api:app --host 0.0.0.0 --port 8000 --workers 1 + + + +``` + +#### 访问 API + +启动完成后，通过 [http://localhost:8000/docs](http://localhost:8000/docs) 访问 API。 + + +:: + +### 方式四：不使用 Docker +::steps{level="4"} +#### 参考上方配置环境变量，已经好配置.env文件 + +#### 安装 Poetry 用于依赖管理： + +```bash +curl -sSL https://install.python-poetry.org | python3 - +``` + +#### Poetry 环境变量配置： + +```bash + +#要开始使用，您需要在“PATH”中找到Poetry的bin目录（/Users/jinyunyuan/.local/bin）`环境变量 +# 现代 macOS 系统默认的 Shell 是 zsh。你可以通过以下命令确认 +1. 确定你使用的 Shell + +echo $SHELL +# 如果输出是 /bin/zsh 或 /usr/bin/env zsh，那么你就是 zsh。 +# (如果你的系统版本较老，可能还在使用 bash，输出会是 /bin/bash) +2. 打开对应的 Shell 配置文件 +# 如果使用的是 zsh (绝大多数情况)： +# 使用 nano 编辑器（推荐新手） +nano ~/.zshrc + +# 或者使用 vim 编辑器 +# vim ~/.zshrc +# 如果使用的是 bash： +nano ~/.bash_profile +# 或者 +nano ~/.bashrc + +3. 添加 PATH 环境变量 + +# 在打开的文件的最末尾，新起一行，粘贴安装提示给你的那行命令： +export PATH="/you-path/.local/bin:$PATH" + +4. 保存并退出编辑器 + +# 如果你用的是 nano： +# 按 Ctrl + O 来写入（保存），按 Enter 确认文件名。 +# 然后按 Ctrl + X 退出编辑器。 + +# 如果你用的是 vim： +# 按 i 进入插入模式，粘贴代码后，按 ESC 键退出插入模式。 +# 输入 :wq，然后按 Enter 来保存并退出。 + +5. 使配置立刻生效 +# 刚刚修改的配置文件不会自动在当前已打开的终端窗口生效，你需要运行以下命令之一来重新加载它： + +# 对于 zsh： +source ~/.zshrc + +# 对于 bash： +source ~/.bash_profile + +6. 验证安装是否成功 +# 现在，你可以执行提示中的测试命令来检查一切是否就绪： +poetry --version +# 成功后将显示版本号 Poetry (version 2.2.0) + +``` + +#### 安装所有项目依赖和开发工具： + +```bash +make install +``` + +#### 先在docker中启动 neo4j 和 qdrant + +#### 启动 FastAPI 服务器（在MomOS目录下）： + +```bash +uvicorn memos.api.product_api:app --host 0.0.0.0 --port 8000 --reload +``` + +#### 服务器运行后,您可以使用OpenAPI文档测试API，网址为 [http://localhost:8000/docs](http://localhost:8000/docs) 或者 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) + +#### 测试用例 (注册用户->添加用户记忆->查询用户记忆) 参考Docker Compose up测试用例 + +:: + + +### 方式五：使用 PyCharm 启动 + +#### 运行 server_api +```bash +1、进入MemOS/docker/Dockerfile文件，修改运行配置 +# Start the docker +CMD ["uvicorn", "memos.api.server_api:app", "--host", "0.0.0.0", "--port"，"8000", "--reload"] + +2、进入目录MemOS/src/memos/api 直接运行server_api.py + +``` +## 用户管理 +开源版内置了多用户体系，通过 UserManager 实现资源归属管理： + +创建用户：使用 POST /users 接口创建新用户，并可指定角色（如 USER 或 ADMIN）。 + +自动初始化：系统首次启动或配置时，若指定的 user_id 不存在，会自动创建一个默认用户，确保服务开箱即用。 + +当前信息查询：通过 GET /users/me 接口获取当前登录用户的详细信息及其有权访问的所有 MemCube 列表。 + +## MemCube 空间管理 +MemCube 是 MemOS 中管理记忆的物理与逻辑单位： + +注册空间：通过 POST /mem_cubes 接口注册一个新的存储空间。您需要指定 mem_cube_name_or_path（本地存储路径）和可选的 mem_cube_id。 + +注销空间：使用 DELETE /mem_cubes/{mem_cube_id} 接口移除不再需要的记忆空间。 + +空间分享：开源版特有的分享功能。通过 POST /mem_cubes/{id}/share 接口，可以将特定的记忆空间分享给其他 target_user_id，实现跨用户的记忆协作。 + +## 数据清理与安全性 +数据隔离：系统通过 RequestContextMiddleware 中间件校验请求中的 user_id，确保不同用户之间的数据无法越权访问。 + +一键清空：使用 DELETE /memories/{mem_cube_id} 接口可以快速清空特定空间下的所有记忆数据，该操作不可恢复。 + +## 调用日志与本地监控 +本地日志：系统采用 Python logging 模块，记录所有 API 请求的执行情况、用户创建及配置变更。 + +监控方式：开发者可以直接在服务器终端或部署环境的日志流中监控接口的调用频率与错误记录。 \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/start/overview.md b/content/cn/open_source/open_source_api/start/overview.md new file mode 100644 index 00000000..3c982f54 --- /dev/null +++ b/content/cn/open_source/open_source_api/start/overview.md @@ -0,0 +1,58 @@ +--- +title: 概述 +--- + +## 1. 接口介绍 + +MemOS 开源项目提供了一个使用 FastAPI 编写的 REST API 服务。用户可以通过 REST 接口执行所有操作。 + + +![MemOS Architecture](https://cdn.memtensor.com.cn/img/memos_run_server_success_compressed.png) +
MemOS REST API 服务支持的 API
+ +### 功能特点 + +- 添加新记忆：为指定用户创建一条新的记忆。 +- 搜索记忆：为指定用户搜索其记忆内容。 +- 获取用户所有记忆：获取某个用户的所有记忆内容。 +- 记忆反馈：为指定用户反馈记忆内容。 +- 与 MemOS 对话：与 MemOS 进行对话，返回 SSE 流式响应。 + + +## 2. 入门指南 + +通过以下两个简单的核心步骤开始使用 MemOS 开源项目API： + +* [**添加消息**](/open_source/open_source_api/core/add_message)：通过 POST /memories 接口，储存用户对话中的原始消息内容，生成记忆； + +* [**检索记忆**](/open_source/open_source_api/core/search_memory)：通过 POST /search 接口，检索召回用户的相关记忆片段，为模型生成的回答内容提供参考。 + + +## 3. 接口分类 + +探索 MemOS 提供的丰富功能接口： + +* [**核心记忆接口**](/open_source/open_source_api/core/add_message)：提供记忆核心操作能力，实现记忆生产到消费的全流程。 + +* [**消息相关接口**](/open_source/open_source_api/message/add_feedback)：用于上传与管理原始消息内容数据。 + +* [**MemCube 空间管理**](/open_source/open_source_api/knowledge/create_kb)：用于管理逻辑隔离的存储空间（MemCube），支持注册、注销及跨用户分享。 + + +## 4. 鉴权认证与上下文 + +所有API请求都需要认证，请在请求头的 `Authorization` 中包含您的接口密钥。从[**MemOS 控制台**](https://memos-dashboard.openmem.net/apikeys/)获取接口密钥。 + +::warning +请勿在客户端或公共仓库中暴露您的接口密钥，所有请求都应通过环境变量或服务器端调用进行。 +:: + +RequestContext： 系统内置了 RequestContextMiddleware 中间件，用于处理请求的上下文信息。 + +身份标识： 在请求体或 Header 中包含 user_id，以确保记忆归属于正确的用户。由于是开源环境，您可以根据需求在 middleware 中自定义更高级的 OAuth 或 API Key 校验。 + +## 5. 下一步行动 + +* 👉 [**添加消息**](/api_docs/core/add_message)：生成你的第一条记忆； + +* 👉 [**检索记忆**](/api_docs/core/search_memory)：使用记忆过滤器实现记忆的高级检索。 From 0a14cc7288af893f0625f1db842a15bfde098ea9 Mon Sep 17 00:00:00 2001 From: abby Date: Thu, 5 Feb 2026 15:53:00 -0500 Subject: [PATCH 3/4] docs: update settings.yml to match titles --- content/cn/settings.yml | 24 +++++++++---------- .../modules/memories/neo4j_graph_db.md | 2 +- content/en/settings.yml | 18 +++++++------- 3 files changed, 22 insertions(+), 22 deletions(-) diff --git a/content/cn/settings.yml b/content/cn/settings.yml index c0dca056..a42d4260 100644 --- a/content/cn/settings.yml +++ b/content/cn/settings.yml @@ -41,19 +41,19 @@ nav: - "(ri:lightbulb-line) 核心概念": open_source/home/core_concepts.md - "(ri:building-2-line) 架构设计": open_source/home/architecture.md - "(ri:file-code-line) REST API 服务": open_source/getting_started/rest_api_server.md - - "(ri:code-line) 示例": open_source/getting_started/examples.md + - "(ri:code-line) MemOS示例": open_source/getting_started/examples.md - "(ri:cpu-line) MemOS": - - "(ri:eye-line) 概览": open_source/modules/mos/overview.md - - "(ri:checkbox-multiple-blank-line) 记忆立方": open_source/modules/mem_cube.md - - "(ri:book-open-line) 记忆读取": open_source/modules/mem_reader.md - - "(ri:calendar-line) 记忆调度": open_source/modules/mem_scheduler.md - - "(ri:calendar-line) 使用记忆进行聊天": open_source/modules/mem_chat.md - - "(ri:feedback-line) 记忆修正": open_source/modules/mem_feedback.md + - "(ri:eye-line) API 开发指南": open_source/modules/mos/overview.md + - "(ri:checkbox-multiple-blank-line) MemCube记忆立方": open_source/modules/mem_cube.md + - "(ri:book-open-line) MemReader记忆读取": open_source/modules/mem_reader.md + - "(ri:calendar-line) MemScheduler记忆调度": open_source/modules/mem_scheduler.md + - "(ri:calendar-line) MemChat使用记忆进行聊天": open_source/modules/mem_chat.md + - "(ri:feedback-line) MemFeedback记忆反馈": open_source/modules/mem_feedback.md - "(ri:brain-line) 记忆系统": - - "(ri:database-2-line) 概览": open_source/modules/memories/overview.md + - "(ri:database-2-line) 记忆模块总览": open_source/modules/memories/overview.md - "(ri:book-2-line) 明文记忆": - "(ri:file-text-line) 简单明文记忆": open_source/modules/memories/naive_textual_memory.md - "(ri:file-text-line) 通用明文记忆": open_source/modules/memories/general_textual_memory.md @@ -71,12 +71,12 @@ nav: - "(ri:tools-line) Coze空间配置Memos的MCP": open_source/best_practice/mcp_for_cozespace_and_tools.md - "(ri:heart-line) 贡献指南": - - "(ri:eye-line) 总览": open_source/contribution/overview.md - - "(ri:tools-line) 环境配置": open_source/contribution/setting_up.md + - "(ri:eye-line) 参与 MemOS 开发": open_source/contribution/overview.md + - "(ri:tools-line) 配置开发环境": open_source/contribution/setting_up.md - "(ri:git-branch-line) 开发流程": open_source/contribution/development_workflow.md - "(ri:git-commit-line) 提交规范": open_source/contribution/commit_guidelines.md - - "(ri:article-line) 文档编写": open_source/contribution/writing_docs.md - - "(ri:flask-line) 测试编写": open_source/contribution/writing_tests.md + - "(ri:article-line) 文档编写指南": open_source/contribution/writing_docs.md + - "(ri:flask-line) 如何编写测试": open_source/contribution/writing_tests.md - "(ri:file-code-line) API 参考文档": api-reference/search-memories diff --git a/content/en/open_source/modules/memories/neo4j_graph_db.md b/content/en/open_source/modules/memories/neo4j_graph_db.md index 9478f253..1de5bcb9 100644 --- a/content/en/open_source/modules/memories/neo4j_graph_db.md +++ b/content/en/open_source/modules/memories/neo4j_graph_db.md @@ -1,5 +1,5 @@ --- -title: Graph Memory Backend +title: Neo4j Graph Database desc: "This module provides graph-based memory storage and querying for memory-augmented systems such as RAG, cognitive agents, or personal memory assistants.
It defines a clean abstraction (`BaseGraphDB`) and includes a production-ready implementation using **Neo4j**." --- diff --git a/content/en/settings.yml b/content/en/settings.yml index 4e77b5f0..be01d452 100644 --- a/content/en/settings.yml +++ b/content/en/settings.yml @@ -36,15 +36,15 @@ nav: - "(ri:github-line) Open Source": - "(ri:rocket-line) Getting Started": - - "(ri:install-line) Installation": open_source/getting_started/installation.md + - "(ri:install-line) Installation Guide": open_source/getting_started/installation.md - "(ri:bookmark-line) Your First Memory": open_source/getting_started/your_first_memory.md - "(ri:lightbulb-line) Core Concepts": open_source/home/core_concepts.md - "(ri:building-2-line) Architecture": open_source/home/architecture.md - "(ri:file-code-line) REST API Server": open_source/getting_started/rest_api_server.md - - "(ri:code-line) Examples": open_source/getting_started/examples.md + - "(ri:code-line) MemOS Examples": open_source/getting_started/examples.md - "(ri:cpu-line) MOS": - - "(ri:eye-line) Overview": open_source/modules/mos/overview.md + - "(ri:eye-line) API Development Guide": open_source/modules/mos/overview.md - "(ri:checkbox-multiple-blank-line) MemCube": open_source/modules/mem_cube.md - "(ri:book-open-line) MemReader": open_source/modules/mem_reader.md - "(ri:calendar-line) MemScheduler": open_source/modules/mem_scheduler.md @@ -53,7 +53,7 @@ nav: - "(ri:brain-line) Memories": - - "(ri:database-2-line) Overview": open_source/modules/memories/overview.md + - "(ri:database-2-line) Memory Modules Overview": open_source/modules/memories/overview.md - "(ri:book-2-line) Plaintext Memory": - "(ri:file-text-line) Naive Textual Memory": open_source/modules/memories/naive_textual_memory.md - "(ri:file-text-line) General Textual Memory": open_source/modules/memories/general_textual_memory.md @@ -66,17 +66,17 @@ nav: - "(ri:star-line) Best Practice": - "(ri:speed-line) Performance Tuning": open_source/best_practice/performance_tuning.md - - "(ri:wifi-line) Network Workarounds": open_source/best_practice/network_workarounds.md + - "(ri:wifi-line) Network Environment Adaptation": open_source/best_practice/network_workarounds.md - "(ri:error-warning-line) Common Errors & Solutions": open_source/best_practice/common_errors_solutions.md - - "(ri:tools-line) MCP for Coze Space and Tools": open_source/best_practice/mcp_for_cozespace_and_tools.md + - "(ri:tools-line) Configuring Memos MCP in Coze Space": open_source/best_practice/mcp_for_cozespace_and_tools.md - "(ri:heart-line) Contribution": - - "(ri:eye-line) Overview": open_source/contribution/overview.md + - "(ri:eye-line) Contributing to MemOS": open_source/contribution/overview.md - "(ri:tools-line) Setting Up": open_source/contribution/setting_up.md - "(ri:git-branch-line) Development Workflow": open_source/contribution/development_workflow.md - "(ri:git-commit-line) Commit Guidelines": open_source/contribution/commit_guidelines.md - - "(ri:article-line) Writing Docs": open_source/contribution/writing_docs.md - - "(ri:flask-line) Writing Tests": open_source/contribution/writing_tests.md + - "(ri:article-line) Documentation Writing Guidelines": open_source/contribution/writing_docs.md + - "(ri:flask-line) How to Write Unit Tests": open_source/contribution/writing_tests.md - "(ri:file-code-line) API Reference": api-reference/search-memories From 4f25b624415e8279ba226be4ca36599aa5c88287 Mon Sep 17 00:00:00 2001 From: abby Date: Thu, 5 Feb 2026 22:13:44 -0500 Subject: [PATCH 4/4] docs: modified and rearranged opensource api docs --- .../getting_started/your_first_memory.md | 2 +- content/cn/open_source/home/architecture.md | 2 +- .../open_source/open_source_api/chat/chat.md | 124 ++--- .../open_source_api/core/add_memory.md | 71 +++ .../open_source_api/core/add_message.md | 248 --------- .../open_source_api/core/delete_memory.md | 100 ++-- .../open_source_api/core/get_memory.md | 106 ++-- .../open_source_api/core/get_memory_by_id.md | 58 ++ .../open_source_api/core/search_memory.md | 133 ++--- .../open_source_api/message/add_feedback.md | 77 --- .../open_source_api/message/feedback.md | 78 +++ .../open_source_api/message/get_status.md | 63 --- .../message/get_suggestion_queries.md | 70 +++ .../open_source_api/scheduler/ wait.md | 77 +++ .../open_source_api/scheduler/get_status.md | 97 ++++ .../open_source_api/start/configuration.md | 514 +----------------- .../open_source_api/start/overview.md | 60 +- .../open_source_api/tools/check_cube.md | 50 ++ .../open_source_api/tools/get_user_names.md | 53 ++ content/en/open_source/modules/mem_cube.md | 2 +- 20 files changed, 782 insertions(+), 1203 deletions(-) create mode 100644 content/cn/open_source/open_source_api/core/add_memory.md delete mode 100644 content/cn/open_source/open_source_api/core/add_message.md create mode 100644 content/cn/open_source/open_source_api/core/get_memory_by_id.md delete mode 100644 content/cn/open_source/open_source_api/message/add_feedback.md create mode 100644 content/cn/open_source/open_source_api/message/feedback.md delete mode 100644 content/cn/open_source/open_source_api/message/get_status.md create mode 100644 content/cn/open_source/open_source_api/message/get_suggestion_queries.md create mode 100644 content/cn/open_source/open_source_api/scheduler/ wait.md create mode 100644 content/cn/open_source/open_source_api/scheduler/get_status.md create mode 100644 content/cn/open_source/open_source_api/tools/check_cube.md create mode 100644 content/cn/open_source/open_source_api/tools/get_user_names.md diff --git a/content/cn/open_source/getting_started/your_first_memory.md b/content/cn/open_source/getting_started/your_first_memory.md index 3ab9caf5..5dd31ad3 100644 --- a/content/cn/open_source/getting_started/your_first_memory.md +++ b/content/cn/open_source/getting_started/your_first_memory.md @@ -1,5 +1,5 @@ --- -title: 你的第一个记忆 +title: 创建你的第一个记忆 desc: "动手实战！我们将带你使用 **SimpleStructMemReader** 从对话中提取记忆，并把它存进 **TreeTextMemory** 里。" --- diff --git a/content/cn/open_source/home/architecture.md b/content/cn/open_source/home/architecture.md index b6335ec0..db140498 100644 --- a/content/cn/open_source/home/architecture.md +++ b/content/cn/open_source/home/architecture.md @@ -1,5 +1,5 @@ --- -title: 架构 +title: 架构设计 desc: MemOS 由**核心模块**组成，这些模块协同工作，将您的 LLM 转变为真正的**记忆增强系统**——从编排到存储到检索。 --- ## 核心模块 diff --git a/content/cn/open_source/open_source_api/chat/chat.md b/content/cn/open_source/open_source_api/chat/chat.md index 546a91b2..924aa8c1 100644 --- a/content/cn/open_source/open_source_api/chat/chat.md +++ b/content/cn/open_source/open_source_api/chat/chat.md @@ -1,120 +1,86 @@ --- title: 对话 -desc: MemOS 提供的一站式对话接口，内置完整的记忆召回与自动管理能力，无需手动拼接上下文。 +desc: 集成“检索、生成、存储”全链路的 RAG 闭环接口，支持基于 MemCube 的个性化回复与记忆自动沉淀。 --- :::note -有关 API 字段、格式等信息的完整列表，详见[Chat 接口文档](/api_docs/chat/chat)。 +有关API字段、格式等信息的完整列表，详见[Chat 接口文档](/api_docs/chat/chat)。 ::: -**接口路径**：`POST /product/chat/complete` 或 `POST /product/chat/stream` -**功能描述**：这是 MemOS 最核心的端到端接口。它整合了“记忆检索”、“Prompt 自动拼装”与“大模型生成”全链路，让您的 AI 应用原生具备长期记忆。 +**接口路径**： +* **全量响应**：`POST /product/chat/complete` +* **流式响应 (SSE)**：`POST /product/chat/stream` +**功能描述**：本接口是 MemOS 的核心业务编排入口。它能够自动从指定的 `readable_cube_ids` 中召回相关记忆，结合当前语境生成回复，并可选地将对话结果自动回写至 `writable_cube_ids` 中，实现 AI 应用的自我进化。 -## 1. 为什么使用 Chat 接口？ - -* **一体化对话能力**：仅需调用一个接口传入当前用户提问，即可获得结合了历史记忆的回答，无需自建复杂的 RAG 链路。 -* **记忆自动化循环**：通过 `add_message_on_answer` 参数，系统在回答的同时会自动加工并写入新记忆，形成闭环。 -* **持久“上下文”理解**：在跨轮次、跨天甚至跨会话中保持连贯，让模型持续“记住”用户的偏好。 +## 1. 核心架构：ChatHandler 编排流程 +1. **记忆检索 (Retrieval)**：根据 `readable_cube_ids` 调用 **SearchHandler**，从隔离的 Cube 中提取相关的事实、偏好及工具背景。 +2. **上下文增强生成 (Generation)**：将检索到的记忆片段注入 Prompt，调用指定的 LLM（通过 `model_name_or_path`）生成针对性回复。 +3. **记忆自动闭环 (Storage)**：若开启 `add_message_on_answer=true`，系统会调用 **AddHandler** 将本次对话异步存入指定的 Cube，无需开发者手动调用添加接口。 ## 2. 关键接口参数 -基于开源版 `src/api/routers/client.py` 的实现，`chat` 接口包含丰富的配置项： - -### 核心参数 +### 2.1 身份与语境 | 参数名 | 类型 | 必填 | 说明 | | :--- | :--- | :--- | :--- | -| `query` | `str` | 是 | 用户的当前提问内容。 | -| `user_id` | `str` | 是 | 用于识别用户身份并检索对应的私有记忆。 | -| `conversation_id` | `str` | 是 | 标识当前会话，用于维持短期对话连贯性。 | +| **`query`** | `str` | 是 | 用户当前的提问内容。 | +| **`user_id`** | `str` | 是 | 用户唯一标识，用于鉴权与数据隔离。 | +| `history` | `list` | 否 | 短期历史对话记录，用于维持当前会话的连贯性。 | +| `session_id` | `str` | 否 | 会话 ID。作为“软信号”提升该会话内相关记忆的召回权重。 | -### 记忆与控制参数 +### 2.2 MemCube 读写控制 | 参数名 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | -| `add_message_on_answer` | `bool` | `False` | **关键功能**：设为 `True` 时，回答完成后自动调用 `add_message` 将对话存入记忆。 | -| `include_preference` | `bool` | `True` | 是否在生成回答时参考用户的偏好记忆。 | -| `knowledgebase_ids` | `list` | `None` | 指定需要包含的知识库 ID 列表，实现 RAG 增强。 | -| `system_prompt` | `str` | `None` | 自定义系统级提示词，覆盖默认配置。 | -| `temperature` | `float` | `None` | 控制生成随机性（0.0-1.0）。 | +| **`readable_cube_ids`** | `list` | - | **读：** 允许检索的记忆 Cube 列表（可跨个人库与公共库）。 | +| **`writable_cube_ids`** | `list` | - | **写：** 对话完成后，自动生成的记忆应存入的目标 Cube 列表。 | +| **`add_message_on_answer`** | `bool` | `true` | 是否开启自动回写。建议开启以维持记忆的持续更新。 | -## 3. 工作原理 +### 2.3 算法与模型配置 +| 参数名 | 类型 | 默认值 | 说明 | +| :--- | :--- | :--- | :--- | +| `mode` | `str` | `fast` | 检索模式：`fast` (快速), `fine` (精细), `mixture` (混合)。 | +| `model_name_or_path` | `str` | - | 指定使用的 LLM 模型名称或路径。 | +| `system_prompt` | `str` | - | 覆盖默认的系统提示词。 | +| `temperature` | `float` | - | 采样温度，控制生成文本的创造性。 | +| `threshold` | `float` | `0.5` | 记忆召回的相关性阈值，低于该值的记忆将被剔除。 | +## 3. 工作原理 +MemOS提供两种响应模式可供选型： +### 3.1 全量响应 (`/complete`) +* **特点**：等待模型生成全部内容后一次性返回 JSON。 +* **场景**：非交互式任务、后台逻辑处理、或对实时性要求较低的简单应用。 -1. **发起请求**：AI 应用调用 `chat` 接口，传入 `user_id`、`query` 等参数。 -2. **自动召回**：MemOS 异步并发从个人记忆空间及关联知识库中提取相关事实。 -3. **Prompt 拼装**：系统将用户记忆、系统指令与当前问题拼接为完整 Prompt。 -4. **模型回答**：调用指定的大模型生成回复，并返回给应用。 -5. **异步加工**：若开启 `add_message_on_answer`，系统在后台自动将本轮对话更新为记忆。 +### 3.2 流式响应 (`/stream`) +* **特点**：采用 **Server-Sent Events (SSE)** 协议，实时推送 Token。 +* **场景**：聊天机器人、智能助手等需要即时打字机反馈效果的 UI 交互。 ## 4. 快速上手 推荐使用开源版内置的 `MemOSClient` 进行调用。以下示例展示了如何询问关于 R 语言学习的建议，并利用记忆功能： ```python -import os from memos.api.client import MemOSClient -# 初始化客户端，指向本地服务地址 -client = MemOSClient( - api_key="YOUR_LOCAL_API_KEY", - base_url="http://localhost:8000/product" -) +client = MemOSClient(api_key="...", base_url="...") -# 发起对话：系统会自动查找用户之前关于“R语言”或“可视化”的记忆 +# 发起对话请求 res = client.chat( - user_id="memos_user_123", - conversation_id="session_r_study", - query="我最近在学 R 语言，除了 ggplot2，还有什么推荐的数据可视化包吗？", - add_message_on_answer=True, # 自动存储本次对话为新记忆 - include_preference=True # 开启偏好召回 + user_id="dev_user_01", + 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" # 使用精细检索模式 ) if res: - print(f"AI 建议: {res.data}") + print(f"AI 回复内容: {res.data}") ``` -## 5. 更多功能 - -除了一键复制上述快速开始代码，本接口还提供了丰富的其他可配置参数，您可以根据业务需求灵活调用 `chat` 接口。 - -### 5.1 筛选召回的记忆 - -通过以下参数，您可以实现精细化的记忆检索控制： - -| **功能** | **字段** | **说明** | -| :--- | :--- | :--- | -| **记忆过滤器** | `filter` | 支持传入 JSON 结构的逻辑条件，用于按标签、元信息或时间筛选记忆。 | -| **召回偏好记忆** | `include_preference` / `preference_limit_number` | 开启后，AI 会参考用户的隐性/显式偏好。 | -| **检索指定知识库** | `knowledgebase_ids` | 用于指定本次对话可访问的关联知识库范围。 | - -### 5.2 调整模型回答 - -您可以直接在请求中调整底层大模型的生成表现，或通过 `/configure` 接口进行全局设置。 - -| **功能** | **字段** | **说明 & 可选值** | -| :--- | :--- | :--- | -| **选定模型** | `model_name` | 指定使用的模型名称。开源版默认模型可在环境配置中通过 `MOS_CHAT_MODEL` 定义。 | -| **自定义指令** | `system_prompt` | 支持传入自定义系统提示词，覆盖默认的记忆安全协议指令。 | -| **流式回答控制** | `async_mode` | 对应接口 `/product/chat/stream`。开启后支持流式输出，提升交互体验。 | -| **温度系数** | `temperature` | 控制生成随机性。建议范围 0.0 - 2.0，默认值为 0.7。 | -| **候选词范围** | `top_p` | 控制生成时的采样范围。默认值为 0.95。 | -| **长度限制** | `max_tokens` | 限制单次回复的最大 Token 数。默认值为 8192。 | - - - -### 5.3 闭环记忆自动化 - -这是开源版的核心特色，支持在对话过程中自动完成记忆的维护： - -| **功能** | **字段** | **说明** | -| :--- | :--- | :--- | -| **自动生成记忆** | `add_message_on_answer` | 开启后（True），系统会自动将用户消息与模型回复处理为新记忆。 | -| **关联元信息** | `info` / `tags` | 为本次对话生成的记忆打上业务标签或存储自定义元数据。 | -| **实体关联** | `agent_id` / `app_id` | 将记忆关联到特定的 Agent 或应用，方便多应用间的数据隔离。 | :::note **开发者提示：** -在开源版本中，所有默认参数均可在项目的 `DEFAULT_CONFIG` 中找到并进行初始化修改。 +若需要针对 `Playground` 环境进行调试，请访问专用的调试流接口 /product/chat/stream/playground 。 ::: \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/core/add_memory.md b/content/cn/open_source/open_source_api/core/add_memory.md new file mode 100644 index 00000000..8c446400 --- /dev/null +++ b/content/cn/open_source/open_source_api/core/add_memory.md @@ -0,0 +1,71 @@ +--- +title: 添加记忆 (Add Memory) +desc: MemOS 的核心生产接口。通过 MemCube 隔离机制，实现个人记忆、知识库及多租户场景下的异步记忆生产。 +--- + +**接口路径**：`POST /product/add` +**功能描述**：这是系统存储非结构化数据的核心入口。它支持通过对话列表、纯文本或元数据，将原始数据转化为结构化的记忆片段。在开源版中，系统通过 **MemCube** 实现记忆的物理隔离与动态组织。 + +## 1. 核心机理：MemCube 与隔离 + +在开源架构中，理解 MemCube 是高效使用接口的关键： + +* **隔离单元**：MemCube 是记忆生成的原子单位，Cube 之间完全独立，系统仅在单个 Cube 内部进行去重和冲突解决。 +* **灵活映射**： + * **个人模式**：将 `user_id` 作为 `writable_cube_ids` 传入，即建立个人私有记忆。 + * **知识库模式**：将知识库的唯一标识（QID）作为 `writable_cube_ids` 传入，内容即存入该知识库。 +* **多目标写入**：接口支持同时向多个 Cube 写入记忆，实现跨域同步。 + + +## 2. 关键接口参数 + +核心参数定义如下： + +| 参数名 | 类型 | 必填 | 默认值 | 说明 | +| :--- | :--- | :--- | :--- | :--- | +| **`user_id`** | `str` | 是 | - | 用户唯一标识符，用于权限校验。 | +| **`messages`** | `list/str`| 是 | - | 待存储的消息列表或纯文本内容。 | +| **`writable_cube_ids`** | `list[str]`| 是 | - | **核心参数**：指定写入的目标 Cube ID 列表。 | +| **`async_mode`** | `str` | 否 | `async` | 处理模式：`async` (后台队列处理) 或 `sync` (当前请求阻塞)。 | +| **`is_feedback`** | `bool` | 否 | `false` | 若为 `true`，系统将自动路由至反馈处理器执行记忆更正。 | +| `session_id` | `str` | 否 | `default` | 会话标识符，用于追踪对话上下文。 | +| `custom_tags` | `list[str]`| 否 | - | 自定义标签，可作为后续搜索时的过滤条件。 | +| `info` | `dict` | 否 | - | 扩展元数据。其中的所有键值对均支持后续过滤检索。 | +| `mode` | `str` | 否 | - | 仅在 `async_mode='sync'` 时生效，可选 `fast` (快速) 或 `fine` (精细)。 | + +## 3. 工作原理 (Component & Handler) + +当请求到达后端时，系统由 **AddHandler** 调度核心组件执行以下逻辑： + +1. **多模态解析**：由 `MemReader` 组件将 `messages` 转化为内部记忆对象。 +2. **反馈路由**：若 `is_feedback=True`，Handler 会提取对话末尾作为反馈，直接修正已有记忆，不生成新事实。 +3. **异步分发**：若为 `async` 模式，`MemScheduler` 将任务推入任务队列，接口立即返回 `task_id`。 +4. **内部组织**：算法在目标 Cube 内执行组织逻辑，通过去重和融合优化记忆质量。 + +## 4. 快速上手示例 + +推荐使用 `MemOSClient` SDK 进行标准化调用： + +```python +from memos.api.client import MemOSClient + +# 初始化客户端 +client = MemOSClient(api_key="...", base_url="...") + +# 场景一：为个人用户添加记忆 +client.add_message( + user_id="sde_dev_01", + writable_cube_ids=["user_01_private"], + messages=[{"role": "user", "content": "我正在学习 R 语言的 ggplot2。"}], + async_mode="async", + custom_tags=["Programming", "R"] +) +# 场景二：往知识库导入内容并开启反馈 +client.add_message( + user_id="admin_01", + writable_cube_ids=["kb_finance_2026"], + messages="2026年财务审计流程已更新，请参考附件。", + is_feedback=True, # 标记为反馈以更正旧版流程 + info={"source": "Internal_Portal"} +) +``` \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/core/add_message.md b/content/cn/open_source/open_source_api/core/add_message.md deleted file mode 100644 index 1469767a..00000000 --- a/content/cn/open_source/open_source_api/core/add_message.md +++ /dev/null @@ -1,248 +0,0 @@ ---- -title: 添加消息 -desc: MemOS 会将您通过接口提交的消息内容，自动处理并持久化为可检索、可召回的个人记忆。 ---- -::warning -**[直接看 API文档 点这里哦](/api_docs/core/add_message)** -
-
- -**本文聚焦于开源项目的功能说明，详细接口字段及限制请点击上方文字链接查看** -:: - -**接口路径**：`POST /product/add` -**功能描述**：这是 MemOS 的核心生产接口。它支持通过对话列表、纯文本或元数据信息，将原始数据转化为结构化的记忆片段，实现 AI 应用的长期记忆能力。 - -## 1. 为什么记忆很重要？ - -在开源版 MemOS 中，添加消息是构建 AI “懂用户”能力的起点： -* **跨会话长期记忆**：能够实现跨会话的长期记忆，避免对话结束后信息丢失。 -* **个性化积累**：随着交互不断积累，让 AI 越来越“懂用户”。 -* **动态更新**：在会话过程中持续写入新信息，动态更新用户记忆。 -* **共享体验**：在您的多个应用或产品之间，共享同一用户的记忆，实现一致的用户体验。 - -## 2. 关键接口参数 - -根据开源代码 `src/api/routers/client.py` 的实现，该接口接受以下核心参数： - -### 核心标识 -| 参数名 | 类型 | 必填 | 说明 | -| :--- | :--- | :--- | :--- | -| `user_id` | `str` | 是 | 用于标识消息所属的唯一用户。 | -| `conversation_id` | `str` | 是 | 用于标识消息所属的唯一会话。 | -| `messages` | `list` | 是 | 对话内容列表，格式为 `[{"role": "user", "content": "..."}]`。 | - -### 扩展配置 -| 参数名 | 类型 | 默认值 | 说明 | -| :--- | :--- | :--- | :--- | -| `tags` | `list[str]` | `None` | 为当前消息添加自定义标签，用于后续记忆过滤。 | -| `async_mode` | `bool` | `True` | 控制添加消息后的处理方式。开启后系统将异步生产记忆。 | -| `info` | `dict` | `None` | 自定义元信息（如 `scene`, `biz_id`），支持后续高级过滤检索。 | -| `allow_public` | `bool` | `False` | 控制生成的记忆是否写入项目级公共记忆空间。 | - -## 3. 工作原理 - - - -当您通过 `POST /product/add` 提交请求后，系统内部将执行以下逻辑： -1. **请求校验**：通过 `RequestContextMiddleware` 校验请求来源及其身份有效性。 -2. **信息提取**：使用内部 LLM 从消息中提取事实、偏好等内容，处理为事实记忆、偏好记忆或工具记忆。 -3. **冲突解决**：系统会自动检查现有记忆是否有重复或矛盾，并完成更新。 -4. **记忆储存**：最终产生的记忆将使用向量数据库与图数据库储存。 - -## 4. 快速上手示例 - -您可以直接使用项目中封装的 `MemOSClient` 进行调用： - -```python -import os -from memos.api.client import MemOSClient - -# 初始化客户端 -# 默认 base_url 指向本地 8000 端口的 /product -client = MemOSClient( - api_key="YOUR_LOCAL_API_KEY", - base_url="http://localhost:8000/product" -) - -# 添加一组对话消息 -res = client.add_message( - user_id="memos_user_123", - conversation_id="conv_2026_01", - messages=[ - {"role": "user", "content": "我计划今年暑假去大连看海。"}, - {"role": "assistant", "content": "大连是个不错的选择，我会记得您的旅行计划。"} - ], - tags=["travel_plan"], - info={"priority": "high"} -) - -if res and res.code == 200: - print("✅ 记忆添加成功") -``` -## 5. 使用场景 - -### 5.1 实时导入对话 - -您可以在用户每次收到模型回复时，实时调用接口同步对话。MemOS 将在后端不断根据新的对话更新用户记忆。 - -```python -import os -from memos.api.client import MemOSClient - -# 初始化客户端，默认指向本地开发环境地址 -client = MemOSClient( - api_key="YOUR_LOCAL_API_KEY", - base_url="http://localhost:8001/product" -) - -def sync_chat_to_memos(user_id, conversation_id, messages): - # 调用开源版客户端封装的 add_message 方法 - res = client.add_message( - user_id=user_id, - conversation_id=conversation_id, - messages=messages, - async_mode=True # 实时同步建议使用异步模式，不阻塞主流程 - ) - - if res and res.code == 200: - print(f"✅ 记忆实时同步成功") - else: - print(f"❌ 同步失败") - -# 示例：同步一组实时生成的对话 -sync_chat_to_memos( - user_id="memos_user_123", - conversation_id="conv_realtime_001", - messages=[ - {"role": "user", "content": "我最近在自学 R 语言，对数据可视化很感兴趣。"}, - {"role": "assistant", "content": "这很棒！R 语言的 ggplot2 包是数据可视化的神器。"} - ] -) -``` -### 5.2 导入历史对话 -```python -如果您已经构建了 AI 对话应用，MemOS 支持批量导入已有聊天记录，帮助助手建立初始记忆。 - -# 示例历史对话数据格式 -history_messages = [ - {"role": "user", "content": "我喜欢吃辣的食物"}, - {"role": "assistant", "content": "明白啦，我记住了，你喜欢辣味的食物。"}, - {"role": "user", "content": "但我又不太喜欢重油的，比如麻辣火锅之类的"} -] - -# 批量导入建议关闭 async_mode 以确保导入顺序和完整性 -client.add_message( - user_id="memos_user_123", - conversation_id="history_import_01", - messages=history_messages, - async_mode=False -) -``` -这是为你整理的开源版 添加消息 (Add Message) 文档中“使用场景”与“更多功能”部分的 Markdown 源代码。 - -我已将示例代码从云服务的原始 requests 方式，修改为直接调用你提供的开源版 MemOSClient 方式，这更符合开源项目的使用习惯。 - -Markdown - -## 5. 使用场景 - -### 5.1 实时导入对话 - -您可以在用户每次收到模型回复时，实时调用接口同步对话。MemOS 将在后端不断根据新的对话更新用户记忆。 - -```python -import os -from memos.api.client import MemOSClient - -# 初始化客户端，默认指向本地开发环境地址 -client = MemOSClient( - api_key="YOUR_LOCAL_API_KEY", - base_url="http://localhost:8001/product" -) - -def sync_chat_to_memos(user_id, conversation_id, messages): - # 调用开源版客户端封装的 add_message 方法 - res = client.add_message( - user_id=user_id, - conversation_id=conversation_id, - messages=messages, - async_mode=True # 实时同步建议使用异步模式，不阻塞主流程 - ) - - if res and res.code == 200: - print(f"✅ 记忆实时同步成功") - else: - print(f"❌ 同步失败") - -# 示例：同步一组实时生成的对话 -sync_chat_to_memos( - user_id="memos_user_123", - conversation_id="conv_realtime_001", - messages=[ - {"role": "user", "content": "我最近在自学 R 语言，对数据可视化很感兴趣。"}, - {"role": "assistant", "content": "这很棒！R 语言的 ggplot2 包是数据可视化的神器。"} - ] -) -5.2 导入历史对话 -如果您已经构建了 AI 对话应用，MemOS 支持批量导入已有聊天记录，帮助助手建立初始记忆。 - -Python - -# 示例历史对话数据格式 -history_messages = [ - {"role": "user", "content": "我喜欢吃辣的食物"}, - {"role": "assistant", "content": "明白啦，我记住了，你喜欢辣味的食物。"}, - {"role": "user", "content": "但我又不太喜欢重油的，比如麻辣火锅之类的"} -] - -# 批量导入建议关闭 async_mode 以确保导入顺序和完整性 -client.add_message( - user_id="memos_user_123", - conversation_id="history_import_01", - messages=history_messages, - async_mode=False -) -``` -### 5.3 记录用户偏好或行为 -除了对话内容，用户的个人偏好、兴趣问卷等结构化数据也可以导入，作为记忆的一部分。 -```python -# 示例用户兴趣信息导入 -client.add_message( - user_id="memos_user_123", - conversation_id="user_profile_001", - messages=[ - { - "role": "user", - "content": """ - 喜欢的电影类型: 科幻, 动作 - 运动习惯: 跑步, 健身 - 饮食偏好: 偏爱辣, 健康饮食 - """ - } - ], - tags=["profile", "preference"] # 使用标签便于后续筛选 -) -``` -## 6. 更多功能 - -开源版 `add_message` 提供了丰富的配置参数，支持精细化的记忆管理与多维度的数据归属。 - -:::note -有关 API 字段定义及格式的完整列表，请参考 [Add Message 详细接口文档](/api_docs/core/add_message)。 -::: - -| **功能** | **字段** | **说明** | -| :--- | :--- | :--- | -| **关联实体** | `agent_id` / `app_id` | 将当前用户的对话消息关联到具体的 Agent 或应用 ID，便于后续按实体维度检索记忆。 | -| **消息列表** | `messages` | 核心对话内容列表。支持 `user` / `assistant` / `system` / `tool` 等角色。 | -| **处理模式** | `async_mode` | 默认为 `True`。开启后系统异步提取记忆并快速返回；关闭则接口会阻塞直至记忆生产完成。 | -| **自定义标签** | `tags` | 为消息添加自定义标签（如 `feedback`），用于后续记忆过滤及高级图召回。 | -| **扩展元信息** | `info` | 自定义键值对字典。建议使用 `biz_id` 或 `scene` 等已索引字段以获得更优的检索性能。 | -| **公共记忆** | `allow_public` | 默认为 `False`。若开启，该消息生成的记忆将共享给项目下的所有用户。 | -| **写入知识库** | `allow_knowledgebase_ids` | 控制生成的记忆是否同步写入指定的知识库 ID 列表中，实现记忆与知识库的联动。 | - -:::note -**开发者提示：** -在开源版 MemOS 中，所有的请求校验（如参数缺失）和业务异常均由 `APIExceptionHandler` 统一捕获，并返回标准化的错误响应格式。 -::: \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/core/delete_memory.md b/content/cn/open_source/open_source_api/core/delete_memory.md index c8721b3b..e24af068 100644 --- a/content/cn/open_source/open_source_api/core/delete_memory.md +++ b/content/cn/open_source/open_source_api/core/delete_memory.md @@ -1,86 +1,62 @@ --- -title: 删除记忆 -desc: 从 MemOS 删除记忆,支持批量删除。 +title: 删除记忆 (Delete Memory) +desc: 从指定的 MemCube 中永久移除记忆条目、关联文件或符合特定过滤条件的记忆集合。 --- -::warning -**[直接看 API文档 点这里哦](/api_docs/core/delete_memory)** -
-
+**接口路径**：`POST /product/delete_memory` +**功能描述**：本接口用于维护记忆库的准确性与合规性。当用户要求遗忘特定信息、数据过时或需要清理特定的上传文件时，可以通过此接口在向量数据库与图数据库中同步执行物理删除。 -**本文聚焦于功能说明，详细接口字段及限制请点击上方文字链接查看** -:: +## 1. 核心机理：Cube 级物理清理 -**接口路径**：`POST /product/delete_memory` -**功能描述**：当某条记忆已过期、不再准确或根据用户隐私要求需要移除时，可以使用此接口从向量数据库与图数据库中永久删除指定的记忆内容。 +在开源版中，删除操作遵循严格的 **MemCube** 隔离逻辑： -## 1. 关键参数 +* **作用域限制**：通过 `writable_cube_ids` 参数，删除操作被严格锁定在指定的记忆体中，绝不会误删其他 Cube 的内容。 +* **多维删除**：支持按 **记忆 ID**（精确）、**文件 ID**（关联删除）以及 **Filter 过滤器**（条件逻辑）三种维度并发执行清理。 +* **原子性同步**：删除操作由 **MemoryHandler** 触发，确保底层向量索引与图数据库中的实体节点同步移除，防止召回“幻觉”。 -* **记忆 ID 列表（memory\_ids[]）**：每条存储在 MemOS 中的记忆都对应一个唯一标识符，支持以列表形式传入，用于精确删除一条或多条指定记忆。 -根据开源代码 `src/api/routers/client.py` 的实现，删除操作需要以下两个核心列表参数： -| 参数名 | 类型 | 必填 | 说明 | -| :--- | :--- | :--- | :--- | -| **用户 ID 列表 (`user_ids`)** | `list[str]` | 是 | 指定这些记忆所属的用户标识列表。 | -| **记忆 ID 列表 (`memory_ids`)** | `list[str]` | 是 | 每条记忆的唯一标识符列表。您可以通过检索接口获取此 ID。 | -:::note -**如何获取待删除记忆的记忆ID** -
-
-在检索记忆（`search/memory`）和获取记忆（`get/memory`）时，返回结果中的每条记忆都包含唯一的 `id` 字段，作为该记忆的唯一标识符。
-当发现某条记忆已过期或不符合预期时，可直接取 `id`，并作为 `memory_ids[]` 参数传入 `delete/memory` 接口，即可删除对应的记忆条目。 -::: +## 2. 关键接口参数 +核心参数定义如下： +| 参数名 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | +| **`writable_cube_ids`** | `list[str]` | 是 | 指定执行删除操作的目标 Cube 列表。 | +| **`memory_ids`** | `list[str]` | 否 | 待删除的记忆唯一标识符列表。 | +| **`file_ids`** | `list[str]` | 否 | 待删除的原始文件标识符列表，将同步清理该文件产生的全部记忆。 | +| **`filter`** | `object` | 否 | 逻辑过滤器。支持按标签、元信息或时间戳批量删除符合条件的记忆。 | -## 2. 工作原理 +## 3. 工作原理 (MemoryHandler) -1. **请求路由**：请求发送至 `server_api.py` 统一定义的路由入口。 -2. **逻辑校验**：系统通过 `_validate_required_params` 确保 `user_ids` 和 `memory_ids` 均不为空。 -3. **物理移除**：MemOS 会同步清理底层向量数据库中的向量索引，以及图数据库中的实体关联。 -4. **异常处理**：若删除过程中出现业务逻辑错误，将由 `APIExceptionHandler` 返回标准化的 400 或 500 响应。 +1. **权限与路由**：系统通过 `user_id` 校验操作权限，并将请求路由至 **MemoryHandler**。 +2. **定位存储**：根据 `writable_cube_ids` 定位底层的 **naive_mem_cube** 组件。 +3. **分发清理任务**： + * **按 ID 清理**：直接根据 UUID 在主数据库和向量库中执行记录抹除。 + * **按 Filter 清理**：先检索出符合条件的记忆 ID 集合，再执行批量物理移除。 +4. **状态反馈**：操作完成后返回成功状态，相关内容将立即从 [**检索接口**](./search_memory.md) 的召回范围中消失。 -## 3. 快速上手 +## 4. 快速上手示例 -推荐使用项目中封装的 `MemOSClient` 进行批量删除操作： +使用 `MemOSClient` 执行不同维度的删除操作： ```python -import os -from memos.api.client import MemOSClient - # 初始化客户端 -client = MemOSClient( - api_key="YOUR_LOCAL_API_KEY", - base_url="http://localhost:8001/product" -) +client = MemOSClient(api_key="...", base_url="...") -# 准备待删除的记忆信息 -target_users = ["memos_user_123"] -target_memories = [ - "4a50618f-797d-4c3b-b914-94d7d1246c8d", - "b210928a-1234-5678-90ab-cdef12345678" -] - -# 执行删除操作 -res = client.delete_memory( - user_ids=target_users, - memory_ids=target_memories +# 场景一：精确删除单条已知的错误记忆 +client.delete_memory( + writable_cube_ids=["user_01_private"], + memory_ids=["2f40be8f-736c-4a5f-aada-9489037769e0"] ) -if res and res.code == 200: - print("✅ 指定记忆已成功删除") - +# 场景二：批量清理某一特定标签下的所有过时记忆 +client.delete_memory( + writable_cube_ids=["kb_finance_2026"], + filter={"tags": {"contains": "deprecated_policy"}} +) ``` - -::note - 想知道是否删除成功？ -一键复制上述代码并运行，再次[检索记忆](/memos_cloud/mem_operations/search_memory)，看看记忆是否删除成功？ -:: - -## 4. 注意事项 +## 5. 注意事项 不可恢复性：删除操作是物理删除。一旦执行成功，该记忆将无法再通过检索接口召回。 -批量效率：建议将需要删除的 ID 整合在一次请求中处理，以减少网络开销并利用后端的批量清理机制。 - -校验机制：开源版要求显式传入 `user_ids`，这为多租户或多用户场景下的数据安全提供了双重保障，防止误删其他用户的记忆。 \ No newline at end of file +文件关联性：通过 `file_ids` 删除时，系统会自动溯源并清理该文件解析出的事实记忆和摘要。 diff --git a/content/cn/open_source/open_source_api/core/get_memory.md b/content/cn/open_source/open_source_api/core/get_memory.md index 3bc44ad7..d4353ae1 100644 --- a/content/cn/open_source/open_source_api/core/get_memory.md +++ b/content/cn/open_source/open_source_api/core/get_memory.md @@ -1,77 +1,81 @@ --- -title: 获取记忆 -desc: 分页查询并列出指定用户的所有记忆内容，支持深度过滤与分类筛选。 +title: 获取记忆 (Get Memories) +desc: 分页查询或全量导出指定 Cube 中的记忆集合，支持按类型过滤及子图提取。 --- -::warning -**[直接看 API文档 点这里哦](/api_docs/core/get_memory)** -
-
+**接口路径**： +* **分页查询**：`POST /product/get_memory` +* **全量导出**：`POST /product/get_all` -**本文聚焦于开源项目的功能说明，详细接口字段及限制请点击上方文字链接查看** -:: +**功能描述**：用于列出或导出指定 **MemCube** 中的记忆资产。通过这两个接口，您可以获取系统生成的原始记忆片段、用户偏好或工具使用记录，支持分页展示与结构化导出。 -**接口路径**：`POST /product/get_memory` -**功能描述**：与侧重于语义匹配的“检索”接口不同，“获取”接口主要用于管理目的。它允许开发者以分页的方式列出指定用户的所有记忆（事实、偏好及工具记忆），常用于构建用户记忆画像展示页或后台管理界面。 +## 1. 核心机理：分页 vs. 全量导出 -## 1. 为什么需要“获取”接口？ +在开源版中，系统通过 **MemoryHandler** 提供了两种不同的集合访问模式： -* **全局视图**：无需输入查询语句即可查看用户已有的全部记忆资产。 -* **分页管理**：支持 `page` 和 `size` 参数，能够高效处理拥有数千条记忆的高级用户数据。 -* **精确清理前置**：在执行删除操作前，通过此接口确认记忆的 `id`。 +* **业务分页模式 (`/get_memory`)**： + * **设计初衷**：为前端 UI 列表设计。支持 `page` 和 `page_size` 参数。 + * **特性**：默认包含偏好记忆（`include_preference`），支持轻量级的数据加载。 +* **全量导出模式 (`/get_all`)**： + * **设计初衷**：为数据迁移或复杂关系分析设计。 + * **核心能力**：支持传入 `search_query` 提取相关的**子图（Subgraph）**，或按 `memory_type`（文本/动作/参数）导出全量数据。 -## 2. 关键参数说明 +## 2. 关键接口参数 + +### 2.1 分页查询参数 (`/get_memory`) | 参数名 | 类型 | 必填 | 说明 | | :--- | :--- | :--- | :--- | -| **`user_id`** | `str` | 是 | 关联用户的唯一标识符。 | -| **`include_preference`** | `bool` | 否 | 是否返回偏好记忆（默认为 `True`）。 | -| **`page`** | `int` | 否 | 分页页码，默认从 `1` 开始。 | -| **`size`** | `int` | 否 | 每页返回的记忆条目数量（建议最大不超过 50）。 | -| **`filter`** | `dict` | 否 | 结构化过滤器。支持按 `create_time` 或自定义 `info` 字段精确锁定。 | - +| **`mem_cube_id`** | `str` | 是 | 目标 MemCube ID。 | +| **`user_id`** | `str` | 否 | 用户唯一标识符。 | +| **`page`** | `int` | 否 | 页码（从 1 开始）。若设为 `None` 则尝试全量导出。 | +| **`page_size`** | `int` | 否 | 每页条目数。 | +| `include_preference` | `bool` | 否 | 是否包含偏好记忆。 | +### 2.2 全量/子图导出参数 (`/get_all`) -## 3. 工作原理 - -1. **多级过滤**：系统根据提供的 `user_id` 定位私有存储空间。 -2. **分类聚合**：根据 `include_preference` 和 `include_tool_memory` 参数，从不同的存储索引中聚合数据。 -3. **分页切片**：利用 `page` 和 `size` 对聚合后的结果集进行切片处理，降低网络传输压力。 -4. **结果返回**：返回包含记忆 ID、内容、标签及创建时间的数据列表。 +| 参数名 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | +| **`user_id`** | `str` | 是 | 用户 ID。 | +| **`memory_type`** | `str` | 是 | 记忆类型：`text_mem`, `act_mem`, `para_mem`。 | +| `mem_cube_ids` | `list` | 否 | 待导出的 Cube ID 列表。 | +| `search_query` | `str` | 否 | 若提供，将基于此查询召回并返回相关的记忆子图。 | -## 4. 快速上手示例 +## 3. 快速上手示例 -通过 `MemOSClient` 快速拉取用户的记忆列表： +### 3.1 前端分页展示 (SDK 调用) ```python -from memos.api.client import MemOSClient - -# 初始化客户端 -client = MemOSClient( - api_key="YOUR_LOCAL_API_KEY", - base_url="http://localhost:8000/product" -) - -# 获取用户最近的 10 条记忆，包含偏好信息 +# 获取第一页，每页 10 条记忆 res = client.get_memory( - user_id="memos_user_123", - include_preference=True, + user_id="sde_dev_01", + mem_cube_id="cube_research_01", page=1, - size=10 + page_size=10 ) -if res and res.code == 200: - for memory in res.data.get('memory_detail_list', []): - print(f"ID: {memory['id']} | 内容: {memory['memory_value']}") +for mem in res.data: + print(f"[{mem['type']}] {mem['memory_value']}") +``` +### 3.2 导出特定的事实记忆子图 +```python +# 提取与“R 语言”相关的全部事实记忆 +res = client.get_all( + user_id="sde_dev_01", + memory_type="text_mem", + search_query="R language visualization" +) ``` -## 5. 使用场景 -### 5.1 构建用户画像看板 -展示“AI 对你的印象”或“已记住的偏好”。由于该接口支持分页，非常适合瀑布流或列表展示。 +## 4. 响应结构说明 +接口返回标准的业务响应，其中 data 包含记忆对象数组。每条记忆通常包含以下核心字段： + +`id`: 记忆唯一标识，用于执行 获取详情 或 删除 操作。 + +`memory_value`: 经过算法加工后的记忆文本。 -### 5.2 数据审计与纠偏 -您可以定期通过此接口扫描某个用户的记忆条目，配合过滤器查找是否存在过时的业务标签（如 custom_status='deprecated'），并利用删除记忆接口进行清理。 +`tags`: 关联的自定义标签。 -### 5.3 导出记忆资产 -支持将用户的记忆批量拉取并导出，方便进行离线分析或跨平台的数据迁移。 \ No newline at end of file +::note +开发者提示： 如果您已知记忆 ID 并希望查看其完整的元数据（如 confidence 或 usage 记录），请使用`获取记忆详情`（Get_ memory_by_id）接口。 ::: \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/core/get_memory_by_id.md b/content/cn/open_source/open_source_api/core/get_memory_by_id.md new file mode 100644 index 00000000..ba11f6a9 --- /dev/null +++ b/content/cn/open_source/open_source_api/core/get_memory_by_id.md @@ -0,0 +1,58 @@ +--- +title: 获取记忆详情 (Get Memory Detail) +desc: 通过记忆唯一标识符 (ID) 获取单条记忆的完整元数据，包括置信度、背景信息及使用记录。 +--- + +**接口路径**：`GET /product/get_memory/{memory_id}` +**功能描述**：本接口允许开发者检索单条记忆的所有底层细节。与返回摘要信息的检索接口不同，此接口会暴露该记忆的生命周期数据（如向量同步状态、AI 提取背景等），是系统管理与故障排查的核心工具。 + +## 1. 为什么需要获取详情？ + +* **元数据透视**：查看 AI 在提取该条记忆时的 `confidence`和 `background`。 +* **生命周期检验**：确认该记忆的 `vector_sync`（向量同步）是否成功，以及其 `updated_at` 时间戳。 +* **使用追踪**：通过 `usage` 记录，追踪该记忆在哪些会话中被召回并辅助了生成。 + + +## 2. 关键接口参数 + +该接口采用标准的 RESTful 路径参数形式： + +| 参数名 | 位置 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | :--- | +| **`memory_id`** | Path | `str` | 是 | 记忆的唯一标识符（UUID）。您可以从 [**获取记忆列表**](./get_memory_list.md) 或 [**检索**](./search_memory.md) 的结果中获得此 ID。 | + +## 3. 工作原理 (MemoryHandler) + +1. **直通查询**：由 **MemoryHandler** 直接绕过业务编排层，与底层核心组件 **naive_mem_cube** 交互。 +2. **数据补全**：系统会从持久化数据库中拉取完整的 `metadata` 字典并返回，不进行任何语义截断。 + +## 4. 响应数据详解 + +响应体中的 `data` 对象包含以下核心字段： + +| 字段名 | 说明 | +| :--- | :--- | +| **`id`** | 记忆唯一标识符。 | +| **`memory`** | 记忆的文本内容，通常包含标注（如 `[user观点]`）。 | +| **`metadata.confidence`** | AI 提取该记忆的置信度分数（0.0 - 1.0）。 | +| **`metadata.type`** | 记忆分类，如 `fact` (事实) 或 `preference` (偏好)。 | +| **`metadata.background`** | 详细描述 AI 为何提取该记忆及其上下文背景。 | +| **`metadata.usage`** | 列表形式，记录该记忆被模型使用的历史时间与环境。 | +| **`metadata.vector_sync`**| 向量数据库同步状态，通常为 `success`。 | + +## 5. 快速上手示例 + +使用 SDK 发起详情查询： + +```python +# 假设已知一条记忆的 ID +mem_id = "2f40be8f-736c-4a5f-aada-9489037769e0" + +# 获取完整详情 +res = client.get_memory_by_id(memory_id=mem_id) + +if res and res.code == 200: + metadata = res.data.get('metadata', {}) + print(f"记忆背景: {metadata.get('background')}") + print(f"同步状态: {metadata.get('vector_sync')}") +``` \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/core/search_memory.md b/content/cn/open_source/open_source_api/core/search_memory.md index f1bfc637..245fddae 100644 --- a/content/cn/open_source/open_source_api/core/search_memory.md +++ b/content/cn/open_source/open_source_api/core/search_memory.md @@ -1,112 +1,95 @@ --- -title: 检索记忆 -desc: 通过语义检索和过滤功能，MemOS召回相关记忆。 +title: 检索记忆 (Search Memory) +desc: 基于 MemCube 隔离机理，利用语义检索和逻辑过滤从记忆库中召回最相关的上下文信息。 --- -::warning -**[直接看 API文档 点这里哦](/api_docs/core/search_memory)** -
-
- -**本文聚焦于开源项目的功能说明，详细接口字段及限制请点击上方文字链接查看** -:: - **接口路径**：`POST /product/search` -**功能描述**：当用户提出问题时，MemOS 会结合开发者预设的过滤条件，从海量记忆中召回最相关、最重要的片段。这些片段可作为大模型的上下文，显著提升回答的准确性与个性化程度。 +**功能描述**：本接口是 MemOS 实现检索增强生成 (RAG) 的核心。它能够跨越多个隔离的 **MemCube** 进行语义匹配，自动召回相关的事实、用户偏好及工具调用记录。 -## 1. 什么是检索记忆？ +## 1. 核心机理：Readable Cubes -检索记忆是指系统根据用户当前的 `query`（查询内容），利用向量相似度匹配和逻辑过滤，从存储的“事实记忆”和“偏好记忆”中提取关键信息。 +与云服务的单一用户视角不同，开源版接口通过 **`readable_cube_ids`** 实现了极其灵活的检索范围控制： + +* **跨 Cube 检索**：您可以同时指定多个 Cube ID（如 `[用户私有Cube, 企业公共知识库Cube]`），算法会并行从这些隔离的记忆体中召回最相关内容。 +* **软信号权重**：通过传入 `session_id`，系统会在召回时优先考虑该会话内的内容。这仅作为提升相关性的“权重”，而非强制过滤。 +* **绝对隔离**：未包含在 `readable_cube_ids` 列表中的 Cube 内容在算法层是完全不可见的，确保了多租户环境下的数据安全性。 -::note -** 为什么需要检索记忆？** -
-* **增强可靠性**：无需为模型手动构建复杂的上下文，直接获取经过验证的记忆片段。 -* **高度相关性**：通过过滤器（Filter）确保召回的内容始终贴合当前的业务语境。 -
-:: ## 2. 关键接口参数 -根据开源代码 `client.py` 的定义，检索接口支持以下参数： +核心检索参数定义如下： +### 检索基础 | 参数名 | 类型 | 必填 | 说明 | | :--- | :--- | :--- | :--- | -| `query` | `str` | 是 | 检索的自然语言问题。系统将基于此内容进行语义匹配。 | -| `user_id` | `str` | 是 | 指定检索哪位用户的记忆库。 | -| `conversation_id` | `str` | 否 | 提供当前会话 ID 可增加该会话内记忆的权重，提升回复连贯性。 | -| `memory_limit_number` | `int` | 否 | 默认召回 6 条。限制返回的事实记忆数量。 | -| `filter` | `dict` | 否 | 基于 JSON 的逻辑条件，用于按标签、时间或元信息缩小范围。 | -| `include_preference` | `bool` | 否 | 是否同时召回该用户的偏好记忆（显式/隐式偏好）。 | +| **`query`** | `str` | 是 | 用户的搜索查询语句，系统将基于此进行语义匹配。 | +| **`user_id`** | `str` | 是 | 请求发起者的唯一标识，用于鉴权与上下文追踪。 | +| **`readable_cube_ids`**| `list[str]`| 是 | **核心参数**：指定本次检索可读取的 Cube ID 列表。 | +| **`mode`** | `str` | 否 | **搜索策略**：可选 `fast` (快速), `fine` (精细), `mixture` (混合)。 | -## 3. 工作原理 +### 召回控制 +| 参数名 | 类型 | 默认值 | 说明 | +| :--- | :--- | :--- | :--- | +| **`top_k`** | `int` | `10` | 召回文本记忆的数量上限。 | +| **`include_preference`**| `bool` | `true` | 是否召回相关的用户偏好记忆（显式/隐式偏好）。 | +| **`search_tool_memory`**| `bool` | `true` | 是否召回相关的工具调用记录。 | +| **`filter`** | `dict` | - | 逻辑过滤器，支持按标签或元数据进行精确过滤。 | +| **`dedup`** | `str` | - | 去重策略：`no` (不去重), `sim` (语义去重), `None` (默认精确文本去重)。 | +## 3. 工作原理 (SearchHandler 策略) +当请求到达后端时，**SearchHandler** 会根据指定的 `mode` 调用不同的组件执行检索： -1. **查询预处理**：MemOS 会对输入的 `query` 进行清理与语义增强，以提升向量检索的效果。 -2. **逻辑过滤**：结合 `filter` 参数中的运算符（如 `contains`, `gt` 等）初步筛选记忆范围。 -3. **语义检索**：基于嵌入（Embedding）向量，在向量数据库中寻找相似度最高的内容。 -4. **结果排序**：根据 `relativity`（相关性分数）和时间权重对记忆片段进行排序并返回。 +1. **查询重写**：利用 LLM 对用户的 `query` 进行语义增强，提升匹配精度。 +2. **多模式匹配**： + * **Fast 模式**：通过向量索引进行快速召回，适用于对响应速度要求极高的场景。 + * **Fine 模式**：增加重排序（Rerank）环节，提升召回内容的相关度。 + * **Mixture 模式**：结合语义搜索与图谱搜索，召回更具深度的关联记忆。 +3. **多维聚合**：系统并行检索事实、偏好（`pref_top_k`）和工具记忆（`tool_mem_top_k`），并将结果聚合返回。 +4. **后处理去重**：根据 `dedup` 配置对高度相似的记忆条目进行压缩。 ## 4. 快速上手示例 -使用开源版 `MemOSClient` 快速执行一次记忆检索： +通过 SDK 进行多 Cube 联合检索： ```python from memos.api.client import MemOSClient -# 初始化客户端 -client = MemOSClient( - api_key="YOUR_LOCAL_API_KEY", - base_url="http://localhost:8001/product" -) +client = MemOSClient(api_key="...", base_url="...") -# 执行检索 +# 场景：同时检索用户记忆和两个专业知识库 res = client.search_memory( - user_id="memos_user_123", - conversation_id="conv_2026_09", - query="我暑假想去旅游，根据我的偏好推荐个城市", - memory_limit_number=5, - include_preference=True # 同时获取用户的偏好，如“喜欢安静”、“偏好南方” + user_id="sde_dev_01", + query="根据我之前的偏好，推荐一些 R 语言的可视化方案", + # 传入可读的 Cube 列表，包括个人空间和两个知识库 + readable_cube_ids=["user_01_private", "kb_r_lang", "kb_data_viz"], + mode="fine", # 使用精细模式以获得更准确的推荐 + include_preference=True, # 召回“用户喜欢简洁风格”等偏好 + top_k=5 ) if res: - # 打印召回的事实记忆 - for mem in res.memory_detail_list: - print(f"Key: {mem['memory_key']}, Value: {mem['memory_value']}") + # 结果包含在 memory_detail_list 中 + print(f"召回结果: {res.data}") ``` -## 5. 使用场景 - -### 5.1 增强对话上下文 -在与 AI 对话的过程中，您可以调用 MemOS 检索与当前用户发言最相关的记忆，并将其填充到大模型的回复提示词中。 -::note -`conversation_id`为非必填项，如填写可以帮助 MemOS 理解当前会话的上下文，提升本会话相关记忆的权重，使对话模型的回复内容更加连贯。 -:: - -### 5.2 用户整体画像分析 -不指定 `conversation_id` 且使用全局查询（如“我的兴趣关键词是什么？”），可以获取用户在所有会话中积累的属性特征，帮助生成个性化画像。 - -### 5.3 进阶过滤器检索 -您可以利用 `filter `字段实现复杂的筛选逻辑。例如：只搜索标签包含“学习计划”且创建时间晚于特定日期的记忆。 - +## 5.进阶：使用过滤器 (Filter) +SearchHandler 支持复杂的过滤器，以满足更细粒度的业务需求： ```python -# 示例：组合过滤器 + +# 示例：仅搜索标签为 "Programming" 且创建于 2026 年之后的记忆 search_filter = { "and": [ - {"tags": {"contains": "学习计划"}}, - {"create_time": {"gt": "2025-11-09"}} + {"tags": {"contains": "Programming"}}, + {"created_at": {"gt": "2026-01-01"}} ] } -``` -## 6. 更多功能 - -::note - 有关 API 字段、格式等信息的完整列表，详见[Search Memory接口文档](/api_docs/core/search_memory)。 -:: -| **功能** | **相关字段** | **说明** | -| -------------- | --------------------------------------------------- | ------------------------------------------------------------ | -| 召回偏好记忆 | `include_preference`
 
`preference_limit_number` | 偏好记忆是 MemOS 基于用户历史消息分析生成的用户偏好信息。开启后，可在检索结果中召回用户偏好记忆。 | -| 召回工具记忆 | `include_tool_memory`
 
`tool_memory_limit_number` | 工具记忆是 MemOS 对已添加的工具调用信息进行分析后生成的记忆。开启后，可在检索结果中召回工具记忆，详见[工具调用](/memos_cloud/features/advanced/tool_calling)。 | -| 检索指定知识库 | `knowledgebase_ids` | 用于指定本次检索可访问的项目关联知识库范围。开发者可借此实现精细的权限控制，灵活定义不同终端用户可访问的知识库集合，详见[知识库](/memos_cloud/features/advanced/knowledge_base)。 | + +res = client.search_memory( + query="数据清洗逻辑", + user_id="sde_dev_01", + readable_cube_ids=["user_01_private"], + filter=search_filter +) +``` \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/message/add_feedback.md b/content/cn/open_source/open_source_api/message/add_feedback.md deleted file mode 100644 index e154fa51..00000000 --- a/content/cn/open_source/open_source_api/message/add_feedback.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: 添加反馈 -desc: 提交用户对大模型回复的反馈内容，帮助 MemOS 实时更正、优化或删除不准确的记忆。 ---- - -::warning -**[直接看 API文档 点这里哦](/api_docs/message/get_status)** -
-
- -**本文聚焦于开源项目的功能说明，详细接口字段及限制请点击上方文字链接查看** -:: - -**接口路径**：`POST /product/feedback` -**功能描述**：当您发现大模型的回答基于了错误的记忆，或者用户的偏好发生了变化时，可以通过此接口提交反馈。MemOS 会分析反馈内容，并据此调整存储在向量库和图数据库中的相关条目。 - -## 1. 为什么需要添加反馈？ - -* **记忆纠偏**：MemOS 能够基于用户的反馈更正已有记忆，解决信息过时或提取错误的问题。 -* **强化偏好**：通过正向或负向反馈，让 AI 更好地理解用户的隐性偏好。 -* **提升准确性**：反馈内容会作为后续记忆生产的参考，防止 AI 重复犯同样的错误。 - -## 2. 关键接口参数 -本接口接受以下参数： - -| 参数名 | 类型 | 必填 | 说明 | -| :--- | :--- | :--- | :--- | -| **`user_id`** | `str` | 是 | 反馈内容所关联的用户唯一标识符。 | -| **`conversation_id`** | `str` | 是 | 反馈内容所关联的会话唯一标识符。 | -| **`feedback_content`** | `str` | 是 | 反馈的文本内容（例如：“我不喜欢吃辣了”或“你记错我的名字了”）。 | -| `feedback_time` | `str` | 否 | 反馈发生的时间，支持结构化或自然语言描述。 | -| `agent_id` / `app_id` | `str` | 否 | 关联的 Agent 或应用标识，用于实现精细化的记忆隔离。 | -| `allow_public` | `bool` | 否 | 是否允许将由此反馈产生的修正记忆写入公共记忆库。 | - -## 3. 工作原理 - -1. **反馈接收**：系统接收到 `feedback_content` 后，结合当前 `conversation_id` 的语境进行解析。 -2. **冲突检测**：AI 会检查反馈内容是否与现有记忆库中的事实存在冲突。 -3. **记忆更正**：如果发现冲突，系统会更新原有的事实条目；如果是新信息，则作为补充记忆存入。 -4. **实时生效**：更正后的记忆在下一次调用 [**检索记忆**](./search_memory.md) 时即可被正确召回。 - -## 4. 快速上手示例 - -推荐使用项目中封装的 `MemOSClient` 提交反馈： - -```python -from memos.api.client import MemOSClient - -# 初始化客户端 -client = MemOSClient( - api_key="YOUR_LOCAL_API_KEY", - base_url="http://localhost:8000/product" -) - -# 提交反馈以更正记忆 -res = client.add_feedback( - user_id="memos_user_123", - conversation_id="conv_888", - feedback_content="我最近开始尝试清淡饮食了，不再喜欢重辣的食物。", - feedback_time="2026-02-04", - tags=["preference_update"] -) - -if res and res.code == 200: - print("✅ 反馈已接收，系统正在更正记忆...") -``` - - -## 5. 使用场景 -### 5.1 纠正 AI 的错误推断 -如果 AI 之前根据对话错误地总结了用户的名字或职业，用户可以直接反馈：“我的名字是 Grace，不是 Gray”。MemOS 会自动修正 `UserMemory` 中的相关条目。 - -### 5.2 更新过时的用户偏好 -用户的喜好会随时间改变。通过记录反馈（如饮食习惯、旅游倾向的变化），可以确保 AI 生成的建议始终符合用户现状。 - -### 5.3 跨实体记忆同步 -通过指定 `allow_knowledgebase_ids`，反馈产生的修正结果可以同步写入关联的知识库，让所有相关 Agent 都能获取到最新的信息。 \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/message/feedback.md b/content/cn/open_source/open_source_api/message/feedback.md new file mode 100644 index 00000000..49cdd4de --- /dev/null +++ b/content/cn/open_source/open_source_api/message/feedback.md @@ -0,0 +1,78 @@ +--- +title: 添加反馈 +desc: 提交用户对大模型回复的反馈内容，帮助 MemOS 实时更正、优化或删除不准确的记忆。 +--- + + +**接口路径**：`POST /product/feedback` +**功能描述**：本接口用于处理用户对 AI 回复或记忆内容的反馈。通过分析 `feedback_content`，系统可以自动定位并修改存储在 **MemCube** 中的错误事实，或根据用户的正负反馈调整记忆的权重。 + +## 1. 核心机理：记忆纠偏循环 + +**FeedbackHandler** 提供了比普通添加接口更精细的控制逻辑： + +* **精确修正 (Precise Correction)**：通过提供 `retrieved_memory_ids`，系统可以直接针对某几条特定的检索结果进行更正，避免误伤其他记忆。 +* **语境分析**：结合 `history`（对话历史），系统能够理解反馈背后的真实意图（例如“你说错了，我现在的公司是 A 而不是 B”）。 +* **结果回显**：如果开启 `corrected_answer=true`，接口在处理完记忆更正后，会尝试返回一个基于新事实生成的更正后回答。 + +## 2. 关键接口参数 +本接口核心参数定义如下： + +| 参数名 | 类型 | 必填 | 默认值 | 说明 | +| :--- | :--- | :--- | :--- | :--- | +| **`user_id`** | `str` | 是 | - | 用户唯一标识符。 | +| **`history`** | `list` | 是 | - | 最近的对话历史，用于提供反馈的语境。 | +| **`feedback_content`** | `str` | 是 | - | **核心：** 用户的反馈文本内容。 | +| **`writable_cube_ids`**| `list` | 否 | - | 需要执行记忆更正的目标 Cube 列表。 | +| `retrieved_memory_ids` | `list` | 否 | - | 可选。上一次检索出的、需要被修正的特定记忆 ID 列表。 | +| `async_mode` | `str` | 否 | `async` | 处理模式：`async` (后台处理) 或 `sync` (实时处理并等待)。 | +| `corrected_answer` | `bool` | 否 | `false` | 是否需要系统在修正记忆后返回一个纠正后的新回答。 | +| `info` | `dict` | 否 | - | 附加元数据。 | + +## 3. 工作原理 + +1. **冲突检测**：`FeedbackHandler` 接收反馈后，会对比 `history` 与 `writable_cube_ids` 中现有的记忆事实。 +2. **定位与更新**： + * 若提供了 `retrieved_memory_ids`，则直接更新对应节点。 + * 若未提供 ID，系统通过语义匹配找到最相关的过时记忆进行覆盖或标记为无效。 +3. **权重调整**：对于态度模糊的反馈，系统会调整特定记忆条目的 `confidence`（置信度）或可信度等级。 +4. **异步生产**：在 `async` 模式下，修正逻辑由 `MemScheduler` 异步执行，接口立即返回 `task_id`。 + +## 4. 快速上手示例 + + +```python +from memos.api.client import MemOSClient + +client = MemOSClient(api_key="...", base_url="...") + +# 场景：修正 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 重新根据新事实回复我 +) + +if res and res.code == 200: + print(f"修正进度: {res.message}") + if res.data: + print(f"更正后的回复: {res.data}") +``` + + +## 5. 使用场景 +### 5.1 纠正 AI 的错误推断 +人工干预：在管理后台提供“纠错”按钮，当管理员发现 AI 提取的记忆条目有误时，调用此接口进行人工更正。 +### 5.2 更新过时的用户偏好 +用户即时纠偏：在对话 UI 中，如果用户说出类似“记错了”、“不是这样的”等话语，可以自动触发此接口，利用 is_feedback=True 实现记忆的实时净化。 + +::note +如果反馈涉及的是公共知识库，请确保当前用户拥有对该 Cube 的写入权限。 +:: \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/message/get_status.md b/content/cn/open_source/open_source_api/message/get_status.md deleted file mode 100644 index c8f5e7d1..00000000 --- a/content/cn/open_source/open_source_api/message/get_status.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: 获取任务状态 -desc: 获取异步处理任务（如记忆生产、文档解析）的实时执行状态。 ---- - -::warning -**[直接看 API文档 点这里哦](/api_docs/message/get_status)** -
-
- -**本文聚焦于开源项目的功能说明，详细接口字段及限制请点击上方文字链接查看** -:: -**接口路径**：`POST /product/get/status` -**功能描述**：MemOS 在处理复杂的记忆提取或大规模文档导入时，通常采用异步模式。本接口允许开发者通过任务 ID 查询后台任务的执行情况，确保记忆生产流程的透明化。 - -## 1. 为什么需要此接口？ - -* **异步追踪**：当 `add_message` 以 `async_mode=True` 调用时，接口会立即返回响应，而实际的记忆提取逻辑在后台运行。 -* **失败排查**：如果任务执行失败，可以通过此接口获取具体的错误原因。 -* **流程控制**：在构建复杂 Agent 时，确保记忆已成功“入库”后再执行后续的高级搜索操作。 - -## 2. 关键参数说明 - -根据开源代码 `client.py` 中的 `get_task_status` 方法定义，核心参数如下： - -| 参数名 | 类型 | 必填 | 说明 | -| :--- | :--- | :--- | :--- | -| **`task_id`** | `str` | 是 | 异步任务的唯一标识符。该 ID 通常在调用 `add_message` 或 `add_knowledgebase_file` 后获得。 | - -## 3. 工作原理 - -1. **状态查询**：系统根据 `task_id` 在内部任务队列中检索记录。 -2. **状态反馈**：返回当前任务的阶段（如 `pending`, `running`, `completed`, `failed`）。 -3. **数据一致性校验**：若状态为 `completed`，通常意味着向量数据库同步（`vector_sync`）已完成，该记忆即可被搜索召回。 - -## 4. 快速上手示例 - -推荐使用项目中封装的 `MemOSClient` 进行状态轮询： - -```python -from memos.api.client import MemOSClient -import time - -# 初始化客户端 -client = MemOSClient( - api_key="YOUR_LOCAL_API_KEY", - base_url="http://localhost:8001/product" -) - -# 假设您在添加消息时获得了一个 task_id -task_id = "async_task_123456789" - -# 轮询任务状态 -while True: - res = client.get_task_status(task_id=task_id) - if res and res.code == 200: - status = res.data.get('status') - print(f"当前任务状态: {status}") - - if status in ['completed', 'failed']: - break - - time.sleep(2) # 建议轮询间隔 2 秒 \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/message/get_suggestion_queries.md b/content/cn/open_source/open_source_api/message/get_suggestion_queries.md new file mode 100644 index 00000000..76ab87bd --- /dev/null +++ b/content/cn/open_source/open_source_api/message/get_suggestion_queries.md @@ -0,0 +1,70 @@ +--- +title: 获取建议问题 (Get Suggestions) +desc: 基于当前对话语境或 Cube 内的近期记忆，自动生成 3 条后续对话建议。 +--- + +# 获取建议问题 (Get Suggestion Queries) + +**接口路径**：`POST /product/suggestions` +**功能描述**：本接口用于实现“猜你想问”功能。系统会根据提供的对话上下文或目标 **MemCube** 中的近期记忆，通过大语言模型生成 3 个相关的建议问题，帮助用户延续对话。 + +## 1. 核心机理：双模式生成策略 + +**SuggestionHandler** 根据入参的不同，支持两种灵活的生成模式： + +* **基于对话的即时建议 (Context-based)**： + * **触发条件**：在请求中提供了 `message`（对话记录）。 + * **逻辑**：系统分析最近的对话内容，生成 3 个与当前话题紧密相关的后续问题。 +* **基于记忆的发现建议 (Memory-based)**： + * **触发条件**：未提供 `message`。 + * **逻辑**：系统会从 `mem_cube_id` 指定的记忆体中检索“最近记忆”，并据此生成与用户近期生活、工作状态相关的启发式问题。 + + + +## 2. 关键接口参数 + +核心参数定义如下： + +| 参数名 | 类型 | 必填 | 默认值 | 说明 | +| :--- | :--- | :--- | :--- | :--- | +| **`user_id`** | `str` | 是 | - | 用户唯一标识符。 | +| **`mem_cube_id`** | `str` | 是 | - | **核心参数**：指定建议生成所依据的记忆空间。 | +| **`language`** | `str` | 否 | `zh` | 生成建议使用的语言：`zh` (中文) 或 `en` (英文)。 | +| `message` | `list/str`| 否 | - | 当前对话上下文。若提供，则生成基于对话的建议。 | + +## 3. 工作原理 (SuggestionHandler) + +1. **语境识别**：`SuggestionHandler` 首先检查 `message` 字段。若有值，则提取对话精髓；若为空，则转向底层 `MemCube` 获取最近动态。 +2. **模板匹配**：系统根据 `language` 参数自动切换内置的中英文提示词模板（Prompt Templates）。 +3. **模型推理**：调用 LLM 对背景资料进行推导，确保生成的 3 个问题既符合逻辑又具有启发性。 +4. **格式化输出**：将建议问题以数组形式返回，便于前端直接渲染为点击按钮。 + +## 4. 快速上手示例 + +使用 SDK 获取针对当前对话的中文建议： + +```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 语言可视化的核心工具。"} + ] +) + +if res and res.code == 200: + # 示例输出: ["如何安装 ggplot2？", "有哪些经典的 ggplot2 教程？", "R 语言还有哪些可视化包？"] + print(f"建议问题: {res.data}") +``` + +## 5. 使用场景建议 +对话引导：在 AI 回复完用户后，自动调用此接口，在回复框下方展示建议按钮，引导用户深入探讨。 + +冷启动激活：当用户进入一个新的会话且尚未发言时，通过“基于记忆模式”展示用户可能感兴趣的往期话题，打破沉默。 \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/scheduler/ wait.md b/content/cn/open_source/open_source_api/scheduler/ wait.md new file mode 100644 index 00000000..e1ddcef7 --- /dev/null +++ b/content/cn/open_source/open_source_api/scheduler/ wait.md @@ -0,0 +1,77 @@ +--- +title: 高级任务同步 (Advanced Task Synchronization) +desc: 提供阻塞等待与流式进度观测能力，确保在执行后续操作前，指定用户的异步任务已全部处理完成。 +--- + + +**接口路径**： +* **同步阻塞等待**：`POST /product/scheduler/wait` +* **实时进度流 (SSE)**：`GET /product/scheduler/wait/stream` + +**功能描述**：在自动化脚本、数据迁移或集成测试场景中，通常需要确保所有的异步记忆提取任务（如 LLM 事实提取、向量入库）已完全结束。本模块接口允许客户端“挂起”请求，直到调度器检测到目标用户的任务队列已清空。 + +## 1. 核心机理：调度器空闲检测 + +系统通过 **SchedulerHandler** 实时监控底层 **MemScheduler** 的运行状态： + +* **队列检查**：系统会检查 Redis Stream 中属于该用户的待处理任务（Pending）及排队任务（Remaining）。 +* **空闲判定**：仅当队列计数为 0 且当前没有 Worker 正在执行该用户的任务时，判定为“空闲 (Idle)”。 +* **超时保护**：为防止无限期阻塞，接口支持设置 `timeout_seconds`。若达到上限任务仍未完成，接口将返回当前状态并停止等待。 + + + +## 2. 关键接口参数 + +这两个接口共享以下查询参数（Query Parameters）： + +| 参数名 | 类型 | 必填 | 默认值 | 说明 | +| :--- | :--- | :--- | :--- | :--- | +| **`user_name`** | `str` | 是 | - | 目标用户的名称或 ID。 | +| `timeout_seconds`| `num` | 否 | - | 最大等待时长（秒）。超过此时间将自动返回。 | +| `poll_interval` | `num` | 否 | - | 内部检查队列状态的频率（秒）。 | + +## 3. 响应模式选型 + +### 3.1 同步阻塞模式 (`/wait`) +* **特点**：标准的 HTTP 响应。连接会保持开启，直到任务清空或超时。 +* **场景**：编写自动化测试脚本或在执行 `search` 前确保数据已入库。 + +### 3.2 实时流模式 (`/wait/stream`) +* **特点**：基于 **Server-Sent Events (SSE)** 技术。 +* **场景**：在管理后台展示动态进度条，实时显示任务队列的缩减过程。 + +## 4. 快速上手示例 + +使用开源版 SDK 进行阻塞式等待： + +```python +from memos.api.client import MemOSClient + +client = MemOSClient(api_key="...", base_url="...") +user_name = "dev_user_01" + +# --- 场景 A：同步阻塞等待 (常用于 Python 自动化脚本) --- +print(f"正在等待用户 {user_name} 的任务队列清空...") +res = client.wait_until_idle( + user_name=user_name, + timeout_seconds=300, + poll_interval=2 +) +if res and res.code == 200: + print("✅ 任务已全部完成。") + +# --- 场景 B：流式进度观测 (常用于前端进度条渲染) --- +print("开始监听任务实时进度流...") +# 注意：SSE 接口在 SDK 中通常返回一个生成器 (Generator) +progress_stream = client.stream_scheduler_progress( + user_name=user_name, + timeout_seconds=300 +) + +for event in progress_stream: + # 实时打印剩余任务数 + print(f"当前排队任务数: {event['remaining_tasks_count']}") + if event['status'] == 'idle': + print("🎉 调度器已空闲") + break +``` \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/scheduler/get_status.md b/content/cn/open_source/open_source_api/scheduler/get_status.md new file mode 100644 index 00000000..624fa394 --- /dev/null +++ b/content/cn/open_source/open_source_api/scheduler/get_status.md @@ -0,0 +1,97 @@ +--- +title: 任务调度与状态监控 (Scheduler Status) +desc: 监控 MemOS 异步任务的生命周期，提供包括任务进度、队列积压及系统负载在内的全方位观测能力。 +--- + +**接口路径**： +* **系统级概览**：`GET /product/scheduler/allstatus` +* **任务进度查询**：`GET /product/scheduler/status` +* **用户队列指标**：`GET /product/scheduler/task_queue_status` + +**功能描述**：本模块接口旨在为开发者提供异步记忆生产链路的可观测性。通过这些接口，您可以实时追踪特定任务的完成状态，监控 Redis 任务队列的积压情况，以及获取整个调度系统的运行指标。 + +## 1. 核心机理：MemScheduler 调度体系 + +在开源架构中，**MemScheduler** 负责处理所有高耗时的后台任务（如 LLM 记忆提取、向量索引构建等）： + +* **状态流转**：任务在生命周期内会经历 `waiting` (等待中)、`in_progress` (执行中)、`completed` (已完成) 或 `failed` (失败) 等状态。 +* **队列监控**：系统基于 Redis Stream 实现任务分发。通过监控 `pending` (已交付未确认) 和 `remaining` (排队中) 任务数，可以评估系统的处理压力。 +* **多维度观测**：支持从“单任务”、“单用户队列”以及“全系统 summary”三个维度进行状态透视。 + + +## 2. 接口详解 + +### 2.1 任务进度查询 (`/status`) +用于追踪特定异步任务的当前执行阶段。 + +| 参数名 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | +| **`user_id`** | `str` | 是 | 请求查询的用户唯一标识符。 | +| `task_id` | `str` | 否 | 可选。若提供，则仅查询该特定任务的状态。 | + +**返回状态说明**： +* `waiting`: 任务已进入队列，等待空闲 Worker 执行。 +* `in_progress`: Worker 正在调用大模型提取记忆或写入数据库。 +* `completed`: 记忆已成功持久化并完成向量索引同步。 +* `failed`: 任务失败。 + +### 2.2 用户队列指标 (`/task_queue_status`) +用于监控指定用户在 Redis 中的任务积压情况。 + +| 参数名 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | +| **`user_id`** | `str` | 是 | 需查询队列状况的用户 ID。 | + +**核心指标项**： +* `pending_tasks_count`: 已分发给 Worker 但尚未收到确认（Ack）的任务数。 +* `remaining_tasks_count`: 当前仍在队列中排队等待分配的任务总数。 +* `stream_keys`: 匹配到的 Redis Stream 键名列表。 + +### 2.3 系统级概览 (`/allstatus`) +获取调度器的全局运行概况，通常用于管理员后台监控。 + +* **核心返回信息**： + * `scheduler_summary`: 包含系统当前的负载与健康状况。 + * `all_tasks_summary`: 所有正在运行及排队任务的聚合统计。 + +## 3. 工作原理 (SchedulerHandler) + +当您发起状态查询请求时，**SchedulerHandler** 会执行以下操作： + +1. **缓存检索**：首先从 Redis 状态缓存中查找 `task_id` 对应的实时进度。 +2. **队列确认**：若查询队列指标，Handler 会调用 Redis 统计指令（如 `XLEN`, `XPENDING`）分析 Stream 状态。 +3. **指标聚合**：对于全局状态请求，Handler 会汇总所有活跃节点的指标，生成系统级的 summary 数据。 + +## 4. 快速上手示例 + +使用 SDK 轮询任务状态直至完成： + +```python +from memos.api.client import MemOSClient +import time + +client = MemOSClient(api_key="...", base_url="...") + +# 1. 系统级概览：查看整个 MemOS 系统的运行健康度 +global_res = client.get_all_scheduler_status() +if global_res: + print(f"系统运行概况: {global_res.data['scheduler_summary']}") + +# 2. 队列指标监控：检查特定用户的任务积压情况 +queue_res = client.get_task_queue_status(user_id="dev_user_01") +if queue_res: + print(f"待处理任务数: {queue_res.data['remaining_tasks_count']}") + print(f"已下发未完成任务数: {queue_res.data['pending_tasks_count']}") + +# 3. 任务进度追踪：轮询特定任务直至结束 +task_id = "task_888999" +while True: + res = client.get_task_status(user_id="dev_user_01", task_id=task_id) + if res and res.code == 200: + current_status = res.data[0]['status'] # data 为状态列表 + print(f"任务 {task_id} 当前状态: {current_status}") + + if current_status in ['completed', 'failed', 'cancelled']: + break + time.sleep(2) +``` \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/start/configuration.md b/content/cn/open_source/open_source_api/start/configuration.md index 76d43c6e..271d3ded 100644 --- a/content/cn/open_source/open_source_api/start/configuration.md +++ b/content/cn/open_source/open_source_api/start/configuration.md @@ -1,517 +1,7 @@ --- title: 项目配置 -desc: MemOS 开源版支持以 User 和 MemCube 为维度来管理资源、权限和数据隔离。您可以将一个 MemCube 视为一个独立的项目空间、一个 Agent 的专属数据库或一款 App 的存储后端。 --- +关于 MemOS 开源版 API 服务器的详细配置说明（包括 LLM 引擎、存储后端及环境变量设置），请参考： - -## 本地运行 - -### 1、本地下载 -```bash -# 将代码下载到本地文件夹下 -git clone https://github.com/MemTensor/MemOS -``` - -### 2、配置环境变量 -```bash -# 进入文件夹目录下 -cd MemOS -``` - -#### 在根目录中创建一个 `.env` 文件并设置你的环境变量。 -##### .env 快速模式配置如下，完整模式参考 .env.example。 - -```bash - -# OpenAI API 密钥 (需自定义配置) -OPENAI_API_KEY=sk-xxx -# OpenAI API 基础 URL -OPENAI_API_BASE=http://xxx:3000/v1 -# 默认模型名称 -MOS_CHAT_MODEL=qwen3-max - -# Memory Reader LLM 模型 -MEMRADER_MODEL=qwen3-max -# Memory Reader API 密钥 -MEMRADER_API_KEY=sk-xxx -# Memory Reader API 基础 URL -MEMRADER_API_BASE=http://xxx:3000/v1 - -# Embedder 模型名称 -MOS_EMBEDDER_MODEL=text-embedding-v4 -# 配置embedding backend 两种选择 ollama | universal_api -MOS_EMBEDDER_BACKEND=universal_api -# Embedder API 基础 URL -MOS_EMBEDDER_API_BASE=http://xxx:8081/v1 -# Embedder API 密钥 -MOS_EMBEDDER_API_KEY=xxx -# Embedding 向量维度 -EMBEDDING_DIMENSION=1024 -# Reranker 后端 (http_bge | etc.) -MOS_RERANKER_BACKEND=cosine_local - -# Neo4j 连接 URI -# 可选值: neo4j-community | neo4j | nebular | polardb -NEO4J_BACKEND=neo4j-community -# 当 backend=neo4j* 时必须 -NEO4J_URI=bolt://localhost:7687 -NEO4J_USER=neo4j -NEO4J_PASSWORD=12345678 -NEO4J_DB_NAME=neo4j -MOS_NEO4J_SHARED_DB=false - -# 是否使用 redis 的调度器 -DEFAULT_USE_REDIS_QUEUE=false - -# 启用聊天 API -ENABLE_CHAT_API=true -# 聊天模型列表 可以通过百炼申请. 模型可自选 -CHAT_MODEL_LIST=[{"backend": "qwen", "api_base": "https://xxx/v1", "api_key": "sk-xxx", "model_name_or_path": "qwen3-max", "extra_body": {"enable_thinking": true} ,"support_models": ["qwen3-max"]}] -``` - -### 3、以百炼为例自定义配置 - -```bash -# 可通过百炼平台申请 -# https://bailian.console.aliyun.com/?spm=a2c4g.11186623.0.0.2f2165b08fRk4l&tab=api#/api -# 申请成功后，获取API_KEY和BASE_URL，示例配置如下 - -# OpenAI API 密钥 (用百炼的API_KEY) -OPENAI_API_KEY=you_bailian_api_key -# OpenAI API 基础 URL -OPENAI_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1 -# 默认模型名称 -MOS_CHAT_MODEL=qwen3-max - -# Memory Reader LLM 模型 -MEMRADER_MODEL=qwen3-max -# Memory Reader API 密钥 (用百炼的API_KEY) -MEMRADER_API_KEY=you_bailian_api_key -# Memory Reader API 基础 URL -MEMRADER_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1 - -# Embedder模型名称可以参考下面链接 -# https://bailian.console.aliyun.com/?spm=a2c4g.11186623.0.0.2f2165b08fRk4l&tab=api#/api/?type=model&url=2846066 -MOS_EMBEDDER_MODEL=text-embedding-v4 -# 配置embedding backend 两种选择 ollama | universal_api -MOS_EMBEDDER_BACKEND=universal_api -# Embedder API 基础 URL -MOS_EMBEDDER_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1 -# Embedder API 密钥 (用百炼的API_KEY) -MOS_EMBEDDER_API_KEY=you_bailian_api_key -# Embedding 向量维度 -EMBEDDING_DIMENSION=1024 -# Reranker 后端 (http_bge | etc.) -MOS_RERANKER_BACKEND=cosine_local - -# Neo4j 连接 URI -# 可选值: neo4j-community | neo4j | nebular | polardb -NEO4J_BACKEND=neo4j-community -# 当 backend=neo4j* 时必须 -NEO4J_URI=bolt://localhost:7687 -NEO4J_USER=neo4j -NEO4J_PASSWORD=12345678 -NEO4J_DB_NAME=neo4j -MOS_NEO4J_SHARED_DB=false - -# 是否使用 redis 的调度器 -DEFAULT_USE_REDIS_QUEUE=false - -# 启用聊天 API -ENABLE_CHAT_API=true - -CHAT_MODEL_LIST=[{"backend": "qwen", "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1", "api_key": "you_bailian_api_key", "model_name_or_path": "qwen3-max-preview", "extra_body": {"enable_thinking": true} ,"support_models": ["qwen3-max-preview"]}] -``` -![MemOS bailian](https://cdn.memtensor.com.cn/img/get_key_url_by_bailian_compressed.png) -
百炼申请 API_KEY和 BASE_URL 示例
- -配置docker/requirement.txt中依赖包的版本等（可忽略）。完整版可参考 requirements.txt。 - -### 4、启动docker -```bash - # 如果没有安装docker,请安装对应版本，下载地址如下： - https://www.docker.com/ - -# 安装完成之后，可通过客户端启动docker，或者通过命令行启动docker -# 通过命令行启动docker -sudo systemctl start docker - -# 安装完成后，查看docker状态 -docker ps - -# 查看docker镜像 （可不用） -docker images - -``` - - -### 方式一：Docker 使用仓库依赖包镜像启动(推荐使用) -::steps{level="4"} - -```bash -#进入docker目录下 -cd docker -``` - -#### 镜像包使用确认 -包含快速模式和完整模式，可区分使用精简包（区分arm和x86）和全量包（区分arm和x86） - -```bash - -● 精简包：简化体量过大的 nvidia相关等依赖，对镜像实现轻量化，使本地部署更加轻量快速。 -url: registry.cn-shanghai.aliyuncs.com/memtensor/memos-base:v1.0 -url: registry.cn-shanghai.aliyuncs.com/memtensor/memos-base-arm:v1.0 - -● 全量包：将 MemOS 全部依赖包打为镜像，可体验完整功能，通过配置 Dockerfile可直接构建启动。 -url: registry.cn-shanghai.aliyuncs.com/memtensor/memos-full-base:v1.0.0 -url: registry.cn-shanghai.aliyuncs.com/memtensor/memos-full-base-arm:v1.0.0 -``` -#### 配置Dockerfile文件 - -```bash -# 当前示例使用精简包 url -FROM registry.cn-shanghai.aliyuncs.com/memtensor/memos-base-arm:v1.0 - -WORKDIR /app - -ENV HF_ENDPOINT=https://hf-mirror.com - -ENV PYTHONPATH=/app/src - -COPY src/ ./src/ - -EXPOSE 8000 - -CMD ["uvicorn", "memos.api.server_api:app", "--host", "0.0.0.0", "--port", "8000", "--reload"] - -``` - -#### 构建并启动服务 ： -```bash -# 在docker目录下 -docker compose up -``` -![MemOS buildComposeupSuccess](https://cdn.memtensor.com.cn/img/memos_build_composeup_success_compressed.png) -
示例图片，端口按 docker 自定义的配置
- -#### 通过 [http://localhost:8000/docs](http://localhost:8000/docs) 访问 API。 - -![MemOS Architecture](https://cdn.memtensor.com.cn/img/memos_run_server_success_compressed.png) - - -#### 测试用例 (添加用户记忆->查询用户记忆) 参考Docker Compose up测试用例 - -:: - - - -### 方式二：客户端install Docker Compose up -::steps{level="4"} -开发环境的 Docker Compose up 已预配置了 qdrant、neo4j。 -运行服务器需要环境变量 `OPENAI_API_KEY`。 - - -#### 进入docker文件夹 -```bash -# 当前文件夹下进入docker文件夹 -cd docker -``` - -#### 安装对应依赖模块 -```bash - -pip install --upgrade pip && pip install --no-cache-dir -r requirements.txt -# 使用阿里云源安装依赖 -pip install --upgrade pip && pip install --no-cache-dir -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ - -# command not found: pip 使用pip3 - - - -``` - - -#### 在docker目录下使用 Docker Compose Up启动容器(保证vpn正常连接)： - -```bash - -# 首次运行需要build -docker compose up --build -# 再次运行则不需要 -docker compose up - -``` - -#### 通过 [http://localhost:8000/docs](http://localhost:8000/docs) 访问 API。 - -#### 示例流程 - -##### (查询用户记忆（没有继续往后）->添加用户记忆->查询用户记忆) - -##### 添加用户记忆 http://localhost:8000/product/add (POST) -```bash -# 请求参数 -{ - "user_id": "8736b16e-1d20-4163-980b-a5063c3facdc", - "mem_cube_id": "b32d0977-435d-4828-a86f-4f47f8b55bca", - "async_mode": "async", - "messages": [ - { - "role": "user", - "content": "我喜欢草莓" - } - ] -} -# 响应 -{ - "code": 200, - "message": "Memory created successfully", - "data": null -} -``` - -##### 查询用户记忆 http://localhost:8000/product/search (POST) -```bash -# 请求参数 -{ - "query": "我喜欢什么", - "user_id": "8736b16e-1d20-4163-980b-a5063c3facdc", - "mem_cube_id": "b32d0977-435d-4828-a86f-4f47f8b55bca" -} - -# 响应 -{ - "code": 200, - "message": "Search completed successfully", - "data": { - "text_mem": [ - { - "cube_id": "7231eda8-6c57-4f6e-97ce-98b699eebb98", - "memories": [ - { - "id": "2f40be8f-736c-4a5f-aada-9489037769e0", - "memory": "[user观点]用户喜欢草莓。", - "metadata": { - "user_id": "de8215e3-3beb-4afc-9b64-ae594d62f1ea", - "session_id": "root_session", - "status": "activated", - "type": "fact", - "key": "用户对草莓的喜好", - "confidence": 0.99, - "source": null, - "tags": [ - "喜好", - "草莓" - ], - "visibility": null, - "updated_at": "2025-09-18T08:23:44.625479000+00:00", - "memory_type": "UserMemory", - "sources": [], - "embedding": [], - "created_at": "2025-09-18T08:23:44.625511000+00:00", - "usage": [ - "{ - \"time\": \"2025-09-18T08:24:17.759748\", - \"info\": { - \"user_id\": \"de8215e3-3beb-4afc-9b64-ae594d62f1ea\", - \"session_id\": \"root_session\" - } - }" - ], - "background": "用户表达了对草莓的喜好，显示出他们在饮食偏好上的倾向。", - "relativity": 0.6349761312470591, - "vector_sync": "success", - "ref_id": "[2f40be8f]", - "id": "2f40be8f-736c-4a5f-aada-9489037769e0", - "memory": "[user观点]用户喜欢草莓。" - }, - "ref_id": "[2f40be8f]" - } - ] - }, - ... - ], - "act_mem": [], - "para_mem": [] - } -} - -# 响应失败，原因排查 -# src/memos/api/config.py -# 检查get_neo4j_community_config方法中配置的"neo4j_vec_db"和"EMBEDDING_DIMENSION" -``` - - -#### 对服务器代码或库代码进行修改将自动重新加载服务器。 - - -:: - -### 方式三：客户端install 使用 CLI 命令 - -::steps{level="4"} - -#### 安装依赖 - -```bash -# pip install --upgrade pip && pip install --no-cache-dir -r ./docker/requirements.txt -# 使用阿里云源安装依赖 -pip install --no-cache-dir -r ./docker/requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ - - -``` - -#### 在终端中打开运行以下命令进行安装： - -```bash - -# 目前可能需要手动安装的包 这两个包需要找资源 -# neo4j.5.26.4.tar qdrant.v1.15.3.tar -docker load -i neo4j.5.26.4.tar -docker load -i qdrant.v1.15.3.tar -# 查看是否安装成功 -docker images -# 查看是否跑起来了 -docker ps -a - -# 若启动时出现ModuleNotFoundError: No module named 'memos'，是因为路径匹配有问题，请执行 -export PYTHONPATH=/you-file-absolute-path/MemOS/src - -# 根目录 - uvicorn memos.api.server_api:app --host 0.0.0.0 --port 8000 --workers 1 - - - -``` - -#### 访问 API - -启动完成后，通过 [http://localhost:8000/docs](http://localhost:8000/docs) 访问 API。 - - -:: - -### 方式四：不使用 Docker -::steps{level="4"} -#### 参考上方配置环境变量，已经好配置.env文件 - -#### 安装 Poetry 用于依赖管理： - -```bash -curl -sSL https://install.python-poetry.org | python3 - -``` - -#### Poetry 环境变量配置： - -```bash - -#要开始使用，您需要在“PATH”中找到Poetry的bin目录（/Users/jinyunyuan/.local/bin）`环境变量 -# 现代 macOS 系统默认的 Shell 是 zsh。你可以通过以下命令确认 -1. 确定你使用的 Shell - -echo $SHELL -# 如果输出是 /bin/zsh 或 /usr/bin/env zsh，那么你就是 zsh。 -# (如果你的系统版本较老，可能还在使用 bash，输出会是 /bin/bash) -2. 打开对应的 Shell 配置文件 -# 如果使用的是 zsh (绝大多数情况)： -# 使用 nano 编辑器（推荐新手） -nano ~/.zshrc - -# 或者使用 vim 编辑器 -# vim ~/.zshrc -# 如果使用的是 bash： -nano ~/.bash_profile -# 或者 -nano ~/.bashrc - -3. 添加 PATH 环境变量 - -# 在打开的文件的最末尾，新起一行，粘贴安装提示给你的那行命令： -export PATH="/you-path/.local/bin:$PATH" - -4. 保存并退出编辑器 - -# 如果你用的是 nano： -# 按 Ctrl + O 来写入（保存），按 Enter 确认文件名。 -# 然后按 Ctrl + X 退出编辑器。 - -# 如果你用的是 vim： -# 按 i 进入插入模式，粘贴代码后，按 ESC 键退出插入模式。 -# 输入 :wq，然后按 Enter 来保存并退出。 - -5. 使配置立刻生效 -# 刚刚修改的配置文件不会自动在当前已打开的终端窗口生效，你需要运行以下命令之一来重新加载它： - -# 对于 zsh： -source ~/.zshrc - -# 对于 bash： -source ~/.bash_profile - -6. 验证安装是否成功 -# 现在，你可以执行提示中的测试命令来检查一切是否就绪： -poetry --version -# 成功后将显示版本号 Poetry (version 2.2.0) - -``` - -#### 安装所有项目依赖和开发工具： - -```bash -make install -``` - -#### 先在docker中启动 neo4j 和 qdrant - -#### 启动 FastAPI 服务器（在MomOS目录下）： - -```bash -uvicorn memos.api.product_api:app --host 0.0.0.0 --port 8000 --reload -``` - -#### 服务器运行后,您可以使用OpenAPI文档测试API，网址为 [http://localhost:8000/docs](http://localhost:8000/docs) 或者 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) - -#### 测试用例 (注册用户->添加用户记忆->查询用户记忆) 参考Docker Compose up测试用例 - -:: - - -### 方式五：使用 PyCharm 启动 - -#### 运行 server_api -```bash -1、进入MemOS/docker/Dockerfile文件，修改运行配置 -# Start the docker -CMD ["uvicorn", "memos.api.server_api:app", "--host", "0.0.0.0", "--port"，"8000", "--reload"] - -2、进入目录MemOS/src/memos/api 直接运行server_api.py - -``` -## 用户管理 -开源版内置了多用户体系，通过 UserManager 实现资源归属管理： - -创建用户：使用 POST /users 接口创建新用户，并可指定角色（如 USER 或 ADMIN）。 - -自动初始化：系统首次启动或配置时，若指定的 user_id 不存在，会自动创建一个默认用户，确保服务开箱即用。 - -当前信息查询：通过 GET /users/me 接口获取当前登录用户的详细信息及其有权访问的所有 MemCube 列表。 - -## MemCube 空间管理 -MemCube 是 MemOS 中管理记忆的物理与逻辑单位： - -注册空间：通过 POST /mem_cubes 接口注册一个新的存储空间。您需要指定 mem_cube_name_or_path（本地存储路径）和可选的 mem_cube_id。 - -注销空间：使用 DELETE /mem_cubes/{mem_cube_id} 接口移除不再需要的记忆空间。 - -空间分享：开源版特有的分享功能。通过 POST /mem_cubes/{id}/share 接口，可以将特定的记忆空间分享给其他 target_user_id，实现跨用户的记忆协作。 - -## 数据清理与安全性 -数据隔离：系统通过 RequestContextMiddleware 中间件校验请求中的 user_id，确保不同用户之间的数据无法越权访问。 - -一键清空：使用 DELETE /memories/{mem_cube_id} 接口可以快速清空特定空间下的所有记忆数据，该操作不可恢复。 - -## 调用日志与本地监控 -本地日志：系统采用 Python logging 模块，记录所有 API 请求的执行情况、用户创建及配置变更。 - -监控方式：开发者可以直接在服务器终端或部署环境的日志流中监控接口的调用频率与错误记录。 \ No newline at end of file +👉 [**REST API 服务器配置指南**](../../../getting_started/rest_api_server.md) \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/start/overview.md b/content/cn/open_source/open_source_api/start/overview.md index 3c982f54..4804772b 100644 --- a/content/cn/open_source/open_source_api/start/overview.md +++ b/content/cn/open_source/open_source_api/start/overview.md @@ -4,55 +4,49 @@ title: 概述 ## 1. 接口介绍 -MemOS 开源项目提供了一个使用 FastAPI 编写的 REST API 服务。用户可以通过 REST 接口执行所有操作。 - +MemOS 开源项目提供了一套基于 **FastAPI** 编写的高性能 REST API 服务。系统采用 **Component (组件) + Handler (处理器)** 架构，所有核心逻辑（如记忆提取、语义搜索、异步调度）均可通过标准的 REST 接口进行调用。 ![MemOS Architecture](https://cdn.memtensor.com.cn/img/memos_run_server_success_compressed.png) -
MemOS REST API 服务支持的 API
- -### 功能特点 +
MemOS REST API 服务架构概览
-- 添加新记忆：为指定用户创建一条新的记忆。 -- 搜索记忆：为指定用户搜索其记忆内容。 -- 获取用户所有记忆：获取某个用户的所有记忆内容。 -- 记忆反馈：为指定用户反馈记忆内容。 -- 与 MemOS 对话：与 MemOS 进行对话，返回 SSE 流式响应。 +### 核心功能特点 +* **多维记忆生产**：支持通过 `AddHandler` 处理对话、文本或文档，并自动转化为结构化记忆。 +* **MemCube 物理隔离**：基于 Cube ID 实现不同用户或知识库之间的数据物理隔离与独立索引。 +* **端到端对话闭环**：通过 `ChatHandler` 编排“检索 -> 生成 -> 异步存储”的全流程。 +* **异步任务调度**：内置 `MemScheduler` 调度引擎，支持大规模记忆生产任务的削峰填谷与状态追踪。 +* **自我纠偏机制**：提供反馈接口，允许利用自然语言对已存储的记忆进行修正或标记。 ## 2. 入门指南 -通过以下两个简单的核心步骤开始使用 MemOS 开源项目API： +通过以下两个核心步骤，快速将记忆能力集成到您的 AI 应用中： -* [**添加消息**](/open_source/open_source_api/core/add_message)：通过 POST /memories 接口，储存用户对话中的原始消息内容，生成记忆； - -* [**检索记忆**](/open_source/open_source_api/core/search_memory)：通过 POST /search 接口，检索召回用户的相关记忆片段，为模型生成的回答内容提供参考。 - +* [**添加记忆**](./core/add_memory.md)：通过 `POST /product/add` 接口，将原始消息流写入指定的 MemCube，开启生产链路。 +* [**检索记忆**](./core/search_memory.md)：通过 `POST /product/search` 接口，基于语义相似度从多个 Cube 中召回相关上下文。 ## 3. 接口分类 -探索 MemOS 提供的丰富功能接口： - -* [**核心记忆接口**](/open_source/open_source_api/core/add_message)：提供记忆核心操作能力，实现记忆生产到消费的全流程。 - -* [**消息相关接口**](/open_source/open_source_api/message/add_feedback)：用于上传与管理原始消息内容数据。 - -* [**MemCube 空间管理**](/open_source/open_source_api/knowledge/create_kb)：用于管理逻辑隔离的存储空间（MemCube），支持注册、注销及跨用户分享。 +MemOS 的功能接口分为以下几大类： +* **[核心记忆 (Core)](./core/add_memory.md)**：包含记忆的增、删、改、查等原子操作。 +* **[智能对话 (Chat)](./chat/chat.md)**：实现带记忆增强的流式或全量对话响应。 +* **[消息管理 (Message)](./message/feedback.md)**：涵盖用户反馈、猜你想问（Suggestion）等增强交互接口。 +* **[异步调度 (Scheduler)](./scheduler/get_status.md)**：用于监控后台记忆提取任务的进度与队列状态。 +* **[系统工具 (Tools)](./tools/check_cube.md)**：提供 Cube 存在性校验及记忆归属反查等辅助功能。 ## 4. 鉴权认证与上下文 -所有API请求都需要认证，请在请求头的 `Authorization` 中包含您的接口密钥。从[**MemOS 控制台**](https://memos-dashboard.openmem.net/apikeys/)获取接口密钥。 - -::warning -请勿在客户端或公共仓库中暴露您的接口密钥，所有请求都应通过环境变量或服务器端调用进行。 -:: - -RequestContext： 系统内置了 RequestContextMiddleware 中间件，用于处理请求的上下文信息。 +### 鉴权机制 +在开源环境中，所有的 API 请求需要在 Header 中包含 `Authorization` 字段。 +* **开发环境**：您可以在本地 `.env` 或 `configuration.md` 中自定义 `API_KEY`。 +* **生产部署**：建议通过 `RequestContextMiddleware` 扩展 OAuth2 或更高级的身份校验逻辑。 -身份标识： 在请求体或 Header 中包含 user_id，以确保记忆归属于正确的用户。由于是开源环境，您可以根据需求在 middleware 中自定义更高级的 OAuth 或 API Key 校验。 +### 请求上下文 +* **user_id**：请求体中必须包含此标识，用于 Handler 层的身份追踪。 +* **MemCube ID**：开源版的核心隔离单元。通过指定 `readable_cube_ids` 或 `writable_cube_ids`，您可以精确控制数据读写的物理边界。 ## 5. 下一步行动 -* 👉 [**添加消息**](/api_docs/core/add_message)：生成你的第一条记忆； - -* 👉 [**检索记忆**](/api_docs/core/search_memory)：使用记忆过滤器实现记忆的高级检索。 +* 👉 [**系统配置**](./start/configuration.md)：配置您的 LLM 提供商与向量数据库引擎。 +* 👉 [**添加第一条记忆**](./core/add_memory.md)：尝试通过 SDK 或 Curl 提交第一组对话消息。 +* 👉 [**探索常见错误**](./help/error_codes.md)：了解 API 状态码及其背后的异常处理机制。 \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/tools/check_cube.md b/content/cn/open_source/open_source_api/tools/check_cube.md new file mode 100644 index 00000000..37029e70 --- /dev/null +++ b/content/cn/open_source/open_source_api/tools/check_cube.md @@ -0,0 +1,50 @@ +--- +title: 检查 MemCube 存在性 (Check Cube Existence) +desc: 校验指定的 MemCube ID 是否已在系统中初始化并可用。 +--- + +**接口路径**：`POST /product/exist_mem_cube_id` +**功能描述**：本接口用于验证指定的 `mem_cube_id` 是否已经存在于系统中。它是确保数据一致性的“守门员”接口，建议在动态创建知识库或为新用户分配空间前调用，以避免重复初始化或无效操作。 + +## 1. 核心机理：Cube 索引校验 + +在 MemOS 架构中，MemCube 的存在性决定了后续所有记忆操作的合法性： + +* **逻辑校验**：系统通过 **MemoryHandler** 检索底层存储索引，确认该 ID 是否已注册。 +* **冷启动保障**：对于按需创建 Cube 的场景，该接口可用于判断是否需要执行初次 `add` 操作来激活记忆空间。 + + + +## 2. 关键接口参数 +请求体定义如下： + +| 参数名 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | +| **`mem_cube_id`** | `str` | 是 | 待校验的 MemCube 唯一标识符。 | + +## 3. 工作原理 (MemoryHandler) + +1. **直通索引**：**MemoryHandler** 接收请求后，直接调用底层 **naive_mem_cube** 的元数据查询接口。 +2. **状态检索**：系统在持久化层中查找该 ID 对应的配置文件或数据库记录。 +3. **布尔反馈**：返回结果不包含记忆内容，仅以 `code` 或 `data` 形式告知该 Cube 是否已激活。 + +## 4. 快速上手示例 + +使用 SDK 校验目标 Cube 状态： + +```python +from memos.api.client import MemOSClient + +client = MemOSClient(api_key="...", base_url="...") + +# 场景：在导入文档前确认目标知识库已创建 +kb_id = "kb_finance_2026" +res = client.exist_mem_cube_id(mem_cube_id=kb_id) + +if res and res.code == 200: + # 假设 data 字段返回布尔值或存在性对象 + if res.data.get('exists'): + print(f"✅ MemCube '{kb_id}' 已就绪。") + else: + print(f"❌ MemCube '{kb_id}' 尚未初始化。") +``` \ No newline at end of file diff --git a/content/cn/open_source/open_source_api/tools/get_user_names.md b/content/cn/open_source/open_source_api/tools/get_user_names.md new file mode 100644 index 00000000..71073418 --- /dev/null +++ b/content/cn/open_source/open_source_api/tools/get_user_names.md @@ -0,0 +1,53 @@ +--- +title: 反向查询用户 (Get User Names) +desc: 通过记忆唯一标识符 (ID) 反向查询该条记忆所属的用户名称。 +--- + +**接口路径**：`POST /product/get_user_names_by_memory_ids` +**功能描述**：本接口提供了一种“逆向追踪”能力。当您在系统日志或共享存储中获取到特定的 `memory_id`，但无法确定其产生者时，可以使用此接口批量获取对应的用户名。 + +## 1. 核心机理：元数据溯源 + +在 MemOS 的存储架构中，每条生成的记忆条目都与原始用户的元数据绑定。本接口通过以下逻辑执行溯源： + +* **多对一映射**：支持一次传入多个 `memory_id`，系统将返回对应的用户列表。 +* **管理透明度**：该工具通常用于管理后台，帮助管理员识别公共 Cube 中不同条目的贡献者。 + + + +## 2. 关键接口参数 + +请求体定义如下： + +| 参数名 | 类型 | 必填 | 说明 | +| :--- | :--- | :--- | :--- | +| **`memory_ids`** | `list[str]` | 是 | 待查询的记忆唯一标识符列表。 | + +## 3. 工作原理 (MemoryHandler) + +1. **ID 解析**：**MemoryHandler** 接收 ID 列表后，查询全局索引表。 +2. **关系检索**：系统从底层的持久化层（或关系图谱节点）中提取关联的 `user_id` 或 `user_name` 属性。 +3. **数据脱敏**：根据系统配置，返回对应的用户显示名称或标识符。 + +## 4. 快速上手示例 + +使用 SDK 执行反向查询： + +```python +from memos.api.client import MemOSClient + +client = MemOSClient(api_key="...", base_url="...") + +# 准备待查的记忆 ID 列表 +target_ids = [ + "2f40be8f-736c-4a5f-aada-9489037769e0", + "5e92be1a-826d-4f6e-97ce-98b699eebb98" +] + +# 执行查询 +res = client.get_user_names_by_memory_ids(memory_ids=target_ids) + +if res and res.code == 200: + # res.data 通常返回一个映射字典或用户列表 + print(f"该记忆片段归属于用户: {res.data}") +``` \ No newline at end of file diff --git a/content/en/open_source/modules/mem_cube.md b/content/en/open_source/modules/mem_cube.md index 12544356..89a53b7a 100644 --- a/content/en/open_source/modules/mem_cube.md +++ b/content/en/open_source/modules/mem_cube.md @@ -1,5 +1,5 @@ --- -title: MemCube Overview +title: MemCube desc: "`MemCube` is the core organizational unit in MemOS, designed to encapsulate and manage all types of memory for a user or agent. It provides a unified interface for loading, saving, and operating on multiple memory modules, making it easy to build, share, and deploy memory-augmented applications." --- ## What is a MemCube?