From 57a22d8da4250882bea43d58dec080764b3d7f79 Mon Sep 17 00:00:00 2001 From: "jinli.yl" Date: Tue, 2 Sep 2025 19:06:07 +0800 Subject: [PATCH] docs(README): update content and rename to README.md - Update README content to reflect new project name and version - Rename README_ZH.md to README.md - Add contribution guide and update documentation links - Correct author information and update project description --- README.md | 270 ------------------ README_ZH.md | 61 ++-- cookbook/appworld/quickstart.md | 5 +- cookbook/bfcl/init_task_memory_pool.py | 2 +- cookbook/bfcl/quickstart.md | 10 +- doc/contribution.md | 36 +++ {library => doc}/index.html | 10 +- doc/personal_memory/personal_memory.md | 6 +- doc/task_memory/task_memory.md | 10 +- library/{appworld_v1.jsonl => appworld.jsonl} | 0 library/{bfcl_v1.jsonl => bfcl_v3.jsonl} | 0 pyproject.toml | 6 +- 12 files changed, 92 insertions(+), 324 deletions(-) create mode 100644 doc/contribution.md rename {library => doc}/index.html (99%) rename library/{appworld_v1.jsonl => appworld.jsonl} (100%) rename library/{bfcl_v1.jsonl => bfcl_v3.jsonl} (100%) diff --git a/README.md b/README.md index f317cab9..e69de29b 100644 --- a/README.md +++ b/README.md @@ -1,270 +0,0 @@ -# ReMe.ai - -

- ReMe.ai Logo -

- -

- Python Version - PyPI Version - License - GitHub Stars -

- -

- 记忆驱动的AI智能体框架
- "如果说我比别人看得更远些，那是因为我站在了巨人的肩膀上。" —— 牛顿 -

