Retrieval Policy

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.