diff --git a/README.md b/README.md index 26a58740..3618fa15 100644 --- a/README.md +++ b/README.md @@ -11,840 +11,484 @@

License - English - 简体中文 + English + 简体中文 GitHub Stars

- Memory Management Kit for Agents, Remember Me, Refine Me.
- If you find it useful, please give us a ⭐ Star. + A memory management toolkit for AI agents — Remember Me, Refine Me.

+> For legacy versions, see [0.2.x Documentation](docs/README_0_2_x.md) + --- -ReMe is a **modular memory management kit** that provides AI agents with unified memory capabilities—enabling the ability to extract, reuse, and share memories across users, tasks, and agents. -Agent memory can be viewed as: +🧠 ReMe is a **memory management framework** built for **AI agents**, offering both **file-based** and **vector-based** +memory systems. -```text -Agent Memory = Long-Term Memory + Short-Term Memory - = (Personal + Task + Tool) Memory + (Working Memory) +It addresses two core problems of agent memory: **limited context windows** (early information gets truncated or lost +during +long conversations) and **stateless sessions** (new conversations cannot inherit history and always start from scratch). + +ReMe gives agents **real memory** — old conversations are automatically condensed, important information is persisted, +and the next conversation can recall it automatically. + +--- + +## 📁 File-Based ReMe + +> Memory as files, files as memory + +Treat **memory as files** — readable, editable, and portable. + +| Traditional Memory Systems | File-Based ReMe | +|----------------------------|--------------------| +| 🗄️ Database storage | 📝 Markdown files | +| 🔒 Opaque | 👀 Read anytime | +| ❌ Hard to modify | ✏️ Edit directly | +| 🚫 Hard to migrate | 📦 Copy to migrate | + +``` +.reme/ +├── MEMORY.md # Long-term memory: user preferences, project config, etc. +└── memory/ + └── YYYY-MM-DD.md # Daily logs: work records for the day, written upon compact ``` -- **Personal Memory**: Understand user preferences and adapt to context -- **Task Memory**: Learn from experience and perform better on similar tasks -- **Tool Memory**: Optimize tool selection and parameter usage based on historical performance -- **Working Memory**: Manage short-term context for long-running agents without context overflow +### Core Capabilities + +[ReMe File Based](reme/reme_fb.py) is the core class of the file-based memory system. It acts like an **intelligent +secretary**, managing all memory-related operations: + +| Method | Function | Key Components | +|-----------------|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `start` | 🚀 Start memory system | [BaseFileStore](reme/core/file_store/base_file_store.py) (local file storage)
[BaseFileWatcher](reme/core/file_watcher/base_file_watcher.py) (file watcher)
[BaseEmbeddingModel](reme/core/embedding/base_embedding_model.py) (embedding cache) | +| `close` | 📕 Close and save | Close file store, stop file watcher, save embedding cache | +| `context_check` | 📏 Check context limit | [ContextChecker](reme/memory/file_based/fb_context_checker.py) | +| `compact` | 📦 Compact history to summary | [Compactor](reme/memory/file_based/fb_compactor.py) | +| `summary` | 📝 Write important memory to files | [Summarizer](reme/memory/file_based/fb_summarizer.py) | +| `memory_search` | 🔍 Semantic memory search | [MemorySearch](reme/memory/tools/chunk/memory_search.py) | +| `memory_get` | 📖 Read specified memory file | [MemoryGet](reme/memory/tools/chunk/memory_get.py) | --- -## 📰 Latest Updates +## 🗃️ Vector-Based ReMe + +[ReMe Vector Based](reme/reme.py) is the core class for the vector-based memory system, supporting unified management of +three memory types: + +| Memory Type | Purpose | Usage Context | +|------------------------------|-----------------------------------------------------|---------------| +| **Personal memory** | User preferences, habits | `user_name` | +| **Task / procedural memory** | Task execution experience, success/failure patterns | `task_name` | +| **Tool memory** | Tool usage experience, parameter tuning | `tool_name` | + +### Core Capabilities + +| Method | Function | Description | +|--------------------|---------------------|-----------------------------------------------------------| +| `summarize_memory` | 🧠 Summarize memory | Automatically extract and store memory from conversations | +| `retrieve_memory` | 🔍 Retrieve memory | Retrieve relevant memory by query | +| `add_memory` | ➕ Add memory | Manually add memory to vector store | +| `get_memory` | 📖 Get memory | Fetch a single memory by ID | +| `update_memory` | ✏️ Update memory | Update content or metadata of existing memory | +| `delete_memory` | 🗑️ Delete memory | Delete specified memory | +| `list_memory` | 📋 List memory | List memories with filtering and sorting | + +--- + +## 💻 ReMeCli: Terminal Assistant with File-Based Memory -- **[2026-02]** 💻 ReMeCli: A terminal-based AI chat assistant with built-in memory management. Automatically compacts long conversations into summaries to free up context space, and persists important information as Markdown files for retrieval in future sessions. Memory design inspired by [OpenClaw](https://github.com/openclaw/openclaw). - - [Quick Start](docs/cli/quick_start_en.md) - - Type `/horse` to trigger the Year of the Horse Easter egg -- fireworks, a galloping horse animation, and a random blessing.
- 马
上
有
钱 + May
You
Prosper 		- 马
到
成
功 + Success
at
Hand
-- **[2025-12]** 📄 Our procedural (task) memory paper has been released on [arXiv](https://arxiv.org/abs/2512.10696) -- **[2025-11]** 🧠 React-agent with working-memory demo ([Intro](docs/work_memory/message_offload.md)) with ([Quick Start](docs/cookbook/working/quick_start.md)) and ([Code](cookbook/working_memory/work_memory_demo.py)) -- **[2025-10]** 🚀 Direct Python import support: use `from reme_ai import ReMeApp` without HTTP/MCP service -- **[2025-10]** 🔧 Tool Memory: data-driven tool selection and parameter optimization ([Guide](docs/tool_memory/tool_memory.md)) -- **[2025-09]** 🎉 Async operations support, integrated into agentscope-runtime -- **[2025-09]** 🎉 Task memory and personal memory integration -- **[2025-09]** 🧪 Validated effectiveness in appworld, bfcl(v3), and frozenlake ([Experiments](docs/cookbook)) -- **[2025-08]** 🚀 MCP protocol support ([Quick Start](docs/mcp_quick_start.md)) -- **[2025-06]** 🚀 Multiple backend vector storage (Elasticsearch & ChromaDB) ([Guide](docs/vector_store_api_guide.md)) -- **[2024-09]** 🧠 Personalized and time-aware memory storage +### When Is Memory Written? ---- +| Scenario | Written to | Trigger | +|---------------------------------------------|------------------------|------------------------------------| +| Auto-compact when context is too long | `memory/YYYY-MM-DD.md` | Automatic in background | +| User runs `/compact` | `memory/YYYY-MM-DD.md` | Manual compact + background save | +| User runs `/new` | `memory/YYYY-MM-DD.md` | New conversation + background save | +| User says "remember this" | `MEMORY.md` or log | Agent writes via `write` tool | +| Agent finds important decisions/preferences | `MEMORY.md` | Agent writes proactively | -## ✨ Architecture Design +### Memory Retrieval Tools -

- ReMe Architecture -

+| Method | Tool | When to use | Example | +|-----------------|-----------------|----------------------------------|---------------------------------------| +| Semantic search | `memory_search` | Unsure where it is, fuzzy lookup | "Earlier discussion about deployment" | +| Direct read | `read` | Know the date or file | Read `memory/2025-02-13.md` | -ReMe provides a **modular memory management kit** with pluggable components that can be integrated into any agent framework. The system consists of: +Search uses **vector + BM25 hybrid retrieval** (vector weight 0.7, BM25 weight 0.3), so queries using both natural +language and exact +keywords can match. -#### 🧠 **Task Memory/Experience** +### Built-in Tools -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](docs/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](docs/personal_memory/personal_memory.md) - -#### 🔧 **Tool Memory** - -Data-driven tool selection and usage optimization - -- **Historical Performance Tracking**: Success rates, execution times, and token costs from real usage -- **LLM-as-Judge Evaluation**: Qualitative insights on why tools succeed or fail -- **Parameter Optimization**: Learn optimal parameter configurations from successful calls -- **Dynamic Guidelines**: Transform static tool descriptions into living, learned manuals - -Learn more about how to use tool memory from [tool memory](docs/tool_memory/tool_memory.md) - -#### 🧠 Working Memory - -Short‑term contextual memory for long‑running agents via **message offload & reload**: -- **Message Offload**: Compact large tool outputs to external files or LLM summaries -- **Message Reload**: Search (`grep_working_memory`) and read (`read_working_memory`) offloaded content on demand -📖 **Concept & API**: -- Message offload overview: [Message Offload](docs/work_memory/message_offload.md) -- Offload / reload operators: [Message Offload Ops](docs/work_memory/message_offload_ops.md), [Message Reload Ops](docs/work_memory/message_reload_ops.md) -💻 **End‑to‑End Demo**: -- Working memory quick start: [Working Memory Quick Start](docs/cookbook/working/quick_start.md) -- ReAct agent with working memory: [react_agent_with_working_memory.py](cookbook/working_memory/react_agent_with_working_memory.py) -- Runnable demo: [work_memory_demo.py](cookbook/working_memory/work_memory_demo.py) - ---- - -## 🛠️ Installation - -### Install from PyPI (Recommended) - -```bash -pip install reme-ai -``` - -### Install from Source - -```bash -git clone https://github.com/agentscope-ai/ReMe.git -cd ReMe -pip install . -``` - -### Environment Configuration - -ReMe requires LLM and embedding model configurations. Copy `example.env` to `.env` and configure: - -```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 -``` +| Tool | Function | Details | +|-----------------|----------------|------------------------------------------------------------| +| `memory_search` | Search memory | Vector + BM25 hybrid search over MEMORY.md and memory/*.md | +| `bash` | Run commands | Execute bash commands with timeout and output truncation | +| `ls` | List directory | Show directory structure | +| `read` | Read file | Text and images supported, with segmented reading | +| `edit` | Edit file | Replace after exact text match | +| `write` | Write file | Create or overwrite, auto-create directories | +| `execute_code` | Run Python | Execute code snippets | +| `web_search` | Web search | Search via Tavily | --- ## 🚀 Quick Start -### HTTP Service Startup +### Installation ```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 +pip install -U reme-ai ``` -### MCP Server Support +### Environment Variables + +API keys are set via environment variables; you can put them in a `.env` file in the project root: + +| Variable | Description | Example | +|---------------------------|----------------------------------|-----------------------------------------------------| +| `REME_LLM_API_KEY` | LLM API key | `sk-xxx` | +| `REME_LLM_BASE_URL` | LLM base URL | `https://dashscope.aliyuncs.com/compatible-mode/v1` | +| `REME_EMBEDDING_API_KEY` | Embedding API key | `sk-xxx` | +| `REME_EMBEDDING_BASE_URL` | Embedding base URL | `https://dashscope.aliyuncs.com/compatible-mode/v1` | +| `TAVILY_API_KEY` | Tavily search API key (optional) | `tvly-xxx` | + +### Using ReMeCli + +#### Start ReMeCli ```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 +remecli config=cli ``` -### Core API Usage +#### ReMeCli System Commands -#### Task Memory Management +> Year of the Horse easter egg: `/horse` — fireworks, galloping animation, and random horse-year blessings. -```python -import requests +Commands starting with `/` control session state: -# 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} - ] -}) +| Command | Description | Waits for response | +|------------|--------------------------------------------------------------------|--------------------| +| `/compact` | Manually compact current conversation and save to long-term memory | Yes | +| `/new` | Start new conversation; history saved to long-term memory | No | +| `/clear` | Clear everything, **without saving** | No | +| `/history` | View uncompressed messages in current conversation | No | +| `/help` | Show command list | No | +| `/exit` | Exit | No | -# 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 -}) -``` +**Difference between the three commands** -
-Python import version +| Command | Compact summary | Long-term memory | Message history | +|------------|-----------------|------------------|-----------------| +| `/compact` | New summary | Saved | Keep recent | +| `/new` | Cleared | Saved | Cleared | +| `/clear` | Cleared | Not saved | Cleared | + +> `/clear` permanently deletes; nothing is persisted anywhere. + +### Using the ReMe Package + +#### File-Based ReMe ```python import asyncio -from reme_ai import ReMeApp -async def main(): - async with ReMeApp( - "llm.default.model_name=qwen3-30b-a3b-thinking-2507", - "embedding_model.default.model_name=text-embedding-v4", - "vector_store.default.backend=memory" - ) as app: - # Experience Summarizer: Learn from execution trajectories - result = await app.async_execute( - name="summary_task_memory", - workspace_id="task_workspace", - trajectories=[ - { - "messages": [ - {"role": "user", "content": "Help me create a project plan"} - ], - "score": 1.0 - } - ] - ) - print(result) - - # Retriever: Get relevant memories - result = await app.async_execute( - name="retrieve_task_memory", - workspace_id="task_workspace", - query="How to efficiently manage project progress?", - top_k=1 - ) - print(result) - -if __name__ == "__main__": - asyncio.run(main()) -``` - -
- -
-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 - }' -``` - -
- -#### 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 -}) -``` - -
-Python import version - -```python -import asyncio -from reme_ai import ReMeApp - -async def main(): - async with ReMeApp( - "llm.default.model_name=qwen3-30b-a3b-thinking-2507", - "embedding_model.default.model_name=text-embedding-v4", - "vector_store.default.backend=memory" - ) as app: - # Memory Integration: Learn from user interactions - result = await app.async_execute( - name="summary_personal_memory", - 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"} - ] - } - ] - ) - print(result) - - # Memory Retrieval: Get personal memory fragments - result = await app.async_execute( - name="retrieve_personal_memory", - workspace_id="task_workspace", - query="What are the user's work habits?", - top_k=5 - ) - print(result) - -if __name__ == "__main__": - asyncio.run(main()) -``` - -
- -
-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 - }' -``` - -
- -#### Tool Memory Management - -```python -import requests - -# Record tool execution results -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 - } - ] -}) - -# Generate usage guidelines from history -response = requests.post("http://localhost:8002/summary_tool_memory", json={ - "workspace_id": "tool_workspace", - "tool_names": "web_search" -}) - -# Retrieve tool guidelines before use -response = requests.post("http://localhost:8002/retrieve_tool_memory", json={ - "workspace_id": "tool_workspace", - "tool_names": "web_search" -}) -``` - -
-Python import version - -```python -import asyncio -from reme_ai import ReMeApp - -async def main(): - async with ReMeApp( - "llm.default.model_name=qwen3-30b-a3b-thinking-2507", - "embedding_model.default.model_name=text-embedding-v4", - "vector_store.default.backend=memory" - ) as app: - # Record tool execution results - result = await app.async_execute( - name="add_tool_call_result", - 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 - } - ] - ) - print(result) - - # Generate usage guidelines from history - result = await app.async_execute( - name="summary_tool_memory", - workspace_id="tool_workspace", - tool_names="web_search" - ) - print(result) - - # Retrieve tool guidelines before use - result = await app.async_execute( - name="retrieve_tool_memory", - workspace_id="tool_workspace", - tool_names="web_search" - ) - print(result) - -if __name__ == "__main__": - asyncio.run(main()) -``` - -
- -
-curl version - -```bash -# Record tool execution results -curl -X POST http://localhost:8002/add_tool_call_result \ - -H "Content-Type: application/json" \ - -d '{ - "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 - } - ] - }' - -# Generate usage guidelines from history -curl -X POST http://localhost:8002/summary_tool_memory \ - -H "Content-Type: application/json" \ - -d '{ - "workspace_id": "tool_workspace", - "tool_names": "web_search" - }' - -# Retrieve tool guidelines before use -curl -X POST http://localhost:8002/retrieve_tool_memory \ - -H "Content-Type: application/json" \ - -d '{ - "workspace_id": "tool_workspace", - "tool_names": "web_search" - }' -``` - -
- -#### Working Memory Management - -```python -import requests - -# Summarize and compact working memory for a long-running conversation -response = requests.post("http://localhost:8002/summary_working_memory", json={ - "messages": [ - { - "role": "system", - "content": "You are a helpful assistant. First use `Grep` to find the line numbers that match the keywords or regular expressions, and then use `ReadFile` to read the code around those locations. If no matches are found, never give up; try different parameters, such as searching with only part of the keywords. After `Grep`, use the `ReadFile` command to view content starting from a specified `offset` and `limit`, and do not exceed 100 lines. If the current content is insufficient, you can continue trying different `offset` and `limit` values with the `ReadFile` command." - }, - { - "role": "user", - "content": "搜索下reme项目的的README内容" - }, - { - "role": "assistant", - "content": "", - "tool_calls": [ - { - "index": 0, - "id": "call_6596dafa2a6a46f7a217da", - "function": { - "arguments": "{\"query\": \"readme\"}", - "name": "web_search" - }, - "type": "function" - } - ] - }, - { - "role": "tool", - "content": "ultra large context , over 50000 tokens......" - }, - { - "role": "user", - "content": "根据readme回答task memory在appworld的效果是多少，需要具体的数值" - } - ], - "working_summary_mode": "auto", - "compact_ratio_threshold": 0.75, - "max_total_tokens": 20000, - "max_tool_message_tokens": 2000, - "group_token_threshold": 4000, - "keep_recent_count": 2, - "store_dir": "test_working_memory", - "chat_id": "demo_chat_id" -}) -``` - -
-Python import version - -```python -import asyncio -from reme_ai import ReMeApp +from reme import ReMeFb async def main(): - async with ReMeApp( - "llm.default.model_name=qwen3-30b-a3b-thinking-2507", - "embedding_model.default.model_name=text-embedding-v4", - "vector_store.default.backend=memory" - ) as app: - # Summarize and compact working memory for a long-running conversation - result = await app.async_execute( - name="summary_working_memory", - messages=[ - { - "role": "system", - "content": "You are a helpful assistant. First use `Grep` to find the line numbers that match the keywords or regular expressions, and then use `ReadFile` to read the code around those locations. If no matches are found, never give up; try different parameters, such as searching with only part of the keywords. After `Grep`, use the `ReadFile` command to view content starting from a specified `offset` and `limit`, and do not exceed 100 lines. If the current content is insufficient, you can continue trying different `offset` and `limit` values with the `ReadFile` command." - }, - { - "role": "user", - "content": "搜索下reme项目的的README内容" - }, - { - "role": "assistant", - "content": "", - "tool_calls": [ - { - "index": 0, - "id": "call_6596dafa2a6a46f7a217da", - "function": { - "arguments": "{\"query\": \"readme\"}", - "name": "web_search" - }, - "type": "function" - } - ] - }, - { - "role": "tool", - "content": "ultra large context , over 50000 tokens......" - }, - { - "role": "user", - "content": "根据readme回答task memory在appworld的效果是多少，需要具体的数值" - } - ], - working_summary_mode="auto", - compact_ratio_threshold=0.75, - max_total_tokens=20000, - max_tool_message_tokens=2000, - group_token_threshold=4000, - keep_recent_count=2, - store_dir="test_working_memory", - chat_id="demo_chat_id", - ) - print(result) + # Initialize and start + reme = ReMeFb( + default_llm_config={ + "backend": "openai", # Backend type, OpenAI-compatible API + "model_name": "qwen3.5-plus", # Model name + }, + default_file_store_config={ + "backend": "chroma", # Store backend: sqlite/chroma/local + "fts_enabled": True, # Enable full-text search + "vector_enabled": False, # Enable vector search (set False if no embedding service) + }, + context_window_tokens=128000, # Model context window size (tokens) + reserve_tokens=36000, # Tokens reserved for output + keep_recent_tokens=20000, # Tokens to keep for recent messages + vector_weight=0.7, # Vector search weight (0–1) for hybrid search + candidate_multiplier=3.0, # Candidate multiplier for recall + ) + await reme.start() + + messages = [ + {"role": "user", "content": "I prefer Python 3.12"}, + {"role": "assistant", "content": "Noted, you prefer Python 3.12"}, + ] + + # Check if context exceeds limit + result = await reme.context_check(messages) + print(f"Compact result: {result}") + + # Compact conversation to summary + summary = await reme.compact(messages_to_summarize=messages) + print(f"Summary: {summary}") + + # Write important memory to files (ReAct Agent does this automatically) + await reme.summary(messages=messages, date="2026-02-28") + + # Semantic search over memory + results = await reme.memory_search(query="Python version preference", max_results=5) + print(f"Search results: {results}") + + # Read specified memory file + content = await reme.memory_get(path="MEMORY.md") + print(f"Memory content: {content}") + + # Close (save embedding cache, stop file watcher) + await reme.close() if __name__ == "__main__": asyncio.run(main()) ``` -
+#### Vector-Based ReMe -
-curl version +```python +import asyncio +from reme import ReMe -```bash -curl -X POST http://localhost:8002/summary_working_memory \ - -H "Content-Type: application/json" \ - -d '{ - "messages": [ - { - "role": "system", - "content": "You are a helpful assistant. First use `Grep` to find the line numbers that match the keywords or regular expressions, and then use `ReadFile` to read the code around those locations. If no matches are found, never give up; try different parameters, such as searching with only part of the keywords. After `Grep`, use the `ReadFile` command to view content starting from a specified `offset` and `limit`, and do not exceed 100 lines. If the current content is insufficient, you can continue trying different `offset` and `limit` values with the `ReadFile` command." - }, - { - "role": "user", - "content": "搜索下reme项目的的README内容" - }, - { - "role": "assistant", - "content": "", - "tool_calls": [ - { - "index": 0, - "id": "call_6596dafa2a6a46f7a217da", - "function": { - "arguments": "{\"query\": \"readme\"}", - "name": "web_search" - }, - "type": "function" - } - ] - }, - { - "role": "tool", - "content": "ultra large context , over 50000 tokens......" - }, - { - "role": "user", - "content": "根据readme回答task memory在appworld的效果是多少，需要具体的数值" - } - ], - "working_summary_mode": "auto", - "compact_ratio_threshold": 0.75, - "max_total_tokens": 20000, - "max_tool_message_tokens": 2000, - "group_token_threshold": 4000, - "keep_recent_count": 2, - "store_dir": "test_working_memory", - "chat_id": "demo_chat_id" - }' + +async def main(): + # Initialize ReMe + reme = ReMe( + working_dir=".reme", + default_llm_config={ + "backend": "openai", + "model_name": "qwen3-30b-a3b-thinking-2507", + }, + default_embedding_model_config={ + "backend": "openai", + "model_name": "text-embedding-v4", + "dimensions": 1024, + }, + default_vector_store_config={ + "backend": "local", # Supports local/chroma/qdrant/elasticsearch + }, + ) + await reme.start() + + messages = [ + {"role": "user", "content": "Help me write a Python script", "time_created": "2026-02-28 10:00:00"}, + {"role": "assistant", "content": "Sure, I'll help you write it", "time_created": "2026-02-28 10:00:05"}, + ] + + # 1. Summarize memory from conversation (auto-extract user preferences, task experience, etc.) + result = await reme.summarize_memory( + messages=messages, + user_name="alice", # Personal memory + task_name="code_writing", # Task memory + ) + print(f"Summarize result: {result}") + + # 2. Retrieve relevant memory + memories = await reme.retrieve_memory( + query="Python programming", + user_name="alice", + task_name="code_writing", + ) + print(f"Retrieve result: {memories}") + + # 3. Manually add memory + memory_node = await reme.add_memory( + memory_content="User prefers concise code style", + user_name="alice", + when_to_use="When writing code for the user", + ) + print(f"Added memory: {memory_node}") + memory_id = memory_node.memory_id + + # 4. Get single memory by ID + fetched_memory = await reme.get_memory(memory_id=memory_id) + print(f"Fetched memory: {fetched_memory}") + + # 5. Update memory content + updated_memory = await reme.update_memory( + memory_id=memory_id, + user_name="alice", + memory_content="User prefers concise, well-commented code style", + when_to_use="When writing or reviewing code for the user", + ) + print(f"Updated memory: {updated_memory}") + + # 6. List all memories for user (with filtering and sorting) + all_memories = await reme.list_memory( + user_name="alice", + limit=10, + sort_key="time_created", + reverse=True, + ) + print(f"User memory list: {all_memories}") + + # 7. Delete specified memory + await reme.delete_memory(memory_id=memory_id) + print(f"Deleted memory: {memory_id}") + + # 8. Delete all memories (use with caution) + # await reme.delete_all() + + await reme.close() + + +if __name__ == "__main__": + asyncio.run(main()) ``` -
- --- -## 📦 Pre-built Memory Library +## 🏛️ Technical Architecture -ReMe provides a **memory library** with pre-extracted, production-ready memories that agents can load and use immediately: +### File-Based ReMe Core Architecture -### Available Memory Packs - -| Memory Pack | Domain | Size | Description | -|----------------------|----------------|---------------|-------------------------------------------------------------------------------------| -| **`appworld.jsonl`** | Task Execution | ~100 memories | Complex task planning patterns, multi-step workflows, and error recovery strategies | -| **`bfcl_v3.jsonl`** | Tool Usage | ~150 memories | Function calling patterns, parameter optimization, and tool selection strategies | - -### Loading Pre-built Memories - -```python -# Load pre-built memories -response = requests.post("http://localhost:8002/vector_store", json={ - "workspace_id": "appworld", - "action": "load", - "path": "./docs/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 -}) +```mermaid +graph TB + User[User / Agent] --> ReMeFb[File based ReMe] + ReMeFb --> ContextCheck[Context Check] + ReMeFb --> Compact[Context Compact] + ReMeFb --> Summary[Memory Summary] + ReMeFb --> Search[Memory Retrieval] + ContextCheck --> FbContextChecker[Check Token Limit] + Compact --> FbCompactor[Compact History to Summary] + Summary --> FbSummarizer[ReAct Agent + File Tools] + Search --> MemorySearch[Vector + BM25 Hybrid Search] + FbSummarizer --> FileTools[read / write / edit] + FileTools --> MemoryFiles[memory/*.md] + MemoryFiles -.->|File change| FileWatcher[Async File Watcher] + FileWatcher -->|Update index| FileStore[Local DB] + MemorySearch --> FileStore ``` -
-Python import version +#### Memory Summary: ReAct + File Tools -```python -import asyncio -from reme_ai import ReMeApp +[Summarizer](reme/memory/file_based/fb_summarizer.py) is the core component for memory summarization. It uses the +**ReAct + file tools** pattern. -async def main(): - async with ReMeApp( - "llm.default.model_name=qwen3-30b-a3b-thinking-2507", - "embedding_model.default.model_name=text-embedding-v4", - "vector_store.default.backend=memory" - ) as app: - # Load pre-built memories - result = await app.async_execute( - name="vector_store", - workspace_id="appworld", - action="load", - path="./docs/library/" - ) - print(result) - - # Query relevant memories - result = await app.async_execute( - name="retrieve_task_memory", - workspace_id="appworld", - query="How to navigate to settings and update user profile?", - top_k=1 - ) - print(result) - -if __name__ == "__main__": - asyncio.run(main()) +```mermaid +graph LR + A[Receive conversation] --> B{Think: What's worth recording?} + B --> C[Act: read memory/YYYY-MM-DD.md] + C --> D{Think: How to merge with existing content?} + D --> E[Act: edit to update file] + E --> F{Think: Anything missing?} + F -->|Yes| B + F -->|No| G[Done] ``` -
+#### File Tool Set -## 🧪 Experiments +Summarizer is equipped with file operation tools so the AI can work directly on memory files: -### 🌍 [Appworld Experiment](docs/cookbook/appworld/quickstart.md) +| Tool | Function | Use case | +|---------|-------------------|-----------------------------------------| +| `read` | Read file content | View existing memory, avoid duplicates | +| `write` | Overwrite file | Create new memory file or major rewrite | +| `edit` | Edit part of file | Append or modify specific sections | -We tested ReMe on Appworld using Qwen3-8B (non-thinking mode): +#### Context Compaction -| Method | Avg@4 | Pass@4 | -|--------------|---------------------|---------------------| -| without ReMe | 0.1497 | 0.3285 | -| with ReMe | 0.1706 **(+2.09%)** | 0.3631 **(+3.46%)** | +When a conversation gets too long, [Compactor](reme/memory/file_based/fb_compactor.py) compresses history into a concise +summary — like **meeting minutes**, turning long discussion into key points. -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. +```mermaid +graph LR + A[Messages 1..N] --> B[📦 Compact summary] +C[Recent messages] --> D[Keep as-is] +B --> E[New context] +D --> E +``` -You can find more details on reproducing the experiment in [quickstart.md](docs/cookbook/appworld/quickstart.md). +The compact summary includes what’s needed to continue: -### 🔧 [BFCL-V3 Experiment](docs/cookbook/bfcl/quickstart.md) +| Content | Description | +|----------------|---------------------------------------------| +| 🎯 Goals | What the user wants to accomplish | +| ⚙️ Constraints | Requirements and preferences mentioned | +| 📈 Progress | Completed / in progress / blocked tasks | +| 🔑 Decisions | Decisions made and reasons | +| 📌 Context | Key data such as file paths, function names | -We tested ReMe on BFCL-V3 multi-turn-base (randomly split 50train/150val) using Qwen3-8B (thinking mode): +#### Memory Retrieval -| Method | Avg@4 | Pass@4 | -|--------------|---------------------|---------------------| -| without ReMe | 0.4033 | 0.5955 | -| with ReMe | 0.4450 **(+4.17%)** | 0.6577 **(+6.22%)** | +[MemorySearch](reme/memory/tools/chunk/memory_search.py) provides **vector + BM25 hybrid retrieval**. The two methods +complement each other: -### 🧊 [Frozenlake Experiment](docs/cookbook/frozenlake/quickstart.md) +| Retrieval | Strength | Weakness | +|---------------------|-------------------------------------------------|----------------------------------------| +| **Vector semantic** | Captures similar meaning with different wording | Weaker on exact token match | +| **BM25 full-text** | Strong exact token match | No synonym or paraphrase understanding | -| without ReMe | with ReMe | -|:----------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------:| -|

