From cd37020ff5eedee4ee8eccdc71f86ad18db3f218 Mon Sep 17 00:00:00 2001 From: "jinli.yl" Date: Tue, 2 Sep 2025 21:39:04 +0800 Subject: [PATCH] refactor(README): update documentation and remove unused code - Remove unused import in reme_ai/summary/task/__init__.py - Remove unused constant in reme_ai/constants/common_constants.py - Update README.md with new content and structure - Update README_ZH.md with minor corrections - Modify task memory documentation for clarity --- README.md | 430 ++++++++++++++++++++++++++ README_ZH.md | 14 +- doc/mcp_quick_start.md | 2 +- doc/task_memory/task_memory.md | 4 +- doc/task_memory/task_summary_ops.md | 2 +- reme_ai/constants/common_constants.py | 2 - reme_ai/summary/task/__init__.py | 1 - 7 files changed, 442 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index e69de29b..686f3f27 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,430 @@ +

+ ReMe Logo +

+ +

+ Python Version + PyPI Version + License + GitHub Stars +

+ +

+ ReMe (formerly MemoryScope): Memory Management Framework for Agents
+ Remember Me, Refine Me +

+ +--- +ReMe provides AI agents with a unified memory system—enabling the ability to extract, reuse, and share memories across +users, tasks, and agents. + +``` +Personal Memory + Task Memory = Agent Memory Management +``` + +Personal memory helps "**understand user needs**", while task memory helps agents "**perform better**". + +--- + +## 📰 Latest Updates + +- **[2025-09]** 🎉 ReMe v0.1.x + officially released, integrating task memory and personal memory. If you want to use the original memoryscope project, + you can find it in [MemoryScope](https://github.com/modelscope/Reme/tree/memoryscope_branch). +- **[2025-09]** 🧪 We validated the effectiveness of task memory extraction and reuse in agents in appworld, bfcl(v3), + and frozenlake environments. For more information, + check [appworld exp](./cookbook/appworld/quickstart.md), [bfcl exp](./cookbook/bfcl/quickstart.md), + and [frozenlake exp](./cookbook/frozenlake/quickstart.md). +- **[2025-08]** 🚀 MCP protocol support is now available -> [Quick Start Guide](./doc/mcp_quick_start.md). +- **[2025-06]** 🚀 Multiple backend vector storage support (Elasticsearch & + ChromaDB) -> [Quick Start Guide](./doc/vector_store_api_guide.md). +- **[2024-09]** 🧠 [MemoryScope](https://github.com/modelscope/Reme/tree/memoryscope_branch) v0.1.x released, + personalized and time-aware memory storage and usage. + +--- + +## ✨ Architecture Design + +ReMe integrates two complementary memory capabilities: + +#### 🧠 **Task Memory/Experience** + +Procedural knowledge reused across agents + +- **Success Pattern Recognition**: Identify effective strategies and understand their underlying principles +- **Failure Analysis Learning**: Learn from mistakes and avoid repeating the same issues +- **Comparative Patterns**: Different sampling trajectories provide more valuable memories through comparison +- **Validation Patterns**: Confirm the effectiveness of extracted memories through validation modules + +Learn more about how to use task memory from [task memory](./doc/task_memory/task_memory.md) + +#### 👤 **Personal Memory** + +Contextualized memory for specific users + +- **Individual Preferences**: User habits, preferences, and interaction styles +- **Contextual Adaptation**: Intelligent memory management based on time and context +- **Progressive Learning**: Gradually build deep understanding through long-term interaction +- **Time Awareness**: Time sensitivity in both retrieval and integration + +Learn more about how to use personal memory from [personal memory](./doc/personal_memory/personal_memory.md) + +--- + +## 🛠️ Installation + +### Install from PyPI (Recommended) + +```bash +pip install reme-ai +``` + +### Install from Source + +```bash +git clone https://github.com/modelscope/ReMe.git +cd ReMe +pip install . +``` + +### Environment Configuration + +Copy `example.env` to .env and modify the corresponding parameters: + +```bash +# Required: LLM API Configuration +FLOW_LLM_API_KEY=sk-xxxx +FLOW_LLM_BASE_URL=https://xxxx/v1 + +# Required: Embedding Model Configuration +FLOW_EMBEDDING_API_KEY=sk-xxxx +FLOW_EMBEDDING_BASE_URL=https://xxxx/v1 +``` + +--- + +## 🚀 Quick Start + +### HTTP Service Startup + +```bash +reme \ + backend=http \ + http.port=8002 \ + llm.default.model_name=qwen3-30b-a3b-thinking-2507 \ + embedding_model.default.model_name=text-embedding-v4 \ + vector_store.default.backend=local +``` + +### MCP Server Support + +```bash +reme \ + backend=mcp \ + mcp.transport=stdio \ + llm.default.model_name=qwen3-30b-a3b-thinking-2507 \ + embedding_model.default.model_name=text-embedding-v4 \ + vector_store.default.backend=local +``` + +### Core API Usage + +#### Task Memory Management + +```python +import requests + +# Experience Summarizer: Learn from execution trajectories +response = requests.post("http://localhost:8002/summary_task_memory", json={ + "workspace_id": "task_workspace", + "trajectories": [ + {"messages": [{"role": "user", "content": "Help me create a project plan"}], "score": 1.0} + ] +}) + +# Retriever: Get relevant memories +response = requests.post("http://localhost:8002/retrieve_task_memory", json={ + "workspace_id": "task_workspace", + "query": "How to efficiently manage project progress?", + "top_k": 1 +}) +``` + +
+curl version + +```bash +# Experience Summarizer: Learn from execution trajectories +curl -X POST http://localhost:8002/summary_task_memory \ + -H "Content-Type: application/json" \ + -d '{ + "workspace_id": "task_workspace", + "trajectories": [ + {"messages": [{"role": "user", "content": "Help me create a project plan"}], "score": 1.0} + ] + }' + +# Retriever: Get relevant memories +curl -X POST http://localhost:8002/retrieve_task_memory \ + -H "Content-Type: application/json" \ + -d '{ + "workspace_id": "task_workspace", + "query": "How to efficiently manage project progress?", + "top_k": 1 + }' +``` + +
+ +
+Node.js version + +```javascript +// Experience Summarizer: Learn from execution trajectories +fetch("http://localhost:8002/summary_task_memory", { + method: "POST", + headers: { + "Content-Type": "application/json", + }, + body: JSON.stringify({ + workspace_id: "task_workspace", + trajectories: [ + {messages: [{role: "user", content: "Help me create a project plan"}], score: 1.0} + ] + }) +}) +.then(response => response.json()) +.then(data => console.log(data)); + +// Retriever: Get relevant memories +fetch("http://localhost:8002/retrieve_task_memory", { + method: "POST", + headers: { + "Content-Type": "application/json", + }, + body: JSON.stringify({ + workspace_id: "task_workspace", + query: "How to efficiently manage project progress?", + top_k: 1 + }) +}) +.then(response => response.json()) +.then(data => console.log(data)); +``` + +
+ +#### Personal Memory Management + +```python +# Memory Integration: Learn from user interactions +response = requests.post("http://localhost:8002/summary_personal_memory", json={ + "workspace_id": "task_workspace", + "trajectories": [ + {"messages": + [ + {"role": "user", "content": "I like to drink coffee while working in the morning"}, + {"role": "assistant", + "content": "I understand, you prefer to start your workday with coffee to stay energized"} + ] + } + ] +}) + +# Memory Retrieval: Get personal memory fragments +response = requests.post("http://localhost:8002/retrieve_personal_memory", json={ + "workspace_id": "task_workspace", + "query": "What are the user's work habits?", + "top_k": 5 +}) +``` + +
+curl version + +```bash +# Memory Integration: Learn from user interactions +curl -X POST http://localhost:8002/summary_personal_memory \ + -H "Content-Type: application/json" \ + -d '{ + "workspace_id": "task_workspace", + "trajectories": [ + {"messages": [ + {"role": "user", "content": "I like to drink coffee while working in the morning"}, + {"role": "assistant", "content": "I understand, you prefer to start your workday with coffee to stay energized"} + ]} + ] + }' + +# Memory Retrieval: Get personal memory fragments +curl -X POST http://localhost:8002/retrieve_personal_memory \ + -H "Content-Type: application/json" \ + -d '{ + "workspace_id": "task_workspace", + "query": "What are the user's work habits?", + "top_k": 5 + }' +``` + +
+ +
+Node.js version + +```javascript +// Memory Integration: Learn from user interactions +fetch("http://localhost:8002/summary_personal_memory", { + method: "POST", + headers: { + "Content-Type": "application/json", + }, + body: JSON.stringify({ + workspace_id: "task_workspace", + trajectories: [ + {messages: [ + {role: "user", content: "I like to drink coffee while working in the morning"}, + {role: "assistant", content: "I understand, you prefer to start your workday with coffee to stay energized"} + ]} + ] + }) +}) +.then(response => response.json()) +.then(data => console.log(data)); + +// Memory Retrieval: Get personal memory fragments +fetch("http://localhost:8002/retrieve_personal_memory", { + method: "POST", + headers: { + "Content-Type": "application/json", + }, + body: JSON.stringify({ + workspace_id: "task_workspace", + query: "What are the user's work habits?", + top_k: 5 + }) +}) +.then(response => response.json()) +.then(data => console.log(data)); +``` + +
+ +--- + +## 📦 Ready-to-Use Libraries + +ReMe provides pre-built memory libraries that agents can immediately use with verified best practices: + +### Available Libraries + +- **`appworld.jsonl`**: Memory library for Appworld agent interactions, covering complex task planning and execution + patterns +- **`bfcl_v3.jsonl`**: Working memory library for BFCL tool calls + +### Quick Usage + +```python +# Load pre-built memories +response = requests.post("http://localhost:8002/vector_store", json={ + "workspace_id": "appworld", + "action": "load", + "path": "./library/" +}) + +# Query relevant memories +response = requests.post("http://localhost:8002/retrieve_task_memory", json={ + "workspace_id": "appworld", + "query": "How to navigate to settings and update user profile?", + "top_k": 1 +}) +``` + +## 🧪 Experiments + +### 🌍 Appworld Experiment + +We tested ReMe on Appworld using qwen3-8b: + +| Method | pass@1 | pass@2 | pass@4 | +|--------------|-----------|-----------|-----------| +| without Reme | 0.083 | 0.140 | 0.228 | +| with Reme | **0.109** | **0.175** | **0.281** | + +Pass@K measures the probability that at least one of the K generated samples successfully completes the task ( +score=1). +The current experiment uses an internal AppWorld environment, which may have slight differences. + +You can find more details on reproducing the experiment in [quickstart.md](cookbook/appworld/quickstart.md). + +### 🧊 Frozenlake Experiment + +| Without memory | With memory | +|:-------------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------:| +|

