From d6e003391a52a84df2890146c25fff83d8b8c821 Mon Sep 17 00:00:00 2001
From: "jinli.yl" <jinli.yl@alibaba-inc.com>
Date: Mon, 1 Sep 2025 22:39:04 +0800
Subject: [PATCH] docs(task_memory): expand task memory documentation and add
 new files

- Update task_memory.md with detailed explanation of task memory functionality
- Add new documentation files:  - task_retrieve_ops.md: describe memory retrieval operations
  - task_summary_ops.md: explain memory summarization operations
- Include configuration logic, basic usage examples, and advanced features
- Provide information on managing task memories (delete, dump, load)
---
 doc/task_memory/task_memory.md       | 219 ++++++++++++++++++++++-----
 doc/task_memory/task_retrieve_ops.md |  73 +++++++++
 doc/task_memory/task_summary_ops.md  | 190 +++++++++++++++++++++++
 3 files changed, 448 insertions(+), 34 deletions(-)
 create mode 100644 doc/task_memory/task_retrieve_ops.md
 create mode 100644 doc/task_memory/task_summary_ops.md

diff --git a/doc/task_memory/task_memory.md b/doc/task_memory/task_memory.md
index 1bc95c28..b00d0ef8 100644
--- a/doc/task_memory/task_memory.md
+++ b/doc/task_memory/task_memory.md
@@ -1,51 +1,202 @@
-# Task Memory
+# Task Memory in Reme
 
-Task Memory in ReMe.ai is designed to enhance task-solving capabilities by leveraging historical experiences. It provides two core operations: retrieval and summarization of task-related memories.
+Task Memory is a key component of Reme that allows AI agents to learn from past experiences and improve their performance on similar tasks in the future. This document explains how task memory works and how to use it in your applications.
 
-## Task Memory Retrieval Pipeline
+## What is Task Memory?
 
-The task memory retrieval pipeline is designed to fetch the most relevant historical experiences based on the current query:
+Task Memory represents knowledge extracted from previous task executions, including:
+- Successful approaches to solving problems
+- Common pitfalls and failures to avoid
+- Comparative insights between different approaches
 
-```
-build_query_op >> recall_vector_store_op >> rerank_memory_op >> rewrite_memory_op
+Each task memory contains:
+- `when_to_use`: Conditions that indicate when this memory is relevant
+- `content`: The actual knowledge or experience to be applied
+- Metadata about the memory's source and utility
+
+## Configuration Logic
+
+Task Memory in Reme is configured through two main flows:
+
+### 1. Summary Task Memory
+
+The `summary_task_memory` flow processes conversation trajectories to extract meaningful memories:
+
+```yaml
+summary_task_memory:
+  flow_content: trajectory_preprocess_op >> (success_extraction_op|failure_extraction_op|comparative_extraction_op) >> memory_validation_op >> update_vector_store_op
+  description: "Summarizes conversation trajectories or messages into structured memory representations for long-term storage"
 ```
 
-### Pipeline Components
+This flow:
+1. Preprocesses trajectories (`trajectory_preprocess_op`)
+2. Extracts memories based on success/failure/comparative analysis
+3. Validates memories (`memory_validation_op`)
+4. Updates the vector store (`update_vector_store_op`)
 
-1. **build_query_op**: Processes and optimizes the user query for memory retrieval
-2. **recall_vector_store_op**: Retrieves relevant memory experiences from the vector database
-3. **rerank_memory_op**: Reranks the retrieved memories based on relevance scores
-4. **rewrite_memory_op**: Reformats the memory content for better presentation
+A simplified version (`summary_task_memory_simple`) is also available for less complex use cases.
 
-### Input Schema
-- `query` (str, required): The user query for which relevant task memories are needed
+### 2. Retrieve Task Memory
 
-### Description
-Retrieves the most relevant top-k memory experiences from historical data based on the current query to enhance task-solving capabilities.
+The `retrieve_task_memory` flow fetches relevant memories based on a query:
 
-## Task Memory Summary Pipeline
-
-The task memory summary pipeline processes conversation trajectories into structured memory representations:
-
-```
-trajectory_preprocess_op >> (success_extraction_op|failure_extraction_op|comparative_extraction_op) >> memory_validation_op >> update_vector_store_op
+```yaml
+retrieve_task_memory:
+  flow_content: build_query_op >> recall_vector_store_op >> rerank_memory_op >> rewrite_memory_op
+  description: "Retrieves the most relevant top-k memory experiences from historical data based on the current query to enhance task-solving capabilities"
 ```
 
-### Pipeline Components
+This flow:
+1. Builds a query from the input (`build_query_op`)
+2. Recalls relevant memories from the vector store (`recall_vector_store_op`)
+3. Reranks memories by relevance (`rerank_memory_op`)
+4. Rewrites memories for better context integration (`rewrite_memory_op`)
 
