aim-search

name	aim-search
description	Search memory system with advanced filtering and intent detection
allowed-tools	Read, Bash

Search Memory - Advanced Memory Retrieval

Search the AI Memory Module using semantic similarity with advanced filtering by collection, type, and intent detection.

Memory System V2.0

The memory system has 3 collections:

• code-patterns - HOW things are built (implementation, error_fix, refactor, file_pattern)
• conventions - WHAT rules to follow (rule, guideline, port, naming, structure)
• discussions - WHY things were decided (decision, session, blocker, preference, context)

Activation

# Basic semantic search (searches code-patterns by default)
/aim-search "how do I implement authentication"

# Search specific collection
/aim-search "error handling patterns" --collection conventions

# Filter by memory type
/aim-search "recent bugs" --type error_fix

# Filter by multiple types
/aim-search "code patterns" --type implementation,refactor

# Use intent detection with cascading search
/aim-search "how do I implement auth" --intent how

# Limit results
/aim-search "database patterns" --limit 10

# Hide decay scores
/aim-search "authentication" --no-decay

Options

• --collection <name> - Target specific collection (code-patterns, conventions, discussions)
• --type <type> - Filter by memory type (see types below)
• --intent <intent> - Use intent detection (how, what, why)
• --limit <n> - Maximum results to return (default: 5)
• --group-id <id> - Filter by project (default: auto-detect from cwd)
• --decay - Show decay scores per result (default: enabled)
• --no-decay - Hide decay scores from output

Memory Types by Collection

code-patterns

• implementation - How features/components were built
• error_fix - Errors encountered and solutions
• refactor - Refactoring patterns applied
• file_pattern - File or module-specific patterns

conventions

• rule - Hard rules that MUST be followed
• guideline - Soft guidelines (SHOULD follow)
• port - Port configuration rules
• naming - Naming conventions
• structure - File and folder structure conventions

discussions

• decision - Architectural/design decisions (DEC-xxx)
• session - Session summaries
• blocker - Blockers and resolutions (BLK-xxx)
• preference - User preferences and working style
• context - Important conversation context

Intent Detection

When using --intent, the system routes to the appropriate primary collection:

• how → code-patterns (implementation examples)
• what → conventions (rules and guidelines)
• why → discussions (decisions and context)

If primary collection has insufficient results, automatically expands to secondary collections.

Output Format

Each result shows relevance score, content summary, metadata, and decay scores:

1. [0.85] Implementation of authentication middleware
   Collection: code-patterns | Type: implementation | 2026-01-15
   Decay: 0.72 (temporal: 0.61, semantic: 0.85)

2. [0.78] JWT token validation pattern
   Collection: code-patterns | Type: implementation | 2026-01-10
   Decay: 0.65 (temporal: 0.52, semantic: 0.78)

When decay scoring is disabled or timestamp is unavailable:

1. [0.85] Implementation of authentication middleware
   Collection: code-patterns | Type: implementation | 2026-01-15
   Decay: n/a (temporal: n/a, semantic: 0.85)

Score Interpretation

Results include three scores:

• Relevance (primary sort): Combined score from semantic + temporal
• Semantic: How closely the content matches your query (vector similarity)
• Temporal: How recent the memory is (exponential decay)

A memory with semantic=0.90 and temporal=0.30 is very relevant but old. A memory with semantic=0.60 and temporal=0.95 is less relevant but very recent.

Decay Formula

final_score = 0.7 * semantic + 0.3 * 0.5^(age_days / half_life)

Sub-scores are recomputed client-side (Qdrant returns only the combined score):

age_days = (datetime.now(timezone.utc) - datetime.fromisoformat(stored_at)).days
temporal_score = 0.5 ** (age_days / half_life)
semantic_score = (combined_score - 0.3 * temporal_score) / 0.7

Half-life varies by memory type (configured via decay_type_overrides):

• conversation, session_summary: 21 days
• github_commit, github_code_blob: 14 days
• github_issue, github_pr: 30 days
• rule, guideline: 60 days

Activation Examples

# Find implementation examples in current project
/aim-search "authentication implementation"

# Find shared conventions across all projects
/aim-search "naming conventions" --collection conventions

# Find specific error fixes
/aim-search "database connection" --type error_fix

# Use cascading search with intent
/aim-search "why did we choose postgres" --intent why

# Find architectural decisions
/aim-search "database choice" --type decision --collection discussions

# Search multiple types
/aim-search "auth patterns" --type implementation,error_fix --limit 10

# Search without decay score display
/aim-search "auth patterns" --no-decay

Python Implementation Reference

This skill uses search_memories() from src/memory/search.py:

from memory.search import search_memories
from memory.secrets_env import pin_qdrant_api_key, is_auth_error

# Pin QDRANT_API_KEY from .env.secrets so a stale exported key can't silently
# fail auth and degrade this search to file-only (run-with-env.sh parity).
pin_qdrant_api_key()

try:
    results = search_memories(
        query="your search query",
        collection="code-patterns",  # Optional
        memory_type="implementation",  # Optional, can be list
        use_cascading=True,  # Enable cascading search
        intent="how",  # Optional: auto-detects from query
        limit=5
    )
except Exception as e:
    # Auth failure: the knowledge base was NOT consulted. Do not present this
    # as "no results found" — results are file-only.
    if is_auth_error(str(e)):
        print("❌ Memory search auth FAILED (401) — knowledge base NOT "
              "consulted; results are file-only")
    raise

Technical Details

• Semantic Search: Uses jina-embeddings-v2-base-en for vector similarity
• Project Scoping: Automatically detects project from current working directory
• Cascading: Searches primary collection first, expands only if insufficient results
• Attribution: All results include collection and type attribution
• Performance: < 2s for typical searches (NFR-P1)
• Decay Scoring: Uses AD-5 formula (SPEC-001). Sub-scores recomputed client-side.

Notes

• Results sorted by relevance score (highest first)
• Score threshold defaults to 0.7 (configurable in .env)
• Project auto-detection uses git repository root
• code-patterns, conventions, and discussions are all filtered by project
• Decay scores displayed to 2 decimal places