GIF 1

|

GIF 2

| + +We tested on 100 random frozenlake maps using qwen3-8b: + +| Method | pass rate | +|--------------|------------------| +| without Reme | 0.66 | +| with Reme | 0.72 **(+9.1%)** | + +You can find more details on reproducing the experiment in [quickstart.md](cookbook/frozenlake/quickstart.md). + +### 🔧 BFCL-V3 Experiment + +We tested ReMe on BFCL-V3 multi-turn-base (randomly split 50train/150val) using qwen3-8b: + +| Method | pass@1 | pass@2 | pass@4 | +|--------------|---------------------|---------------------|---------------------| +| without Reme | 0.2472 | 0.2733 | 0.2922 | +| with Reme | 0.3061 **(+5.89%)** | 0.3500 **(+7.67%)** | 0.3888 **(+9.66%)** | + +## 📚 Resources + +- **[Quick Start](./cookbook/simple_demo)**: Get started quickly with practical examples +- **[Vector Storage Setup](./doc/vector_store_api_guide.md)**: Configure local/vector databases and usage +- **[MCP Guide](./doc/mcp_quick_start.md)**: Create MCP services +- **Link Description**: Operators used in personal memory and task memory and their meanings can be found + in [personal memory](./doc/personal_memory) and [task memory](./doc/task_memory) respectively. You can modify the + config to customize the links +- **[Example Collection](./cookbook)**: Real use cases and best practices + +--- + +## 🤝 Contribution + +We believe the best memory systems come from collective wisdom. Contributions welcome: + +### Code Contributions + +- New operation and tool development +- Backend implementation and optimization +- API enhancements and new endpoints + +### Documentation Improvements + +- Usage examples and tutorials +- Best practice guides + +[Guide](./doc/contribution.md) +--- + +## 📄 Citation + +```bibtex +@software{ReMe2025, + title = {ReMe: Memory Framework for AI Agent}, + author = {Li Yu, Jiaji Deng, Zouying Cao}, + url = {https://github.com/modelscope/ReMe}, + year = {2025} +} +``` + +--- + +## ⚖️ License + +This project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) file for details. + +--- diff --git a/README_ZH.md b/README_ZH.md index 6345951a..d12052b3 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -1,7 +1,7 @@

