memory-retrieval

Two-stage memory retrieval skill using semantic matching and utility filtering for higher-quality recall.

SKILL.md

GitHub

Two-Stage Memory Retrieval

Description

A high-quality memory retrieval skill based on MemRL paper (arXiv:2601.03192). Uses a two-stage process: semantic matching followed by utility filtering to solve the "stability-plasticity dilemma" in memory systems.

Activation Keywords

  • 记忆检索
  • memory retrieval
  • 查找知识
  • find knowledge
  • 搜索记忆
  • search memory
  • 两阶段检索
  • two-stage retrieval
  • 效用过滤
  • utility filtering

Recommended Model

  • sonnet4.5 (Recommended for semantic understanding and utility evaluation)

Tools Used

  • memory_search: Semantic search in MEMORY.md and memory/*.md
  • memory_get: Retrieve specific memory snippets
  • read: Read full memory files when needed
  • write: Update memory with utility scores

Usage Patterns

Basic Retrieval

查找关于 [topic] 的知识

With Context

检索记忆:[query],上下文:[context]

Utility-Based

查找最相关的 [topic] 知识,按效用排序

Instructions for Agents

Overview

The two-stage retrieval solves a fundamental problem in memory systems:

┌─────────────────────────────────────────────────────────┐
│           Two-Stage Memory Retrieval                     │
├─────────────────────────────────────────────────────────┤
│                                                          │
│   Stage 1: Semantic Matching                             │
│   ┌─────────────────────────────────────────────────┐   │
│   │  Query → memory_search → Relevant Results       │   │
│   │  (Broad search, semantic similarity)            │   │
│   └─────────────────────────────────────────────────┘   │
│                        ↓                                 │
│   Stage 2: Utility Filtering                            │
│   ┌─────────────────────────────────────────────────┐   │
│   │  Results → Utility Scoring → Filtered Results   │   │
│   │  (Quality check, usefulness rating)             │   │
│   └─────────────────────────────────────────────────┘   │
│                        ↓                                 │
│   High-Quality Memory Retrieval                          │
│                                                          │
└─────────────────────────────────────────────────────────┘

Stage 1: Semantic Matching

Purpose: Find all potentially relevant memories

Process:

  1. Construct Query

    • Extract key concepts from user request
    • Generate multiple query variants
    • Include synonyms and related terms
  2. Execute Search

    # Use memory_search tool
    memory_search(
        query="search terms",
        maxResults=10,  # Get more results for filtering
        minScore=0.5    # Lower threshold for broad match
    )
    
  3. Collect Results

    • Gather all matching snippets
    • Note file paths and line numbers
    • Preserve context around matches

Output: List of semantically relevant memory snippets

Stage 2: Utility Filtering

Purpose: Filter and rank by practical usefulness

Utility Scoring Formula:

Utility = (Recency × 0.3) + (SuccessRate × 0.4) + (Relevance × 0.3)

Where:
- Recency: How recently was this memory used (0-1)
- SuccessRate: How often did it help solve problems (0-1)
- Relevance: How relevant to current context (0-1)

Evaluation Criteria:

Factor Weight Measurement
Recency 0.3 Days since last use
Success Rate 0.4 Successful applications / Total uses
Relevance 0.3 Semantic similarity score
User Feedback Bonus Positive feedback adds +0.1

Process:

  1. Score Each Result

    def calculate_utility(result, current_context):
        recency = get_recency_score(result.last_used)
        success_rate = result.success_count / result.use_count
        relevance = calculate_relevance(result, current_context)
        
        utility = (recency * 0.3) + (success_rate * 0.4) + (relevance * 0.3)
        
        # Apply bonus for user feedback
        if result.has_positive_feedback:
            utility += 0.1
        
        return min(utility, 1.0)  # Cap at 1.0
    
  2. Filter Low-Utility Results

    # Default threshold
    UTILITY_THRESHOLD = 0.5
    
    filtered_results = [
        r for r in results
        if r.utility >= UTILITY_THRESHOLD
    ]
    
  3. Rank by Utility

    ranked_results = sorted(
        filtered_results,
        key=lambda r: r.utility,
        reverse=True
    )
    

Output: Ranked list of high-utility memory snippets

Integration Pattern

def two_stage_retrieval(query, context, max_results=5):
    """Two-stage memory retrieval with utility filtering."""
    
    # Stage 1: Semantic Matching
    semantic_results = memory_search(
        query=query,
        maxResults=max_results * 2,  # Get more for filtering
        minScore=0.5
    )
    
    # Stage 2: Utility Filtering
    scored_results = []
    for result in semantic_results:
        utility = calculate_utility(result, context)
        if utility >= UTILITY_THRESHOLD:
            scored_results.append({
                'content': result.content,
                'source': result.path,
                'utility': utility
            })
    
    # Rank and return
    ranked = sorted(scored_results, key=lambda r: r['utility'], reverse=True)
    return ranked[:max_results]

Context Files

~/.openclaw/workspace/MEMORY.md

Long-term memory file with utility metadata.

~/.openclaw/workspace/memory/*.md

Daily memory files.

~/.openclaw/workspace/memory/utility-scores.json

Utility scores for memory entries (to be created).

{
  "MEMORY.md#主动汇报约定": {
    "use_count": 5,
    "success_count": 4,
    "last_used": "2026-03-05T11:00:00Z",
    "utility": 0.85
  }
}

Error Handling

No Results Found

If Stage 1 returns no results:
  1. Broaden query terms
  2. Lower minScore threshold
  3. Search in related domains
  4. Report "No relevant memory found"

All Results Filtered Out

If Stage 2 filters all results:
  1. Lower UTILITY_THRESHOLD temporarily
  2. Return best available result with warning
  3. Suggest creating new memory entry

Utility Data Missing

If utility scores don't exist:
  1. Default to recency + relevance only
  2. Initialize utility tracking
  3. Track future uses for scoring

Examples

Example 1: Basic Retrieval

User: "查找关于股票分析的技能"

Agent Process:
1. Stage 1: Semantic Matching
   - Query: "股票分析 stock analysis skill"
   - Results: 5 matches found

2. Stage 2: Utility Filtering
   - Scoring each result:
     * stock-analysis SKILL.md: utility=0.9 (high success)
     * akshare usage: utility=0.75 (recent use)
     * old analysis notes: utility=0.4 (outdated)
   
   - Filtered: 2 results above threshold

3. Return ranked results:
   1. stock-analysis SKILL.md (utility: 0.9)
   2. akshare usage notes (utility: 0.75)

Agent: 找到 2 条相关记忆(按效用排序):

**1. stock-analysis 技能** (效用: 0.9)
- 来源: knowledge/skills/external/stock-analysis.md
- 成功率: 90%, 最近使用: 今天

**2. AkShare 使用笔记** (效用: 0.75)
- 来源: knowledge/topics/optimization/api-stability.md
- 成功率: 75%, 最近使用: 昨天

Example 2: Context-Aware Retrieval

User: "我需要处理 API 超时问题,查找相关知识"

Agent Process:
1. Stage 1: Semantic Matching
   - Query: "API timeout 超时处理 error handling"
   - Context: Current task is about API reliability
   - Results: 8 matches found

2. Stage 2: Utility Filtering
   - Context relevance scoring:
     * timeout-handling.md: relevance=0.95 (exact match)
     * api-stability.md: relevance=0.85 (related)
     * general error handling: relevance=0.5 (generic)
   
   - Combined utility:
     * timeout-handling.md: utility=0.92
     * api-stability.md: utility=0.78
     * general error: utility=0.45 (filtered out)

3. Return context-aware results:
   1. timeout-handling.md (utility: 0.92)
   2. api-stability.md (utility: 0.78)

Agent: 找到 2 条高相关记忆:

**1. 超时处理指南** (效用: 0.92)
- 高度相关当前任务
- 来源: knowledge/topics/optimization/timeout-handling.md

**2. API 稳定性方案** (效用: 0.78)
- 包含新浪财经备用 API
- 来源: TOOLS.md#api-数据源备份方案

Best Practices

  1. Track Usage: Record when memory entries are used
  2. Track Success: Note if memory helped solve problems
  3. Periodic Cleanup: Remove or archive low-utility memories
  4. Context Matters: Always consider current task context
  5. Iterate Thresholds: Adjust utility threshold based on results

Limitations

  • Requires utility tracking infrastructure
  • Initial utility scores may be inaccurate
  • Can filter out potentially useful but untested memories
  • Requires regular maintenance of utility data

Implementation Checklist

  • Create utility-scores.json tracking file
  • Implement utility calculation function
  • Add usage tracking to memory access
  • Add success/failure tracking
  • Create periodic utility recalculation
  • Add threshold configuration

Resources

Related Skills

  • ice-review: Consolidate knowledge after tasks
  • self-challenge: Test and validate memories
  • skill-extractor: Extract patterns from memories

Notes

  • Two-stage retrieval significantly improves result quality
  • The "stability-plasticity dilemma" refers to balancing old knowledge with new
  • Utility scoring should be domain-aware for best results
  • Consider user preferences in utility calculation