RAG Enhancement Framework

When This Activates

This skill activates for explanation/understanding requests:

• "How does X work?"

• "Explain the Y system"

• "Give me background on Z"

• "What's the context for this?"

• Understanding complex codebases

Hybrid Search (BM25 + Semantic)

The system uses Reciprocal Rank Fusion (RRF) to combine:

BM25 (Keyword)

• Catches exact matches (function names, acronyms)

• Fast, works without embeddings

• Good for specific terms

Semantic (Embeddings)

• Catches conceptually similar content

• Works for paraphrased queries

• Understands intent

RRF Formula:

RRF(d) = Σ(1 / (k + rank(d)))

Where k=60 works well empirically.

Context Building

For explanations, the system retrieves:

1. Relevant Files

Based on query similarity:

memory_query "how does authentication work" → Returns top files with summaries

2. Database Schema (if data-related)

Keywords: database, collection, store, save, user, data, schema

Collections and their fields

3. Function Definitions (if code-related)

Keywords: function, method, how does, implement, call

Function name, file, line number

4. Architectural Decisions (if why-related)

Keywords: decision, why, chose, architecture, pattern

Past decisions with context

5. Past Observations (if problem-related)

Keywords: bug, fix, issue, pattern, learned, gotcha

Category, description, resolution

6. Project Conventions (if style-related)

Keywords: convention, rule, preference, style, standard

Name and rule description

Recency Weighting

Recently modified files get boosted:

• Files modified today: +20% score boost

• Linear decay over 30 days to +0%

This helps surface actively developed code.

RAG Workflow

• Receive question about the codebase

• Hybrid search for relevant files

• Keyword detect for additional context types

• Build context with all relevant information

• Generate answer using retrieved context only

• Reference file paths in the response

MCP Tools for RAG

Hybrid search

memory_query "how does X work"

Semantic search

memory_search query="authentication flow"

Function lookup

memory_functions name="handleLogin"

Similar files

memory_similar file="src/auth/login.ts"

Session observations

memory_sessions category=decision query="auth"

Explanation Format

When explaining code:

How [X] Works

Overview

Brief description of the system/feature.

Key Files

• path/to/file.ts:123 - Main implementation
• path/to/other.ts:45 - Helper functions

Data Flow

1. User triggers [action]
2. [Component] handles request
3. [Service] processes data
4. Result returned to [destination]

Relevant Decisions

• Decision 1 (why this approach)
• Decision 2 (trade-offs made)

Gotchas

• Known issue or quirk to watch for

Local RAG (Free)

For simple explanations, route to local:

local_ask question="where is login handled?" mode=rag

Uses Ollama with project context, $0 cost.