From be8053194b85ee789b85501643d781581d2261a9 Mon Sep 17 00:00:00 2001 From: "jinli.yl" Date: Tue, 11 Nov 2025 19:35:17 +0800 Subject: [PATCH] docs(readme): add Chinese README and improve documentation --- README.md | 4 + README_zh.md | 335 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 339 insertions(+) create mode 100644 README_zh.md diff --git a/README.md b/README.md index 58d108af..af099c6e 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,10 @@ Remember Me, Refine Me.

+

+ English | 简体中文 +

+ --- ReMe provides AI agents with a unified memory system—enabling the ability to extract, reuse, and share memories across diff --git a/README_zh.md b/README_zh.md new file mode 100644 index 00000000..197a42b4 --- /dev/null +++ b/README_zh.md @@ -0,0 +1,335 @@ +

+ ReMe 标志 +

+ +

+ Python 版本 + PyPI 版本 + 许可证 + GitHub Stars +

+ +

+ Agentscope ReMe：面向智能体的记忆管理工具包
+ Remember Me, Refine Me. +

+ +

+ English | 简体中文 +

+ +--- + +ReMe 为智能体提供统一的记忆系统——支持在用户、任务与智能体之间提取、复用与共享记忆。 + +``` +个人记忆 Personal + 任务记忆 Task + 工具记忆 Tool = 智能体记忆 Agent Memory +``` + +个人记忆用于“理解用户偏好”，任务记忆用于“提升任务表现”，工具记忆用于“更聪明地使用工具”。 + +--- + +## ✨ 架构设计 + +

+ ReMe 架构 +

