memory-retrieval
Two-stage memory retrieval skill using semantic matching and utility filtering for higher-quality recall.
SKILL.mdcollection/skills/other/memory-retrieval/SKILL.md
GitHubTwo-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:
Construct Query
- Extract key concepts from user request
- Generate multiple query variants
- Include synonyms and related terms
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 )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:
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.0Filter Low-Utility Results
# Default threshold UTILITY_THRESHOLD = 0.5 filtered_results = [ r for r in results if r.utility >= UTILITY_THRESHOLD ]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
- Track Usage: Record when memory entries are used
- Track Success: Note if memory helped solve problems
- Periodic Cleanup: Remove or archive low-utility memories
- Context Matters: Always consider current task context
- 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
- Source Paper: https://arxiv.org/abs/2601.03192
- MEMORY.md: ~/.openclaw/workspace/MEMORY.md
- Utility Tracking: ~/.openclaw/workspace/memory/utility-scores.json
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