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
2026-08-28 05:25:04 +00:00 · 2025-09-02 21:39:04 +08:00 · 2025-09-02 21:39:04 +08:00 · cd37020ff5
commit cd37020ff5
parent 96124c50b4
7 changed files with 442 additions and 13 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,430 @@
+<p align="center">
+ <img src="doc/figure/reme_logo.png" alt="ReMe Logo" width="50%">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/reme-ai/"><img src="https://img.shields.io/badge/python-3.12+-blue" alt="Python Version"></a>
+  <a href="https://pypi.org/project/reme-ai/"><img src="https://img.shields.io/badge/pypi-v0.1.x-blue?logo=pypi" alt="PyPI Version"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-black" alt="License"></a>
+  <a href="https://github.com/modelscope/ReMe"><img src="https://img.shields.io/github/stars/modelscope/ReMe?style=social" alt="GitHub Stars"></a>
+</p>
+
+<p align="center">
+  <strong>ReMe (formerly MemoryScope): Memory Management Framework for Agents</strong><br>
+  <em>Remember Me, Refine Me</em>
+</p>
+
+---
+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
+})
+```
+
+<details>
+<summary>curl version</summary>
+
+```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
+  }'
+```
+
+</details>
+
+<details>
+<summary>Node.js version</summary>
+
+```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));
+```
+
+</details>
+
+#### 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
+})
+```
+
+<details>
+<summary>curl version</summary>
+
+```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
+  }'
+```
+
+</details>
+
+<details>
+<summary>Node.js version</summary>
+
+```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));
+```
+
+</details>
+
+---
+
+## 📦 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                                         |
+|:-------------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------:|
+| <p align="center"><img src="doc/figure/frozenlake_failure.gif" alt="GIF 1" width="30%"></p> | <p align="center"><img src="doc/figure/frozenlake_success.gif" alt="GIF 2" width="30%"></p> |
+
+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.
+
+---
--- a/README_ZH.md
+++ b/README_ZH.md
@ -1,7 +1,7 @@


 <p align="center">
- <img src="doc/figure/reme_logo.png" alt="ReMe Logo" width="100%">
+ <img src="doc/figure/reme_logo.png" alt="ReMe Logo" width="50%">
 </p>

 <p align="center">
@ -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}
 }
--- 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

--- 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:
--- 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

--- 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"
--- 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