- ReMe Logo + ReMe Logo

@@ -34,7 +34,7 @@ ReMe为AI智能体提供了统一的记忆与经验系统——在跨用户、 中找到。 - **[2025-09]** 🧪 我们在appworld, bfcl(v3) 以及frozenlake环境验证了任务记忆抽取与复用在Agent中的效果，更多信息请查看 [appworld exp](./cookbook/appworld/quickstart.md), [bfcl exp](./cookbook/bfcl/quickstart.md) - and [frozenlake exp](./cookbook/frozenlake/quickstart.md)。 + 和 [frozenlake exp](./cookbook/frozenlake/quickstart.md)。 - **[2025-08]** 🚀 MCP协议支持已上线-> [快速开始指南](./doc/mcp_quick_start.md)。 - **[2025-06]** 🚀 多后端向量存储支持 (Elasticsearch & ChromaDB) -> [快速开始指南](./doc/vector_store_api_guide.md)。 - **[2024-09]** 🧠 [MemoryScope](https://github.com/modelscope/Reme/tree/memoryscope_branch) v0.1.x 发布，个性化和时间感知的记忆存储与使用。 @@ -61,7 +61,7 @@ ReMe整合两种互补的记忆能力： - **渐进学习**：通过长期交互逐步建立深度理解 - **时间感知**：检索和整合时都具备时间敏感性 -- 你可以从[personal memory](./doc/personal_memory/personal_memory.md)了解更多如何使用personal memory的方法 +你可以从[personal memory](./doc/personal_memory/personal_memory.md)了解更多如何使用personal memory的方法 --- @@ -101,8 +101,8 @@ FLOW_EMBEDDING_BASE_URL=https://xxxx/v1 ### HTTP服务启动 ```bash reme \ - backend=http \ - http.port=8001 \ + backend=http \ + http.port=8002 \ llm.default.model_name=qwen3-30b-a3b-thinking-2507 \ embedding_model.default.model_name=text-embedding-v4 \ vector_store.default.backend=local @@ -385,6 +385,8 @@ Pass@K 衡量的是在生成的 K 个样本中，至少有一个成功完成任 - 使用示例和教程 - 最佳实践指南 +[指南](./doc/contribution.md) + --- ## 📄 引用 @@ -392,7 +394,7 @@ Pass@K 衡量的是在生成的 K 个样本中，至少有一个成功完成任 ```bibtex @software{ReMe2025, title = {ReMe: Memory Framework for AI Agent}, - author = {jinli.yl, dengjiaji.djj, caozouying.czy}, + author = {Li Yu, Jiaji Deng, Zouying Cao}, url = {https://github.com/modelscope/ReMe}, year = {2025} } diff --git a/doc/mcp_quick_start.md b/doc/mcp_quick_start.md index aebef04d..30f6b754 100644 --- a/doc/mcp_quick_start.md +++ b/doc/mcp_quick_start.md @@ -8,7 +8,7 @@ integration with MCP-compatible clients. - How to set up and configure ReMe MCP server - How to connect to the server using Python MCP clients - How to use task memory operations through MCP -- How to build experience-enhanced agents with MCP integration +- How to build memory-enhanced agents with MCP integration ## 📋 Prerequisites diff --git a/doc/task_memory/task_memory.md b/doc/task_memory/task_memory.md index 79afaa5e..5e232225 100644 --- a/doc/task_memory/task_memory.md +++ b/doc/task_memory/task_memory.md @@ -11,7 +11,7 @@ Task Memory represents knowledge extracted from previous task executions, includ Each task memory contains: - `when_to_use`: Conditions that indicate when this memory is relevant -- `content`: The actual knowledge or experience to be applied +- `content`: The actual knowledge or memory to be applied - Metadata about the memory's source and utility ## Configuration Logic @@ -43,7 +43,7 @@ The `retrieve_task_memory` flow fetches relevant memories based on a query: ```yaml retrieve_task_memory: flow_content: build_query_op >> recall_vector_store_op >> rerank_memory_op >> rewrite_memory_op - description: "Retrieves the most relevant top-k memory experiences from historical data based on the current query to enhance task-solving capabilities" + description: "Retrieves the most relevant top-k memory from historical data based on the current query to enhance task-solving capabilities" ``` This flow: diff --git a/doc/task_memory/task_summary_ops.md b/doc/task_memory/task_summary_ops.md index c4de0bc2..138f5812 100644 --- a/doc/task_memory/task_summary_ops.md +++ b/doc/task_memory/task_summary_ops.md @@ -44,7 +44,7 @@ Extracts task memories from successful trajectories. ### Functionality -- Processes successful trajectories to identify valuable experiences +- Processes successful trajectories to identify valuable memories - Can work with both entire trajectories and segmented step sequences - Uses LLM to extract structured task memories with when-to-use conditions diff --git a/reme_ai/constants/common_constants.py b/reme_ai/constants/common_constants.py index 74645416..99ce3887 100644 --- a/reme_ai/constants/common_constants.py +++ b/reme_ai/constants/common_constants.py @@ -5,8 +5,6 @@ WORKFLOW_NAME = "workflow_name" -MEMORYSCOPE_CONTEXT = "memoryscope_context" - RESULT = "result" MEMORIES = "memories" diff --git a/reme_ai/summary/task/__init__.py b/reme_ai/summary/task/__init__.py index 169f8958..30e6193b 100644 --- a/reme_ai/summary/task/__init__.py +++ b/reme_ai/summary/task/__init__.py @@ -2,7 +2,6 @@ from .comparative_extraction_op import ComparativeExtractionOp from .failure_extraction_op import FailureExtractionOp from .memory_deduplication_op import MemoryDeduplicationOp from .memory_validation_op import MemoryValidationOp -from .pdf_preprocess_op_wrapper import PDFPreprocessOp from .simple_comparative_summary_op import SimpleComparativeSummaryOp from .simple_summary_op import SimpleSummaryOp from .success_extraction_op import SuccessExtractionOp