aim-search

# 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 ```text # 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): ```python 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 ```text # 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`: ```python 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