// 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.
| 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. |
Intelligent retrieval decision-making for agent memory queries. The "brainstem" that decides how to search.
| Use Case | Best Approach |
|---|---|
| Detect available search capabilities | retrieval status |
| Classify query intent | retrieval classify <query> |
| Route query through optimal layers | retrieval route <query> |
| Understand why a method was chosen | Check explainability payload |
| Handle layer failures gracefully | Automatic fallback chains |
# 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"
The system detects available layers and maps to tiers:
| Tier | Name | Layers Available | Description |
|---|---|---|---|
| 1 | Full | Topics + Hybrid + Agentic | Complete cognitive stack |
| 2 | Hybrid | BM25 + Vector + Agentic | Keyword + semantic |
| 3 | Semantic | Vector + Agentic | Embeddings only |
| 4 | Keyword | BM25 + Agentic | Text matching only |
| 5 | Agentic | Agentic only | TOC navigation (always works) |
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)
Queries are classified into four intents:
| Intent | Triggers | Optimal Strategy |
|---|---|---|
| Explore | "browse", "discover", "what topics" | Topics-first, broad fan-out |
| Answer | "what did", "how did", "find" | Hybrid, precision-focused |
| Locate | Identifiers, exact phrases, quotes | BM25-first, exact match |
| Time-boxed | "yesterday", "last week", dates | Time-filtered, sequential |
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)
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)
| Condition | Action |
|---|---|
| Layer returns 0 results | Try next layer |
| Layer timeout exceeded | Skip to next layer |
| Layer health check failed | Skip layer entirely |
| Min confidence not met | Continue to next layer |
Control query execution with stop conditions:
| Condition | Default | Description |
|---|---|---|
max_depth | 3 | Maximum drill-down levels |
max_nodes | 50 | Maximum nodes to visit |
timeout_ms | 5000 | Query timeout in milliseconds |
beam_width | 3 | Parallel branches to explore |
min_confidence | 0.5 | Minimum result confidence |
| Intent | max_nodes | timeout_ms | beam_width |
|---|---|---|---|
| Explore | 100 | 10000 | 5 |
| Answer | 50 | 5000 | 3 |
| Locate | 20 | 3000 | 1 |
| Time-boxed | 30 | 4000 | 2 |
| Mode | Description | Best For |
|---|---|---|
| Sequential | One layer at a time, stop on success | Locate intent, exact matches |
| Parallel | All layers simultaneously, merge results | Explore intent, broad discovery |
| Hybrid | Primary layer + backup, merge with weights | Answer intent, balanced results |
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
}
## 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
When implementing memory queries, follow this contract:
Always check tier first:
memory-daemon retrieval status
Classify intent before routing:
memory-daemon retrieval classify "<query>"
Use tier-appropriate commands:
teleport hybridteleport vectorteleport searchquery searchInclude explainability in response:
Before returning results:
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 | Resolution |
|---|---|
| All layers failed | Return Tier 5 (Agentic) results |
| Timeout exceeded | Return partial results with explanation |
| No results found | Broaden query or suggest alternatives |
| Intent unclear | Default to Answer intent |
Results are ranked using Phase 16 signals:
| Signal | Weight | Description |
|---|---|---|
| Salience score | 0.3 | Memory importance (Procedure > Observation) |
| Recency | 0.3 | Time-decayed scoring |
| Relevance | 0.3 | BM25/Vector match score |
| Usage | 0.1 | Access frequency (if enabled) |
See Command Reference for full CLI options.
BM25 keyword search for agent-memory. Use when asked to "find exact terms", "keyword search", "search for specific function names", "locate exact phrase", or when semantic search returns too many results. Provides fast BM25 full-text search via Tantivy index.
Query past conversations from the agent-memory system. Use when asked to "recall what we discussed", "search conversation history", "find previous session", "what did we talk about last week", or "get context from earlier". Provides tier-aware retrieval with automatic fallback chains, intent-based routing, and full explainability. Includes command-equivalent instructions for search, recent, and context operations.
Topic graph exploration for agent-memory. Use when asked to "explore topics", "show related concepts", "what themes have I discussed", "find topic connections", or "discover patterns in conversations". Provides semantic topic extraction with time-decayed importance scoring.
Semantic vector search for agent-memory. Use when asked to "find similar discussions", "semantic search", "find related topics", "what's conceptually related to X", or when keyword search returns poor results. Provides vector similarity search and hybrid BM25+vector fusion.
Wizard-style configuration guidance for a single-agent agent-memory setup. Shows defaults inline, provides a full sample config, and includes a dry-run config check step. Always confirm before creating or editing files.
Wizard-style installation guide for agent-memory (macOS/Linux). Helps users choose an install path, check prerequisites, and set PATH. Always confirm before any file edits or copying binaries. Provide verification commands only.