Hybrid Memory Retrieval

Name: memory-retrieve
Rating: 92
Author: whiteboardev

Search memories using the optimal strategy based on query analysis.

State Machine

code

START → PARSE_QUERY → CLASSIFY
     ├→ NO_QUERY ────→ GET_RECENT ────────────────────┐
     ├→ RECENT ──────→ GET_RECENT_N ──────────────────┤
     ├→ KEYWORD ─────→ KEYWORD_SEARCH ────────────────┤
     └→ SEMANTIC ────→ VECTOR_SEARCH ──┬→ RESULTS ────┤
                                       └→ FALLBACK ───┤
                                                      ▼
                              INCLUDE_SUMMARIES? → FORMAT → END

Query Classification

Pattern	Type	Example	Strategy
Empty	none	`""`	Recent memories
Temporal	recent	`"last 5"`, `"recent"`	Recent N memories
Short specific	keyword	`"JWT token"`	Keyword match
Question/conceptual	semantic	`"How does auth work?"`	Vector + fallback

Execution

Path A: Subagent (preferred)

code

Task(
  subagent_type: "summarizer",
  prompt: "Search memories in project PROJECT_ID for: QUERY"
)

Path B: Direct script

bash

bun .opencode/skills/memory-retrieve/scripts/retrieve-memories.ts PROJECT_ID [QUERY] [OPTIONS]

Commands

Main Retrieval

bash

# Recent memories (no query)
bun .opencode/skills/memory-retrieve/scripts/retrieve-memories.ts PROJECT_ID

# Semantic search
bun .opencode/skills/memory-retrieve/scripts/retrieve-memories.ts PROJECT_ID "authentication flow"

# With summaries
bun .opencode/skills/memory-retrieve/scripts/retrieve-memories.ts PROJECT_ID "JWT" --include-summaries

# JSON output
bun .opencode/skills/memory-retrieve/scripts/retrieve-memories.ts PROJECT_ID "auth" --format json --limit 10

Individual Scripts

bash

# Classify query type
bun .opencode/skills/memory-retrieve/scripts/classify-query.ts "QUERY"

# Recent only
bun .opencode/skills/memory-retrieve/scripts/get-recent-memories.ts PROJECT_ID --limit 10

# Vector search
bun .opencode/skills/memory-retrieve/scripts/search-vector.ts PROJECT_ID "QUERY" --limit 20

# Keyword fallback
bun .opencode/skills/memory-retrieve/scripts/search-keyword.ts PROJECT_ID "QUERY" --limit 20

Options

Option	Default	Description
`--limit N`	20	Max results
`--include-summaries`	false	Include project summaries
`--format json\|text`	text	Output format
`--quiet`	false	JSON only, no progress

Exit Codes

Code	Meaning
0	Success
1	Error
2	No results (search scripts only - triggers fallback)

Output

Text Format

code

## Summaries

### coding_session (1/8/2026)
OBJECTIVE: Implement authentication...

## Memories

- **fact** [0.92]: Implemented JWT verification...
- **fact** [0.89]: Added refresh token logic...

JSON Format

json

{
  "success": true,
  "memories": [...],
  "summaries": [...],
  "searchMethod": "vector",
  "totalTokens": 2340,
  "count": 8
}

Environment Variables

Variable	Default	Description
`BRAINY_API_URL`	`http://localhost:3000`	API endpoint
`BRAINY_PROJECT_ID`	`3afb861a-...`	Default project if not specified
`RETRIEVE_RECENT_LIMIT`	`10`	Default limit for recent queries
`RETRIEVE_SEARCH_LIMIT`	`20`	Default limit for search queries
`RETRIEVE_MIN_SIMILARITY`	`0.5`	Min similarity for vector results