+ +ReMe 集成三类互补的记忆能力： + +#### 🧠 任务记忆 / 经验记忆 +可在不同智能体之间复用的程序性知识 +- 成功模式识别：总结有效策略与其原理 +- 失败分析学习：吸取错误避免重复 +- 对比式记忆：多采样轨迹带来更有价值的经验 +- 验证机制：通过验证模块确认经验有效性 + +详见文档：[任务记忆](docs/task_memory/task_memory.md) + +#### 👤 个人记忆 +面向特定用户的情境化记忆 +- 个体偏好：习惯、偏好、交互风格 +- 情境自适应：基于时间与上下文的智能管理 +- 渐进式学习：长期交互中逐步深入理解 +- 时间敏感：在检索与整合中考虑时间因素 + +详见文档：[个人记忆](docs/personal_memory/personal_memory.md) + +#### 🔧 工具记忆 +基于数据的工具选择与使用优化 +- 历史表现追踪：成功率、耗时与 Token 成本 +- LLM-as-Judge：为什么成功/失败的定性洞察 +- 参数优化：从成功调用中学习最优参数 +- 动态指南：将静态工具描述转为可演化的“活文档” + +详见文档：[工具记忆](docs/tool_memory/tool_memory.md) + +--- + +## 📰 最新进展 + +- [2025-10] 直接 Python 导入：`from reme_ai import ReMeApp`，无需 HTTP/MCP 服务 +- [2025-10] 工具记忆：数据驱动的工具选择与参数优化（见指南 docs/tool_memory/tool_memory.md） +- [2025-09] 支持异步操作，已集成至 agentscope-runtime +- [2025-09] 集成任务记忆与个人记忆 +- [2025-09] 在 Appworld、BFCL(v3)、FrozenLake 验证有效性（见 docs/cookbook） +- [2025-08] 支持 MCP 协议（见 docs/mcp_quick_start.md） +- [2025-06] 多后端向量库（Elasticsearch 与 ChromaDB）（见 docs/vector_store_api_guide.md） +- [2024-09] 个性化与时间敏感的记忆存储 + +--- + +## 🛠️ 安装 + +### 通过 PyPI 安装（推荐） + +```bash +pip install reme-ai +``` + +### 从源码安装 + +```bash +git clone https://github.com/agentscope-ai/ReMe.git +cd ReMe +pip install . +``` + +### 环境变量配置 + +复制 `example.env` 为 `.env` 并按需修改： + +```bash +FLOW_LLM_API_KEY=sk-xxxx +FLOW_LLM_BASE_URL=https://xxxx/v1 +FLOW_EMBEDDING_API_KEY=sk-xxxx +FLOW_EMBEDDING_BASE_URL=https://xxxx/v1 +``` + +--- + +## 🚀 快速开始 + +### 启动 HTTP 服务 + +```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 + +```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": "Help me create a project plan"}], "score": 1.0} + ] +}) + +# 记忆检索：获取相关经验 +response = requests.post("http://localhost:8002/retrieve_task_memory", json={ + "workspace_id": "task_workspace", + "query": "How to efficiently manage project progress?", + "top_k": 1 +}) +``` + +详情可见同页下方 Python 导入 / curl / Node.js 示例，接口参数与英文版一致。 + +#### 个人记忆管理 + +```python +# 记忆整合：从用户交互中学习 +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"} + ] + } + ] +}) + +# 记忆检索：获取个人记忆片段 +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 +}) +``` + +#### 工具记忆管理 + +```python +import requests + +# 记录工具调用结果 +response = requests.post("http://localhost:8002/add_tool_call_result", json={ + "workspace_id": "tool_workspace", + "tool_call_results": [ + { + "create_time": "2025-10-21 10:30:00", + "tool_name": "web_search", + "input": {"query": "Python asyncio tutorial", "max_results": 10}, + "output": "Found 10 relevant results...", + "token_cost": 150, + "success": True, + "time_cost": 2.3 + } + ] +}) + +# 从历史生成使用指南 +response = requests.post("http://localhost:8002/summary_tool_memory", json={ + "workspace_id": "tool_workspace", + "tool_names": "web_search" +}) + +# 在使用前检索指南 +response = requests.post("http://localhost:8002/retrieve_tool_memory", json={ + "workspace_id": "tool_workspace", + "tool_names": "web_search" +}) +``` + +--- + +## 📦 开箱即用的记忆库 + +ReMe 提供可直接使用的记忆文件，内含已验证的最佳实践： + +### 可用记忆 +- `appworld.jsonl`：Appworld 交互记忆，覆盖复杂任务规划与执行 +- `bfcl_v3.jsonl`：BFCL 工具调用工作记忆 + +### 快速使用 + +```python +# 加载内置记忆 +response = requests.post("http://localhost:8002/vector_store", json={ + "workspace_id": "appworld", + "action": "load", + "path": "./docs/library/" +}) + +# 查询相关记忆 +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 +}) +``` + +--- + +## 🧪 实验结果 + +### 🌍 Appworld 实验（qwen3-8b） + +| 方法 | pass@1 | pass@2 | pass@4 | +|----------------|-------------------|-------------------|-------------------| +| 无 ReMe | 0.083 | 0.140 | 0.228 | +| 使用 ReMe | 0.109（+2.6%） | 0.175（+3.5%） | 0.281（+5.3%） | + +Pass@K 衡量在生成 K 个候选中至少一个成功完成任务（score=1）的概率。 +当前实验使用内部 AppWorld 环境，可能存在轻微差异。复现实验详见 `docs/cookbook/appworld/quickstart.md`。 + +### 🧊 FrozenLake 实验（qwen3-8b，100 张随机地图） + +| 方法 | 通过率 | +|----------------|------------------| +| 无 ReMe | 0.66 | +| 使用 ReMe | 0.72（+6.0%） | + +### 🔧 工具记忆基准（Qwen3-30B-Instruct） + +| 场景 | 平均分 | 提升 | +|-----------------------|--------|----------| +| 训练集（无记忆） | 0.650 | - | +| 测试集（无记忆） | 0.672 | 基线 | +| 测试集（使用记忆） | 0.772 | +14.88% | + +关键结论： +- 工具记忆可基于历史表现进行数据驱动的工具选择 +- 通过学习参数配置，成功率提升约 15% + +更多细节见 `docs/tool_memory/tool_bench.md` 与实现 `cookbook/tool_memory/run_reme_tool_bench.py`。 + +--- + +## 📚 资源 + +- 快速上手：`./cookbook/simple_demo` + - 工具记忆演示：`cookbook/simple_demo/use_tool_memory_demo.py` + - 工具记忆基准：`cookbook/tool_memory/run_reme_tool_bench.py` +- 向量库配置指南：`docs/vector_store_api_guide.md` +- MCP 使用指南：`docs/mcp_quick_start.md` +- 个人记忆 / 任务记忆 / 工具记忆的运算符说明与可配置流程：见 `docs/personal_memory`、`docs/task_memory`、`docs/tool_memory` +- 案例集：`./cookbook` + +--- + +## 🤝 参与贡献 + +我们相信最好的记忆系统来自群体智慧。欢迎贡献 👉 文档见 `docs/contribution.md`。 + +### 代码贡献 +- 新操作与工具开发 +- 后端实现与性能优化 +- API 增强与新端点 + +### 文档改进 +- 使用示例与教程 +- 最佳实践指南 + +--- + +## 📄 引用 + +```bibtex +@software{AgentscopeReMe2025, + title = {AgentscopeReMe: Memory Management Kit for Agents}, + author = {Li Yu, Jiaji Deng, Zouying Cao}, + url = {https://reme.agentscope.io}, + year = {2025} +} +``` + +--- + +## ⚖️ 许可证 + +本项目基于 Apache License 2.0 开源，详见 [LICENSE](./LICENSE)。 + +--- + +## Star 历史 + +[![Star History Chart](https://api.star-history.com/svg?repos=modelscope/ReMe&type=Date)](https://www.star-history.com/#modelscope/ReMe&Date) + +