-1. **trajectory_preprocess_op**: Preprocesses conversation trajectories for memory extraction
-2. **success_extraction_op**: Extracts successful task-solving experiences
-3. **failure_extraction_op**: Extracts failed task attempts and lessons learned
-4. **comparative_extraction_op**: Extracts comparative experiences and insights
-5. **memory_validation_op**: Validates the extracted memory content for accuracy
-6. **update_vector_store_op**: Stores the validated memories in the vector database
+A simplified version (`retrieve_task_memory_simple`) is also available.
 
-### Input Schema
-- `trajectories` (list, optional): A list of conversation trajectory information, including message content and score. This field is automatically completed by the system.
+## Basic Usage
 
-### Description
-Summarizes conversation trajectories or messages into structured memory representations for long-term storage.
+Here's how to use Task Memory in your application:
 
-## Usage
+### Step 1: Set Up Your Environment
 
-These pipelines work together to create a continuous learning system where past task experiences inform current task-solving capabilities, improving the overall performance and effectiveness of the AI assistant.
\ No newline at end of file
+```python
+import requests
+
+# API configuration
+BASE_URL = "http://0.0.0.0:8002/"
+WORKSPACE_ID = "your_workspace_id"
+```
+
+### Step 2: Run an Agent and Generate Memories
+
+```python
+# Run the agent with a query
+response = requests.post(
+    url=f"{BASE_URL}react",
+    json={"query": "Your query here"}
+)
+messages = response.json().get("messages", [])
+
+# Summarize the conversation to create task memories
+response = requests.post(
+    url=f"{BASE_URL}summary_task_memory",
+    json={
+        "workspace_id": WORKSPACE_ID,
+        "trajectories": [
+            {"messages": messages, "score": 1.0}
+        ]
+    }
+)
+```
+
+### Step 3: Retrieve Relevant Memories for a New Task
+
+```python
+# Retrieve memories relevant to a new query
+response = requests.post(
+    url=f"{BASE_URL}retrieve_task_memory",
+    json={
+        "workspace_id": WORKSPACE_ID,
+        "query": "Your new query here"
+    }
+)
+retrieved_memory = response.json().get("answer", "")
+```
+
+### Step 4: Use Retrieved Memories to Enhance Agent Performance
+
+```python
+# Augment a new query with retrieved memories
+augmented_query = f"{retrieved_memory}\n\nUser Question:\n{your_query}"
+
+# Run agent with the augmented query
+response = requests.post(
+    url=f"{BASE_URL}react",
+    json={"query": augmented_query}
+)
+```
+
+## Complete Example
+
+Here's a complete example workflow that demonstrates how to use task memory:
+
+```python
+def run_agent_with_memory(query_first, query_second):
+    # Run agent with second query to build initial memories
+    messages = run_agent(query=query_second)
+    
+    # Summarize conversation to create memories
+    requests.post(
+        url=f"{BASE_URL}summary_task_memory",
+        json={
+            "workspace_id": WORKSPACE_ID,
+            "trajectories": [
+                {"messages": messages, "score": 1.0}
+            ]
+        }
+    )
+    
+    # Retrieve relevant memories for the first query
+    response = requests.post(
+        url=f"{BASE_URL}retrieve_task_memory",
+        json={
+            "workspace_id": WORKSPACE_ID,
+            "query": query_first
+        }
+    )
+    retrieved_memory = response.json().get("answer", "")
+    
+    # Run agent with first query augmented with retrieved memories
+    augmented_query = f"{retrieved_memory}\n\nUser Question:\n{query_first}"
+    return run_agent(query=augmented_query)
+```
+
+## Managing Task Memories
+
+### Delete a Workspace
+
+```python
+response = requests.post(
+    url=f"{BASE_URL}vector_store",
+    json={
+        "workspace_id": WORKSPACE_ID,
+        "action": "delete"
+    }
+)
+```
+
+### Dump Memories to Disk
+
+```python
+response = requests.post(
+    url=f"{BASE_URL}vector_store",
+    json={
+        "workspace_id": WORKSPACE_ID,
+        "action": "dump",
+        "path": "./"
+    }
+)
+```
+
+### Load Memories from Disk
+
+```python
+response = requests.post(
+    url=f"{BASE_URL}vector_store",
+    json={
+        "workspace_id": WORKSPACE_ID,
+        "action": "load",
+        "path": "./"
+    }
+)
+```
+
+## Advanced Features
+
+Reme also provides additional task memory operations:
+
+- `record_task_memory`: Update frequency and utility attributes of retrieved memories
+- `delete_task_memory`: Delete memories based on utility/frequency thresholds
+
+For more detailed examples, see the `use_task_memory_demo.py` file in the cookbook directory of the Reme project.
diff --git a/doc/task_memory/task_retrieve_ops.md b/doc/task_memory/task_retrieve_ops.md
new file mode 100644
index 00000000..a12e8698
--- /dev/null
+++ b/doc/task_memory/task_retrieve_ops.md
@@ -0,0 +1,73 @@
+# Task Memory Retrieval Operations
+
+## BuildQueryOp
+
+### Purpose
+
+Constructs a query for memory retrieval either from a direct query input or by analyzing conversation messages.
+
+### Functionality
+
+- If a direct `query` is provided in the context, it uses that query
+- If `messages` are provided in the context, it can:
+    - Use an LLM to generate a query based on the conversation context
+    - Or create a simple query from recent messages without using an LLM
+
+### Parameters
+
+- `op.build_query_op.params.enable_llm_build` (boolean, default: `true`):
+    - When `true`, uses an LLM to generate a query from conversation messages
+    - When `false`, creates a simple query by concatenating recent messages
+
+## RerankMemoryOp
+
+### Purpose
+
+Reranks and filters recalled memories to ensure the most relevant memories are prioritized.
+
+### Functionality
+
+- Reranks memories using LLM-based analysis (optional)
+- Filters memories based on quality scores (optional)
+- Returns the top-k most relevant memories
+
+### Parameters
+
+- `op.rerank_memory_op.params.enable_llm_rerank` (boolean, default: `true`):
+    - When `true`, uses an LLM to rerank memories based on their relevance to the query
+- `op.rerank_memory_op.params.enable_score_filter` (boolean, default: `false`):
+    - When `true`, filters memories based on their quality scores
+- `op.rerank_memory_op.params.min_score_threshold` (float, default: `0.3`):
+    - Minimum score threshold for filtering memories when `enable_score_filter` is `true`
+- `op.rerank_memory_op.params.top_k` (integer, default: `5`):
+    - Number of top memories to retain after reranking
+
+## RewriteMemoryOp
+
+### Purpose
+
+Rewrites and formats the retrieved memories to make them more relevant and actionable for the current context.
+
+### Functionality
+
+- Formats retrieved memories into a structured format
+- Can use an LLM to rewrite memories to better fit the current context (optional)
+- Generates a cohesive context message from multiple memories
+
+### Parameters
+
+- `op.rewrite_memory_op.params.enable_llm_rewrite` (boolean, default: `true`):
+    - When `true`, uses an LLM to rewrite the memories to make them more relevant and actionable
+    - When `false`, simply formats the memories without LLM-based rewriting
+
+## MergeMemoryOp
+
+### Purpose
+
+An alternative to RewriteMemoryOp that merges multiple memories into a single response without using an LLM.
+
+### Functionality
+
+- Collects the content from all memories in the memory list
+- Formats them into a single response with a standard structure
+- Adds a prompt to consider the helpful parts when answering the question
diff --git a/doc/task_memory/task_summary_ops.md b/doc/task_memory/task_summary_ops.md
new file mode 100644
index 00000000..d7c391aa
--- /dev/null
+++ b/doc/task_memory/task_summary_ops.md
@@ -0,0 +1,190 @@
+# Task Summary Operations
+
+## TrajectoryPreprocessOp
+
+### Purpose
+
+Preprocesses trajectories by validating and classifying them based on their score.
+
+### Functionality
+
+- Validates and classifies trajectories as success or failure based on a threshold
+- Modifies tool calls in messages to ensure consistent format
+- Sets context for downstream operators with classified trajectories
+
+### Parameters
+
+- `op.trajectory_preprocess_op.params.success_threshold` (float, default: `1.0`):
+  - The threshold score that determines if a trajectory is considered successful
+  - Trajectories with scores greater than or equal to this value are classified as successful
+
+## TrajectorySegmentationOp
+
+### Purpose
+
+Segments trajectories into meaningful step sequences to enable more granular memory extraction.
+
+### Functionality
+
+- Uses LLM to identify logical break points in trajectories
+- Adds segmentation information to trajectory metadata
+- Enables more focused memory extraction from specific parts of conversations
+
+### Parameters
+
+- `op.trajectory_segmentation_op.params.segment_target` (string, default: `"all"`):
+  - Determines which trajectories to segment
+  - Options: `"all"`, `"success"`, `"failure"`
+
+## SuccessExtractionOp
+
+### Purpose
+
+Extracts task memories from successful trajectories.
+
+### Functionality
+
+- Processes successful trajectories to identify valuable experiences
+- Can work with both entire trajectories and segmented step sequences
+- Uses LLM to extract structured task memories with when-to-use conditions
+
+### Parameters
+
+No specific parameters beyond the LLM configuration.
+
+## FailureExtractionOp
+
+### Purpose
+
+Extracts task memories from failed trajectories to capture lessons learned from unsuccessful attempts.
+
+### Functionality
+
+- Processes failed trajectories to identify pitfalls and mistakes
+- Can work with both entire trajectories and segmented step sequences
+- Uses LLM to extract structured task memories with when-to-use conditions
+
+### Parameters
+
+No specific parameters beyond the LLM configuration.
+
+## ComparativeExtractionOp
+
+### Purpose
+
+Extracts comparative task memories by comparing different scoring trajectories.
+
+### Functionality
+
+- Performs "soft comparison" between highest and lowest scoring trajectories
+- Can perform "hard comparison" between success and failure trajectories using similarity search
+- Identifies key differences that contributed to success or failure
+
+### Parameters
+
+- `op.comparative_extraction_op.params.enable_soft_comparison` (boolean, default: `true`):
+  - When `true`, enables comparison between highest and lowest scoring trajectories
+- `op.comparative_extraction_op.params.enable_similarity_comparison` (boolean, default: `false`):
+  - When `true`, enables similarity-based comparison between success and failure trajectories
+- `op.comparative_extraction_op.params.similarity_threshold` (float, default: `0.3`):
+  - The threshold for considering two trajectories similar
+- `op.comparative_extraction_op.params.max_similarity_sequences` (integer, default: `5`):
+  - Maximum number of sequences to compare to avoid computational overload
+- `op.comparative_extraction_op.params.max_similarity_pairs` (integer, default: `3`):
+  - Maximum number of similar pairs to process
+
+## MemoryValidationOp
+
+### Purpose
+
+Validates the quality of extracted task memories to ensure they are useful and relevant.
+
+### Functionality
+
+- Uses LLM to validate each extracted memory
+- Scores memories based on quality and relevance
+- Filters out low-quality memories based on validation threshold
+
+### Parameters
+
+- `op.memory_validation_op.params.validation_threshold` (float, default: `0.5`):
+  - The minimum score for a memory to be considered valid
+
+## MemoryDeduplicationOp
+
+### Purpose
+
+Removes duplicate task memories to avoid redundancy in the vector store.
+
+### Functionality
+
+- Compares new memories with existing memories in the vector store
+- Uses embedding similarity to identify duplicates
+- Ensures only unique memories are stored
+
+### Parameters
+
+- `op.memory_deduplication_op.params.similarity_threshold` (float, default: `0.5`):
+  - The threshold for considering two memories similar
+- `op.memory_deduplication_op.params.max_existing_task_memories` (integer, default: `1000`):
+  - Maximum number of existing memories to check against
+
+## SimpleSummaryOp
+
+### Purpose
+
+A simplified version of memory extraction that processes entire trajectories in one step.
+
+### Functionality
+
+- Classifies trajectories as success or failure based on score threshold
+- Extracts memories directly from complete trajectories
+- Useful for simpler use cases where detailed segmentation is not required
+
+### Parameters
+
+- `op.simple_summary_op.params.success_score_threshold` (float, default: `0.9`):
+  - The threshold score that determines if a trajectory is considered successful
+
+## SimpleComparativeSummaryOp
+
+### Purpose
+
+A simplified version of comparative memory extraction.
+
+### Functionality
+
+- Groups trajectories by task ID
+- Compares the highest and lowest scoring trajectories for each task
+- Extracts comparative insights without complex segmentation
+
+### Parameters
+
+No specific parameters beyond the LLM configuration.
+
+## PDFPreprocessOp
+
+### Purpose
+
+Processes PDF files to extract content that can be used for memory creation.
+
+### Functionality
+
+- Extracts text content from PDF files
+- Creates markdown representation of PDF content
+- Chunks content into manageable pieces for processing
+
+### Parameters
+
+- `op.pdf_preprocess_op.params.method` (string, default: `"auto"`):
+  - The method to use for PDF processing
+  - Options: `"auto"`, `"text"`, `"layout"`
+- `op.pdf_preprocess_op.params.lang` (string, default: `null` (auto-detect)):
+  - The language of the PDF content
+- `op.pdf_preprocess_op.params.backend` (string, default: `"pipeline"`):
+  - The backend to use for PDF processing
+  - Options: `"pipeline"`, `"pdfminer"`
+- `op.pdf_preprocess_op.params.create_chunks` (boolean, default: `true`):
+  - Whether to create chunks from the PDF content
+- `op.pdf_preprocess_op.params.max_chunk_length` (integer, default: `4000`):
+  - The maximum length of each chunk
\ No newline at end of file