- ---- - -Remember Everyone, Recreate Everything - -Remember Me, Reshape Me - -Remember Me, Refine Me - -Remember Me, Reinvent Me - -今天的每个AI智能体都在从零开始。每当智能体处理任务时，它都在重新发明无数其他智能体已经发现的解决方案。这就像要求每个人都从头发现火、农业和数学一样。 - -ReMe.ai希望改变这一点。我们为AI智能体提供了统一的记忆与经验系统——在跨用户、跨任务、跨智能体下抽取、复用和分享记忆的能力。 - -``` -任务经验 (Task Memory) + 个人记忆 (Personal Memory) = agent的记忆管理 -``` - -个人记忆回答"**如何理解用户需要**"，任务记忆回答"**如何做得更好**"， - ---- - -## 📰 最新动态 -- **[2025-09]** 🎉 ReMe.ai v1.0.0 正式发布，整合任务经验与个人记忆 -- **[2025-08]** 🚀 MCP协议支持已上线！→ [快速开始指南](./doc/mcp_quick_start.md) -- **[2025-07]** 📚 完整文档和快速开始指南发布 -- **[2025-06]** 🚀 多后端向量存储支持 (Elasticsearch & ChromaDB) - ---- - -## ✨ 架构设计 - -### 🎯 双模记忆系统 - -ReMe.ai整合两种互补的记忆能力： - -#### 🧠 **任务经验 (Task Memory/Experience)** -跨智能体复用的程序性知识 -- **成功模式识别**：识别有效策略并理解其根本原理 -- **失败分析学习**：从错误中学习，避免重复同样的问题 -- **规划策略**：不同问题类型的规划策略 -- **工具使用模式**：经过验证的有效工具使用方法 -- **标准操作流程**：经过验证的方法论和流程 - -你可以从[快速开始指南](./doc/task_memory_readme.md)了解更多如何使用task memory的方法 - -#### 👤 **个人记忆 (personal memory)** -特定用户的情境化记忆 -- **个体偏好**：用户的习惯、偏好和交互风格 -- **情境适应**：基于时间和上下文的智能记忆管理 -- **渐进学习**：通过长期交互逐步建立深度理解 -- **时间感知**：检索和整合时都具备时间敏感性 - -- 你可以从[快速开始指南](./doc/personal_memory_readme.md)了解更多如何使用personal memory的方法 - - ---- - -## 🛠️ 安装 - -### 从PyPI安装（推荐） -```bash -pip install reme-ai -``` - -### 从源码安装 -```bash -git clone https://github.com/modelscope/ReMe.ai.git -cd ReMe.ai -pip install . -``` - -### 环境配置 -创建`.env`文件： -```bash -# 必需：LLM API配置 -LLM_API_KEY="sk-xxx" -LLM_BASE_URL="https://xxx.com/v1" - -# 必需：嵌入模型配置 -EMBEDDING_MODEL_API_KEY="sk-xxx" -EMBEDDING_MODEL_BASE_URL="https://xxx.com/v1" -``` - ---- - -## 🚀 快速开始 - -### HTTP服务启动 -```bash -reme \ - backend=http \ - http.port=8001 \ - llm.default.model_name=qwen3-30b-a3b-thinking-2507 \ - embedding_model.default.model_name=text-embedding-v4 \ - vector_store.default.backend=local -``` - -### MCP服务器支持 -```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 -``` - -### 核心API使用 - -#### 任务经验管理 -```python -import requests - -# 经验总结器：从执行轨迹学习 -response = requests.post("http://localhost:8002/summary_task_memory", json={ - "workspace_id": "task_workspace", - "trajectories": [ - {"messages": [{"role": "user", "content": "帮我制定项目计划"}], "score": 1.0} - ] -}) - -# 经验检索器：获取相关经验 -response = requests.post("http://localhost:8002/retrieve_task_memory", json={ - "workspace_id": "task_workspace", - "query": "如何高效管理项目进度？", - "top_k": 1 -}) -``` - -#### 个人记忆管理 -```python -# 记忆整合：从用户交互中学习 -response = requests.post("http://localhost:8002/summary_personal_memory", json={ - "workspace_id": "task_workspace", - "trajectories": [ - {"messages": - [ - {"role": "user", "content": "我喜欢早上喝咖啡工作"}, - {"role": "assistant", "content": "了解，您习惯早上用咖啡提神来开始工作"} - ] - } - ] -}) - -# 记忆检索：获取个人记忆片段 -response = requests.post("http://localhost:8002/retrieve_personal_memory", json={ - "workspace_id": "task_workspace", - "query": "用户的工作习惯是什么？", - "top_k": 5 -}) -``` - ---- - -## 🧪 实验结果 - -### Appworld基准测试 -使用qwen3-8b在Appworld上的测试结果： - -| 方法 | pass@1 | pass@2 | pass@4 | -|----------------------------|-----------|-------------|-----------| -| 无记忆（基线） | 0.083 | 0.140 | 0.228 | -| **使用任务经验** | **0.109** | **0.175** | **0.281** | - -详见：[quickstart.md](cookbook/appworld/quickstart.md) - -### FrozenLake实验 -使用qwen3-8b在100个随机FrozenLake地图上测试： - -| 方法 | 通过率 | -|---------------------------|-----------------| -| 无记忆（基线） | 0.66 | -| **使用任务经验** | 0.72 **(+9.1%)** | - -| 无经验 | 有经验 | -|:----------------------------------------------------------:|:---------------------------------------:| -|

失败案例

|

成功案例

- -详见：[quickstart.md](cookbook/frozenlake/quickstart.md) - ---- - -## 📦 即用型经验库 - -ReMe.ai提供预构建的经验库，智能体可以立即使用经过验证的最佳实践： - -### 可用经验库 -- **`appworld_v1.jsonl`**：Appworld智能体交互的记忆库，涵盖复杂任务规划和执行模式 -- **`bfcl_v1.jsonl`**：BFCL工具调用的工作记忆库 - -### 快速使用 -```python -# 加载预构建经验 -response = requests.post("http://localhost:8002/vector_store", json={ - "workspace_id": "appworld_v1", - "action": "load", - "path": "./library/" -}) - -# 查询相关经验 -response = requests.post("http://localhost:8002/retrieve_task_memory", json={ - "workspace_id": "appworld_v1", - "query": "如何导航到设置并更新用户资料？", - "top_k": 1 -}) -``` - -## 📚 相关资源 - -- **[快速开始](./cookbook/simple_demo/quick_start.md)**：通过实际示例快速上手 -- **[向量存储设置](./doc/vector_store_setup.md)**：生产部署指南 -- **[配置指南](./doc/configuration_guide.md)**：详细配置参考 -- **[操作文档](./doc/operations_documentation.md)**：操作配置说明 -- **[示例集合](./cookbook)**：实际用例和最佳实践 - ---- - -## 🤝 贡献 - -我们相信最好的记忆系统来自集体智慧。欢迎贡献： - -### 代码贡献 -- 新操作和工具开发 -- 后端实现和优化 -- API增强和新端点 - -### 文档改进 -- 使用示例和教程 -- 最佳实践指南 -- 翻译和本地化 - ---- - -## 📄 引用 - -```bibtex -@software{ReMe2025, - title = {ReMe.ai: Memory-Driven AI Agent Framework}, - author = {The ReMe.ai Team}, - url = {https://github.com/modelscope/ReMe.ai}, - year = {2025} -} -``` - ---- - -## ⚖️ 许可证 - -本项目采用Apache License 2.0许可证 - 详情请参阅[LICENSE](./LICENSE)文件。 - ---- \ No newline at end of file diff --git a/README_ZH.md b/README_ZH.md index de3b7ede..08a6809b 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -1,27 +1,22 @@ -# ReMe (formerly memoryscope) +# ReMe (formerly MemoryScope)

