Z = 0.0  ←──────────────────────────────→  Z = 1.0
EXACT                                      BROAD
│                                          │
├─ Precise lexical match                   ├─ Thematic relevance
├─ Specific phrase/keyword                 ├─ Conceptual similarity  
├─ Named entity identification             ├─ Analogical connections
└─ Temporal/contextual anchors             └─ Abstract pattern matching

@dataclass
class MemoryResult:
    content: str
    node_id: str                    # X-axis position
    embedding_similarity: float     # Y-axis score (0-1)
    lexical_precision: float        # Z-axis anchor (0-1)
    z_position: float               # Computed Z value
    timestamp: datetime
    metadata: dict

def compute_lexical_precision(query: str, content: str) -> float:
    """
    Returns 0-1 score where:
    - 1.0 = Exact phrase match
    - 0.8+ = All query terms present, high term frequency
    - 0.5 = Partial term overlap
    - 0.0 = No lexical overlap
    """
    # Implementation using rank_bm25 or similar
    tokenized_query = tokenize(query)
    tokenized_content = tokenize(content)
    
    # Exact phrase bonus
    if query.lower() in content.lower():
        return 1.0
    
    # BM25 score normalized to 0-1
    bm25_score = compute_bm25(tokenized_query, tokenized_content)
    return normalize(bm25_score)

def compute_z_position(
    lexical_score: float, 
    semantic_score: float
) -> float:
    """
    Z approaches 0 when lexical >> semantic (exact match)
    Z approaches 1 when semantic >> lexical (broad match)
    """
    if lexical_score == 0 and semantic_score == 0:
        return 0.5  # Neutral
    
    total = lexical_score + semantic_score
    z = semantic_score / total
    return z

@dataclass
class QueryIntent:
    target_z: float           # Center of desired Z-range
    z_tolerance: float        # Acceptable deviation (±)
    confidence: float         # How certain we are of intent

def analyze_query_intent(query: str) -> QueryIntent:
    """
    Detect retrieval intent from query patterns
    """
    # Exact match indicators (Z → 0)
    exact_patterns = [
        r"exact(ly)?",
        r"specific(ally)?", 
        r"where (did )?(I|we) (say|mention|write)",
        r"find (the|that) (conversation|chat|discussion)",
        r"quote",
        r'"[^"]+"',  # Quoted phrases
    ]
    
    # Broad match indicators (Z → 1)  
    broad_patterns = [
        r"(think|thought|thinking) about",
        r"ideas? (on|about|related)",
        r"explore",
        r"generally",
        r"themes?",
        r"pattern",
        r"similar to",
    ]
    
    exact_score = sum(
        1 for p in exact_patterns 
        if re.search(p, query, re.IGNORECASE)
    )
    broad_score = sum(
        1 for p in broad_patterns 
        if re.search(p, query, re.IGNORECASE)
    )
    
    # Default to balanced (0.5) with moderate tolerance
    if exact_score == 0 and broad_score == 0:
        return QueryIntent(target_z=0.5, z_tolerance=0.3, confidence=0.5)
    
    # Calculate target Z
    total = exact_score + broad_score
    target_z = broad_score / total
    confidence = min(1.0, total / 3)  # More signals = higher confidence
    
    # Tighter tolerance for confident intent detection
    z_tolerance = 0.2 if confidence > 0.7 else 0.35
    
    return QueryIntent(
        target_z=target_z, 
        z_tolerance=z_tolerance, 
        confidence=confidence
    )

class BrainRetriever:
    def retrieve(
        self, 
        query: str, 
        node_ids: list[str] = None,  # X-axis filter
        z_override: float = None,     # Manual Z targeting
        limit: int = 10
    ) -> list[MemoryResult]:
        
        # Step 1: Detect query intent (or use override)
        if z_override is not None:
            intent = QueryIntent(
                target_z=z_override, 
                z_tolerance=0.15, 
                confidence=1.0
            )
        else:
            intent = analyze_query_intent(query)
        
        # Step 2: Parallel retrieval strategies
        lexical_results = self.lexical_search(query, node_ids)
        semantic_results = self.semantic_search(query, node_ids)
        
        # Step 3: Merge and score
        all_results = self.merge_results(lexical_results, semantic_results)
        
        # Step 4: Compute Z-position for each result
        for result in all_results:
            result.z_position = compute_z_position(
                result.lexical_precision,
                result.embedding_similarity
            )
        
        # Step 5: Rank by Z-distance from target
        def z_relevance_score(result: MemoryResult) -> float:
            z_distance = abs(result.z_position - intent.target_z)
            z_penalty = z_distance / intent.z_tolerance
            
            # Combine intrinsic quality with Z-alignment
            base_score = (
                result.lexical_precision * (1 - intent.target_z) +
                result.embedding_similarity * intent.target_z
            )
            
            # Penalize results outside Z tolerance
            if z_distance > intent.z_tolerance:
                return base_score * 0.5
            
            return base_score * (1 - z_penalty * 0.3)
        
        ranked = sorted(all_results, key=z_relevance_score, reverse=True)
        return ranked[:limit]

