retrieval-policy

name: retrieval-policy description: | Agent retrieval policy for intelligent memory search. Use when implementing memory queries to detect capabilities, classify intent, route through optimal layers, and handle fallbacks. Provides tier detection, intent classification, fallback chains, and full explainability for all retrieval operations. license: MIT metadata: version: 1.0.0 author: SpillwaveSolutions

Retrieval Policy Skill

Intelligent retrieval decision-making for agent memory queries. The "brainstem" that decides how to search.

When to Use

When Not to Use

• Direct search operations (use memory-query skill)
• Topic exploration (use topic-graph skill)
• BM25 keyword search (use bm25-search skill)
• Vector semantic search (use vector-search skill)

Quick Start

# Check retrieval tier
memory-daemon retrieval status

# Classify query intent
memory-daemon retrieval classify "What JWT issues did we have?"

# Route query through layers
memory-daemon retrieval route "authentication errors last week"

Capability Tiers

The system detects available layers and maps to tiers:

Tier Detection

memory-daemon retrieval status

Output:

Retrieval Capabilities
----------------------------------------
Current Tier:    2 (Hybrid)
Available Layers:
  - bm25:    healthy (2847 docs)
  - vector:  healthy (2103 vectors)
  - agentic: healthy (TOC available)
Unavailable:
  - topics:  disabled (topics.enabled = false)

Query Intent Classification

Queries are classified into four intents:

Classification Command

memory-daemon retrieval classify "What JWT issues did we debug last Tuesday?"

Output:

Query Intent Classification
----------------------------------------
Intent:          Answer
Confidence:      0.87
Time Constraint: 2026-01-28 (last Tuesday)
Keywords:        [JWT, issues, debug]
Suggested Mode:  Hybrid (BM25 + Vector)

Fallback Chains

Each tier has a predefined fallback chain:

Tier 1: Topics → Hybrid → Vector → BM25 → Agentic
Tier 2: Hybrid → Vector → BM25 → Agentic
Tier 3: Vector → BM25 → Agentic
Tier 4: BM25 → Agentic
Tier 5: Agentic (no fallback needed)

Fallback Triggers

Stop Conditions

Control query execution with stop conditions:

Intent-Specific Defaults

Execution Modes

Explainability Payload

Every retrieval returns an explanation:

{
  "tier_used": 2,
  "tier_name": "Hybrid",
  "intent": "Answer",
  "method": "bm25_then_vector",
  "layers_tried": ["bm25", "vector"],
  "layers_succeeded": ["bm25", "vector"],
  "fallbacks_used": [],
  "time_constraint": "2026-01-28",
  "stop_reason": "max_results_reached",
  "results_per_layer": {
    "bm25": 5,
    "vector": 3
  },
  "execution_time_ms": 234,
  "confidence": 0.87
}

Displaying to Users

## Retrieval Report

Method: Hybrid tier (BM25 + Vector reranking)
Layers: bm25 (5 results), vector (3 results)
Fallbacks: 0
Time filter: 2026-01-28
Execution: 234ms
Confidence: 0.87

Skill Contract

When implementing memory queries, follow this contract:

Required Steps

1. Always check tier first:

   memory-daemon retrieval status
   

2. Classify intent before routing:

   memory-daemon retrieval classify "<query>"
   

3. Use tier-appropriate commands:

   • Tier 1-2: teleport hybrid
   • Tier 3: teleport vector
   • Tier 4: teleport search
   • Tier 5: query search

4. Include explainability in response:

   • Report tier used
   • Report layers tried
   • Report fallbacks triggered

Validation Checklist

Before returning results:

• Tier detection completed
• Intent classified
• Appropriate layers used for tier
• Fallbacks handled gracefully
• Explainability payload included
• Stop conditions respected

Configuration

Retrieval policy is configured in ~/.config/agent-memory/config.toml:

[retrieval]
default_timeout_ms = 5000
default_max_nodes = 50
default_max_depth = 3
parallel_fan_out = 3

[retrieval.intent_defaults]
explore_beam_width = 5
answer_beam_width = 3
locate_early_stop = true
timeboxed_max_depth = 2

[retrieval.fallback]
enabled = true
max_fallback_attempts = 3
fallback_timeout_factor = 0.5

Error Handling

Integration with Ranking

Results are ranked using Phase 16 signals:

See Command Reference for full CLI options.