GIF 1

|

GIF 2

| +**Fusion**: Both retrieval paths are used; results are combined by weighted sum (vector 0.7 + BM25 0.3), so both +natural-language queries and exact lookups get reliable results. -We tested on 100 random frozenlake maps using qwen3-8b: - -| Method | pass rate | -|--------------|------------------| -| without ReMe | 0.66 | -| with ReMe | 0.72 **(+6.0%)** | - -You can find more details on reproducing the experiment in [quickstart.md](docs/cookbook/frozenlake/quickstart.md). - -### 🛠️ [Tool Memory Benchmark](docs/tool_memory/tool_bench.md) - -We evaluated Tool Memory effectiveness using a controlled benchmark with three mock search tools using Qwen3-30B-Instruct: - -| Scenario | Avg Score | Improvement | -|------------------------|-----------|-------------| -| Train (No Memory) | 0.650 | - | -| Test (No Memory) | 0.672 | Baseline | -| **Test (With Memory)** | **0.772** | **+14.88%** | - -**Key Findings:** -- Tool Memory enables data-driven tool selection based on historical performance -- Success rates improved by ~15% with learned parameter configurations - -You can find more details in [tool_bench.md](docs/tool_memory/tool_bench.md) and the implementation at [run_reme_tool_bench.py](cookbook/tool_memory/run_reme_tool_bench.py). - -## 📚 Resources - -### Getting Started -- **[Quick Start](./cookbook/simple_demo)**: Practical examples for immediate use - - [Tool Memory Demo](cookbook/simple_demo/use_tool_memory_demo.py): Complete lifecycle demonstration of tool memory - - [Tool Memory Benchmark](cookbook/tool_memory/run_reme_tool_bench.py): Evaluate tool memory effectiveness - -### Integration Guides -- **[Direct Python Import](docs/cookbook/working/quick_start.md)**: Embed ReMe directly into your agent code -- **[HTTP Service API](docs/vector_store_api_guide.md)**: RESTful API for multi-agent systems -- **[MCP Protocol](docs/mcp_quick_start.md)**: Integration with Claude Desktop and MCP-compatible clients - -### Memory System Configuration -- **[Personal Memory](docs/personal_memory)**: User preference learning and contextual adaptation -- **[Task Memory](docs/task_memory)**: Procedural knowledge extraction and reuse -- **[Tool Memory](docs/tool_memory)**: Data-driven tool selection and optimization -- **[Working Memory](docs/work_memory/message_offload.md)**: Short-term context management for long-running agents - -### Advanced Topics -- **[Operator Pipelines](reme_ai/config/default.yaml)**: Customize memory processing workflows by modifying operator chains -- **[Vector Store Backends](docs/vector_store_api_guide.md)**: Configure local, Elasticsearch, Qdrant, or ChromaDB storage -- **[Example Collection](./cookbook)**: Real-world use cases and best practices +```mermaid +graph LR + Q[Search query] --> V[Vector search × 0.7] +Q --> B[BM25 × 0.3] +V --> M[Dedupe + weighted merge] +B --> M +M --> R[Top-N results] +``` --- -## ⭐ Support & Community +### Vector-Based ReMe Core Architecture -- **Star & Watch**: Stars surface ReMe to more agent builders; watching keeps you updated on new releases. -- **Share your wins**: Open an issue or discussion with what ReMe unlocked for your agents—we love showcasing community builds. -- **Need a feature?** File a request and we’ll help shape it together. +```mermaid +graph TB + User[User / Agent] --> ReMe[Vector Based ReMe] + ReMe --> Summarize[Memory Summarize] + ReMe --> Retrieve[Memory Retrieve] + ReMe --> CRUD[CRUD] + Summarize --> PersonalSum[PersonalSummarizer] + Summarize --> ProceduralSum[ProceduralSummarizer] + Summarize --> ToolSum[ToolSummarizer] + Retrieve --> PersonalRet[PersonalRetriever] + Retrieve --> ProceduralRet[ProceduralRetriever] + Retrieve --> ToolRet[ToolRetriever] + PersonalSum --> VectorStore[Vector DB] + ProceduralSum --> VectorStore + ToolSum --> VectorStore + PersonalRet --> VectorStore + ProceduralRet --> VectorStore + ToolRet --> VectorStore +``` --- -## 🤝 Contribution - -We believe the best memory systems come from collective wisdom. Contributions welcome 👉[Guide](docs/contribution.md): - -### Code Contributions - -- **New Operators**: Develop custom memory processing operators (retrieval, summarization, etc.) -- **Backend Implementations**: Add support for new vector stores or LLM providers -- **Memory Services**: Extend with new memory types or capabilities -- **API Enhancements**: Improve existing endpoints or add new ones - -### Documentation Improvements - -- **Integration Examples**: Show how to integrate ReMe with different agent frameworks -- **Operator Tutorials**: Document custom operator development -- **Best Practice Guides**: Share effective memory management patterns -- **Use Case Studies**: Demonstrate ReMe in real-world applications +## ⭐ Community & Support +- **Star & Watch**: Star helps more agent developers discover ReMe; Watch keeps you updated on new releases and + features. +- **Share your work**: In Issues or Discussions, share what ReMe unlocks for your agents — we’re happy to highlight + great community examples. +- **Need a new feature?** Open a Feature Request; we’ll iterate with the community. +- **Code contributions**: All forms of code contribution are welcome. See + the [Contribution Guide](docs/contribution.md). +- **Acknowledgments**: Thanks to OpenClaw, Mem0, MemU, CoPaw, and other open-source projects for inspiration and + support. --- @@ -853,46 +497,20 @@ We believe the best memory systems come from collective wisdom. Contributions we ```bibtex @software{AgentscopeReMe2025, title = {AgentscopeReMe: Memory Management Kit for Agents}, - author = {Li Yu and - Jiaji Deng and - Zouying Cao and - Weikang Zhou and - Tiancheng Qin and - Qingxu Fu and - Sen Huang and - Xianzhe Xu and - Zhaoyang Liu and - Boyin Liu}, + author = {ReMe Team}, url = {https://reme.agentscope.io}, year = {2025} } - -@misc{AgentscopeReMe2025Paper, - title={Remember Me, Refine Me: A Dynamic Procedural Memory Framework for Experience-Driven Agent Evolution}, - author={Zouying Cao and - Jiaji Deng and - Li Yu and - Weikang Zhou and - Zhaoyang Liu and - Bolin Ding and - Hai Zhao}, - year={2025}, - eprint={2512.10696}, - archivePrefix={arXiv}, - primaryClass={cs.AI}, - url={https://arxiv.org/abs/2512.10696}, -} ``` --- ## ⚖️ License -This project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) file for details. +This project is open source under the Apache License 2.0. See the [LICENSE](./LICENSE) file for details. --- -## Star History +## 📈 Star History [![Star History Chart](https://api.star-history.com/svg?repos=agentscope-ai/ReMe&type=Date)](https://www.star-history.com/#agentscope-ai/ReMe&Date) - diff --git a/README_ZH.md b/README_ZH.md index e9fd9477..d78c7474 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -17,33 +17,82 @@