- ReMe.ai Logo + ReMe Logo

Python Version - PyPI Version + PyPI Version License GitHub Stars

- ReMe: 为agent设计的记忆管理框架
+ ReMe: 为Agent设计的记忆管理框架
Remember Me, Refine Me

--- - -agent时代的记忆不单是用于保存个性化的用户信息。agent在完成任务时，我们希望它能够有区分性地记住用户的偏好，以及如何正确地行动。 - -当智能体处理任务时，它都在重新发明无数其他智能体已经发现的解决方案。这就像要求每个人都从头发现火、农业和数学一样。 - ReMe为AI智能体提供了统一的记忆与经验系统——在跨用户、跨任务、跨智能体下抽取、复用和分享记忆的能力。 ``` @@ -34,12 +29,15 @@ ReMe为AI智能体提供了统一的记忆与经验系统——在跨用户、 ## 📰 最新动态 -- **[2025-09]** 🧪 我们在appworld, bfcl(v3) 以及frozenlake环境验证了记忆抽取与复用在agent中的效果，更多信息请查看 [appworld exp](./cookbook/appworld/quickstart.md), [bfcl exp](./cookbook/bfcl/quickstart.md) & [frozenlake exp](./cookbook/frozenlake/quickstart.md) -- **[2025-09]** 🎉 ReMe(formerly [MemoryScope](./memoryscope/README.md)) v1.0 正式发布，整合任务经验与个人记忆。 如果想使用原始的memoryscope项目，你可以在[MemoryScope](./memoryscope)找到 -- **[2025-08]** 🚀 MCP协议支持已上线！→ [快速开始指南](./doc/mcp_quick_start.md) -- **[2025-07]** 📚 完整文档和快速开始指南发布 -- **[2025-06]** 🚀 多后端向量存储支持 (Elasticsearch & ChromaDB) -> [快速开始指南](./doc/vector_store_api_guide.md) -- **[2024-09]** 🧠 MemoryScope v0.1.1.0 发布，个性化和时间感知的记忆存储与使用 +- **[2025-09]** 🎉 ReMe v0.1.x + 正式发布，整合任务记忆与个人记忆。如果想使用原始的memoryscope项目，你可以在[MemoryScope](https://github.com/modelscope/Reme/tree/memoryscope_branch) + 中找到。 +- **[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)。 +- **[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 发布，个性化和时间感知的记忆存储与使用。 --- @@ -58,7 +56,7 @@ ReMe整合两种互补的记忆能力： 你可以从[task memory](./doc/task_memory/task_memory.md)了解更多如何使用task memory的方法 -#### 👤 **个人记忆 (personal memory)** +#### 👤 **个人记忆 (Personal Memory)** 特定用户的情境化记忆 - **个体偏好**：用户的习惯、偏好和交互风格 - **情境适应**：基于时间和上下文的智能记忆管理 @@ -124,7 +122,7 @@ reme \ ### 核心API使用 -#### 任务经验管理 +#### 任务记忆管理 ```python import requests @@ -174,21 +172,22 @@ response = requests.post("http://localhost:8002/retrieve_personal_memory", json= ReMe提供预构建的经验库，智能体可以立即使用经过验证的最佳实践： ### 可用经验库 -- **`appworld_v1.jsonl`**：Appworld智能体交互的记忆库，涵盖复杂任务规划和执行模式 -- **`bfcl_v1.jsonl`**：BFCL工具调用的工作记忆库 + +- **`appworld.jsonl`**：Appworld智能体交互的记忆库，涵盖复杂任务规划和执行模式 +- **`bfcl_v3.jsonl`**：BFCL工具调用的工作记忆库 ### 快速使用 ```python # 加载预构建经验 response = requests.post("http://localhost:8002/vector_store", json={ - "workspace_id": "appworld_v1", + "workspace_id": "appworld", "action": "load", "path": "./library/" }) # 查询相关经验 response = requests.post("http://localhost:8002/retrieve_task_memory", json={ - "workspace_id": "appworld_v1", + "workspace_id": "appworld", "query": "如何导航到设置并更新用户资料？", "top_k": 1 }) @@ -200,11 +199,10 @@ response = requests.post("http://localhost:8002/retrieve_task_memory", json={ 我们在 Appworld 上使用 qwen3-8b 测试 ReMe： -| 方法 | pass@1 | pass@2 | pass@4 | -|---------------------|-----------|-------------|-----------| -| 不使用 ReMe (baseline) | 0.083 | 0.140 | 0.228 | -| **使用 ReMe** | | | | -| w/ memory(直接使用) | **0.109** | **0.175** | **0.281** | +| 方法 | pass@1 | pass@2 | pass@4 | +|--------------|-----------|-----------|-----------| +| without Reme | 0.083 | 0.140 | 0.228 | +| with Reme | **0.109** | **0.175** | **0.281** | Pass@K 衡量的是在生成的 K 个样本中，至少有一个成功完成任务（score=1）的概率。 当前实验使用的是一个内部的 AppWorld 环境，可能存在轻微差异。 @@ -220,11 +218,10 @@ Pass@K 衡量的是在生成的 K 个样本中，至少有一个成功完成任 我们在 100 个随机 frozenlake 地图上使用 qwen3-8b 进行测试： -| 方法 | pass rate | -|---------------------|----------------| -| 不使用 ReMe (baseline) | 0.66 | -| **使用 ReMe** | | -| w/ memory (直接使用) | 0.72 **(+9.1%)** | +| 方法 | pass rate | +|--------------|------------------| +| without Reme | 0.66 | +| with Reme | 0.72 **(+9.1%)** | 你可以在 [quickstart.md](cookbook/frozenlake/quickstart.md) 中找到复现实验的更多细节。 @@ -267,7 +264,7 @@ Pass@K 衡量的是在生成的 K 个样本中，至少有一个成功完成任 ```bibtex @software{ReMe2025, title = {ReMe: Memory Framework for AI Agent}, - author = {The ReMe Team}, + author = {jinli.yl, dengjiaji.djj, caozouying.czy}, url = {https://github.com/modelscope/ReMe}, year = {2025} } diff --git a/cookbook/appworld/quickstart.md b/cookbook/appworld/quickstart.md index dd759eb3..639c4182 100644 --- a/cookbook/appworld/quickstart.md +++ b/cookbook/appworld/quickstart.md @@ -56,10 +56,11 @@ Launch the ReMe service to enable memory library functionality: ```bash reme \ - http_service.port=8001 \ + backend=http \ + http.port=8001 \ llm.default.model_name=qwen-max-latest \ embedding_model.default.model_name=text-embedding-v4 \ - vector_store.default.backend=local_file + vector_store.default.backend=local ``` add memories for appworld: diff --git a/cookbook/bfcl/init_task_memory_pool.py b/cookbook/bfcl/init_task_memory_pool.py index 5f4d9021..8c00d4a6 100644 --- a/cookbook/bfcl/init_task_memory_pool.py +++ b/cookbook/bfcl/init_task_memory_pool.py @@ -147,7 +147,7 @@ def process_trajectories_with_threads(grouped_trajectories: List[List[Any]], def main(): parser = argparse.ArgumentParser(description='Convert JSONL to memories using ReMe service') parser.add_argument('--jsonl_file', type=str, required=True, help='Path to the JSONL file') - parser.add_argument('--service_url', type=str, default='http://localhost:8001', help='Reme service URL') + parser.add_argument('--service_url', type=str, default='http://localhost:8001', help='ReMe service URL') parser.add_argument('--workspace_id', type=str, required=True, help='Workspace ID for the task memory pool') parser.add_argument('--output_file', type=str, help='Output file to save results (optional)') parser.add_argument('--n_threads', type=int, default=4, help='Number of threads for processing') diff --git a/cookbook/bfcl/quickstart.md b/cookbook/bfcl/quickstart.md index 213760df..c5a66a5f 100644 --- a/cookbook/bfcl/quickstart.md +++ b/cookbook/bfcl/quickstart.md @@ -55,7 +55,7 @@ After collecting trajectories, Launch the ReMe service (make sure you have insta ```bash reme \ backend=http \ - http.port=8001 \ + http.port=8002 \ llm.default.model_name=qwen-max-2025-01-25 \ embedding_model.default.model_name=text-embedding-v4 \ vector_store.default.backend=local @@ -69,14 +69,14 @@ python init_exp_pool.py **Configuration options in `init_exp_pool.py`:** - `jsonl_file`: Path to the collloaded trajectories -- `service_url`: ReMe service URL (default: `http://localhost:8001`) +- `service_url`: ReMe service URL (default: `http://localhost:8002`) - `workspace_id`: Workspace ID for the task memory pool (default: `bfcl_test`) - `n_threads`: Number of threads for processing (default: `4`) - `output_file`: Output file to save results (optional) -Now you have inited the task memory pool using `local` backend (start on `http://localhost:8001`). Then, use `local_file_to_library.py` script to convert the local file to the memory library or run the following `curl` command: +Now you have inited the task memory pool using `local` backend (start on `http://localhost:8002`). Then, use `local_file_to_library.py` script to convert the local file to the memory library or run the following `curl` command: ```bash -curl -X POST "http://0.0.0.0:8001/vector_store" \ +curl -X POST "http://0.0.0.0:8002/vector_store" \ -H "Content-Type: application/json" \ -d '{ "workspace_id": "bfcl_test", @@ -88,7 +88,7 @@ to dump the memory library (default in `./library/bfcl_test.jsonl`). Next time, you can import this previously exported task memory data to populate the new started workspace with existing knowledge: ```bash -curl -X POST "http://0.0.0.0:8001/vector_store" \ +curl -X POST "http://0.0.0.0:8002/vector_store" \ -H "Content-Type: application/json" \ -d '{ "workspace_id": "bfcl_test", diff --git a/doc/contribution.md b/doc/contribution.md new file mode 100644 index 00000000..fd1328b2 --- /dev/null +++ b/doc/contribution.md @@ -0,0 +1,36 @@ +# Contribute to ReMe +Our community thrives on the diverse ideas and contributions of its members. Whether you're fixing a bug, adding a new feature, improving the documentation, or adding examples, your help is welcome. Here's how you can contribute: +## Report Bugs and Ask For New Features? +Did you find a bug or have a feature request? Please first check the issue tracker to see if it has already been reported. If not, feel free to open a new issue. Include as much detail as possible: +- A descriptive title +- Clear description of the issue +- Steps to reproduce the problem +- Version of the ReMe you are using +- Any relevant code snippets or error messages +## Contribute to Codebase +### Fork and Clone the Repository +To work on an issue or a new feature, start by forking the ReMe repository and then cloning your fork locally. +```bash +git clone https://github.com/your-username/ReMe.git +cd ReMe +``` +### Create a New Branch +Create a new branch for your work. This helps keep proposed changes organized and separate from the `main` branch. +```bash +git checkout -b your-feature-branch-name +``` +### Making Changes +With your new branch checked out, you can now make your changes to the code. Remember to keep your changes as focused as possible. If you're addressing multiple issues or features, it's better to create separate branches and pull requests for each. + +### Commit Your Changes +Once you've made your changes, it's time to commit them. Write clear and concise commit messages that explain your changes. +```bash +git add -A +git commit -m "A brief description of the changes" +``` + +### Submit a Pull Request +When you're ready for feedback, submit a pull request to the ReMe `main` branch. In your pull request description, explain the changes you've made and any other relevant context. +We will review your pull request. This process might involve some discussion, additional changes on your part, or both. +### Code Review +Wait for us to review your pull request. We may suggest some changes or improvements. Keep an eye on your GitHub notifications and be responsive to any feedback. \ No newline at end of file diff --git a/library/index.html b/doc/index.html similarity index 99% rename from library/index.html rename to doc/index.html index 44643474..6636a102 100644 --- a/library/index.html +++ b/doc/index.html @@ -3,7 +3,7 @@ - Reme - Memory Library + ReMe - Memory Library