Search & Hybrid Scoring
Relevant source files
The following files were used as context for generating this wiki page:
Search & Hybrid Scoring is the primary retrieval mechanism in CORTEX. It uses a 7-factor weighted formula to rank memories based on semantic relevance, temporal characteristics, emotional importance, and cognitive connections. Unlike standard vector databases, this system incorporates neuroscience-inspired signals like Ebbinghaus-adjusted resonance and CA3 autoassociative pattern completion to determine what an agent should remember in a specific context.
Sources: README.md:204-210, paper/drafts/cortex-v2-4-technical-note.md:58-64
Scoring Architecture
The hybrid search scoring logic combines traditional vector similarity with metadata-driven boosts. The system executes a single SQL query against PostgreSQL using pgvector to calculate the base scores, then blends secondary cognitive activations in parallel.
Hybrid Score Factors
The ranking algorithm applies specific weights to different attributes of a memory_node.
| Factor | Weight | Description |
|---|---|---|
| Cosine Similarity | 0.45 - 0.50 | Semantic relevance between query and memory embeddings. |
| Text Match | 0.18 - 0.20 | Exact keyword hit (ILIKE matching). |
| Recency | 0.12 - 0.15 | Exponential decay with a 30-day half-life. |
| Resonance | 0.10 | Ebbinghaus stability-adjusted importance score (normalized 0-1). |
| Priority Boost | 0.05 | Manual importance levels (P0=1.0 down to P4=0.1). |
| Emotional Boost | 0.10 | Salience boost based on 6D emotional valence vectors. |
Sources: src/api/search.ts:38-44, src/mcp/server.ts:60-65, paper/drafts/cortex-v2-4-technical-note.md:67-75
Data Flow Diagram
The following diagram illustrates the lifecycle of a search request and how scores are aggregated.
Cognitive Enhancements
Beyond standard hybrid retrieval, CORTEX applies two neurobiological mechanisms during the search process: CA3 activation and the Labile Window.
CA3 Pattern Completion
The system runs autoassociative recall in parallel with the main hybrid search. It uses sparse-overlap initial activation and recurrent spread through the memory_synapses graph to converge on a full pattern. If CA3 identifies relevant memories, their scores receive a 0.3 * CA3_activation boost before the final result set is sorted.
Sources: src/api/search.ts:93-103, paper/drafts/cortex-v2-4-technical-note.md:46-55
Labile Window & Reconsolidation
Every search operation triggers a critical learning mechanism. When memories are retrieved, they are marked as labile via the markLabile() function. This opens a one-hour window where the agent can update or correct the memory content based on new information.
Sources: src/api/search.ts:110-125, REFERENCES.md:95-104
Implementation Details
SQL Scoring Logic
The core scoring happens inside a WITH vector_scores Common Table Expression (CTE). It calculates recency using an exponential decay formula and maps priority levels to static floats.
// Example Recency Calculation from src/api/search.ts:67
// Exponential decay, 30-day half-life
EXP(-0.023 * EXTRACT(EPOCH FROM (NOW() - created_at)) / 86400) AS recency
Sources: src/api/search.ts:67, src/mcp/server.ts:80
Retrieval Components
| Component | Function | File Path |
|---|---|---|
hybridSearch | Main orchestration of scoring and blending. | src/api/search.ts |
cortex_search | MCP tool wrapper for hybrid retrieval. | src/mcp/server.ts |
patternComplete | CA3 autoassociative recall implementation. | src/hippocampus/index.ts |
temporalSearch | Filtered retrieval based on valid_from / valid_until. | benchmarks/cogbench/client.ts |
Sources: src/api/search.ts:37, src/mcp/server.ts:50, benchmarks/cogbench/client.ts:210
API and Tools
REST Endpoint
POST /api/v1/search
- Request Body:
{ query: string, agentId: number, limit?: number } - Behavior: Resolves the internal agent ID, performs hybrid search, and returns a
SearchResult[]including ascoreBreakdownfor debugging.
Sources: src/api/search.ts:182-205
MCP Tools
Agents (like Claude Code) access search through two primary tools:
cortex_search: Standard hybrid retrieval with optional verbose metadata (resonance, validity).cortex_recall: Token-budget-aware retrieval. It fills a specified token limit (e.g., 4000 tokens) with the highest-ranked memories and recent cognitive artifacts.
Sources: src/mcp/server.ts:50-130, src/mcp/server.ts:133-205
Search & Hybrid Scoring ensures that agent retrieval is not just a nearest-neighbor vector lookup, but a contextual judgment. By weighting semantic matches alongside emotional salience and temporal validity, the system maintains cognitive consistency over long durations.