- 面向智能体的记忆管理工具包, Remember Me, Refine Me.
- 如果 ReMe 对你有帮助，欢迎点一个 ⭐ Star，你的支持是我们持续改进的动力。 + 面向智能体的记忆管理工具包，Remember Me, Refine Me.

+> 老版本请参阅 [0.2.x 版本文档](docs/README_0_2_x_ZH.md) + --- -ReMe 是一个**模块化的记忆管理工具包**，为 AI 智能体提供统一的记忆能力——支持在用户、任务与智能体之间提取、复用与共享记忆。 +🧠 ReMe 是一个专为 **AI 智能体** 打造的记忆管理框架，同时提供基于文件系统和基于向量库的记忆系统。 -智能体的记忆可以被视为： +它解决智能体记忆的两类核心问题：**上下文窗口有限**（长对话时早期信息被截断或丢失）、**会话无状态**（新对话无法继承历史，每次从零开始）。 -```text -Agent Memory = Long-Term Memory + Short-Term Memory - = (Personal + Task + Tool) Memory + (Working Memory) +ReMe 让智能体拥有**真正的记忆力**——旧对话自动浓缩，重要信息持久保存，下次对话自动想起来。 + + +--- + +## 📁 基于文件的 ReMe + +> 记忆即文件，文件即记忆 + +将**记忆视为文件**——可读、可编辑、可复制。 + +| 传统记忆系统 | File Based ReMe | +|-----------|-----------------| +| 🗄️ 数据库存储 | 📝 Markdown 文件 | +| 🔒 不可见 | 👀 随时可读 | +| ❌ 难修改 | ✏️ 直接编辑 | +| 🚫 难迁移 | 📦 复制即迁移 | + +``` +.reme/ +├── MEMORY.md # 长期记忆：用户偏好、项目配置等不常变的信息 +└── memory/ + └── YYYY-MM-DD.md # 每日日志：当天的工作记录，压缩时自动写入 ``` -- **个人记忆（Personal Memory）**：理解用户偏好并适应上下文 -- **任务记忆（Task Memory）**：从经验中学习并在类似任务中表现更好 -- **工具记忆（Tool Memory）**：基于历史表现优化工具选择和参数使用 -- **工作记忆（Working Memory）**：管理长运行智能体的短期上下文，避免上下文溢出 +### 核心能力 + +[ReMe File Based](reme/reme_fb.py) 是基于文件的记忆系统的核心类，就像一个**智能秘书**，帮你管理所有记忆相关的事务： + +| 方法 | 功能 | 关键组件 | +|-----------------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `start` | 🚀 启动记忆系统 | [BaseFileStore](reme/core/file_store/base_file_store.py)（本地文件store）
[BaseFileWatcher](reme/core/file_watcher/base_file_watcher.py)（文件监控）
[BaseEmbeddingModel](reme/core/embedding/base_embedding_model.py)（Embedding 缓存） | +| `close` | 📕 关闭并保存 | 关闭文件store、停止文件监控、保存 Embedding 缓存 | +| `context_check` | 📏 检查上下文是否超限 | [ContextChecker](reme/memory/file_based/fb_context_checker.py) | +| `compact` | 📦 压缩历史对话为摘要 | [Compactor](reme/memory/file_based/fb_compactor.py) | +| `summary` | 📝 将重要记忆写入文件 | [Summarizer](reme/memory/file_based/fb_summarizer.py) | +| `memory_search` | 🔍 语义搜索记忆 | [MemorySearch](reme/memory/tools/chunk/memory_search.py) | +| `memory_get` | 📖 读取指定记忆文件 | [MemoryGet](reme/memory/tools/chunk/memory_get.py) | + +## 🗃️ 基于向量库的 ReMe + +[ReMe Vector Based](reme/reme.py) 是基于向量库的记忆系统核心类，支持三种记忆类型的统一管理： + +| 记忆类型 | 用途 | 使用场景 | +|--------------|------------------|-------------| +| **个人记忆** | 记录用户偏好、习惯 | `user_name` | +| **任务/程序性记忆** | 记录任务执行经验、成功/失败模式 | `task_name` | +| **工具记忆** | 记录工具使用经验、参数优化 | `tool_name` | + +### 核心能力 + +| 方法 | 功能 | 说明 | +|--------------------|----------|----------------| +| `summarize_memory` | 🧠 记忆总结 | 从对话中自动提取并存储记忆 | +| `retrieve_memory` | 🔍 记忆检索 | 根据查询检索相关记忆 | +| `add_memory` | ➕ 添加记忆 | 手动添加记忆到向量库 | +| `get_memory` | 📖 获取记忆 | 通过 ID 获取单条记忆 | +| `update_memory` | ✏️ 更新记忆 | 更新已有记忆的内容或元数据 | +| `delete_memory` | 🗑️ 删除记忆 | 删除指定记忆 | +| `list_memory` | 📋 列出记忆 | 列出某类记忆，支持过滤和排序 | --- -## 📰 最新进展 +## 💻 ReMeCli：基于文件记忆的终端助手 -- **[2026-02]** 💻 ReMeCli：终端 AI 聊天助手，内置记忆管理能力。当对话过长时自动将旧内容压缩为摘要以释放上下文空间，同时将重要信息以 Markdown 文件持久化存储，供未来会话自动检索使用。记忆设计灵感来源于 [OpenClaw](https://github.com/openclaw/openclaw)。 - - [快速开始](docs/cli/quick_start_en.md) - - 输入 `/horse` 触发马年彩蛋——烟花、奔马动画和随机马年祝福。
@@ -58,798 +107,368 @@ Agent Memory = Long-Term Memory + Short-Term Memory
-- **[2025-12]** 📄 我们的程序性（任务）记忆论文已在 [arXiv](https://arxiv.org/abs/2512.10696) 发布 -- **[2025-11]** 🧠 基于工作记忆的 react-agent demo（[介绍](docs/work_memory/message_offload.md)、[Quick Start](docs/cookbook/working/quick_start.md)、[代码](cookbook/working_memory/work_memory_demo.py)） -- **[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]** 🧠 支持个性化与时间敏感的记忆存储 +### 什么时候会写记忆？ ---- +| 场景 | 写到哪 | 怎么触发 | +|------------------|------------------------|----------------------| +| 上下文超长自动压缩 | `memory/YYYY-MM-DD.md` | 后台自动 | +| 用户执行 `/compact` | `memory/YYYY-MM-DD.md` | 手动压缩 + 后台保存 | +| 用户执行 `/new` | `memory/YYYY-MM-DD.md` | 新对话 + 后台保存 | +| 用户说"记住这个" | `MEMORY.md` 或日志 | Agent 用 `write` 工具写入 | +| Agent 发现了重要决策/偏好 | `MEMORY.md` | Agent 主动写 | -## ✨ 架构设计 +### 记忆检索工具 -

- ReMe 架构 -

+| 方式 | 工具 | 什么时候用 | 举例 | +|------|-----------------|------------|--------------------------| +| 语义搜索 | `memory_search` | 不确定记在哪，模糊找 | "之前关于部署的讨论" | +| 直接读 | `read` | 知道是哪天、哪个文件 | 读 `memory/2025-02-13.md` | -ReMe 提供了一个**模块化的记忆管理工具包**，具有可插拔的组件，可以集成到任何智能体框架中。系统包括： +搜索用的是**向量 + BM25 混合检索**（向量权重 0.7，BM25 权重 0.3），无论自然语言还是精确关键词都能命中。 -#### 🧠 **任务记忆 / 经验记忆（Task Memory/Experience）** +### 内置工具 -可在不同智能体之间复用的程序性知识： - -- **成功模式识别**：识别有效策略并理解其背后的原理 -- **失败分析学习**：从错误中学习，避免重复踩坑 -- **对比式模式**：通过多条采样轨迹的对比获取更有价值的记忆 -- **验证模式**：通过验证模块确认提炼出的经验是否有效 - -了解如何使用任务记忆可参考：[任务记忆文档](docs/task_memory/task_memory.md) - -#### 👤 **个人记忆（Personal Memory）** - -面向特定用户的情境化长期记忆： - -- **个体偏好**：记录用户的习惯、偏好与交互风格 -- **情境自适应**：基于时间与上下文动态管理记忆 -- **渐进式学习**：在长期多轮交互中不断加深对用户的理解 -- **时间敏感**：在记忆检索与整合中考虑时间因素 - -了解如何使用个人记忆可参考：[个人记忆文档](docs/personal_memory/personal_memory.md) - -#### 🔧 **工具记忆（Tool Memory）** - -基于真实调用数据的工具选择与使用优化： - -- **历史表现追踪**：记录成功率、调用耗时与 Token 成本 -- **LLM-as-Judge 评估**：提供工具成功 / 失败原因的定性洞察 -- **参数优化**：从历史成功调用中学习最优参数配置 -- **动态指南**：将静态工具描述演化为可持续更新的「活文档」 - -了解如何使用工具记忆可参考：[工具记忆文档](docs/tool_memory/tool_memory.md) - -#### 🧠 **工作记忆（Working Memory）** - -面向长流程智能体的短期上下文记忆，通过**消息卸载与重载（message offload & reload）**实现： -- **消息卸载（Message Offload）**：将体积巨大的工具输出压缩为外部文件或 LLM 摘要 -- **消息重载（Message Reload）**：按需搜索（`grep_working_memory`）并读取（`read_working_memory`）已卸载的内容 - -📖 **概念与 API：** -- 消息卸载概览：[Message Offload](docs/work_memory/message_offload.md) -- 卸载 / 重载算子：[Message Offload Ops](docs/work_memory/message_offload_ops.md)、[Message Reload Ops](docs/work_memory/message_reload_ops.md) - -💻 **端到端 Demo：** -- 工作记忆快速上手：[Working Memory Quick Start](docs/cookbook/working/quick_start.md) -- 带工作记忆的 ReAct 智能体：[react_agent_with_working_memory.py](cookbook/working_memory/react_agent_with_working_memory.py) -- 可运行 Demo：[work_memory_demo.py](cookbook/working_memory/work_memory_demo.py) - ---- - -## 🛠️ 安装 - -### 通过 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 -``` +| 工具 | 功能 | 细节 | +|-----------------|----------|----------------------------------------| +| `memory_search` | 搜记忆 | MEMORY.md 和 memory/*.md 里做向量+BM25 混合检索 | +| `bash` | 跑命令 | 执行 bash 命令，有超时和输出截断 | +| `ls` | 看目录 | 列目录结构 | +| `read` | 读文件 | 文本和图片都行，支持分段读 | +| `edit` | 改文件 | 精确匹配文本后替换 | +| `write` | 写文件 | 创建或覆盖，自动建目录 | +| `execute_code` | 跑 Python | 运行代码片段 | +| `web_search` | 联网搜索 | 通过 Tavily | --- ## 🚀 快速开始 -### 启动 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 +pip install -U reme-ai ``` -### 启动 MCP Server +### 环境变量 + +API 密钥通过环境变量设置，可写在项目根目录的 `.env` 文件中： + +| 环境变量 | 说明 | 示例 | +|---------------------------|-----------------------|-----------------------------------------------------| +| `REME_LLM_API_KEY` | LLM 的 API Key | `sk-xxx` | +| `REME_LLM_BASE_URL` | LLM 的 Base URL | `https://dashscope.aliyuncs.com/compatible-mode/v1` | +| `REME_EMBEDDING_API_KEY` | Embedding 的 API Key | `sk-xxx` | +| `REME_EMBEDDING_BASE_URL` | Embedding 的 Base URL | `https://dashscope.aliyuncs.com/compatible-mode/v1` | +| `TAVILY_API_KEY` | Tavily 搜索 API Key（可选） | `tvly-xxx` | + +### 使用 ReMeCli + +#### 启动 ReMeCli ```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 +remecli config=cli ``` -### 核心 API 用法 +#### ReMeCli 系统命令 -#### 任务记忆管理 +> 马年彩蛋：`/horse` 触发——烟花、奔马动画和随机马年祝福。 -```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} - ] -}) +| 命令 | 说明 | 需等待响应 | +|------------|---------------------|-------| +| `/compact` | 手动压缩当前对话，同时后台存到长期记忆 | 是 | +| `/new` | 开始新对话，历史后台保存到长期记忆 | 否 | +| `/clear` | 清空一切，**不保存** | 否 | +| `/history` | 看当前对话里未压缩的消息 | 否 | +| `/help` | 看命令列表 | 否 | +| `/exit` | 退出 | 否 | -# 记忆检索：获取相关经验 -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 导入版本 +| 命令 | 压缩摘要 | 长期记忆 | 消息历史 | +|------------|-------|------|-------| +| `/compact` | 生成新摘要 | 保存 | 保留最近的 | +| `/new` | 清空 | 保存 | 清空 | +| `/clear` | 清空 | 不保存 | 清空 | + +> `/clear` 是真删，删了就没了，不会存到任何地方。 + +### 使用 ReMe Package + +#### 基于文件的 ReMe ```python import asyncio -from reme_ai import ReMeApp -async def main(): - async with ReMeApp( - "llm.default.model_name=qwen3-30b-a3b-thinking-2507", - "embedding_model.default.model_name=text-embedding-v4", - "vector_store.default.backend=memory" - ) as app: - # 经验总结：从执行轨迹中学习 - result = await app.async_execute( - name="summary_task_memory", - workspace_id="task_workspace", - trajectories=[ - { - "messages": [ - {"role": "user", "content": "Help me create a project plan"} - ], - "score": 1.0 - } - ] - ) - print(result) - - # 记忆检索：获取相关经验 - result = await app.async_execute( - name="retrieve_task_memory", - workspace_id="task_workspace", - query="How to efficiently manage project progress?", - top_k=1 - ) - print(result) - -if __name__ == "__main__": - asyncio.run(main()) -``` - -
- -
-curl 版本 - -```bash -# 经验总结：从执行轨迹中学习 -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} - ] - }' - -# 记忆检索：获取相关经验 -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 - }' -``` - -
- -#### 个人记忆管理 - -```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 导入版本 - -```python -import asyncio -from reme_ai import ReMeApp - -async def main(): - async with ReMeApp( - "llm.default.model_name=qwen3-30b-a3b-thinking-2507", - "embedding_model.default.model_name=text-embedding-v4", - "vector_store.default.backend=memory" - ) as app: - # 记忆整合：从用户交互中学习 - result = await app.async_execute( - name="summary_personal_memory", - 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"} - ] - } - ] - ) - print(result) - - # 记忆检索：获取个人记忆片段 - result = await app.async_execute( - name="retrieve_personal_memory", - workspace_id="task_workspace", - query="What are the user's work habits?", - top_k=5 - ) - print(result) - -if __name__ == "__main__": - asyncio.run(main()) -``` - -
- -
-curl 版本 - -```bash -# 记忆整合：从用户交互中学习 -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"} - ]} - ] - }' - -# 记忆检索：获取个人记忆片段 -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 - }' -``` - -
- -#### 工具记忆管理 - -```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" -}) -``` - -
-Python 导入版本 - -```python -import asyncio -from reme_ai import ReMeApp - -async def main(): - async with ReMeApp( - "llm.default.model_name=qwen3-30b-a3b-thinking-2507", - "embedding_model.default.model_name=text-embedding-v4", - "vector_store.default.backend=memory" - ) as app: - # 记录工具调用结果 - result = await app.async_execute( - name="add_tool_call_result", - 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 - } - ] - ) - print(result) - - # 从历史生成使用指南 - result = await app.async_execute( - name="summary_tool_memory", - workspace_id="tool_workspace", - tool_names="web_search" - ) - print(result) - - # 在使用前检索工具指南 - result = await app.async_execute( - name="retrieve_tool_memory", - workspace_id="tool_workspace", - tool_names="web_search" - ) - print(result) - -if __name__ == "__main__": - asyncio.run(main()) -``` - -
- -
-curl 版本 - -```bash -# 记录工具调用结果 -curl -X POST http://localhost:8002/add_tool_call_result \ - -H "Content-Type: application/json" \ - -d '{ - "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 - } - ] - }' - -# 从历史生成使用指南 -curl -X POST http://localhost:8002/summary_tool_memory \ - -H "Content-Type: application/json" \ - -d '{ - "workspace_id": "tool_workspace", - "tool_names": "web_search" - }' - -# 在使用前检索工具指南 -curl -X POST http://localhost:8002/retrieve_tool_memory \ - -H "Content-Type: application/json" \ - -d '{ - "workspace_id": "tool_workspace", - "tool_names": "web_search" - }' -``` - -
- -#### 工作记忆管理 - -```python -import requests - -# 对长对话 / 长流程的工作记忆进行压缩与总结 -response = requests.post("http://localhost:8002/summary_working_memory", json={ - "messages": [ - { - "role": "system", - "content": "You are a helpful assistant. First use `Grep` to find the line numbers that match the keywords or regular expressions, and then use `ReadFile` to read the code around those locations. If no matches are found, never give up; try different parameters, such as searching with only part of the keywords. After `Grep`, use the `ReadFile` command to view content starting from a specified `offset` and `limit`, and do not exceed 100 lines. If the current content is insufficient, you can continue trying different `offset` and `limit` values with the `ReadFile` command." - }, - { - "role": "user", - "content": "搜索下reme项目的的README内容" - }, - { - "role": "assistant", - "content": "", - "tool_calls": [ - { - "index": 0, - "id": "call_6596dafa2a6a46f7a217da", - "function": { - "arguments": "{\"query\": \"readme\"}", - "name": "web_search" - }, - "type": "function" - } - ] - }, - { - "role": "tool", - "content": "ultra large context , over 50000 tokens......" - }, - { - "role": "user", - "content": "根据readme回答task memory在appworld的效果是多少，需要具体的数值" - } - ], - "working_summary_mode": "auto", - "compact_ratio_threshold": 0.75, - "max_total_tokens": 20000, - "max_tool_message_tokens": 2000, - "group_token_threshold": 4000, - "keep_recent_count": 2, - "store_dir": "test_working_memory", - "chat_id": "demo_chat_id" -}) -``` - -
-Python 导入版本 - -```python -import asyncio -from reme_ai import ReMeApp +from reme import ReMeFb async def main(): - async with ReMeApp( - "llm.default.model_name=qwen3-30b-a3b-thinking-2507", - "embedding_model.default.model_name=text-embedding-v4", - "vector_store.default.backend=memory" - ) as app: - # 对长对话 / 长流程的工作记忆进行压缩与总结 - result = await app.async_execute( - name="summary_working_memory", - messages=[ - { - "role": "system", - "content": "You are a helpful assistant. First use `Grep` to find the line numbers that match the keywords or regular expressions, and then use `ReadFile` to read the code around those locations. If no matches are found, never give up; try different parameters, such as searching with only part of the keywords. After `Grep`, use the `ReadFile` command to view content starting from a specified `offset` and `limit`, and do not exceed 100 lines. If the current content is insufficient, you can continue trying different `offset` and `limit` values with the `ReadFile` command." - }, - { - "role": "user", - "content": "搜索下reme项目的的README内容" - }, - { - "role": "assistant", - "content": "", - "tool_calls": [ - { - "index": 0, - "id": "call_6596dafa2a6a46f7a217da", - "function": { - "arguments": "{\"query\": \"readme\"}", - "name": "web_search" - }, - "type": "function" - } - ] - }, - { - "role": "tool", - "content": "ultra large context , over 50000 tokens......" - }, - { - "role": "user", - "content": "根据readme回答task memory在appworld的效果是多少，需要具体的数值" - } - ], - working_summary_mode="auto", - compact_ratio_threshold=0.75, - max_total_tokens=20000, - max_tool_message_tokens=2000, - group_token_threshold=4000, - keep_recent_count=2, - store_dir="test_working_memory", - chat_id="demo_chat_id", - ) - print(result) + # 初始化并启动 + reme = ReMeFb( + default_llm_config={ + "backend": "openai", # 后端类型，支持 openai 兼容接口 + "model_name": "qwen3.5-plus", # 模型名称 + }, + default_file_store_config={ + "backend": "chroma", # 存储后端，支持 sqlite/chroma/local + "fts_enabled": True, # 是否启用全文搜索 + "vector_enabled": False, # 是否启用向量搜索（无 embedding 服务可设为 False） + }, + context_window_tokens=128000, # 模型上下文窗口大小（tokens） + reserve_tokens=36000, # 预留给输出的 token 数量 + keep_recent_tokens=20000, # 保留最近消息的 token 数量 + vector_weight=0.7, # 向量搜索权重（0-1），用于混合搜索 + candidate_multiplier=3.0, # 候选结果倍数，用于召回更多候选项 + ) + await reme.start() + + messages = [ + {"role": "user", "content": "我喜欢用 Python 3.12"}, + {"role": "assistant", "content": "好的，已记录你偏好 Python 3.12"}, + ] + + # 检查上下文是否超限 + result = await reme.context_check(messages) + print(f"压缩结论: {result}") + + # 压缩对话为摘要 + summary = await reme.compact(messages_to_summarize=messages) + print(f"摘要: {summary}") + + # 将重要记忆写入文件（ReAct Agent 自动操作） + await reme.summary(messages=messages, date="2026-02-28") + + # 语义搜索记忆 + results = await reme.memory_search(query="Python 版本偏好", max_results=5) + print(f"搜索结果: {results}") + + # 读取指定记忆文件 + content = await reme.memory_get(path="MEMORY.md") + print(f"记忆内容: {content}") + + # 关闭（保存 Embedding 缓存、停止文件监控） + await reme.close() if __name__ == "__main__": asyncio.run(main()) ``` -
+#### 基于向量库的 ReMe -
-curl 版本 +```python +import asyncio +from reme import ReMe -```bash -curl -X POST http://localhost:8002/summary_working_memory \ - -H "Content-Type: application/json" \ - -d '{ - "messages": [ - { - "role": "system", - "content": "You are a helpful assistant. First use `Grep` to find the line numbers that match the keywords or regular expressions, and then use `ReadFile` to read the code around those locations. If no matches are found, never give up; try different parameters, such as searching with only part of the keywords. After `Grep`, use the `ReadFile` command to view content starting from a specified `offset` and `limit`, and do not exceed 100 lines. If the current content is insufficient, you can continue trying different `offset` and `limit` values with the `ReadFile` command." - }, - { - "role": "user", - "content": "搜索下reme项目的的README内容" - }, - { - "role": "assistant", - "content": "", - "tool_calls": [ - { - "index": 0, - "id": "call_6596dafa2a6a46f7a217da", - "function": { - "arguments": "{\"query\": \"readme\"}", - "name": "web_search" - }, - "type": "function" - } - ] - }, - { - "role": "tool", - "content": "ultra large context , over 50000 tokens......" - }, - { - "role": "user", - "content": "根据readme回答task memory在appworld的效果是多少，需要具体的数值" - } - ], - "working_summary_mode": "auto", - "compact_ratio_threshold": 0.75, - "max_total_tokens": 20000, - "max_tool_message_tokens": 2000, - "group_token_threshold": 4000, - "keep_recent_count": 2, - "store_dir": "test_working_memory", - "chat_id": "demo_chat_id" - }' + +async def main(): + # 初始化 ReMe + reme = ReMe( + working_dir=".reme", + default_llm_config={ + "backend": "openai", + "model_name": "qwen3-30b-a3b-thinking-2507", + }, + default_embedding_model_config={ + "backend": "openai", + "model_name": "text-embedding-v4", + "dimensions": 1024, + }, + default_vector_store_config={ + "backend": "local", # 支持 local/chroma/qdrant/elasticsearch + }, + ) + await reme.start() + + messages = [ + {"role": "user", "content": "帮我写一个 Python 脚本", "time_created": "2026-02-28 10:00:00"}, + {"role": "assistant", "content": "好的，我来帮你写", "time_created": "2026-02-28 10:00:05"}, + ] + + # 1. 从对话中总结记忆（自动提取用户偏好、任务经验等） + result = await reme.summarize_memory( + messages=messages, + user_name="alice", # 个人记忆 + task_name="code_writing", # 任务记忆 + ) + print(f"总结结果: {result}") + + # 2. 检索相关记忆 + memories = await reme.retrieve_memory( + query="Python 编程", + user_name="alice", + task_name="code_writing", + ) + print(f"检索结果: {memories}") + + # 3. 手动添加记忆 + memory_node = await reme.add_memory( + memory_content="用户喜欢简洁的代码风格", + user_name="alice", + when_to_use="当为用户编写代码时", + ) + print(f"添加的记忆: {memory_node}") + memory_id = memory_node.memory_id + + # 4. 通过 ID 获取单条记忆 + fetched_memory = await reme.get_memory(memory_id=memory_id) + print(f"获取的记忆: {fetched_memory}") + + # 5. 更新记忆内容 + updated_memory = await reme.update_memory( + memory_id=memory_id, + user_name="alice", + memory_content="用户喜欢简洁且带注释的代码风格", + when_to_use="当为用户编写或审查代码时", + ) + print(f"更新后的记忆: {updated_memory}") + + # 6. 列出用户的所有记忆（支持过滤和排序） + all_memories = await reme.list_memory( + user_name="alice", + limit=10, + sort_key="time_created", + reverse=True, + ) + print(f"用户记忆列表: {all_memories}") + + # 7. 删除指定记忆 + await reme.delete_memory(memory_id=memory_id) + print(f"已删除记忆: {memory_id}") + + # 8. 删除所有记忆（谨慎使用） + # await reme.delete_all() + + await reme.close() + + +if __name__ == "__main__": + asyncio.run(main()) ``` -
+## 🏛️ 技术架构 + +### 基于文件的 ReMe 核心架构 + +```mermaid +graph TB + User[用户 / Agent] --> ReMeFb[File based ReMe] + ReMeFb --> ContextCheck[上下文检查] + ReMeFb --> Compact[上下文压缩] + ReMeFb --> Summary[记忆总结] + ReMeFb --> Search[记忆检索] + ContextCheck --> FbContextChecker[检查 Token 是否超限] + Compact --> FbCompactor[压缩历史对话为摘要] + Summary --> FbSummarizer[ReAct Agent + 文件工具] + Search --> MemorySearch[向量 + BM25 混合检索] + FbSummarizer --> FileTools[read / write / edit] + FileTools --> MemoryFiles[memory/*.md] + MemoryFiles -.->|文件变更| FileWatcher[异步文件监控] + FileWatcher -->|更新索引| FileStore[本地数据库] + MemorySearch --> FileStore +``` + +#### 记忆总结：ReAct + 文件工具 + +[Summarizer](reme/memory/file_based/fb_summarizer.py) 是记忆总结的核心组件，它采用 **ReAct + 文件工具** 模式。 + +```mermaid +graph LR + A[接收对话] --> B{思考: 有什么值得记录?} + B --> C[行动: read memory/YYYY-MM-DD.md] + C --> D{思考: 如何与现有内容合并?} + D --> E[行动: edit 更新文件] + E --> F{思考: 还有遗漏吗?} + F -->|是| B + F -->|否| G[完成] +``` + +#### 文件工具集 + +Summarizer 配备了一套文件操作工具，让 AI 能够直接操作记忆文件： + +| 工具 | 功能 | 使用场景 | +|---------|--------|--------------| +| `read` | 读取文件内容 | 查看现有记忆，避免重复 | +| `write` | 覆盖写入文件 | 创建新记忆文件或大幅重构 | +| `edit` | 编辑文件局部 | 追加新内容或修改特定部分 | + +#### 上下文压缩 + +当对话过长时，[Compactor](reme/memory/file_based/fb_compactor.py) 负责将历史对话压缩为精华摘要——就像写**会议纪要** +，把冗长的讨论浓缩成关键要点。 + +```mermaid +graph LR + A[消息1..N] --> B[📦 压缩摘要] +C[最近消息] --> D[保留原样] +B --> E[新的上下文] +D --> E +``` + +压缩摘要包含继续工作所需的关键信息： + +| 内容 | 说明 | +|--------|---------------| +| 🎯 目标 | 用户想要完成什么 | +| ⚙️ 约束 | 用户提到的要求和偏好 | +| 📈 进展 | 已完成/进行中/阻塞的任务 | +| 🔑 决策 | 做出的决策及原因 | +| 📌 上下文 | 文件路径、函数名等关键数据 | + +#### 记忆检索 + +[MemorySearch](reme/memory/tools/chunk/memory_search.py) 提供**向量 + BM25 混合检索**能力，两种方式优势互补： + +| 检索方式 | 优势 | 劣势 | +|-------------|-----------------|----------------| +| **向量语义** | 捕捉意义相近但措辞不同的内容 | 对精确 token 匹配较弱 | +| **BM25 全文** | 精确 token 命中效果极佳 | 无法理解同义词和改写 | + +**融合机制**：同时使用两路召回，按权重加权求和（向量 0.7 + BM25 0.3），确保无论是「自然语言提问」还是「精确查找」都能获得可靠结果。 + +```mermaid +graph LR + Q[搜索查询] --> V[向量搜索 × 0.7] +Q --> B[BM25 × 0.3] +V --> M[去重 + 加权融合] +B --> M +M --> R[Top-N 结果] +``` --- -## 📦 开箱即用的记忆库 +### 基于向量库的 ReMe 核心架构 -ReMe 提供一个**记忆库**，包含预先提取的、生产就绪的记忆，智能体可以立即加载和使用： - -### 可用记忆包 - -| 记忆包 | 领域 | 规模 | 描述 | -|----------------------|------------|----------------|--------------------------------------------------------| -| **`appworld.jsonl`** | 任务执行 | ~100 条记忆 | 复杂任务规划模式、多步骤工作流和错误恢复策略 | -| **`bfcl_v3.jsonl`** | 工具使用 | ~150 条记忆 | 函数调用模式、参数优化和工具选择策略 | - -### 加载预构建记忆 - -```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 -}) +```mermaid +graph TB + User[用户 / Agent] --> ReMe[Vector Based ReMe] + ReMe --> Summarize[记忆总结] + ReMe --> Retrieve[记忆检索] + ReMe --> CRUD[增删改查] + Summarize --> PersonalSum[PersonalSummarizer] + Summarize --> ProceduralSum[ProceduralSummarizer] + Summarize --> ToolSum[ToolSummarizer] + Retrieve --> PersonalRet[PersonalRetriever] + Retrieve --> ProceduralRet[ProceduralRetriever] + Retrieve --> ToolRet[ToolRetriever] + PersonalSum --> VectorStore[向量数据库] + ProceduralSum --> VectorStore + ToolSum --> VectorStore + PersonalRet --> VectorStore + ProceduralRet --> VectorStore + ToolRet --> VectorStore ``` -
-Python 导入版本 - -```python -import asyncio -from reme_ai import ReMeApp - -async def main(): - async with ReMeApp( - "llm.default.model_name=qwen3-30b-a3b-thinking-2507", - "embedding_model.default.model_name=text-embedding-v4", - "vector_store.default.backend=memory" - ) as app: - # 加载内置记忆 - result = await app.async_execute( - name="vector_store", - workspace_id="appworld", - action="load", - path="./docs/library/" - ) - print(result) - - # 查询相关记忆 - result = await app.async_execute( - name="retrieve_task_memory", - workspace_id="appworld", - query="How to navigate to settings and update user profile?", - top_k=1 - ) - print(result) - -if __name__ == "__main__": - asyncio.run(main()) -``` - -
- ---- - -## 🧪 实验结果 - -### 🌍 [Appworld 实验](docs/cookbook/appworld/quickstart.md) - -我们在 Appworld 环境上使用 Qwen3-8B（非思考模式）进行评测： - -| 方法 | Avg@4 | Pass@4 | -|-----------|-------------------|-------------------| -| 无 ReMe | 0.1497 | 0.3285 | -| 使用 ReMe | 0.1706 **(+2.09%)** | 0.3631 **(+3.46%)** | - -Pass@K 衡量在生成 K 个候选中，至少一个成功完成任务（score=1）的概率。 -当前实验使用的是内部 AppWorld 环境，可能与对外版本存在轻微差异。 - -关于如何复现实验的更多细节，见 [quickstart.md](docs/cookbook/appworld/quickstart.md)。 - -### 🔧 [BFCL-V3 实验](docs/cookbook/bfcl/quickstart.md) - -我们在 BFCL-V3 multi-turn-base 任务（随机划分 50 train / 150 val）上，使用 Qwen3-8B（思考模式）进行评测： - -| 方法 | Avg@4 | Pass@4 | -|------------|-----------------|---------------------| -| 无 ReMe | 0.4033 | 0.5955 | -| 使用 ReMe | 0.4450 **(+4.17%)** | 0.6577 **(+6.22%)** | - -### 🧊 [Frozenlake 实验](docs/cookbook/frozenlake/quickstart.md) - -| 无 ReMe | 使用 ReMe | -|:------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------:| -|

失败示例

|

成功示例

| - -我们在 100 张随机 frozenlake 地图上，使用 qwen3-8b 进行测试： - -| 方法 | 通过率 | -|------------|-----------------| -| 无 ReMe | 0.66 | -| 使用 ReMe | 0.72 **(+6.0%)** | - -更多复现实验细节见 [quickstart.md](docs/cookbook/frozenlake/quickstart.md)。 - -### 🛠️ [工具记忆基准](docs/tool_memory/tool_bench.md) - -我们在一个受控基准上，使用三个模拟搜索工具与 Qwen3-30B-Instruct 评估工具记忆的效果： - -| 场景 | 平均分 | 提升 | -|-----------------------|--------|------------| -| 训练集（无记忆） | 0.650 | - | -| 测试集（无记忆） | 0.672 | 基线 | -| **测试集（使用记忆）** | **0.772** | **+14.88%** | - -**关键结论：** -- 工具记忆可以基于历史表现进行数据驱动的工具选择 -- 通过学习参数配置，成功率约提升 15% - -更多细节见 [tool_bench.md](docs/tool_memory/tool_bench.md) 与实现代码 [run_reme_tool_bench.py](cookbook/tool_memory/run_reme_tool_bench.py)。 - ---- - -## 📚 资源 - -### 快速入门 -- **[Quick Start](./cookbook/simple_demo)**：实用示例，可立即使用 - - [工具记忆 Demo](cookbook/simple_demo/use_tool_memory_demo.py)：工具记忆的完整生命周期演示 - - [工具记忆基准](cookbook/tool_memory/run_reme_tool_bench.py)：评估工具记忆效果 - -### 集成指南 -- **[直接 Python 导入](docs/cookbook/working/quick_start.md)**：将 ReMe 直接嵌入到你的智能体代码中 -- **[HTTP 服务 API](docs/vector_store_api_guide.md)**：用于多智能体系统的 RESTful API -- **[MCP 协议](docs/mcp_quick_start.md)**：与 Claude Desktop 和 MCP 兼容客户端集成 - -### 记忆系统配置 -- **[个人记忆](docs/personal_memory)**：用户偏好学习和上下文自适应 -- **[任务记忆](docs/task_memory)**：程序性知识提取和复用 -- **[工具记忆](docs/tool_memory)**：数据驱动的工具选择和优化 -- **[工作记忆](docs/work_memory/message_offload.md)**：长流程智能体的短期上下文管理 - -### 高级主题 -- **[算子管道](reme_ai/config/default.yaml)**：通过修改算子链来自定义记忆处理工作流 -- **[向量存储后端](docs/vector_store_api_guide.md)**：配置本地、Elasticsearch、Qdrant 或 ChromaDB 存储 -- **[案例集](./cookbook)**：真实场景的用例和最佳实践 - ---- - ## ⭐ 社区与支持 -- **Star & Watch**：Star 可以让更多智能体开发者发现 ReMe；Watch 能帮助你第一时间获知新版本与特性。 +- **Star 与 Watch**：Star 可让更多智能体开发者发现 ReMe；Watch 可助你第一时间获知新版本与特性。 - **分享你的成果**：在 Issue 或 Discussion 中分享 ReMe 为你的智能体解锁了什么——我们非常乐意展示社区的优秀案例。 -- **需要新功能？** 提交 Feature Request，我们将一起完善它。 - ---- - -## 🤝 参与贡献 - -我们相信，最好的记忆系统来自社区的集体智慧。欢迎贡献 👉[贡献指南](docs/contribution.md)： - -### 代码贡献 - -- **新算子**：开发自定义记忆处理算子（检索、总结等） -- **后端实现**：添加对新向量存储或 LLM 提供商的支持 -- **记忆服务**：扩展新的记忆类型或能力 -- **API 增强**：改进现有端点或添加新端点 - -### 文档改进 - -- **集成示例**：展示如何将 ReMe 与不同智能体框架集成 -- **算子教程**：记录自定义算子开发 -- **最佳实践指南**：分享有效的记忆管理模式 -- **用例研究**：展示 ReMe 在实际应用中的使用 +- **需要新功能？** 提交 Feature Request，我们将与社区一起完善。 +- **代码贡献**：欢迎任何形式的代码贡献，请参阅 [贡献指南](docs/contribution.md)。 +- **致谢**：感谢 OpenClaw、Mem0、MemU、CoPaw 等优秀的开源项目，为项目带来诸多启发与帮助。 --- @@ -858,35 +477,10 @@ Pass@K 衡量在生成 K 个候选中，至少一个成功完成任务（score=1 ```bibtex @software{AgentscopeReMe2025, title = {AgentscopeReMe: Memory Management Kit for Agents}, - author = {Li Yu and - Jiaji Deng and - Zouying Cao and - Weikang Zhou and - Tiancheng Qin and - Qingxu Fu and - Sen Huang and - Xianzhe Xu and - Zhaoyang Liu and - Boyin Liu}, + author = {ReMe Team}, url = {https://reme.agentscope.io}, year = {2025} } - -@misc{AgentscopeReMe2025Paper, - title={Remember Me, Refine Me: A Dynamic Procedural Memory Framework for Experience-Driven Agent Evolution}, - author={Zouying Cao and - Jiaji Deng and - Li Yu and - Weikang Zhou and - Zhaoyang Liu and - Bolin Ding and - Hai Zhao}, - year={2025}, - eprint={2512.10696}, - archivePrefix={arXiv}, - primaryClass={cs.AI}, - url={https://arxiv.org/abs/2512.10696}, -} ``` --- @@ -897,6 +491,6 @@ Pass@K 衡量在生成 K 个候选中，至少一个成功完成任务（score=1 --- -## Star 历史 +## 📈 Star 历史 [![Star History Chart](https://api.star-history.com/svg?repos=agentscope-ai/ReMe&type=Date)](https://www.star-history.com/#agentscope-ai/ReMe&Date) diff --git a/docs/README_0_2_x.md b/docs/README_0_2_x.md new file mode 100644 index 00000000..e1bc85a1 --- /dev/null +++ b/docs/README_0_2_x.md @@ -0,0 +1,897 @@ +

+ ReMe Logo +

+ +

+ Python Version + PyPI Version + PyPI Downloads + GitHub commit activity +

+ +

+ License + English + 简体中文 + GitHub Stars +

+ +

+ Memory Management Kit for Agents, Remember Me, Refine Me.
+ If you find it useful, please give us a ⭐ Star. +

+ +--- + +ReMe is a **modular memory management kit** that provides AI agents with unified memory capabilities—enabling the ability to extract, reuse, and share memories across users, tasks, and agents. +Agent memory can be viewed as: + +```text +Agent Memory = Long-Term Memory + Short-Term Memory + = (Personal + Task + Tool) Memory + (Working Memory) +``` + +- **Personal Memory**: Understand user preferences and adapt to context +- **Task Memory**: Learn from experience and perform better on similar tasks +- **Tool Memory**: Optimize tool selection and parameter usage based on historical performance +- **Working Memory**: Manage short-term context for long-running agents without context overflow + +--- + +## 📰 Latest Updates + +- **[2026-02]** 💻 ReMeCli: A terminal-based AI chat assistant with built-in memory management. Automatically compacts long conversations into summaries to free up context space, and persists important information as Markdown files for retrieval in future sessions. Memory design inspired by [OpenClaw](https://github.com/openclaw/openclaw). + - [Quick Start](docs/cli/quick_start_en.md) + - Type `/horse` to trigger the Year of the Horse Easter egg -- fireworks, a galloping horse animation, and a random blessing. + + + + + + +
+ 马
上
有
钱 + 		+ + + 马
到
成
功 +
+ +- **[2025-12]** 📄 Our procedural (task) memory paper has been released on [arXiv](https://arxiv.org/abs/2512.10696) +- **[2025-11]** 🧠 React-agent with working-memory demo ([Intro](docs/work_memory/message_offload.md)) with ([Quick Start](docs/cookbook/working/quick_start.md)) and ([Code](cookbook/working_memory/work_memory_demo.py)) +- **[2025-10]** 🚀 Direct Python import support: use `from reme_ai import ReMeApp` without HTTP/MCP service +- **[2025-10]** 🔧 Tool Memory: data-driven tool selection and parameter optimization ([Guide](docs/tool_memory/tool_memory.md)) +- **[2025-09]** 🎉 Async operations support, integrated into agentscope-runtime +- **[2025-09]** 🎉 Task memory and personal memory integration +- **[2025-09]** 🧪 Validated effectiveness in appworld, bfcl(v3), and frozenlake ([Experiments](docs/cookbook)) +- **[2025-08]** 🚀 MCP protocol support ([Quick Start](docs/mcp_quick_start.md)) +- **[2025-06]** 🚀 Multiple backend vector storage (Elasticsearch & ChromaDB) ([Guide](docs/vector_store_api_guide.md)) +- **[2024-09]** 🧠 Personalized and time-aware memory storage + +--- + +## ✨ Architecture Design + +

+ ReMe Architecture +

+ +ReMe provides a **modular memory management kit** with pluggable components that can be integrated into any agent framework. The system consists of: + +#### 🧠 **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](docs/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](docs/personal_memory/personal_memory.md) + +#### 🔧 **Tool Memory** + +Data-driven tool selection and usage optimization + +- **Historical Performance Tracking**: Success rates, execution times, and token costs from real usage +- **LLM-as-Judge Evaluation**: Qualitative insights on why tools succeed or fail +- **Parameter Optimization**: Learn optimal parameter configurations from successful calls +- **Dynamic Guidelines**: Transform static tool descriptions into living, learned manuals + +Learn more about how to use tool memory from [tool memory](docs/tool_memory/tool_memory.md) + +#### 🧠 Working Memory + +Short‑term contextual memory for long‑running agents via **message offload & reload**: +- **Message Offload**: Compact large tool outputs to external files or LLM summaries +- **Message Reload**: Search (`grep_working_memory`) and read (`read_working_memory`) offloaded content on demand +📖 **Concept & API**: +- Message offload overview: [Message Offload](docs/work_memory/message_offload.md) +- Offload / reload operators: [Message Offload Ops](docs/work_memory/message_offload_ops.md), [Message Reload Ops](docs/work_memory/message_reload_ops.md) +💻 **End‑to‑End Demo**: +- Working memory quick start: [Working Memory Quick Start](docs/cookbook/working/quick_start.md) +- ReAct agent with working memory: [react_agent_with_working_memory.py](cookbook/working_memory/react_agent_with_working_memory.py) +- Runnable demo: [work_memory_demo.py](cookbook/working_memory/work_memory_demo.py) + +--- + +## 🛠️ Installation + +### Install from PyPI (Recommended) + +```bash +pip install reme-ai +``` + +### Install from Source + +```bash +git clone https://github.com/agentscope-ai/ReMe.git +cd ReMe +pip install . +``` + +### Environment Configuration + +ReMe requires LLM and embedding model configurations. Copy `example.env` to `.env` and configure: + +```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 +``` + +--- + +## 🚀 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 +}) +``` + +
+Python import version + +```python +import asyncio +from reme_ai import ReMeApp + +async def main(): + async with ReMeApp( + "llm.default.model_name=qwen3-30b-a3b-thinking-2507", + "embedding_model.default.model_name=text-embedding-v4", + "vector_store.default.backend=memory" + ) as app: + # Experience Summarizer: Learn from execution trajectories + result = await app.async_execute( + name="summary_task_memory", + workspace_id="task_workspace", + trajectories=[ + { + "messages": [ + {"role": "user", "content": "Help me create a project plan"} + ], + "score": 1.0 + } + ] + ) + print(result) + + # Retriever: Get relevant memories + result = await app.async_execute( + name="retrieve_task_memory", + workspace_id="task_workspace", + query="How to efficiently manage project progress?", + top_k=1 + ) + print(result) + +if __name__ == "__main__": + asyncio.run(main()) +``` + +
+ +
+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 + }' +``` + +
+ +#### 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 +}) +``` + +
+Python import version + +```python +import asyncio +from reme_ai import ReMeApp + +async def main(): + async with ReMeApp( + "llm.default.model_name=qwen3-30b-a3b-thinking-2507", + "embedding_model.default.model_name=text-embedding-v4", + "vector_store.default.backend=memory" + ) as app: + # Memory Integration: Learn from user interactions + result = await app.async_execute( + name="summary_personal_memory", + 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"} + ] + } + ] + ) + print(result) + + # Memory Retrieval: Get personal memory fragments + result = await app.async_execute( + name="retrieve_personal_memory", + workspace_id="task_workspace", + query="What are the user's work habits?", + top_k=5 + ) + print(result) + +if __name__ == "__main__": + asyncio.run(main()) +``` + +
+ +
+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 + }' +``` + +
+ +#### Tool Memory Management + +```python +import requests + +# Record tool execution results +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 + } + ] +}) + +# Generate usage guidelines from history +response = requests.post("http://localhost:8002/summary_tool_memory", json={ + "workspace_id": "tool_workspace", + "tool_names": "web_search" +}) + +# Retrieve tool guidelines before use +response = requests.post("http://localhost:8002/retrieve_tool_memory", json={ + "workspace_id": "tool_workspace", + "tool_names": "web_search" +}) +``` + +
+Python import version + +```python +import asyncio +from reme_ai import ReMeApp + +async def main(): + async with ReMeApp( + "llm.default.model_name=qwen3-30b-a3b-thinking-2507", + "embedding_model.default.model_name=text-embedding-v4", + "vector_store.default.backend=memory" + ) as app: + # Record tool execution results + result = await app.async_execute( + name="add_tool_call_result", + 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 + } + ] + ) + print(result) + + # Generate usage guidelines from history + result = await app.async_execute( + name="summary_tool_memory", + workspace_id="tool_workspace", + tool_names="web_search" + ) + print(result) + + # Retrieve tool guidelines before use + result = await app.async_execute( + name="retrieve_tool_memory", + workspace_id="tool_workspace", + tool_names="web_search" + ) + print(result) + +if __name__ == "__main__": + asyncio.run(main()) +``` + +
+ +
+curl version + +```bash +# Record tool execution results +curl -X POST http://localhost:8002/add_tool_call_result \ + -H "Content-Type: application/json" \ + -d '{ + "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 + } + ] + }' + +# Generate usage guidelines from history +curl -X POST http://localhost:8002/summary_tool_memory \ + -H "Content-Type: application/json" \ + -d '{ + "workspace_id": "tool_workspace", + "tool_names": "web_search" + }' + +# Retrieve tool guidelines before use +curl -X POST http://localhost:8002/retrieve_tool_memory \ + -H "Content-Type: application/json" \ + -d '{ + "workspace_id": "tool_workspace", + "tool_names": "web_search" + }' +``` + +
+ +#### Working Memory Management + +```python +import requests + +# Summarize and compact working memory for a long-running conversation +response = requests.post("http://localhost:8002/summary_working_memory", json={ + "messages": [ + { + "role": "system", + "content": "You are a helpful assistant. First use `Grep` to find the line numbers that match the keywords or regular expressions, and then use `ReadFile` to read the code around those locations. If no matches are found, never give up; try different parameters, such as searching with only part of the keywords. After `Grep`, use the `ReadFile` command to view content starting from a specified `offset` and `limit`, and do not exceed 100 lines. If the current content is insufficient, you can continue trying different `offset` and `limit` values with the `ReadFile` command." + }, + { + "role": "user", + "content": "搜索下reme项目的的README内容" + }, + { + "role": "assistant", + "content": "", + "tool_calls": [ + { + "index": 0, + "id": "call_6596dafa2a6a46f7a217da", + "function": { + "arguments": "{\"query\": \"readme\"}", + "name": "web_search" + }, + "type": "function" + } + ] + }, + { + "role": "tool", + "content": "ultra large context , over 50000 tokens......" + }, + { + "role": "user", + "content": "根据readme回答task memory在appworld的效果是多少，需要具体的数值" + } + ], + "working_summary_mode": "auto", + "compact_ratio_threshold": 0.75, + "max_total_tokens": 20000, + "max_tool_message_tokens": 2000, + "group_token_threshold": 4000, + "keep_recent_count": 2, + "store_dir": "test_working_memory", + "chat_id": "demo_chat_id" +}) +``` + +
+Python import version + +```python +import asyncio +from reme_ai import ReMeApp + + +async def main(): + async with ReMeApp( + "llm.default.model_name=qwen3-30b-a3b-thinking-2507", + "embedding_model.default.model_name=text-embedding-v4", + "vector_store.default.backend=memory" + ) as app: + # Summarize and compact working memory for a long-running conversation + result = await app.async_execute( + name="summary_working_memory", + messages=[ + { + "role": "system", + "content": "You are a helpful assistant. First use `Grep` to find the line numbers that match the keywords or regular expressions, and then use `ReadFile` to read the code around those locations. If no matches are found, never give up; try different parameters, such as searching with only part of the keywords. After `Grep`, use the `ReadFile` command to view content starting from a specified `offset` and `limit`, and do not exceed 100 lines. If the current content is insufficient, you can continue trying different `offset` and `limit` values with the `ReadFile` command." + }, + { + "role": "user", + "content": "搜索下reme项目的的README内容" + }, + { + "role": "assistant", + "content": "", + "tool_calls": [ + { + "index": 0, + "id": "call_6596dafa2a6a46f7a217da", + "function": { + "arguments": "{\"query\": \"readme\"}", + "name": "web_search" + }, + "type": "function" + } + ] + }, + { + "role": "tool", + "content": "ultra large context , over 50000 tokens......" + }, + { + "role": "user", + "content": "根据readme回答task memory在appworld的效果是多少，需要具体的数值" + } + ], + working_summary_mode="auto", + compact_ratio_threshold=0.75, + max_total_tokens=20000, + max_tool_message_tokens=2000, + group_token_threshold=4000, + keep_recent_count=2, + store_dir="test_working_memory", + chat_id="demo_chat_id", + ) + print(result) + + +if __name__ == "__main__": + asyncio.run(main()) +``` + +
+ +
+curl version + +```bash +curl -X POST http://localhost:8002/summary_working_memory \ + -H "Content-Type: application/json" \ + -d '{ + "messages": [ + { + "role": "system", + "content": "You are a helpful assistant. First use `Grep` to find the line numbers that match the keywords or regular expressions, and then use `ReadFile` to read the code around those locations. If no matches are found, never give up; try different parameters, such as searching with only part of the keywords. After `Grep`, use the `ReadFile` command to view content starting from a specified `offset` and `limit`, and do not exceed 100 lines. If the current content is insufficient, you can continue trying different `offset` and `limit` values with the `ReadFile` command." + }, + { + "role": "user", + "content": "搜索下reme项目的的README内容" + }, + { + "role": "assistant", + "content": "", + "tool_calls": [ + { + "index": 0, + "id": "call_6596dafa2a6a46f7a217da", + "function": { + "arguments": "{\"query\": \"readme\"}", + "name": "web_search" + }, + "type": "function" + } + ] + }, + { + "role": "tool", + "content": "ultra large context , over 50000 tokens......" + }, + { + "role": "user", + "content": "根据readme回答task memory在appworld的效果是多少，需要具体的数值" + } + ], + "working_summary_mode": "auto", + "compact_ratio_threshold": 0.75, + "max_total_tokens": 20000, + "max_tool_message_tokens": 2000, + "group_token_threshold": 4000, + "keep_recent_count": 2, + "store_dir": "test_working_memory", + "chat_id": "demo_chat_id" + }' +``` + +
+ +--- + +## 📦 Pre-built Memory Library + +ReMe provides a **memory library** with pre-extracted, production-ready memories that agents can load and use immediately: + +### Available Memory Packs + +| Memory Pack | Domain | Size | Description | +|----------------------|----------------|---------------|-------------------------------------------------------------------------------------| +| **`appworld.jsonl`** | Task Execution | ~100 memories | Complex task planning patterns, multi-step workflows, and error recovery strategies | +| **`bfcl_v3.jsonl`** | Tool Usage | ~150 memories | Function calling patterns, parameter optimization, and tool selection strategies | + +### Loading Pre-built Memories + +```python +# Load pre-built memories +response = requests.post("http://localhost:8002/vector_store", json={ + "workspace_id": "appworld", + "action": "load", + "path": "./docs/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 +}) +``` + +
+Python import version + +```python +import asyncio +from reme_ai import ReMeApp + +async def main(): + async with ReMeApp( + "llm.default.model_name=qwen3-30b-a3b-thinking-2507", + "embedding_model.default.model_name=text-embedding-v4", + "vector_store.default.backend=memory" + ) as app: + # Load pre-built memories + result = await app.async_execute( + name="vector_store", + workspace_id="appworld", + action="load", + path="./docs/library/" + ) + print(result) + + # Query relevant memories + result = await app.async_execute( + name="retrieve_task_memory", + workspace_id="appworld", + query="How to navigate to settings and update user profile?", + top_k=1 + ) + print(result) + +if __name__ == "__main__": + asyncio.run(main()) +``` + +
+ +## 🧪 Experiments + +### 🌍 [Appworld Experiment](docs/cookbook/appworld/quickstart.md) + +We tested ReMe on Appworld using Qwen3-8B (non-thinking mode): + +| Method | Avg@4 | Pass@4 | +|--------------|---------------------|---------------------| +| without ReMe | 0.1497 | 0.3285 | +| with ReMe | 0.1706 **(+2.09%)** | 0.3631 **(+3.46%)** | + +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](docs/cookbook/appworld/quickstart.md). + +### 🔧 [BFCL-V3 Experiment](docs/cookbook/bfcl/quickstart.md) + +We tested ReMe on BFCL-V3 multi-turn-base (randomly split 50train/150val) using Qwen3-8B (thinking mode): + +| Method | Avg@4 | Pass@4 | +|--------------|---------------------|---------------------| +| without ReMe | 0.4033 | 0.5955 | +| with ReMe | 0.4450 **(+4.17%)** | 0.6577 **(+6.22%)** | + +### 🧊 [Frozenlake Experiment](docs/cookbook/frozenlake/quickstart.md) + +| without ReMe | with ReMe | +|:----------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------:| +|

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 **(+6.0%)** | + +You can find more details on reproducing the experiment in [quickstart.md](docs/cookbook/frozenlake/quickstart.md). + +### 🛠️ [Tool Memory Benchmark](docs/tool_memory/tool_bench.md) + +We evaluated Tool Memory effectiveness using a controlled benchmark with three mock search tools using Qwen3-30B-Instruct: + +| Scenario | Avg Score | Improvement | +|------------------------|-----------|-------------| +| Train (No Memory) | 0.650 | - | +| Test (No Memory) | 0.672 | Baseline | +| **Test (With Memory)** | **0.772** | **+14.88%** | + +**Key Findings:** +- Tool Memory enables data-driven tool selection based on historical performance +- Success rates improved by ~15% with learned parameter configurations + +You can find more details in [tool_bench.md](docs/tool_memory/tool_bench.md) and the implementation at [run_reme_tool_bench.py](cookbook/tool_memory/run_reme_tool_bench.py). + +## 📚 Resources + +### Getting Started +- **[Quick Start](./cookbook/simple_demo)**: Practical examples for immediate use + - [Tool Memory Demo](cookbook/simple_demo/use_tool_memory_demo.py): Complete lifecycle demonstration of tool memory + - [Tool Memory Benchmark](cookbook/tool_memory/run_reme_tool_bench.py): Evaluate tool memory effectiveness + +### Integration Guides +- **[Direct Python Import](docs/cookbook/working/quick_start.md)**: Embed ReMe directly into your agent code +- **[HTTP Service API](docs/vector_store_api_guide.md)**: RESTful API for multi-agent systems +- **[MCP Protocol](docs/mcp_quick_start.md)**: Integration with Claude Desktop and MCP-compatible clients + +### Memory System Configuration +- **[Personal Memory](docs/personal_memory)**: User preference learning and contextual adaptation +- **[Task Memory](docs/task_memory)**: Procedural knowledge extraction and reuse +- **[Tool Memory](docs/tool_memory)**: Data-driven tool selection and optimization +- **[Working Memory](docs/work_memory/message_offload.md)**: Short-term context management for long-running agents + +### Advanced Topics +- **[Operator Pipelines](reme_ai/config/default.yaml)**: Customize memory processing workflows by modifying operator chains +- **[Vector Store Backends](docs/vector_store_api_guide.md)**: Configure local, Elasticsearch, Qdrant, or ChromaDB storage +- **[Example Collection](./cookbook)**: Real-world use cases and best practices + +--- + +## ⭐ Support & Community + +- **Star & Watch**: Stars surface ReMe to more agent builders; watching keeps you updated on new releases. +- **Share your wins**: Open an issue or discussion with what ReMe unlocked for your agents—we love showcasing community builds. +- **Need a feature?** File a request and we’ll help shape it together. + +--- + +## 🤝 Contribution + +We believe the best memory systems come from collective wisdom. Contributions welcome 👉[Guide](docs/contribution.md): + +### Code Contributions + +- **New Operators**: Develop custom memory processing operators (retrieval, summarization, etc.) +- **Backend Implementations**: Add support for new vector stores or LLM providers +- **Memory Services**: Extend with new memory types or capabilities +- **API Enhancements**: Improve existing endpoints or add new ones + +### Documentation Improvements + +- **Integration Examples**: Show how to integrate ReMe with different agent frameworks +- **Operator Tutorials**: Document custom operator development +- **Best Practice Guides**: Share effective memory management patterns +- **Use Case Studies**: Demonstrate ReMe in real-world applications + + +--- + +## 📄 Citation + +```bibtex +@software{AgentscopeReMe2025, + title = {AgentscopeReMe: Memory Management Kit for Agents}, + author = {Li Yu and + Jiaji Deng and + Zouying Cao and + Weikang Zhou and + Tiancheng Qin and + Qingxu Fu and + Sen Huang and + Xianzhe Xu and + Zhaoyang Liu and + Boyin Liu}, + url = {https://reme.agentscope.io}, + year = {2025} +} + +@misc{AgentscopeReMe2025Paper, + title={Remember Me, Refine Me: A Dynamic Procedural Memory Framework for Experience-Driven Agent Evolution}, + author={Zouying Cao and + Jiaji Deng and + Li Yu and + Weikang Zhou and + Zhaoyang Liu and + Bolin Ding and + Hai Zhao}, + year={2025}, + eprint={2512.10696}, + archivePrefix={arXiv}, + primaryClass={cs.AI}, + url={https://arxiv.org/abs/2512.10696}, +} +``` + +--- + +## ⚖️ License + +This project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) file for details. + +--- + +## Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=agentscope-ai/ReMe&type=Date)](https://www.star-history.com/#agentscope-ai/ReMe&Date) \ No newline at end of file diff --git a/docs/README_0_2_x_ZH.md b/docs/README_0_2_x_ZH.md new file mode 100644 index 00000000..e2b7d5c4 --- /dev/null +++ b/docs/README_0_2_x_ZH.md @@ -0,0 +1,902 @@ +

