engine7 7.1.23 → 7.1.24

package/src/memory/everos/python/agentic_search.py

@@ -0,0 +1,980 @@
+#!/usr/bin/env python3
+"""
+Agentic Search Pipeline — 1:1 搬运 EverOS everalgo/rank 逻辑
+
+Pipeline:
+  fact-MaxSim (dense + sparse) → hybrid_full (RRF) → cluster_scoped →
+  aagentic_retrieve (rerank → sufficiency → multi_query/refined_query → merge)
+
+Fallback: cluster empty → hybrid_full + rerank.
+
+Usage:
+    C:/Users/24045/.openclaw/everos-venv/Scripts/python.exe agentic_search.py "丢手机"
+    C:/Users/24045/.openclaw/everos-venv/Scripts/python.exe agentic_search.py "丢手机" --compare
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sqlite3
+import time
+from dataclasses import dataclass, field
+from typing import Literal
+
+import httpx
+import lancedb
+
+# ── Config (env-driven, override via environment variables) ────────
+import os
+
+EVEROS_URL = os.getenv("EVEROS_URL", "http://127.0.0.1:8100")
+DEEPINFRA_URL = os.getenv("RERANK_URL", "https://api.deepinfra.com/v1/inference/Qwen/Qwen3-Reranker-4B")
+DEEPINFRA_KEY = os.getenv("RERANK_API_KEY", "")
+GLM_URL = os.getenv("LLM_BASE_URL", "https://open.bigmodel.cn/api/coding/paas/v4/chat/completions")
+GLM_KEY = os.getenv("LLM_API_KEY", "")
+GLM_MODEL = os.getenv("LLM_MODEL", "glm-5.2")
+
+LANCEDB_PATH = os.getenv("LANCEDB_PATH", os.path.expanduser("~/.everos/.index/lancedb"))
+SQLITE_PATH = os.getenv("SQLITE_PATH", os.path.expanduser("~/.everos/.index/sqlite/system.db"))
+
+# These are per-request, not global — but kept as defaults
+DEFAULT_USER_ID = os.getenv("EVEROS_USER_ID", "xiaomei")
+DEFAULT_APP_ID = os.getenv("EVEROS_APP_ID", "xiaomei")
+DEFAULT_PROJECT_ID = os.getenv("EVEROS_PROJECT_ID", "default")
+
+# ── Hyperparameters (1:1 with everos/memory/search/agentic.py) ────────
+DENSE_CANDIDATES = 50
+SPARSE_CANDIDATES = 50
+HYBRID_RRF_K = 40              # FIX #6: episode path uses 40, not 60
+CLUSTER_BASE_CANDIDATES = 100
+CLUSTER_TOP_K = 10
+ROUND1_TOP_N = 30
+ROUND1_RERANK_TOP_N = 10
+ROUND2_CAP = 40
+MULTI_QUERY_COUNT = 3
+REFINEMENT_STRATEGY: str = "multi_query"  # FIX #1: configurable, matches default
+
+RERANK_INSTRUCTION = (
+    "Determine if the passage contains specific facts, entities "
+    "(names, dates, locations), or details that directly answer the question."
+)
+
+# ── Prompts (1:1 with everalgo/rank/prompts/en/) ─────────────────────
+
+# FIX #3: Full sufficiency prompt (was simplified)
+SUFFICIENCY_PROMPT = """You are an expert in information retrieval evaluation. Assess whether the retrieved documents provide sufficient information to answer the user's query.
+
+--------------------------
+User Query:
+{query}
+
+Retrieved Documents:
+{retrieved_docs}
+--------------------------
+
+### Instructions:
+
+1. **Analyze the Query's Needs**
+   - **Entities**: Who/What is being asked about?
+   - **Attributes**: What specific details (color, time, location, quantity)?
+   - **Time**: Does it ask for a specific time (absolute or relative like "last week")?
+
+2. **Evaluate Document Evidence**
+   - Check **Content**: Do the documents mention the entities and attributes?
+   - Check **Dates**:
+     - Use the `Date` field of each document.
+     - For relative time queries (e.g., "last week", "yesterday"), verify if document dates fall within that timeframe.
+     - If the query asks "When did X happen?", do you have the specific date or just a vague mention?
+
+3. **Judgment Logic**
+   - **Sufficient**: You can answer the query *completely* and *precisely* using ONLY the provided documents.
+   - **Insufficient**:
+     - The specific entity is not found.
+     - The entity is found, but the specific attribute (e.g., "price") is missing.
+     - The time reference cannot be resolved (e.g., doc says "yesterday" but has no date, or doc date doesn't match query timeframe).
+     - Conflicting information without resolution.
+
+### Output Format (strict JSON):
+{{
+  "is_sufficient": true or false,
+  "reasoning": "Brief explanation. If insufficient, state WHY (e.g., 'Found X but missing date', 'No mention of Y').",
+  "key_information_found": ["Fact 1 (Source: Doc 1)", "Fact 2 (Source: Doc 2)"],
+  "missing_information": ["Specific gap 1", "Specific gap 2"]
+}}
+
+Now evaluate:"""
+
+# FIX #4: Full multi-query prompt with 4 strategies + 3 styles
+MULTI_QUERY_PROMPT = """You are an expert at query reformulation for conversational memory retrieval.
+Your goal is to generate 2-3 complementary queries to find the MISSING information.
+
+--------------------------
+Original Query:
+{original_query}
+
+Key Information Found:
+{key_info}
+
+Missing Information:
+{missing_info}
+
+Retrieved Documents (Context):
+{retrieved_docs}
+--------------------------
+
+### Strategy Selection (Choose based on WHY info is missing):
+
+**[A] Pivot / Entity Association (If entity is missing)**
+- If the specific entity is not found, search for related entities or broader categories.
+- Example: "manager's feedback" not found → try "performance review", "work evaluation".
+
+**[B] Temporal Calculation (If time is missing/unclear)**
+- Use `Date` from Retrieved Documents to anchor relative times.
+- Example: doc dated 2024-03-15 mentions "last month" → search for "February 2024".
+- Search for the *event* to find its timestamp: "When did the deadline change?"
+
+**[C] Concept Expansion (If vocabulary mismatch)**
+- Synonyms: "residence" → "living", "staying at", "moved to".
+- General/Specific: "Italian cuisine" ↔ "pasta", "pizza", "restaurant".
+
+**[D] Constraint Relaxation (If too specific)**
+- If "quarterly sales report from Q3" fails, try "sales report", "Q3 results".
+- Remove one constraint at a time.
+
+### Query Style Requirements (Use DIFFERENT styles):
+
+1. **Keyword Combo** (2-5 words): Key entities only. High recall.
+   - e.g., "project deadline", "vacation plans summer"
+2. **Natural Question** (5-10 words): Rephrased question.
+   - e.g., "When was the meeting scheduled?", "What was discussed about the budget?"
+3. **Hypothetical Statement** (HyDE, 5-10 words): A likely sentence in the memory.
+   - e.g., "We decided to postpone the launch", "The client requested changes"
+
+### Requirements:
+- Generate 2-3 queries.
+- **CRITICAL**: Use the strategies above to target the *Missing Information*.
+- Keep queries SHORT and SEARCHABLE.
+
+### Output Format (STRICT JSON):
+{{
+  "queries": [
+    "Query 1",
+    "Query 2",
+    "Query 3"
+  ],
+  "reasoning": "Strategy used for each query (e.g., Q1: Pivot, Q2: Temporal)"
+}}
+
+Now generate:
+"""
+
+# FIX #1: refined_query prompt (was missing entirely)
+REFINED_QUERY_PROMPT = """You are an expert at query reformulation for information retrieval.
+
+**Task**: Generate a refined query that targets the missing information in the retrieved results.
+
+**Original Query**:
+{original_query}
+
+**Retrieved Documents** (insufficient):
+{retrieved_docs}
+
+**Missing Information**:
+{missing_info}
+
+**Instructions**:
+1. Keep the core intent of the original query unchanged.
+2. Add specific keywords or rephrase to target the missing information.
+3. Make the query more specific and focused.
+4. The refined query should be a direct question that seeks to extract the missing facts.
+5. Do NOT change the query's meaning or make it too broad.
+6. Keep it concise (1-2 sentences maximum).
+
+Now generate the refined query (output only the refined query, no additional text):
+Original Query: {original_query}
+Missing Info: {missing_info}
+
+Refined Query:
+"""
+
+
+# ── Data Types ───────────────────────────────────────────────────────
+@dataclass
+class Episode:
+    id: str
+    parent_id: str  # memcell_id
+    subject: str
+    summary: str
+    episode: str  # full content
+    timestamp: str
+    score: float = 0.0
+
+
+@dataclass
+class ClusterInfo:
+    id: str
+    members: list[str]  # memcell_ids
+
+
+@dataclass
+class AgenticResult:
+    episodes: list[Episode]
+    method: str
+    is_sufficient: bool = False
+    multi_queries: list[str] = field(default_factory=list)
+    reasoning: str = ""
+    timing: dict[str, float] = field(default_factory=dict)
+
+
+# ── DB Layer ─────────────────────────────────────────────────────────
+class DB:
+    def __init__(self):
+        self.lance = lancedb.connect(LANCEDB_PATH)
+        self.episode_tbl = self.lance.open_table("episode")
+        self.sqlite = sqlite3.connect(SQLITE_PATH)
+
+    def get_clusters(self) -> list[ClusterInfo]:
+        cur = self.sqlite.execute("SELECT cluster_id, member_id FROM cluster_member")
+        cluster_map: dict[str, list[str]] = {}
+        for cid, mid in cur.fetchall():
+            cluster_map.setdefault(cid, []).append(mid)
+        return [ClusterInfo(id=cid, members=mids) for cid, mids in cluster_map.items()]
+
+    def get_all_episodes(self) -> list[Episode]:
+        rows = (
+            self.episode_tbl.search()
+            .where(f"owner_id = '{DEFAULT_USER_ID}'")
+            .limit(2000)
+            .to_list()
+        )
+        return [
+            Episode(
+                id=r["id"],
+                parent_id=r.get("parent_id", ""),
+                subject=r.get("subject", "") or "",
+                summary=r.get("summary", "") or "",
+                episode=r.get("episode", "") or "",
+                timestamp=str(r.get("timestamp", "")),
+            )
+            for r in rows
+        ]
+
+
+# ── Search Layer ─────────────────────────────────────────────────────
+# Cache: episode_id → parent_id (loaded once from LanceDB)
+_ep_id_to_parent: dict[str, str] | None = None
+
+
+def _load_parent_id_map() -> dict[str, str]:
+    """Load episode_id → parent_id from LanceDB (API doesn't return parent_id)."""
+    global _ep_id_to_parent
+    if _ep_id_to_parent is not None:
+        return _ep_id_to_parent
+    lance = lancedb.connect(LANCEDB_PATH)
+    tbl = lance.open_table("episode")
+    rows = tbl.search().where(f"owner_id = '{DEFAULT_USER_ID}'").limit(2000).to_list()
+    _ep_id_to_parent = {r["id"]: r.get("parent_id", "") or "" for r in rows}
+    return _ep_id_to_parent
+
+
+def hybrid_search(query: str, top_k: int = 20, user_id: str = None, app_id: str = None, project_id: str = None) -> tuple[list[Episode], float]:
+    """Call EverOS hybrid search API (dense + sparse RRF fusion).
+    Backfills parent_id from LanceDB (API doesn't return it)."""
+    user_id = user_id or DEFAULT_USER_ID
+    app_id = app_id or DEFAULT_APP_ID
+    project_id = project_id or DEFAULT_PROJECT_ID
+    pid_map = _load_parent_id_map()
+    t0 = time.time()
+    r = httpx.post(
+        f"{EVEROS_URL}/api/v1/memory/search",
+        json={
+            "query": query,
+            "user_id": user_id,
+            "app_id": app_id,
+            "project_id": project_id,
+            "top_k": top_k,
+            "method": "hybrid",
+        },
+        timeout=60,
+    )
+    dt = time.time() - t0
+    data = r.json().get("data", {}).get("episodes", [])
+    episodes = [
+        Episode(
+            id=ep.get("id", ""),
+            parent_id=pid_map.get(ep.get("id", ""), ""),  # backfill from LanceDB
+            subject=ep.get("subject", "") or "",
+            summary=ep.get("summary", "") or "",
+            episode=ep.get("episode", ep.get("summary", "")) or "",
+            timestamp=str(ep.get("timestamp", "")),
+            score=ep.get("score", 0.0),
+        )
+        for ep in data
+    ]
+    return episodes, dt
+
+
+RERANK_BATCH_SIZE = 100  # DeepInfra 429s above ~200 docs per call
+
+
+def rerank(query: str, episodes: list[Episode]) -> tuple[list[Episode], float]:
+    """DeepInfra Qwen3-Reranker cross-encoder rerank (batched to avoid 429)."""
+    if not episodes:
+        return [], 0.0
+    documents = [ep.episode[:500] or ep.summary[:500] or ep.subject for ep in episodes]
+    t0 = time.time()
+
+    all_scores: list[float] = []
+    for i in range(0, len(documents), RERANK_BATCH_SIZE):
+        batch = documents[i : i + RERANK_BATCH_SIZE]
+        r = httpx.post(
+            DEEPINFRA_URL,
+            headers={
+                "Authorization": f"Bearer {DEEPINFRA_KEY}",
+                "Content-Type": "application/json",
+            },
+            json={"queries": [query], "documents": batch},
+            timeout=30,
+        )
+        if r.status_code == 429:
+            # Rate limited — wait and retry this batch
+            time.sleep(2)
+            r = httpx.post(
+                DEEPINFRA_URL,
+                headers={
+                    "Authorization": f"Bearer {DEEPINFRA_KEY}",
+                    "Content-Type": "application/json",
+                },
+                json={"queries": [query], "documents": batch},
+                timeout=30,
+            )
+        batch_scores = r.json().get("scores", [])
+        if batch_scores and isinstance(batch_scores[0], list):
+            batch_scores = batch_scores[0]
+        all_scores.extend(batch_scores)
+
+    dt = time.time() - t0
+
+    ranked = sorted(zip(all_scores, episodes), key=lambda x: -x[0])
+    result = []
+    for score, ep in ranked:
+        ep.score = score
+        result.append(ep)
+    return result, dt
+
+
+def llm_chat(prompt: str, temperature: float = 0.0) -> str:
+    """Call GLM-5.2 with thinking disabled."""
+    r = httpx.post(
+        GLM_URL,
+        headers={
+            "Authorization": f"Bearer {GLM_KEY}",
+            "Content-Type": "application/json",
+        },
+        json={
+            "model": GLM_MODEL,
+            "messages": [{"role": "user", "content": prompt}],
+            "max_tokens": 2000,
+            "temperature": temperature,
+            "thinking": {"type": "disabled"},
+        },
+        timeout=30,
+    )
+    return r.json()["choices"][0]["message"]["content"]
+
+
+def extract_json(text: str) -> dict:
+    """Extract outermost JSON object from LLM response."""
+    start = text.find("{")
+    end = text.rfind("}")
+    if start == -1 or end == -1 or end < start:
+        raise ValueError(f"No JSON in: {text[:200]}")
+    return json.loads(text[start : end + 1])
+
+
+# ── FIX #2: RRF Fusion ───────────────────────────────────────────────
+def rrf_fusion(*ranked_lists: list[Episode], k: int = 60) -> list[Episode]:
+    """Reciprocal Rank Fusion over N ranked lists. score = Σ 1/(k+rank_i)."""
+    doc_scores: dict[str, float] = {}
+    doc_map: dict[str, Episode] = {}
+
+    for ranked_list in ranked_lists:
+        for rank, ep in enumerate(ranked_list, start=1):
+            if not ep.id:
+                continue
+            doc_map.setdefault(ep.id, ep)
+            doc_scores[ep.id] = doc_scores.get(ep.id, 0.0) + 1.0 / (k + rank)
+
+    sorted_ids = sorted(doc_scores.items(), key=lambda kv: kv[1], reverse=True)
+    result = []
+    for ep_id, score in sorted_ids:
+        ep = doc_map[ep_id]
+        ep.score = score
+        result.append(ep)
+    return result
+
+
+# ── Agentic Pipeline ─────────────────────────────────────────────────
+def cluster_scoped_search(
+    query: str,
+    all_episodes: list[Episode],
+    clusters: list[ClusterInfo],
+    top_k: int = CLUSTER_BASE_CANDIDATES,
+) -> list[Episode]:
+    """
+    1. Run hybrid search for wide candidate pool
+    2. Map candidates to clusters (MaxSim: cluster_score = max member score)
+    3. Pick top-K clusters
+    4. Expand selected clusters' full memberships
+    """
+    base_results, _ = hybrid_search(query, top_k=top_k)
+    if not base_results:
+        return []
+
+    # Build episode_id → memcell_id map
+    ep_to_memcell = {ep.id: ep.parent_id for ep in all_episodes if ep.parent_id}
+
+    # Build memcell_id → cluster_id map
+    memcell_to_cluster: dict[str, str] = {}
+    for cluster in clusters:
+        for member in cluster.members:
+            memcell_to_cluster[member] = cluster.id
+
+    # MaxSim: cluster_score = max(member_score) over members in base_results
+    cluster_scores: dict[str, float] = {}
+    for base_ep in base_results:
+        memcell_id = ep_to_memcell.get(base_ep.id, base_ep.parent_id)
+        if not memcell_id:
+            continue
+        cluster_id = memcell_to_cluster.get(memcell_id)
+        if cluster_id is None:
+            continue
+        prev = cluster_scores.get(cluster_id)
+        if prev is None or base_ep.score > prev:
+            cluster_scores[cluster_id] = base_ep.score
+
+    if not cluster_scores:
+        return []
+
+    selected = {
+        cid
+        for cid, _ in sorted(
+            cluster_scores.items(), key=lambda kv: kv[1], reverse=True
+        )[:CLUSTER_TOP_K]
+    }
+
+    member_ids: set[str] = set()
+    for cluster in clusters:
+        if cluster.id in selected:
+            member_ids.update(cluster.members)
+
+    return [ep for ep in all_episodes if ep.parent_id in member_ids]
+
+
+def check_sufficiency(
+    query: str, episodes: list[Episode]
+) -> dict:
+    """LLM sufficiency check (temperature=0.0)."""
+    docs_str = format_docs(episodes)
+    prompt = SUFFICIENCY_PROMPT.format(query=query, retrieved_docs=docs_str)
+    resp = llm_chat(prompt, temperature=0.0)
+    return extract_json(resp)
+
+
+def generate_multi_queries(
+    query: str,
+    episodes: list[Episode],
+    missing_info: list[str],
+    key_info: list[str],
+) -> list[str]:
+    """LLM multi-query generation (temperature=0.4)."""
+    docs_str = format_docs(episodes)
+    prompt = MULTI_QUERY_PROMPT.format(
+        original_query=query,
+        key_info=", ".join(key_info) if key_info else "N/A",
+        missing_info=", ".join(missing_info) if missing_info else "N/A",
+        retrieved_docs=docs_str,
+    )
+    resp = llm_chat(prompt, temperature=0.4)
+    data = extract_json(resp)
+    return data.get("queries", [])[:MULTI_QUERY_COUNT]
+
+
+# FIX #1: refined_query strategy
+def generate_refined_query(
+    query: str,
+    episodes: list[Episode],
+    missing_info: list[str],
+) -> str:
+    """LLM refined-query generation (temperature=0.3)."""
+    docs_str = format_docs(episodes)
+    prompt = REFINED_QUERY_PROMPT.format(
+        original_query=query,
+        retrieved_docs=docs_str,
+        missing_info=", ".join(missing_info) if missing_info else "N/A",
+    )
+    resp = llm_chat(prompt, temperature=0.3).strip()
+    # Strip known prefixes
+    for prefix in ("Refined Query:", "Output:", "Answer:", "Query:"):
+        if resp.startswith(prefix):
+            resp = resp[len(prefix):].strip()
+    # Validate: fallback to original if garbage
+    if not (5 <= len(resp) <= 300) or resp.lower() == query.lower():
+        return query
+    return resp
+
+
+def format_docs(episodes: list[Episode], max_chars: int = 500) -> str:
+    """Format episodes as doc blocks for LLM prompt."""
+    if not episodes:
+        return "No retrieval results"
+    lines = []
+    for i, ep in enumerate(episodes, 1):
+        body = (ep.episode or ep.summary or ep.subject)[:max_chars]
+        lines.append(
+            f"Document {i}:\n"
+            f"  Title: {ep.subject[:100]}\n"
+            f"  Date: {ep.timestamp[:20]}\n"
+            f"  Content: {body}\n"
+        )
+    return "\n".join(lines)
+
+
+def dedup_by_id(episodes: list[Episode]) -> list[Episode]:
+    seen = set()
+    result = []
+    for ep in episodes:
+        if ep.id not in seen:
+            seen.add(ep.id)
+            result.append(ep)
+    return result
+
+
+# ── Main Pipeline ────────────────────────────────────────────────────
+async def agentic_search(
+    query: str, top_k: int = 5, strategy: str = REFINEMENT_STRATEGY
+) -> AgenticResult:
+    """
+    Full agentic pipeline 1:1 with EverOS:
+    1. Load clusters + all episodes
+    2. Round 1: cluster_scoped search
+    3. Round 1: rerank → truncate to ROUND1_RERANK_TOP_N
+    4. Sufficiency check
+    5. If sufficient → return reranked[:top_k]
+    6. If insufficient → Round 2 (multi_query or refined_query)
+    7. Merge R1 + R2 unique, cap, final rerank
+    Fallback: cluster empty → hybrid + rerank
+    """
+    timing = {}
+    t_total = time.time()
+
+    db = DB()
+
+    # Load corpus
+    t0 = time.time()
+    clusters = db.get_clusters()
+    all_episodes = db.get_all_episodes()
+    timing["load_corpus"] = time.time() - t0
+
+    # Round 1: cluster_scoped (= acluster_retrieve)
+    t0 = time.time()
+    round1 = cluster_scoped_search(query, all_episodes, clusters)
+
+    if not round1:
+        # Fallback: hybrid + rerank
+        fb_eps, fb_time = hybrid_search(query, top_k=top_k * 2)
+        fb_reranked, rr_time = rerank(query, fb_eps)
+        fb_reranked = fb_reranked[:top_k]
+        timing["fallback_hybrid"] = fb_time
+        timing["fallback_rerank"] = rr_time
+        timing["total"] = time.time() - t_total
+        return AgenticResult(
+            episodes=fb_reranked,
+            method="fallback_hybrid",
+            timing=timing,
+        )
+
+    timing["cluster_scoped"] = time.time() - t0
+
+    # Round 1 rerank
+    t0 = time.time()
+    reranked, _ = rerank(query, round1)
+    reranked = reranked[:ROUND1_RERANK_TOP_N]
+    timing["round1_rerank"] = time.time() - t0
+
+    # Sufficiency check
+    t0 = time.time()
+    try:
+        sufficiency = check_sufficiency(query, reranked)
+    except Exception:
+        timing["sufficiency"] = time.time() - t0
+        timing["total"] = time.time() - t_total
+        return AgenticResult(
+            episodes=reranked[:top_k],
+            method="agentic (sufficiency_error)",
+            timing=timing,
+        )
+    timing["sufficiency"] = time.time() - t0
+
+    if sufficiency.get("is_sufficient", True):
+        timing["total"] = time.time() - t_total
+        return AgenticResult(
+            episodes=reranked[:top_k],
+            method="agentic (sufficient_r1)",
+            is_sufficient=True,
+            reasoning=sufficiency.get("reasoning", ""),
+            timing=timing,
+        )
+
+    # ── Round 2 ─────────────────────────────────────────────────────────
+    missing = sufficiency.get("missing_information", [])
+    key_info = sufficiency.get("key_information_found", [])
+
+    if strategy == "refined_query":
+        # FIX #1: refined_query path (1 query, 1 retrieve)
+        t0 = time.time()
+        try:
+            refined = generate_refined_query(query, reranked, missing)
+        except Exception:
+            refined = query
+        timing["refined_query_gen"] = time.time() - t0
+
+        # Round 2: hybrid_full (NOT cluster_scoped)
+        t0 = time.time()
+        r2_eps, _ = hybrid_search(refined, top_k=ROUND1_TOP_N)
+        timing["round2_search"] = time.time() - t0
+
+        # Merge: reranked + r2_unique
+        seen_ids = {ep.id for ep in reranked}
+        r2_unique = [ep for ep in r2_eps if ep.id not in seen_ids]
+
+        # Cap: len(reranked) + len(r2_kept) <= ROUND2_CAP
+        keep = max(0, ROUND2_CAP - len(reranked))
+        r2_unique = r2_unique[:keep]
+        merged = list(reranked) + r2_unique
+
+        # Final rerank
+        t0 = time.time()
+        final, _ = rerank(query, merged)
+        final = final[:top_k]
+        timing["final_rerank"] = time.time() - t0
+
+        timing["total"] = time.time() - t_total
+        return AgenticResult(
+            episodes=final,
+            method="agentic (refined_query)",
+            is_sufficient=False,
+            multi_queries=[refined],
+            reasoning=sufficiency.get("reasoning", ""),
+            timing=timing,
+        )
+
+    # else: multi_query path
+    t0 = time.time()
+    try:
+        multi_queries = generate_multi_queries(query, reranked, missing, key_info)
+    except Exception:
+        multi_queries = []
+    timing["multi_query_gen"] = time.time() - t0
+
+    if not multi_queries:
+        timing["total"] = time.time() - t_total
+        return AgenticResult(
+            episodes=reranked[:top_k],
+            method="agentic (multi_query_failed)",
+            is_sufficient=False,
+            reasoning=sufficiency.get("reasoning", ""),
+            timing=timing,
+        )
+
+    # Round 2: parallel hybrid_full per sub-query
+    t0 = time.time()
+    round2_lists = []
+    for mq in multi_queries:
+        r2_eps, _ = hybrid_search(mq, top_k=ROUND1_TOP_N)
+        round2_lists.append(r2_eps)
+    timing["round2_search"] = time.time() - t0
+
+    # FIX #2: RRF fuse Round 2 lists (was: flat extend)
+    if len(round2_lists) == 1:
+        fused = round2_lists[0]
+    else:
+        fused = rrf_fusion(*round2_lists, k=HYBRID_RRF_K)
+
+    # Merge: reranked + fused_unique (1:1 with _merge_truncate_rerank)
+    seen_ids = {ep.id for ep in reranked}
+    r2_unique = [ep for ep in fused if ep.id not in seen_ids]
+
+    # Cap
+    keep = max(0, ROUND2_CAP - len(reranked))
+    r2_unique = r2_unique[:keep]
+    merged = list(reranked) + r2_unique
+
+    # Final rerank
+    t0 = time.time()
+    final, _ = rerank(query, merged)
+    final = final[:top_k]
+    timing["final_rerank"] = time.time() - t0
+
+    timing["total"] = time.time() - t_total
+    return AgenticResult(
+        episodes=final,
+        method="agentic (multi_round)",
+        is_sufficient=False,
+        multi_queries=multi_queries,
+        reasoning=sufficiency.get("reasoning", ""),
+        timing=timing,
+    )
+
+
+
+# -- CLI ---------------------------------------------------------------
+def print_result(result: AgenticResult, query: str):
+    C_BOLD = "\033[1m"
+    C_GREEN = "\033[32m"
+    C_YELLOW = "\033[33m"
+    C_CYAN = "\033[36m"
+    C_DIM = "\033[2m"
+    C_MAGENTA = "\033[35m"
+    C_RESET = "\033[0m"
+
+    print(f"\n{C_BOLD}{'='*65}{C_RESET}")
+    if "full_agentic" in result.method or result.method.startswith("agentic"):
+        color = C_GREEN
+    elif "hybrid_agentic" in result.method:
+        color = C_CYAN
+    else:
+        color = C_YELLOW
+    print(f"{color} {result.method}{C_RESET}  {C_DIM}query: {query}{C_RESET}")
+    if result.multi_queries:
+        print(f"  {C_MAGENTA}queries: {result.multi_queries}{C_RESET}")
+    if result.reasoning:
+        print(f"  {C_DIM}reasoning: {result.reasoning[:120]}{C_RESET}")
+    t = result.timing
+    parts = [f"{k}={v:.2f}s" for k, v in t.items() if k != "total"]
+    print(f"  {C_DIM}{' | '.join(parts)} = {t.get('total', 0):.2f}s{C_RESET}")
+    print(f"{C_BOLD}{'='*65}{C_RESET}\n")
+
+    for i, ep in enumerate(result.episodes):
+        bar = "\u2588" * int(ep.score * 20) if ep.score > 0 else ""
+        print(f"  {C_BOLD}[{i+1}]{C_RESET} {C_GREEN}score={ep.score:.4f}{C_RESET} {bar}")
+        print(f"       {C_BOLD}subject:{C_RESET} {ep.subject[:80]}")
+        print(f"       {C_DIM}summary: {ep.summary[:200]}{C_RESET}")
+        print()
+
+
+# -- Level 2: hybrid_agentic_search -----------------------------------
+async def hybrid_agentic_search(query: str, top_k: int = 5, strategy: str = "multi_query") -> AgenticResult:
+    """
+    Level 2: hybrid + rerank + LLM sufficiency + optional multi_query.
+    No cluster expansion. ~5-15s typical.
+    """
+    timing = {}
+    t_total = time.time()
+
+    # Round 1: hybrid + rerank
+    t0 = time.time()
+    eps, _ = hybrid_search(query, top_k=ROUND1_TOP_N)
+    if not eps:
+        timing["total"] = time.time() - t_total
+        return AgenticResult(episodes=[], method="hybrid_agentic (empty)", timing=timing)
+    reranked, _ = rerank(query, eps)
+    reranked = reranked[:ROUND1_RERANK_TOP_N]
+    timing["hybrid_rerank"] = time.time() - t0
+
+    # Sufficiency check
+    t0 = time.time()
+    try:
+        sufficiency = check_sufficiency(query, reranked)
+    except Exception:
+        timing["sufficiency"] = time.time() - t0
+        timing["total"] = time.time() - t_total
+        return AgenticResult(
+            episodes=reranked[:top_k],
+            method="hybrid_agentic (sufficiency_error)",
+            timing=timing,
+        )
+    timing["sufficiency"] = time.time() - t0
+
+    if sufficiency.get("is_sufficient", True):
+        timing["total"] = time.time() - t_total
+        return AgenticResult(
+            episodes=reranked[:top_k],
+            method="hybrid_agentic (sufficient_r1)",
+            is_sufficient=True,
+            reasoning=sufficiency.get("reasoning", ""),
+            timing=timing,
+        )
+
+    # -- Round 2 --
+    missing = sufficiency.get("missing_information", [])
+    key_info = sufficiency.get("key_information_found", [])
+
+    if strategy == "refined_query":
+        t0 = time.time()
+        try:
+            refined = generate_refined_query(query, reranked, missing)
+        except Exception:
+            refined = query
+        timing["refined_query_gen"] = time.time() - t0
+
+        t0 = time.time()
+        r2_eps, _ = hybrid_search(refined, top_k=ROUND1_TOP_N)
+        timing["round2_search"] = time.time() - t0
+
+        seen_ids = {ep.id for ep in reranked}
+        r2_unique = [ep for ep in r2_eps if ep.id not in seen_ids]
+        keep = max(0, ROUND2_CAP - len(reranked))
+        r2_unique = r2_unique[:keep]
+        merged = list(reranked) + r2_unique
+
+        t0 = time.time()
+        final, _ = rerank(query, merged)
+        final = final[:top_k]
+        timing["final_rerank"] = time.time() - t0
+
+        timing["total"] = time.time() - t_total
+        return AgenticResult(
+            episodes=final,
+            method="hybrid_agentic (refined_query)",
+            is_sufficient=False,
+            multi_queries=[refined],
+            reasoning=sufficiency.get("reasoning", ""),
+            timing=timing,
+        )
+
+    # multi_query path
+    t0 = time.time()
+    try:
+        multi_queries = generate_multi_queries(query, reranked, missing, key_info)
+    except Exception:
+        multi_queries = []
+    timing["multi_query_gen"] = time.time() - t0
+
+    if not multi_queries:
+        timing["total"] = time.time() - t_total
+        return AgenticResult(
+            episodes=reranked[:top_k],
+            method="hybrid_agentic (multi_query_failed)",
+            is_sufficient=False,
+            reasoning=sufficiency.get("reasoning", ""),
+            timing=timing,
+        )
+
+    # Parallel hybrid per sub-query
+    t0 = time.time()
+    round2_lists = []
+    for mq in multi_queries:
+        r2_eps, _ = hybrid_search(mq, top_k=ROUND1_TOP_N)
+        round2_lists.append(r2_eps)
+    timing["round2_search"] = time.time() - t0
+
+    # RRF fuse
+    if len(round2_lists) == 1:
+        fused = round2_lists[0]
+    else:
+        fused = rrf_fusion(*round2_lists, k=HYBRID_RRF_K)
+
+    # Merge
+    seen_ids = {ep.id for ep in reranked}
+    r2_unique = [ep for ep in fused if ep.id not in seen_ids]
+    keep = max(0, ROUND2_CAP - len(reranked))
+    r2_unique = r2_unique[:keep]
+    merged = list(reranked) + r2_unique
+
+    # Final rerank
+    t0 = time.time()
+    final, _ = rerank(query, merged)
+    final = final[:top_k]
+    timing["final_rerank"] = time.time() - t0
+
+    timing["total"] = time.time() - t_total
+    return AgenticResult(
+        episodes=final,
+        method="hybrid_agentic (multi_round)",
+        is_sufficient=False,
+        multi_queries=multi_queries,
+        reasoning=sufficiency.get("reasoning", ""),
+        timing=timing,
+    )
+
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Memory Search Pipeline (3 modes)")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--top-k", type=int, default=5)
+    parser.add_argument("--compare", "-c", action="store_true", help="Show all 3 modes side by side")
+    parser.add_argument(
+        "--mode", "-m",
+        choices=["hybrid", "hybrid_agentic", "agentic"],
+        default="hybrid_agentic",
+        help="hybrid(~2s) | hybrid_agentic(~5-15s) | agentic(~40s)",
+    )
+    parser.add_argument(
+        "--strategy",
+        choices=["multi_query", "refined_query"],
+        default="multi_query",
+    )
+    args = parser.parse_args()
+
+    if args.mode == "hybrid":
+        t0 = time.time()
+        eps, _ = hybrid_search(args.query, top_k=10)
+        reranked, _ = rerank(args.query, eps)
+        result = AgenticResult(
+            episodes=reranked[:args.top_k],
+            method="hybrid+rerank",
+            timing={"total": time.time() - t0},
+        )
+        print_result(result, args.query)
+
+    elif args.mode == "hybrid_agentic":
+        result = asyncio.run(hybrid_agentic_search(args.query, top_k=args.top_k, strategy=args.strategy))
+        print_result(result, args.query)
+
+    elif args.mode == "agentic":
+        result = asyncio.run(agentic_search(args.query, top_k=args.top_k, strategy=args.strategy))
+        print_result(result, args.query)
+
+    if args.compare:
+        print(f"\n{'='*65}")
+        print(f"  --- Compare: all 3 modes ---")
+        print(f"{'='*65}")
+
+        # Mode 1: hybrid+rerank
+        t0 = time.time()
+        eps, _ = hybrid_search(args.query, top_k=10)
+        reranked, _ = rerank(args.query, eps)
+        dt1 = time.time() - t0
+        print(f"\n  [Mode 1: hybrid+rerank] ({dt1:.1f}s)")
+        for i, ep in enumerate(reranked[:args.top_k]):
+            print(f"    [{i+1}] score={ep.score:.4f} | {ep.subject[:65]}")
+
+        # Mode 2: hybrid_agentic
+        t0 = time.time()
+        result2 = asyncio.run(hybrid_agentic_search(args.query, top_k=args.top_k))
+        dt2 = time.time() - t0
+        print(f"\n  [Mode 2: hybrid_agentic] ({dt2:.1f}s) sufficient={result2.is_sufficient}")
+        if result2.multi_queries:
+            print(f"    queries: {result2.multi_queries}")
+        for i, ep in enumerate(result2.episodes):
+            print(f"    [{i+1}] score={ep.score:.4f} | {ep.subject[:65]}")
+
+        # Mode 3: full agentic
+        t0 = time.time()
+        result3 = asyncio.run(agentic_search(args.query, top_k=args.top_k))
+        dt3 = time.time() - t0
+        print(f"\n  [Mode 3: agentic] ({dt3:.1f}s) sufficient={result3.is_sufficient}")
+        if result3.multi_queries:
+            print(f"    queries: {result3.multi_queries}")
+        for i, ep in enumerate(result3.episodes):
+            print(f"    [{i+1}] score={ep.score:.4f} | {ep.subject[:65]}")
+
+        print(f"\n  Timing: hybrid={dt1:.1f}s | hybrid_agentic={dt2:.1f}s | agentic={dt3:.1f}s")
+
+
+if __name__ == "__main__":
+    main()