@dataclass
class TieredResults:
    exact_matches: list[MemoryResult]      # Z < 0.3
    precise_matches: list[MemoryResult]    # 0.3 ≤ Z < 0.5
    semantic_matches: list[MemoryResult]   # 0.5 ≤ Z < 0.7
    conceptual_matches: list[MemoryResult] # Z ≥ 0.7

def tiered_retrieve(query: str, node_ids: list[str] = None) -> TieredResults:
    """
    Returns results organized by Z-tier for UI display
    """
    all_results = retrieve(query, node_ids, limit=50)
    
    return TieredResults(
        exact_matches=[r for r in all_results if r.z_position < 0.3],
        precise_matches=[r for r in all_results if 0.3 <= r.z_position < 0.5],
        semantic_matches=[r for r in all_results if 0.5 <= r.z_position < 0.7],
        conceptual_matches=[r for r in all_results if r.z_position >= 0.7],
    )

{
  "name": "brain_recall",
  "description": "Retrieve memories from Brain's 3D memory space",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Natural language query"
      },
      "focus": {
        "type": "string",
        "enum": ["exact", "precise", "balanced", "conceptual", "broad"],
        "default": "auto",
        "description": "Z-axis targeting preset (auto = intent detection)"
      },
      "z_value": {
        "type": "number",
        "minimum": 0,
        "maximum": 1,
        "description": "Explicit Z-axis target (overrides focus)"
      },
      "nodes": {
        "type": "array",
        "items": {"type": "string"},
        "description": "X-axis filter: specific Knowledge Graph nodes"
      },
      "limit": {
        "type": "integer",
        "default": 10,
        "description": "Maximum results to return"
      },
      "tiered": {
        "type": "boolean",
        "default": false,
        "description": "Return results grouped by Z-tier"
      }
    },
    "required": ["query"]
  }
}

{
  "results": [
    {
      "content": "...",
      "node": {
        "id": "node_123",
        "label": "aiConnected/Brain/Architecture"
      },
      "scores": {
        "lexical": 0.85,
        "semantic": 0.72,
        "z_position": 0.46,
        "relevance": 0.91
      },
      "metadata": {
        "timestamp": "2026-01-15T14:30:00Z",
        "source": "conversation",
        "conversation_id": "conv_456"
      }
    }
  ],
  "query_analysis": {
    "detected_intent": "precise",
    "target_z": 0.35,
    "confidence": 0.82
  }
}

🎯 Exact Matches (Z < 0.3)
   └─ "The equity split is 53% for me, 10% each for..." [Jan 15]

📍 Precise Matches (Z 0.3-0.5)  
   └─ Discussion with Jacob about CTO compensation structure [Jan 12]

💭 Conceptual Matches (Z 0.5-0.7)
   └─ Notes on fair partnership principles from startup reading [Dec 28]

🌐 Broad Matches (Z > 0.7)
   └─ General thoughts on building founding teams [Nov 15]

- "exactly"
- "specifically" 
- "word for word"
- "where did I say"
- "find the conversation where"
- "quote"
- Quoted phrases ("...")
- Specific numbers or dates
- Proper nouns with modifiers

- "thinking about"
- "ideas on"
- "explore"
- "related to"
- "similar to"
- "themes"
- "patterns"
- "generally"
- "overall"
- Abstract nouns without specifics

                              Y-Axis (Vector Similarity)
                                        │
                                        │
                              ┌─────────┼─────────┐
                             /│         │         │
                            / │    High Semantic  │
                           /  │    Low Lexical    │
                          /   │    (Z → 1.0)      │
                         /    │         │         │
        X-Axis          /     ├─────────┼─────────┤
    (Knowledge Graph)──/──────┤         │         │
                      /       │  Balanced Match   │
                     /        │    (Z ≈ 0.5)      │
                    /         │         │         │
                   /          ├─────────┼─────────┤
                  /           │         │         │
                 /            │   High Lexical    │
                /             │   Low Semantic    │
               /              │    (Z → 0.0)      │
              /               │         │         │
             /                └─────────┴─────────┘
            /                           │
           /                    Z-Axis (Specificity)
          /                             │
         ▼                              ▼
    Node Navigation              Exact ◄────► Broad