+ ReMe 标志 +

+ +

+ Python Version + PyPI Version + PyPI Downloads + GitHub commit activity +

+ +

+ License + English + 简体中文 + GitHub Stars +

+ +

+ 面向智能体的记忆管理工具包, Remember Me, Refine Me.
+ 如果 ReMe 对你有帮助，欢迎点一个 ⭐ Star，你的支持是我们持续改进的动力。 +

+ +--- + +ReMe 是一个**模块化的记忆管理工具包**，为 AI 智能体提供统一的记忆能力——支持在用户、任务与智能体之间提取、复用与共享记忆。 + +智能体的记忆可以被视为： + +```text +Agent Memory = Long-Term Memory + Short-Term Memory + = (Personal + Task + Tool) Memory + (Working Memory) +``` + +- **个人记忆（Personal Memory）**：理解用户偏好并适应上下文 +- **任务记忆（Task Memory）**：从经验中学习并在类似任务中表现更好 +- **工具记忆（Tool Memory）**：基于历史表现优化工具选择和参数使用 +- **工作记忆（Working Memory）**：管理长运行智能体的短期上下文，避免上下文溢出 + +--- + +## 📰 最新进展 + +- **[2026-02]** 💻 ReMeCli：终端 AI 聊天助手，内置记忆管理能力。当对话过长时自动将旧内容压缩为摘要以释放上下文空间，同时将重要信息以 Markdown 文件持久化存储，供未来会话自动检索使用。记忆设计灵感来源于 [OpenClaw](https://github.com/openclaw/openclaw)。 + - [快速开始](docs/cli/quick_start_en.md) + - 输入 `/horse` 触发马年彩蛋——烟花、奔马动画和随机马年祝福。 + + + + + + +
+ 马
上
有
钱 + 		+ + + 马
到
成
功 +
+ +- **[2025-12]** 📄 我们的程序性（任务）记忆论文已在 [arXiv](https://arxiv.org/abs/2512.10696) 发布 +- **[2025-11]** 🧠 基于工作记忆的 react-agent demo（[介绍](docs/work_memory/message_offload.md)、[Quick Start](docs/cookbook/working/quick_start.md)、[代码](cookbook/working_memory/work_memory_demo.py)） +- **[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]** 🧠 支持个性化与时间敏感的记忆存储 + +--- + +## ✨ 架构设计 + +

+ ReMe 架构 +

+ +ReMe 提供了一个**模块化的记忆管理工具包**，具有可插拔的组件，可以集成到任何智能体框架中。系统包括： + +#### 🧠 **任务记忆 / 经验记忆（Task Memory/Experience）** + +可在不同智能体之间复用的程序性知识： + +- **成功模式识别**：识别有效策略并理解其背后的原理 +- **失败分析学习**：从错误中学习，避免重复踩坑 +- **对比式模式**：通过多条采样轨迹的对比获取更有价值的记忆 +- **验证模式**：通过验证模块确认提炼出的经验是否有效 + +了解如何使用任务记忆可参考：[任务记忆文档](docs/task_memory/task_memory.md) + +#### 👤 **个人记忆（Personal Memory）** + +面向特定用户的情境化长期记忆： + +- **个体偏好**：记录用户的习惯、偏好与交互风格 +- **情境自适应**：基于时间与上下文动态管理记忆 +- **渐进式学习**：在长期多轮交互中不断加深对用户的理解 +- **时间敏感**：在记忆检索与整合中考虑时间因素 + +了解如何使用个人记忆可参考：[个人记忆文档](docs/personal_memory/personal_memory.md) + +#### 🔧 **工具记忆（Tool Memory）** + +基于真实调用数据的工具选择与使用优化： + +- **历史表现追踪**：记录成功率、调用耗时与 Token 成本 +- **LLM-as-Judge 评估**：提供工具成功 / 失败原因的定性洞察 +- **参数优化**：从历史成功调用中学习最优参数配置 +- **动态指南**：将静态工具描述演化为可持续更新的「活文档」 + +了解如何使用工具记忆可参考：[工具记忆文档](docs/tool_memory/tool_memory.md) + +#### 🧠 **工作记忆（Working Memory）** + +面向长流程智能体的短期上下文记忆，通过**消息卸载与重载（message offload & reload）**实现： +- **消息卸载（Message Offload）**：将体积巨大的工具输出压缩为外部文件或 LLM 摘要 +- **消息重载（Message Reload）**：按需搜索（`grep_working_memory`）并读取（`read_working_memory`）已卸载的内容 + +📖 **概念与 API：** +- 消息卸载概览：[Message Offload](docs/work_memory/message_offload.md) +- 卸载 / 重载算子：[Message Offload Ops](docs/work_memory/message_offload_ops.md)、[Message Reload Ops](docs/work_memory/message_reload_ops.md) + +💻 **端到端 Demo：** +- 工作记忆快速上手：[Working Memory Quick Start](docs/cookbook/working/quick_start.md) +- 带工作记忆的 ReAct 智能体：[react_agent_with_working_memory.py](cookbook/working_memory/react_agent_with_working_memory.py) +- 可运行 Demo：[work_memory_demo.py](cookbook/working_memory/work_memory_demo.py) + +--- + +## 🛠️ 安装 + +### 通过 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 导入版本 + +```python +import asyncio +from reme_ai import ReMeApp + +async def main(): + async with ReMeApp( + "llm.default.model_name=qwen3-30b-a3b-thinking-2507", + "embedding_model.default.model_name=text-embedding-v4", + "vector_store.default.backend=memory" + ) as app: + # 经验总结：从执行轨迹中学习 + result = await app.async_execute( + name="summary_task_memory", + workspace_id="task_workspace", + trajectories=[ + { + "messages": [ + {"role": "user", "content": "Help me create a project plan"} + ], + "score": 1.0 + } + ] + ) + print(result) + + # 记忆检索：获取相关经验 + result = await app.async_execute( + name="retrieve_task_memory", + workspace_id="task_workspace", + query="How to efficiently manage project progress?", + top_k=1 + ) + print(result) + +if __name__ == "__main__": + asyncio.run(main()) +``` + +
+ +
+curl 版本 + +```bash +# 经验总结：从执行轨迹中学习 +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} + ] + }' + +# 记忆检索：获取相关经验 +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 + }' +``` + +
+ +#### 个人记忆管理 + +```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 导入版本 + +```python +import asyncio +from reme_ai import ReMeApp + +async def main(): + async with ReMeApp( + "llm.default.model_name=qwen3-30b-a3b-thinking-2507", + "embedding_model.default.model_name=text-embedding-v4", + "vector_store.default.backend=memory" + ) as app: + # 记忆整合：从用户交互中学习 + result = await app.async_execute( + name="summary_personal_memory", + 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"} + ] + } + ] + ) + print(result) + + # 记忆检索：获取个人记忆片段 + result = await app.async_execute( + name="retrieve_personal_memory", + workspace_id="task_workspace", + query="What are the user's work habits?", + top_k=5 + ) + print(result) + +if __name__ == "__main__": + asyncio.run(main()) +``` + +
+ +
+curl 版本 + +```bash +# 记忆整合：从用户交互中学习 +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"} + ]} + ] + }' + +# 记忆检索：获取个人记忆片段 +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 + }' +``` + +
+ +#### 工具记忆管理 + +```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" +}) +``` + +
+Python 导入版本 + +```python +import asyncio +from reme_ai import ReMeApp + +async def main(): + async with ReMeApp( + "llm.default.model_name=qwen3-30b-a3b-thinking-2507", + "embedding_model.default.model_name=text-embedding-v4", + "vector_store.default.backend=memory" + ) as app: + # 记录工具调用结果 + result = await app.async_execute( + name="add_tool_call_result", + 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 + } + ] + ) + print(result) + + # 从历史生成使用指南 + result = await app.async_execute( + name="summary_tool_memory", + workspace_id="tool_workspace", + tool_names="web_search" + ) + print(result) + + # 在使用前检索工具指南 + result = await app.async_execute( + name="retrieve_tool_memory", + workspace_id="tool_workspace", + tool_names="web_search" + ) + print(result) + +if __name__ == "__main__": + asyncio.run(main()) +``` + +
+ +
+curl 版本 + +```bash +# 记录工具调用结果 +curl -X POST http://localhost:8002/add_tool_call_result \ + -H "Content-Type: application/json" \ + -d '{ + "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 + } + ] + }' + +# 从历史生成使用指南 +curl -X POST http://localhost:8002/summary_tool_memory \ + -H "Content-Type: application/json" \ + -d '{ + "workspace_id": "tool_workspace", + "tool_names": "web_search" + }' + +# 在使用前检索工具指南 +curl -X POST http://localhost:8002/retrieve_tool_memory \ + -H "Content-Type: application/json" \ + -d '{ + "workspace_id": "tool_workspace", + "tool_names": "web_search" + }' +``` + +
+ +#### 工作记忆管理 + +```python +import requests + +# 对长对话 / 长流程的工作记忆进行压缩与总结 +response = requests.post("http://localhost:8002/summary_working_memory", json={ + "messages": [ + { + "role": "system", + "content": "You are a helpful assistant. First use `Grep` to find the line numbers that match the keywords or regular expressions, and then use `ReadFile` to read the code around those locations. If no matches are found, never give up; try different parameters, such as searching with only part of the keywords. After `Grep`, use the `ReadFile` command to view content starting from a specified `offset` and `limit`, and do not exceed 100 lines. If the current content is insufficient, you can continue trying different `offset` and `limit` values with the `ReadFile` command." + }, + { + "role": "user", + "content": "搜索下reme项目的的README内容" + }, + { + "role": "assistant", + "content": "", + "tool_calls": [ + { + "index": 0, + "id": "call_6596dafa2a6a46f7a217da", + "function": { + "arguments": "{\"query\": \"readme\"}", + "name": "web_search" + }, + "type": "function" + } + ] + }, + { + "role": "tool", + "content": "ultra large context , over 50000 tokens......" + }, + { + "role": "user", + "content": "根据readme回答task memory在appworld的效果是多少，需要具体的数值" + } + ], + "working_summary_mode": "auto", + "compact_ratio_threshold": 0.75, + "max_total_tokens": 20000, + "max_tool_message_tokens": 2000, + "group_token_threshold": 4000, + "keep_recent_count": 2, + "store_dir": "test_working_memory", + "chat_id": "demo_chat_id" +}) +``` + +
+Python 导入版本 + +```python +import asyncio +from reme_ai import ReMeApp + + +async def main(): + async with ReMeApp( + "llm.default.model_name=qwen3-30b-a3b-thinking-2507", + "embedding_model.default.model_name=text-embedding-v4", + "vector_store.default.backend=memory" + ) as app: + # 对长对话 / 长流程的工作记忆进行压缩与总结 + result = await app.async_execute( + name="summary_working_memory", + messages=[ + { + "role": "system", + "content": "You are a helpful assistant. First use `Grep` to find the line numbers that match the keywords or regular expressions, and then use `ReadFile` to read the code around those locations. If no matches are found, never give up; try different parameters, such as searching with only part of the keywords. After `Grep`, use the `ReadFile` command to view content starting from a specified `offset` and `limit`, and do not exceed 100 lines. If the current content is insufficient, you can continue trying different `offset` and `limit` values with the `ReadFile` command." + }, + { + "role": "user", + "content": "搜索下reme项目的的README内容" + }, + { + "role": "assistant", + "content": "", + "tool_calls": [ + { + "index": 0, + "id": "call_6596dafa2a6a46f7a217da", + "function": { + "arguments": "{\"query\": \"readme\"}", + "name": "web_search" + }, + "type": "function" + } + ] + }, + { + "role": "tool", + "content": "ultra large context , over 50000 tokens......" + }, + { + "role": "user", + "content": "根据readme回答task memory在appworld的效果是多少，需要具体的数值" + } + ], + working_summary_mode="auto", + compact_ratio_threshold=0.75, + max_total_tokens=20000, + max_tool_message_tokens=2000, + group_token_threshold=4000, + keep_recent_count=2, + store_dir="test_working_memory", + chat_id="demo_chat_id", + ) + print(result) + + +if __name__ == "__main__": + asyncio.run(main()) +``` + +
+ +
+curl 版本 + +```bash +curl -X POST http://localhost:8002/summary_working_memory \ + -H "Content-Type: application/json" \ + -d '{ + "messages": [ + { + "role": "system", + "content": "You are a helpful assistant. First use `Grep` to find the line numbers that match the keywords or regular expressions, and then use `ReadFile` to read the code around those locations. If no matches are found, never give up; try different parameters, such as searching with only part of the keywords. After `Grep`, use the `ReadFile` command to view content starting from a specified `offset` and `limit`, and do not exceed 100 lines. If the current content is insufficient, you can continue trying different `offset` and `limit` values with the `ReadFile` command." + }, + { + "role": "user", + "content": "搜索下reme项目的的README内容" + }, + { + "role": "assistant", + "content": "", + "tool_calls": [ + { + "index": 0, + "id": "call_6596dafa2a6a46f7a217da", + "function": { + "arguments": "{\"query\": \"readme\"}", + "name": "web_search" + }, + "type": "function" + } + ] + }, + { + "role": "tool", + "content": "ultra large context , over 50000 tokens......" + }, + { + "role": "user", + "content": "根据readme回答task memory在appworld的效果是多少，需要具体的数值" + } + ], + "working_summary_mode": "auto", + "compact_ratio_threshold": 0.75, + "max_total_tokens": 20000, + "max_tool_message_tokens": 2000, + "group_token_threshold": 4000, + "keep_recent_count": 2, + "store_dir": "test_working_memory", + "chat_id": "demo_chat_id" + }' +``` + +
+ +--- + +## 📦 开箱即用的记忆库 + +ReMe 提供一个**记忆库**，包含预先提取的、生产就绪的记忆，智能体可以立即加载和使用： + +### 可用记忆包 + +| 记忆包 | 领域 | 规模 | 描述 | +|----------------------|------------|----------------|--------------------------------------------------------| +| **`appworld.jsonl`** | 任务执行 | ~100 条记忆 | 复杂任务规划模式、多步骤工作流和错误恢复策略 | +| **`bfcl_v3.jsonl`** | 工具使用 | ~150 条记忆 | 函数调用模式、参数优化和工具选择策略 | + +### 加载预构建记忆 + +```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 +}) +``` + +
+Python 导入版本 + +```python +import asyncio +from reme_ai import ReMeApp + +async def main(): + async with ReMeApp( + "llm.default.model_name=qwen3-30b-a3b-thinking-2507", + "embedding_model.default.model_name=text-embedding-v4", + "vector_store.default.backend=memory" + ) as app: + # 加载内置记忆 + result = await app.async_execute( + name="vector_store", + workspace_id="appworld", + action="load", + path="./docs/library/" + ) + print(result) + + # 查询相关记忆 + result = await app.async_execute( + name="retrieve_task_memory", + workspace_id="appworld", + query="How to navigate to settings and update user profile?", + top_k=1 + ) + print(result) + +if __name__ == "__main__": + asyncio.run(main()) +``` + +
+ +--- + +## 🧪 实验结果 + +### 🌍 [Appworld 实验](docs/cookbook/appworld/quickstart.md) + +我们在 Appworld 环境上使用 Qwen3-8B（非思考模式）进行评测： + +| 方法 | Avg@4 | Pass@4 | +|-----------|-------------------|-------------------| +| 无 ReMe | 0.1497 | 0.3285 | +| 使用 ReMe | 0.1706 **(+2.09%)** | 0.3631 **(+3.46%)** | + +Pass@K 衡量在生成 K 个候选中，至少一个成功完成任务（score=1）的概率。 +当前实验使用的是内部 AppWorld 环境，可能与对外版本存在轻微差异。 + +关于如何复现实验的更多细节，见 [quickstart.md](docs/cookbook/appworld/quickstart.md)。 + +### 🔧 [BFCL-V3 实验](docs/cookbook/bfcl/quickstart.md) + +我们在 BFCL-V3 multi-turn-base 任务（随机划分 50 train / 150 val）上，使用 Qwen3-8B（思考模式）进行评测： + +| 方法 | Avg@4 | Pass@4 | +|------------|-----------------|---------------------| +| 无 ReMe | 0.4033 | 0.5955 | +| 使用 ReMe | 0.4450 **(+4.17%)** | 0.6577 **(+6.22%)** | + +### 🧊 [Frozenlake 实验](docs/cookbook/frozenlake/quickstart.md) + +| 无 ReMe | 使用 ReMe | +|:------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------:| +|

失败示例

|

成功示例

| + +我们在 100 张随机 frozenlake 地图上，使用 qwen3-8b 进行测试： + +| 方法 | 通过率 | +|------------|-----------------| +| 无 ReMe | 0.66 | +| 使用 ReMe | 0.72 **(+6.0%)** | + +更多复现实验细节见 [quickstart.md](docs/cookbook/frozenlake/quickstart.md)。 + +### 🛠️ [工具记忆基准](docs/tool_memory/tool_bench.md) + +我们在一个受控基准上，使用三个模拟搜索工具与 Qwen3-30B-Instruct 评估工具记忆的效果： + +| 场景 | 平均分 | 提升 | +|-----------------------|--------|------------| +| 训练集（无记忆） | 0.650 | - | +| 测试集（无记忆） | 0.672 | 基线 | +| **测试集（使用记忆）** | **0.772** | **+14.88%** | + +**关键结论：** +- 工具记忆可以基于历史表现进行数据驱动的工具选择 +- 通过学习参数配置，成功率约提升 15% + +更多细节见 [tool_bench.md](docs/tool_memory/tool_bench.md) 与实现代码 [run_reme_tool_bench.py](cookbook/tool_memory/run_reme_tool_bench.py)。 + +--- + +## 📚 资源 + +### 快速入门 +- **[Quick Start](./cookbook/simple_demo)**：实用示例，可立即使用 + - [工具记忆 Demo](cookbook/simple_demo/use_tool_memory_demo.py)：工具记忆的完整生命周期演示 + - [工具记忆基准](cookbook/tool_memory/run_reme_tool_bench.py)：评估工具记忆效果 + +### 集成指南 +- **[直接 Python 导入](docs/cookbook/working/quick_start.md)**：将 ReMe 直接嵌入到你的智能体代码中 +- **[HTTP 服务 API](docs/vector_store_api_guide.md)**：用于多智能体系统的 RESTful API +- **[MCP 协议](docs/mcp_quick_start.md)**：与 Claude Desktop 和 MCP 兼容客户端集成 + +### 记忆系统配置 +- **[个人记忆](docs/personal_memory)**：用户偏好学习和上下文自适应 +- **[任务记忆](docs/task_memory)**：程序性知识提取和复用 +- **[工具记忆](docs/tool_memory)**：数据驱动的工具选择和优化 +- **[工作记忆](docs/work_memory/message_offload.md)**：长流程智能体的短期上下文管理 + +### 高级主题 +- **[算子管道](reme_ai/config/default.yaml)**：通过修改算子链来自定义记忆处理工作流 +- **[向量存储后端](docs/vector_store_api_guide.md)**：配置本地、Elasticsearch、Qdrant 或 ChromaDB 存储 +- **[案例集](./cookbook)**：真实场景的用例和最佳实践 + +--- + +## ⭐ 社区与支持 + +- **Star & Watch**：Star 可以让更多智能体开发者发现 ReMe；Watch 能帮助你第一时间获知新版本与特性。 +- **分享你的成果**：在 Issue 或 Discussion 中分享 ReMe 为你的智能体解锁了什么——我们非常乐意展示社区的优秀案例。 +- **需要新功能？** 提交 Feature Request，我们将一起完善它。 + +--- + +## 🤝 参与贡献 + +我们相信，最好的记忆系统来自社区的集体智慧。欢迎贡献 👉[贡献指南](docs/contribution.md)： + +### 代码贡献 + +- **新算子**：开发自定义记忆处理算子（检索、总结等） +- **后端实现**：添加对新向量存储或 LLM 提供商的支持 +- **记忆服务**：扩展新的记忆类型或能力 +- **API 增强**：改进现有端点或添加新端点 + +### 文档改进 + +- **集成示例**：展示如何将 ReMe 与不同智能体框架集成 +- **算子教程**：记录自定义算子开发 +- **最佳实践指南**：分享有效的记忆管理模式 +- **用例研究**：展示 ReMe 在实际应用中的使用 + +--- + +## 📄 引用 + +```bibtex +@software{AgentscopeReMe2025, + title = {AgentscopeReMe: Memory Management Kit for Agents}, + author = {Li Yu and + Jiaji Deng and + Zouying Cao and + Weikang Zhou and + Tiancheng Qin and + Qingxu Fu and + Sen Huang and + Xianzhe Xu and + Zhaoyang Liu and + Boyin Liu}, + url = {https://reme.agentscope.io}, + year = {2025} +} + +@misc{AgentscopeReMe2025Paper, + title={Remember Me, Refine Me: A Dynamic Procedural Memory Framework for Experience-Driven Agent Evolution}, + author={Zouying Cao and + Jiaji Deng and + Li Yu and + Weikang Zhou and + Zhaoyang Liu and + Bolin Ding and + Hai Zhao}, + year={2025}, + eprint={2512.10696}, + archivePrefix={arXiv}, + primaryClass={cs.AI}, + url={https://arxiv.org/abs/2512.10696}, +} +``` + +--- + +## ⚖️ 许可证 + +本项目基于 Apache License 2.0 开源，详情参见 [LICENSE](./LICENSE) 文件。 + +--- + +## Star 历史 + +[![Star History Chart](https://api.star-history.com/svg?repos=agentscope-ai/ReMe&type=Date)](https://www.star-history.com/#agentscope-ai/ReMe&Date) \ No newline at end of file diff --git a/reme/memory/skills/__init__.py b/reme/memory/skills/__init__.py new file mode 100644 index 00000000..e69de29b