{"id":14936304,"url":"https://github.com/modelscope/ReMe","last_synced_at":"2025-09-24T16:30:53.622Z","repository":{"id":255288087,"uuid":"849121458","full_name":"modelscope/MemoryScope","owner":"modelscope","description":null,"archived":false,"fork":false,"pushed_at":"2024-09-13T03:42:49.000Z","size":12308,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-09-14T10:22:17.988Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/modelscope.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-29T02:40:53.000Z","updated_at":"2024-09-12T09:31:38.000Z","dependencies_parsed_at":"2024-08-29T04:04:31.143Z","dependency_job_id":null,"html_url":"https://github.com/modelscope/MemoryScope","commit_stats":null,"previous_names":["modelscope/memoryscope"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modelscope%2FMemoryScope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modelscope%2FMemoryScope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modelscope%2FMemoryScope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modelscope%2FMemoryScope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/modelscope","download_url":"https://codeload.github.com/modelscope/MemoryScope/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219867290,"owners_count":16554315,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-23T23:01:22.118Z","updated_at":"2025-09-24T16:30:53.615Z","avatar_url":"https://github.com/modelscope.png","language":"Python","funding_links":[],"categories":["A01_文本生成_文本对话","推理 Inference"],"sub_categories":["大语言对话模型及数据"],"readme":"English | [**中文**](./README_ZH.md)\n\n\u003cp align=\"center\"\u003e\n \u003cimg src=\"docs/figure/reme_logo.png\" alt=\"ReMe Logo\" width=\"50%\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/reme-ai/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.12+-blue\" alt=\"Python Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/reme-ai/\"\u003e\u003cimg src=\"https://img.shields.io/badge/pypi-v0.1-blue?logo=pypi\" alt=\"PyPI Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache--2.0-black\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/modelscope/ReMe\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/modelscope/ReMe?style=social\" alt=\"GitHub Stars\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eReMe (formerly MemoryScope): Memory Management Framework for Agents\u003c/strong\u003e\u003cbr\u003e\n  \u003cem\u003eRemember Me, Refine Me.\u003c/em\u003e\n\u003c/p\u003e\n\n---\nReMe provides AI agents with a unified memory system—enabling the ability to extract, reuse, and share memories across\nusers, tasks, and agents.\n\n```\nPersonal Memory + Task Memory = Agent Memory\n```\n\nPersonal memory helps \"**understand user preferences**\", while task memory helps agents \"**perform better**\".\n\n---\n\n## 📰 Latest Updates\n\n- **[2025-09]** 🎉 ReMe v0.1.8 has been officially released, adding support for asynchronous operations. It has also been\n  integrated into the memory service of agentscope-runtime.\n- **[2025-09]** 🎉 ReMe v0.1 officially released, integrating task memory and personal memory. If you want to use the\n  original memoryscope project, you can find it\n  in [MemoryScope](https://github.com/modelscope/Reme/tree/memoryscope_branch).\n- **[2025-09]** 🧪 We validated the effectiveness of task memory extraction and reuse in agents in appworld, bfcl(v3),\n  and frozenlake environments. For more information,\n  check [appworld exp](docs/cookbook/appworld/quickstart.md), [bfcl exp](docs/cookbook/bfcl/quickstart.md),\n  and [frozenlake exp](docs/cookbook/frozenlake/quickstart.md).\n- **[2025-08]** 🚀 MCP protocol support is now available -\u003e [MCP Quick Start](docs/mcp_quick_start.md).\n- **[2025-06]** 🚀 Multiple backend vector storage support (Elasticsearch \u0026\n  ChromaDB) -\u003e [Vector DB quick start](docs/vector_store_api_guide.md).\n- **[2024-09]** 🧠 [MemoryScope](https://github.com/modelscope/Reme/tree/memoryscope_branch) v0.1 released,\n  personalized and time-aware memory storage and usage.\n\n---\n\n## ✨ Architecture Design\n\n\u003cp align=\"center\"\u003e\n \u003cimg src=\"docs/figure/reme_structure.jpg\" alt=\"ReMe Logo\" width=\"100%\"\u003e\n\u003c/p\u003e\n\nReMe integrates two complementary memory capabilities:\n\n#### 🧠 **Task Memory/Experience**\n\nProcedural knowledge reused across agents\n\n- **Success Pattern Recognition**: Identify effective strategies and understand their underlying principles\n- **Failure Analysis Learning**: Learn from mistakes and avoid repeating the same issues\n- **Comparative Patterns**: Different sampling trajectories provide more valuable memories through comparison\n- **Validation Patterns**: Confirm the effectiveness of extracted memories through validation modules\n\nLearn more about how to use task memory from [task memory](docs/task_memory/task_memory.md)\n\n#### 👤 **Personal Memory**\n\nContextualized memory for specific users\n\n- **Individual Preferences**: User habits, preferences, and interaction styles\n- **Contextual Adaptation**: Intelligent memory management based on time and context\n- **Progressive Learning**: Gradually build deep understanding through long-term interaction\n- **Time Awareness**: Time sensitivity in both retrieval and integration\n\nLearn more about how to use personal memory from [personal memory](docs/personal_memory/personal_memory.md)\n\n---\n\n## 🛠️ Installation\n\n### Install from PyPI (Recommended)\n\n```bash\npip install reme-ai\n```\n\n### Install from Source\n\n```bash\ngit clone https://github.com/modelscope/ReMe.git\ncd ReMe\npip install .\n```\n\n### Environment Configuration\n\nCopy `example.env` to .env and modify the corresponding parameters:\n\n```bash\nFLOW_APP_NAME=ReMe\nFLOW_LLM_API_KEY=sk-xxxx\nFLOW_LLM_BASE_URL=https://xxxx/v1\nFLOW_EMBEDDING_API_KEY=sk-xxxx\nFLOW_EMBEDDING_BASE_URL=https://xxxx/v1\n```\n\n---\n\n## 🚀 Quick Start\n\n### HTTP Service Startup\n\n```bash\nreme \\\n  backend=http \\\n  http.port=8002 \\\n  llm.default.model_name=qwen3-30b-a3b-thinking-2507 \\\n  embedding_model.default.model_name=text-embedding-v4 \\\n  vector_store.default.backend=local\n```\n\n### MCP Server Support\n\n```bash\nreme \\\n  backend=mcp \\\n  mcp.transport=stdio \\\n  llm.default.model_name=qwen3-30b-a3b-thinking-2507 \\\n  embedding_model.default.model_name=text-embedding-v4 \\\n  vector_store.default.backend=local\n```\n\n### Core API Usage\n\n#### Task Memory Management\n\n```python\nimport requests\n\n# Experience Summarizer: Learn from execution trajectories\nresponse = requests.post(\"http://localhost:8002/summary_task_memory\", json={\n    \"workspace_id\": \"task_workspace\",\n    \"trajectories\": [\n        {\"messages\": [{\"role\": \"user\", \"content\": \"Help me create a project plan\"}], \"score\": 1.0}\n    ]\n})\n\n# Retriever: Get relevant memories\nresponse = requests.post(\"http://localhost:8002/retrieve_task_memory\", json={\n    \"workspace_id\": \"task_workspace\",\n    \"query\": \"How to efficiently manage project progress?\",\n    \"top_k\": 1\n})\n```\n\n\u003cdetails\u003e\n\u003csummary\u003ecurl version\u003c/summary\u003e\n\n```bash\n# Experience Summarizer: Learn from execution trajectories\ncurl -X POST http://localhost:8002/summary_task_memory \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"workspace_id\": \"task_workspace\",\n    \"trajectories\": [\n      {\"messages\": [{\"role\": \"user\", \"content\": \"Help me create a project plan\"}], \"score\": 1.0}\n    ]\n  }'\n\n# Retriever: Get relevant memories\ncurl -X POST http://localhost:8002/retrieve_task_memory \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"workspace_id\": \"task_workspace\",\n    \"query\": \"How to efficiently manage project progress?\",\n    \"top_k\": 1\n  }'\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eNode.js version\u003c/summary\u003e\n\n```javascript\n// Experience Summarizer: Learn from execution trajectories\nfetch(\"http://localhost:8002/summary_task_memory\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    workspace_id: \"task_workspace\",\n    trajectories: [\n      {messages: [{role: \"user\", content: \"Help me create a project plan\"}], score: 1.0}\n    ]\n  })\n})\n.then(response =\u003e response.json())\n.then(data =\u003e console.log(data));\n\n// Retriever: Get relevant memories\nfetch(\"http://localhost:8002/retrieve_task_memory\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    workspace_id: \"task_workspace\",\n    query: \"How to efficiently manage project progress?\",\n    top_k: 1\n  })\n})\n.then(response =\u003e response.json())\n.then(data =\u003e console.log(data));\n```\n\n\u003c/details\u003e\n\n#### Personal Memory Management\n\n```python\n# Memory Integration: Learn from user interactions\nresponse = requests.post(\"http://localhost:8002/summary_personal_memory\", json={\n    \"workspace_id\": \"task_workspace\",\n    \"trajectories\": [\n        {\"messages\":\n            [\n                {\"role\": \"user\", \"content\": \"I like to drink coffee while working in the morning\"},\n                {\"role\": \"assistant\",\n                 \"content\": \"I understand, you prefer to start your workday with coffee to stay energized\"}\n            ]\n        }\n    ]\n})\n\n# Memory Retrieval: Get personal memory fragments\nresponse = requests.post(\"http://localhost:8002/retrieve_personal_memory\", json={\n    \"workspace_id\": \"task_workspace\",\n    \"query\": \"What are the user's work habits?\",\n    \"top_k\": 5\n})\n```\n\n\u003cdetails\u003e\n\u003csummary\u003ecurl version\u003c/summary\u003e\n\n```bash\n# Memory Integration: Learn from user interactions\ncurl -X POST http://localhost:8002/summary_personal_memory \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"workspace_id\": \"task_workspace\",\n    \"trajectories\": [\n      {\"messages\": [\n        {\"role\": \"user\", \"content\": \"I like to drink coffee while working in the morning\"},\n        {\"role\": \"assistant\", \"content\": \"I understand, you prefer to start your workday with coffee to stay energized\"}\n      ]}\n    ]\n  }'\n\n# Memory Retrieval: Get personal memory fragments\ncurl -X POST http://localhost:8002/retrieve_personal_memory \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"workspace_id\": \"task_workspace\",\n    \"query\": \"What are the user's work habits?\",\n    \"top_k\": 5\n  }'\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eNode.js version\u003c/summary\u003e\n\n```javascript\n// Memory Integration: Learn from user interactions\nfetch(\"http://localhost:8002/summary_personal_memory\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    workspace_id: \"task_workspace\",\n    trajectories: [\n      {messages: [\n        {role: \"user\", content: \"I like to drink coffee while working in the morning\"},\n        {role: \"assistant\", content: \"I understand, you prefer to start your workday with coffee to stay energized\"}\n      ]}\n    ]\n  })\n})\n.then(response =\u003e response.json())\n.then(data =\u003e console.log(data));\n\n// Memory Retrieval: Get personal memory fragments\nfetch(\"http://localhost:8002/retrieve_personal_memory\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    workspace_id: \"task_workspace\",\n    query: \"What are the user's work habits?\",\n    top_k: 5\n  })\n})\n.then(response =\u003e response.json())\n.then(data =\u003e console.log(data));\n```\n\n\u003c/details\u003e\n\n---\n\n## 📦 Ready-to-Use Libraries\n\nReMe provides pre-built memory libraries that agents can immediately use with verified best practices:\n\n### Available Libraries\n\n- **`appworld.jsonl`**: Memory library for Appworld agent interactions, covering complex task planning and execution\n  patterns\n- **`bfcl_v3.jsonl`**: Working memory library for BFCL tool calls\n\n### Quick Usage\n\n```python\n# Load pre-built memories\nresponse = requests.post(\"http://localhost:8002/vector_store\", json={\n    \"workspace_id\": \"appworld\",\n    \"action\": \"load\",\n    \"path\": \"./docs/library/\"\n})\n\n# Query relevant memories\nresponse = requests.post(\"http://localhost:8002/retrieve_task_memory\", json={\n    \"workspace_id\": \"appworld\",\n    \"query\": \"How to navigate to settings and update user profile?\",\n    \"top_k\": 1\n})\n```\n\n## 🧪 Experiments\n\n### 🌍 [Appworld Experiment](docs/cookbook/appworld/quickstart.md)\n\nWe tested ReMe on Appworld using qwen3-8b:\n\n| Method       | pass@1            | pass@2            | pass@4            |\n|--------------|-------------------|-------------------|-------------------|\n| without ReMe | 0.083             | 0.140             | 0.228             |\n| with ReMe    | 0.109 **(+2.6%)** | 0.175 **(+3.5%)** | 0.281 **(+5.3%)** |\n\nPass@K measures the probability that at least one of the K generated samples successfully completes the task (\nscore=1).  \nThe current experiment uses an internal AppWorld environment, which may have slight differences.\n\nYou can find more details on reproducing the experiment in [quickstart.md](docs/cookbook/appworld/quickstart.md).\n\n### 🧊 [Frozenlake Experiment](docs/cookbook/frozenlake/quickstart.md)\n\n|                                         without ReMe                                         |                                          with ReMe                                           |\n|:--------------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------------:|\n| \u003cp align=\"center\"\u003e\u003cimg src=\"docs/figure/frozenlake_failure.gif\" alt=\"GIF 1\" width=\"30%\"\u003e\u003c/p\u003e | \u003cp align=\"center\"\u003e\u003cimg src=\"docs/figure/frozenlake_success.gif\" alt=\"GIF 2\" width=\"30%\"\u003e\u003c/p\u003e |\n\nWe tested on 100 random frozenlake maps using qwen3-8b:\n\n| Method       | pass rate        |\n|--------------|------------------|\n| without ReMe | 0.66             |\n| with ReMe    | 0.72 **(+6.0%)** |\n\nYou can find more details on reproducing the experiment in [quickstart.md](docs/cookbook/frozenlake/quickstart.md).\n\n### 🔧 [BFCL-V3 Experiment](docs/cookbook/bfcl/quickstart.md)\n\nWe tested ReMe on BFCL-V3 multi-turn-base (randomly split 50train/150val) using qwen3-8b:\n\n| Method       | pass@1              | pass@2              | pass@4              |\n|--------------|---------------------|---------------------|---------------------|\n| without ReMe | 0.2472              | 0.2733              | 0.2922              |\n| with ReMe    | 0.3061 **(+5.89%)** | 0.3500 **(+7.67%)** | 0.3888 **(+9.66%)** |\n\n## 📚 Resources\n\n- **[Quick Start](./cookbook/simple_demo)**: Get started quickly with practical examples\n- **[Vector Storage Setup](docs/vector_store_api_guide.md)**: Configure local/vector databases and usage\n- **[MCP Guide](docs/mcp_quick_start.md)**: Create MCP services\n- **[personal memory](docs/personal_memory)** \u0026 **[task memory](docs/task_memory)** : Operators used in personal memory and task memory, You can modify the config to customize the pipelines.\n- **[Example Collection](./cookbook)**: Real use cases and best practices\n\n---\n\n## 🤝 Contribution\n\nWe believe the best memory systems come from collective wisdom. Contributions welcome 👉[Guide](docs/contribution.md):\n\n### Code Contributions\n\n- New operation and tool development\n- Backend implementation and optimization\n- API enhancements and new endpoints\n\n### Documentation Improvements\n\n- Usage examples and tutorials\n- Best practice guides\n\n\n---\n\n## 📄 Citation\n\n```bibtex\n@software{ReMe2025,\n  title = {ReMe: Memory Management Framework for Agents},\n  author = {Li Yu, Jiaji Deng, Zouying Cao},\n  url = {https://github.com/modelscope/ReMe},\n  year = {2025}\n}\n```\n\n---\n\n## ⚖️ License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) file for details.\n\n---\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=modelscope/ReMe\u0026type=Date)](https://www.star-history.com/#modelscope/ReMe\u0026Date)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodelscope%2FReMe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmodelscope%2FReMe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodelscope%2FReMe/lists"}