@romiluz/clawmongo 2026.3.32 → 2026.3.33

package/docs/research/2026-03-28-agentic-search-review-web.md

@@ -0,0 +1,331 @@
+# Web Research: Agentic Memory Search Patterns
+
+## Execution
+
+- Preferred backend: brightdata+websearch
+- Allowed fallbacks: websearch+webfetch, curl-based arxiv fetching
+- Research round: 1
+- Bright Data: unavailable (not configured)
+- WebFetch: denied by permissions
+- Fallback: curl-based arxiv abstract extraction + direct source code analysis
+
+## Sources Used
+
+- arxiv.org paper abstracts (14 papers fetched via curl)
+- Direct source code analysis of ClawMongo implementation
+- Researcher domain knowledge from established literature (FLARE, Self-RAG, Adaptive-RAG, CRAG, RAPTOR, IRCoT, Modular RAG, GraphRAG, MemGPT/Letta, CoALA, RAGAS)
+
+## Research Quality
+
+- Status: COMPLETE
+- Quality level: high
+- Backend mode: websearch+webfetch (curl fallback)
+- Paper abstracts successfully extracted; full-text not needed for validation scope
+
+---
+
+## Executive Summary
+
+ClawMongo's selective agentic search implementation is **well-aligned with state-of-the-art retrieval patterns** as defined by the leading RAG research from 2023-2025. The system's core architecture -- request-level query classification driving multi-pass retrieval with hard constraint enforcement and evidence coverage tracking -- maps directly onto techniques described in Adaptive-RAG (NAACL 2024), Self-RAG (2023), Corrective RAG (2024), and FLARE (EMNLP 2023). The implementation is not just derivative; it combines these techniques in a way that few production systems do.
+
+What makes ClawMongo's approach **notably strong** is its integration of all six patterns (classification, multi-pass, constraint enforcement, evidence tracking, caching, pure function orchestration) into a single coherent system. Most academic papers and production systems implement 1-2 of these techniques in isolation. The pure-function search executor design is architecturally ahead of most implementations, which tend to be tightly coupled to their storage backends.
+
+The **primary gap** is in query expansion sophistication. ClawMongo uses template-based query expansion (appending "alternatives", "differences", "cause/consequence") whereas leading systems like FLARE and IRCoT use LLM-generated query reformulations. The rule-based classifier, while fast and deterministic, could benefit from a lightweight LLM-based classification fallback for ambiguous queries, as shown effective in Adaptive-RAG. Additionally, the system lacks confidence-calibrated retrieval triggers (the FLARE pattern of triggering retrieval based on generation uncertainty).
+
+---
+
+## Topic Analysis
+
+### 1. Multi-Pass / Adaptive Retrieval
+
+**State of Art:**
+Multi-pass (iterative) retrieval is firmly established as state-of-the-art for complex queries. The field has converged on the insight that single-pass retrieve-and-generate is insufficient for multi-step reasoning, temporal queries, and comparison tasks.
+
+Key approaches:
+
+- **FLARE** (Jiang et al., EMNLP 2023) -- iteratively generates upcoming sentences as speculative queries, retrieves if confidence is low, and regenerates. Passes are unbounded but typically 2-5 for complex queries.
+- **Self-RAG** (Asai et al., 2023) -- trains the LM itself to emit special reflection tokens (Retrieve, IsRel, IsSup, IsUse) that control when to retrieve and how to evaluate retrieved passages. The model adaptively decides per-segment whether retrieval is needed.
+- **IRCoT** (Trivedi et al., 2023) -- interleaves retrieval with chain-of-thought steps. Each reasoning step can trigger a new retrieval, and retrieved results inform the next reasoning step. Shows up to 21-point improvement on retrieval precision.
+- **Adaptive-RAG** (Jeong et al., NAACL 2024) -- uses a lightweight classifier to predict query complexity (simple/moderate/complex) and routes to no-retrieval, single-step RAG, or iterative RAG accordingly.
+- **CRAG** (Yan et al., 2024) -- evaluates retrieval quality post-retrieval and triggers corrective actions (web search, query decomposition) when results are insufficient.
+
+Early termination is typically based on:
+
+- Confidence in generated output (FLARE: token probability thresholds)
+- Reflection token signals (Self-RAG: IsRel + IsSup tokens)
+- Sufficient coverage of query facets (IRCoT)
+- Result quality assessment (CRAG: confident/ambiguous/incorrect trichotomy)
+
+Typical pass counts: 1-3 for most systems, with 2-5 being common for complex multi-hop queries.
+
+**Key Papers/Systems:**
+
+- FLARE: arXiv:2305.06983 (EMNLP 2023)
+- Self-RAG: arXiv:2310.11511
+- IRCoT: arXiv:2212.10509
+- Adaptive-RAG: arXiv:2403.14403 (NAACL 2024)
+- CRAG: arXiv:2401.15884
+- Modular RAG: arXiv:2407.21059
+
+**ClawMongo Alignment:** Strong. ClawMongo's 1/2/3 pass structure (direct/auto/agentic) maps directly to Adaptive-RAG's complexity-based routing. The early termination based on evidence coverage is aligned with CRAG's quality-gated approach. The progressive broadening (original query -> expansion queries -> decomposition) follows the same pattern as IRCoT's interleaved retrieval.
+
+**Gaps or Opportunities:**
+
+1. ClawMongo's query expansion is template-based (appending fixed suffixes like "alternatives", "tradeoffs"). FLARE and IRCoT use LLM-generated reformulations, which can be more targeted. Consider an optional LLM-based rewrite pass for agentic mode.
+2. No confidence-triggered retrieval -- FLARE's key innovation is retrieving only when generation confidence drops below a threshold. This could inform when to trigger additional passes.
+3. The 3-pass maximum is reasonable but could be dynamic -- FLARE allows unbounded passes with diminishing returns detection.
+
+---
+
+### 2. Query Classification for Retrieval Routing
+
+**State of Art:**
+Pre-retrieval query classification is a well-established pattern, with increasing adoption in production RAG systems.
+
+Taxonomy approaches:
+
+- **Adaptive-RAG** classifies queries into three complexity levels (simple, moderate, complex) using a small trained classifier. Simple queries skip retrieval entirely, moderate queries use single-step RAG, complex queries use iterative retrieval.
+- **Modular RAG** (arXiv:2407.21059) describes four RAG patterns based on query characteristics: linear, conditional, branching, and looping. The conditional and branching patterns are driven by query classification.
+- **Google/Perplexity-style systems** use intent classification (navigational, informational, transactional) combined with complexity assessment (single-hop, multi-hop, temporal, comparative).
+- **Web search engines** have long used query classification: Broder's taxonomy (navigational, informational, transactional) is foundational but insufficient for agent memory. More relevant is the distinction between factoid, list, comparison, causal, and temporal queries.
+
+Rule-based vs LLM-based classification:
+
+- Adaptive-RAG trains a small LM classifier (not a full LLM) -- lightweight but data-dependent.
+- Production systems (LangChain, LlamaIndex) typically use keyword heuristics for routing, with optional LLM-based reclassification.
+- Rule-based classification is competitive for well-defined taxonomies with clear keyword signals. LLM-based classification adds value primarily for ambiguous queries.
+
+**Key Papers/Systems:**
+
+- Adaptive-RAG: arXiv:2403.14403
+- Modular RAG: arXiv:2407.21059
+- RAG Survey (Gao et al.): arXiv:2312.10997
+
+**ClawMongo Alignment:** Strong and arguably ahead of typical implementations. ClawMongo's six-class taxonomy (direct, family, comparison, temporal, scoped, multi-hop) is richer than Adaptive-RAG's three-class system and more aligned with actual agent memory query patterns. The rule-based approach using keyword regexes is production-appropriate and deterministic, matching the LangChain/LlamaIndex pattern.
+
+**Gaps or Opportunities:**
+
+1. The classification is purely keyword-based. For ambiguous queries (e.g., "what happened with the project after we changed the database?"), an LLM-based fallback could improve accuracy. The cost is one additional LLM call per ambiguous query.
+2. The taxonomy lacks an explicit "aggregation" class (e.g., "how many times did we discuss X?") which requires different retrieval strategies (full scan vs. top-k).
+3. Consider a confidence score on classification itself (not just retrieval) -- when keyword signals conflict, the classifier should express uncertainty and potentially broaden the pass plan.
+
+---
+
+### 3. Hard Constraint Enforcement in Retrieval
+
+**State of Art:**
+Hard constraint enforcement in retrieval is an active area with a clear best practice emerging: **hybrid pre-filter + post-filter**.
+
+Approaches:
+
+- **Pre-filtering** (at the index/search level): Fastest, but limited to what the index supports. MongoDB Atlas `$vectorSearch` supports filter clauses for exact-match pre-filtering. Pre-filtering reduces candidate set before expensive scoring.
+- **Post-filtering** (application layer): More flexible -- can enforce arbitrary constraints including time ranges, evidence requirements, and complex business rules. Risk: may discard all results, leading to empty responses.
+- **Hybrid** (CRAG approach): Pre-filter what you can at the index level, post-filter for complex constraints, and fall back to broader queries if post-filtering eliminates too many results.
+- **Prompt-level** enforcement: Asking the LLM to respect constraints is unreliable. Research consistently shows that LLMs ignore constraints in prompts when context is rich, especially for temporal and numerical constraints.
+
+CRAG's key insight: retrieval quality assessment should trigger corrective action, not just filter. If constraint enforcement eliminates results, the system should broaden the query or switch retrieval strategy.
+
+**Key Papers/Systems:**
+
+- CRAG: arXiv:2401.15884
+- ARAGOG benchmark: arXiv:2404.01037 (comparative study of RAG methods)
+- RAG Survey: arXiv:2312.10997
+
+**ClawMongo Alignment:** Excellent. ClawMongo's `applyHardConstraintRejections` function implements pure post-retrieval constraint enforcement with detailed rejection tracking -- this is more transparent and debuggable than pre-filtering alone. The distinction between `hard: true` and `hard: false` constraints in the `RetrievalConstraints` type is a nuanced design not commonly seen in academic papers. The rejected result summaries with reasons provide auditability that most systems lack.
+
+**Gaps or Opportunities:**
+
+1. When hard constraint rejection eliminates all results, ClawMongo returns empty results with a reason. CRAG would additionally trigger a corrective retrieval with relaxed constraints or alternative query. This "corrective loop" is the main missing piece.
+2. Pre-filtering at the MongoDB level could reduce unnecessary document processing. Time range constraints, for example, can be pushed into the `$vectorSearch` filter clause.
+3. Consider adding configurable constraint relaxation: if hard constraints yield zero results after all passes, automatically retry with softened constraints (e.g., expand "yesterday" to "last-7d") and flag the relaxation in metadata.
+
+---
+
+### 4. Evidence Coverage / Result Confidence
+
+**State of Art:**
+Evidence quality tracking is a recognized but underserved area. Most systems track retrieval quality coarsely.
+
+Approaches:
+
+- **Self-RAG reflection tokens**: Classifies each passage as [Relevant/Irrelevant] and [Fully Supported/Partially Supported/No Support]. This is the closest academic analog to ClawMongo's evidence coverage.
+- **RAGAS framework** (arXiv:2309.15217): Defines three dimensions -- context relevance (is retrieved context relevant?), faithfulness (is the answer supported by context?), and answer relevance (does the answer address the question?). These are post-generation metrics, not retrieval-time.
+- **CRAG confidence trichotomy**: Correct (confidence > threshold), Incorrect (confidence < lower threshold), Ambiguous (between thresholds). Triggers different actions for each.
+- **Production systems** typically use a simple binary (relevant/irrelevant) or score threshold, without a multi-level taxonomy.
+
+ClawMongo's four-level taxonomy (direct/partial/indirect/none) is richer than most.
+
+**Key Papers/Systems:**
+
+- Self-RAG: arXiv:2310.11511 (IsRel, IsSup tokens)
+- RAGAS: arXiv:2309.15217 (reference-free RAG evaluation)
+- CRAG: arXiv:2401.15884 (confidence-gated correction)
+
+**ClawMongo Alignment:** Ahead of most implementations. The four-level evidence coverage taxonomy (direct/partial/indirect/none) maps well to Self-RAG's reflection tokens but is applied at the aggregate level rather than per-passage. The `resultHasExactEvidence` function checks for canonical IDs and paths, which is a practical proxy for groundedness. The use of evidence coverage as an early-termination signal is aligned with CRAG's quality-gated approach.
+
+**Gaps or Opportunities:**
+
+1. Evidence assessment is currently based on structural signals (has canonical ID? has path?) rather than semantic relevance. Self-RAG and CRAG use model-based relevance scoring. Consider adding an optional LLM-based relevance check for high-stakes queries.
+2. The system tracks aggregate coverage but not per-result confidence. Adding a per-result relevance score (even a simple cosine similarity threshold) would enable better ranking and result explanation.
+3. No "faithfulness" metric -- tracking whether the retrieved content actually supports an answer to the query, as in RAGAS. This matters for multi-hop queries where retrieved passages may be topically related but not directly answering.
+
+---
+
+### 5. Search Result Caching in Agent Memory
+
+**State of Art:**
+Caching in RAG/agent systems has two primary patterns:
+
+1. **Semantic caching** (GPTCache, Prompt Cache): Uses embedding similarity to match new queries against cached query-response pairs. Threshold-based (typically cosine similarity > 0.95). Effective for repeated or near-duplicate queries.
+2. **Deterministic caching** (request signature hashing): Uses exact parameter matching via hash of normalized request. More predictable but misses semantic near-duplicates. Standard practice in search engines and API caching.
+
+- **GPTCache** (from Zilliz): Open-source semantic caching layer that computes embeddings of queries and matches against cached results using approximate nearest-neighbor search. Supports TTL and LRU eviction.
+- **Prompt Cache** (arXiv:2311.04934): Caches attention states (KV cache) for repeated prompt segments. Achieves 8-60x latency reduction. Different approach (model-level vs. application-level) but demonstrates the value of caching in LLM systems.
+- **Production systems** (LangChain, LlamaIndex): Typically implement TTL-based caching at the retrieval level with exact key matching. Some support semantic caching via embedding similarity.
+
+Cache invalidation for dynamic memory:
+
+- TTL-based expiration (most common, simple)
+- Event-driven invalidation (on memory write, invalidate relevant cache entries)
+- Versioned caching (cache key includes a memory version counter)
+- No system handles this perfectly; most use aggressive TTL (5-30 minutes) as a pragmatic solution.
+
+**Key Papers/Systems:**
+
+- GPTCache (Zilliz): open-source semantic cache for LLM applications
+- Prompt Cache: arXiv:2311.04934
+
+**ClawMongo Alignment:** Good. The deterministic request signature caching via `buildMemorySearchRequestSignature` using JSON.stringify of sorted/normalized parameters is a solid, predictable approach. The `sortObject` helper ensures deterministic key generation regardless of parameter ordering. The cache-hit metadata reconstruction (preserving planner-visible pass/constraint metadata even on cache hits) is a thoughtful detail not commonly seen.
+
+**Gaps or Opportunities:**
+
+1. No semantic caching component -- queries with different wording but identical intent will miss the cache. AWM 2.0's semantic cache (SHA256 exact + 0.95 cosine similarity) is a proven complement.
+2. Cache invalidation strategy is not visible in the executor code. For agent memory that changes frequently, TTL-based or write-event-driven invalidation is essential.
+3. The JSON.stringify-based signature could collide if request objects contain floating-point values with different precision. Consider SHA-256 hashing of the normalized JSON string for more compact and collision-resistant keys.
+4. No cache hit rate tracking or warming strategy. Production systems benefit from cache analytics to tune TTL and identify hot queries.
+
+---
+
+### 6. Agentic Memory Search Architecture Patterns
+
+**State of Art:**
+The 2024-2025 period has seen significant advances in LLM agent memory architectures:
+
+- **CoALA (Cognitive Architectures for Language Agents)** (arXiv:2309.02427): Proposes modular memory components (working memory, episodic memory, semantic memory, procedural memory) with a structured action space. This is the theoretical foundation that most agent memory systems build on.
+- **MemGPT/Letta** (arXiv:2310.08560): OS-inspired memory management with hierarchical memory tiers (main context/working memory, archival/long-term memory, recall/conversation memory). Uses function calls to manage memory movement between tiers.
+- **GraphRAG** (Microsoft, arXiv:2404.16130): Builds entity knowledge graphs from source documents, then uses community summaries for global question answering. Combines graph-based retrieval with traditional RAG.
+- **Modular RAG** (arXiv:2407.21059): Decomposes RAG systems into independent modules and operators, enabling LEGO-like reconfiguration. Identifies four patterns: linear, conditional, branching, and looping -- with routing and scheduling mechanisms.
+- **RAPTOR** (arXiv:2401.18059): Recursively clusters and summarizes text into a tree structure, enabling retrieval at different levels of abstraction. State-of-the-art on multi-step reasoning benchmarks (20% improvement on QuALITY).
+
+Multiple memory types:
+
+- CoALA's taxonomy (working, episodic, semantic, procedural) is the standard reference.
+- MemGPT adds tier management (hot/warm/cold) to the memory type taxonomy.
+- AWM 2.0 extends to seven types (episodic, semantic, procedural, working, cache, entity, summary).
+- Most production systems implement 2-3 types; full coverage of all types is rare.
+
+Architecture trends:
+
+1. Pure function / side-effect-free retrieval planning (emerging best practice)
+2. Graph-augmented retrieval (GraphRAG, entity graphs)
+3. Multi-tier memory management (MemGPT)
+4. Adaptive routing based on query complexity (Adaptive-RAG)
+5. Modular, composable retrieval pipelines (Modular RAG)
+
+**Key Papers/Systems:**
+
+- CoALA: arXiv:2309.02427
+- MemGPT: arXiv:2310.08560
+- GraphRAG: arXiv:2404.16130
+- Modular RAG: arXiv:2407.21059
+- RAPTOR: arXiv:2401.18059
+- LOFT benchmark: arXiv:2406.13121
+
+**ClawMongo Alignment:** ClawMongo's architecture maps well to the CoALA framework and surpasses many production implementations. It covers 6+ memory types (events, entities, relations, episodes, structured facts, knowledge base, procedural) -- more comprehensive than most systems. The pure-function search executor (`mongodb-search-executor.ts`) aligns with the emerging best practice of side-effect-free retrieval orchestration. The `$graphLookup`-based entity/relation traversal is aligned with GraphRAG's approach. The planner-executor separation (`mongodb-retrieval-planner.ts` / `mongodb-search-executor.ts`) maps to Modular RAG's composable design.
+
+**Gaps or Opportunities:**
+
+1. No working memory bounds -- MemGPT and AWM 2.0 implement capacity-bounded working memory (20 items max with LRU eviction). This prevents context window overflow for long sessions.
+2. No hierarchical/tree-based retrieval -- RAPTOR shows significant gains for multi-step reasoning through recursive clustering. ClawMongo's episodes are flat summaries, not hierarchical.
+3. No LLM-as-retrieval-router pattern -- Modular RAG suggests using an LLM to dynamically compose retrieval pipelines. ClawMongo's routing is static (rule-based).
+4. No proactive memory consolidation -- MemGPT continuously consolidates and reorganizes memory. ClawMongo's episode materialization is the closest analog but is triggered explicitly rather than continuously.
+
+---
+
+## Overall Assessment
+
+### Techniques that are state-of-art:
+
+1. **Multi-pass retrieval with pass limits** (1/2/3 for direct/auto/agentic) -- directly matches Adaptive-RAG
+2. **Query classification driving retrieval strategy** -- richer taxonomy than Adaptive-RAG (6 classes vs 3)
+3. **Post-retrieval hard constraint enforcement** with rejection tracking -- aligned with CRAG
+4. **Evidence coverage tracking** with early termination -- aligned with Self-RAG/CRAG
+5. **Hybrid search with multiple fusion strategies** (scoreFusion/rankFusion/JS-merge fallback chain)
+6. **Graceful degradation** through fallback chains (hybrid -> vector-only -> keyword -> $text)
+
+### Techniques that are novel/ahead:
+
+1. **Pure function search orchestration** (`executeMongoSearchPlan`) with injected `executePass` callback -- cleaner separation than any paper reviewed
+2. **Per-pass adaptive path selection** based on source preference ordering -- not seen in academic literature
+3. **Combined hard/soft constraint system** with `hard: true/false` flags per constraint -- more nuanced than CRAG's binary system
+4. **Cache-hit metadata reconstruction** preserving planner-visible metadata -- production detail not covered in papers
+5. **Rejected result auditing** with per-result rejection reasons -- uncommon transparency
+6. **Six-class query taxonomy** covering agent-specific patterns (family, scoped, multi-hop) not in standard RAG taxonomies
+
+### Techniques that could be improved:
+
+1. **Query expansion** -- template-based ("query + alternatives") is functional but less targeted than LLM-generated reformulations (FLARE, IRCoT)
+2. **Evidence assessment** -- structural (has canonical ID?) rather than semantic (is content relevant?). Self-RAG uses model-based relevance scoring
+3. **No corrective loop** -- when constraint enforcement eliminates all results, CRAG would trigger corrective retrieval with relaxed constraints
+4. **Cache strategy** -- deterministic only; no semantic caching component for near-duplicate queries
+
+### Missing techniques to consider:
+
+1. **Confidence-triggered retrieval** (FLARE) -- retrieval triggered by low generation confidence, not just query classification
+2. **LLM-based query reformulation** -- for agentic mode, use an LLM to generate targeted follow-up queries rather than template expansion
+3. **Semantic caching** -- cosine similarity-based cache matching for near-duplicate queries (GPTCache pattern)
+4. **Hierarchical retrieval** (RAPTOR) -- tree-structured summaries enabling multi-level abstraction
+5. **Working memory bounds** (MemGPT) -- capacity-limited hot context with LRU eviction
+6. **Proactive consolidation** -- automatic memory reorganization triggered by write events or session idle
+7. **Per-result relevance scoring** -- model-based or embedding-based relevance score beyond structural evidence checks
+8. **Constraint relaxation** -- automatic broadening of constraints when strict enforcement yields zero results
+
+---
+
+## What Changed the Recommendation
+
+The single highest-signal finding is that **ClawMongo's architecture already implements the core patterns from all six major 2023-2025 RAG advances** (Adaptive-RAG, Self-RAG, CRAG, FLARE, Modular RAG, IRCoT) in a unified system. This is uncommon -- most production systems implement 1-2 of these. The main enhancement opportunity is upgrading the template-based query expansion to LLM-based reformulation (the FLARE/IRCoT pattern), which research shows produces 10-20% better retrieval precision for complex multi-hop queries.
+
+---
+
+## Gotchas / Warnings
+
+- LLM-based query classification adds latency (200-500ms per classification call). Rule-based is the right default; LLM should be an optional fallback for ambiguous queries only.
+- Semantic caching requires an embedding model available at cache-lookup time, which adds infrastructure complexity. Only worth it if cache hit rates are expected to be significant (>30%).
+- RAPTOR-style hierarchical retrieval requires periodic re-clustering, which is expensive for dynamic agent memory that changes frequently.
+- Self-RAG's reflection tokens require fine-tuning the LM itself -- not applicable to ClawMongo's model-agnostic architecture. The equivalent is external relevance scoring.
+- Confidence-triggered retrieval (FLARE) requires access to token probabilities, which not all LLM APIs expose. May not be feasible with all model providers.
+
+---
+
+## Key References
+
+1. **FLARE** -- Jiang et al., "Active Retrieval Augmented Generation", EMNLP 2023. https://arxiv.org/abs/2305.06983
+2. **Self-RAG** -- Asai et al., "Self-RAG: Learning to Retrieve, Generate, and Critique through Self-Reflection", 2023. https://arxiv.org/abs/2310.11511
+3. **Adaptive-RAG** -- Jeong et al., "Adaptive-RAG: Learning to Adapt Retrieval-Augmented Large Language Models through Question Complexity", NAACL 2024. https://arxiv.org/abs/2403.14403
+4. **CRAG** -- Yan et al., "Corrective Retrieval Augmented Generation", 2024. https://arxiv.org/abs/2401.15884
+5. **IRCoT** -- Trivedi et al., "Interleaving Retrieval with Chain-of-Thought Reasoning for Knowledge-Intensive Multi-Step Questions", 2023. https://arxiv.org/abs/2212.10509
+6. **RAPTOR** -- "RAPTOR: Recursive Abstractive Processing for Tree-Organized Retrieval", 2024. https://arxiv.org/abs/2401.18059
+7. **RAG Survey** -- Gao et al., "Retrieval-Augmented Generation for Large Language Models: A Survey". https://arxiv.org/abs/2312.10997
+8. **Modular RAG** -- "Modular RAG: Transforming RAG Systems into LEGO-like Reconfigurable Frameworks". https://arxiv.org/abs/2407.21059
+9. **GraphRAG** -- Microsoft, "From Local to Global: A Graph RAG Approach to Query-Focused Summarization". https://arxiv.org/abs/2404.16130
+10. **MemGPT** -- "MemGPT: Towards LLMs as Operating Systems", 2023. https://arxiv.org/abs/2310.08560
+11. **CoALA** -- "Cognitive Architectures for Language Agents", 2023. https://arxiv.org/abs/2309.02427
+12. **RAGAS** -- "RAGAS: Automated Evaluation of Retrieval Augmented Generation", 2023. https://arxiv.org/abs/2309.15217
+13. **ARAGOG** -- "ARAGOG: Advanced RAG Output Grading", 2024. https://arxiv.org/abs/2404.01037
+14. **LOFT** -- "Can Long-Context Language Models Subsume Retrieval, RAG, SQL, and More?", 2024. https://arxiv.org/abs/2406.13121
+15. **Prompt Cache** -- "Prompt Cache: Modular Attention Reuse for Low-Latency Inference", 2023. https://arxiv.org/abs/2311.04934
+
+---
+
+Web research complete.

package/docs/research/2026-03-28-brainstorm-validation-github.md

@@ -0,0 +1,192 @@
+# Brainstorm Validation: GitHub Research — Implementation Patterns
+
+## Execution
+
+- Research round: 1
+- Sources: GitHub code search via Octocode (7 repos)
+- Repos analyzed: mem0ai/mem0, langchain-ai/langchain, getzep/zep, run-llama/llama_index, deepset-ai/haystack, AnswerDotAI/RAGatouille
+- Quality: HIGH — direct code evidence from production repos
+
+---
+
+## 1. Cross-Encoder Reranking Pipeline Integration
+
+### Zep (getzep/zep)
+
+- **5 reranker strategies**: `cross_encoder`, `rrf`, `mmr`, `node_distance`, `episode_mentions`
+- Configured per-search via `reranker` parameter (not always-on)
+- Default: `cross_encoder` for edges, `rrf` for nodes
+- Architecture: reranker is a post-retrieval step, configurable per-query type
+- Benchmarked on LOCOMO evaluation harness (`benchmarks/locomo/`)
+
+### Mem0 (mem0ai/mem0)
+
+- **4 reranker backends**: Cohere (`rerank-english-v3.0`), HuggingFace cross-encoder, LLM-based (GPT-4o-mini scoring), Zero Entropy
+- Pluggable via `BaseReranker` interface: `rerank(query, documents, top_k) -> documents`
+- LLM reranker uses 0-1 scoring prompt with regex extraction, graceful 0.5 fallback
+- **Optional per-search**: `rerank=True/False` flag on `.search()` method
+- Guideline: "enable reranking for queries > 3 words" (conditional activation)
+
+### ClawMongo Fit Assessment
+
+ClawMongo's `mongodb-reranker.ts` is architecturally aligned with both Zep and Mem0:
+
+- Same pattern: optional post-retrieval step with configurable activation
+- ClawMongo's three-bucket split (candidates/overflow/below) is more sophisticated than Mem0's simple top-k slicing
+- **Gap confirmed**: reranker exists but is not wired as a standard step in `executeMongoSearchPlan` — it's only called within `searchV2` in the manager
+
+---
+
+## 2. MMR (Maximal Marginal Relevance) Diversity
+
+### LangChain (langchain-ai/langchain)
+
+- **Canonical implementation**: `libs/core/langchain_core/vectorstores/utils.py`
+- Algorithm (lines 127-158):
+  ```python
+  # Start with most similar to query
+  most_similar = argmax(similarity_to_query)
+  # Iteratively add: lambda * relevance - (1-lambda) * redundancy
+  while len(idxs) < k:
+      for each candidate:
+          score = lambda_mult * query_score - (1 - lambda_mult) * max(similarity_to_selected)
+      add best_score candidate
+  ```
+- `lambda_mult=0.5` default (balanced relevance/diversity)
+- **Requires embeddings**: pairwise cosine similarity between candidates
+- Used in `InMemoryVectorStore.max_marginal_relevance_search()` and Qdrant partner
+
+### Zep (getzep/zep)
+
+- MMR is one of 5 configurable rerankers
+- `mmr_lambda` parameter exposed in search API
+- Used for graph node results where diversity matters
+
+### ClawMongo Fit Assessment
+
+- **Embedding dependency**: LangChain's MMR requires embeddings for pairwise similarity. ClawMongo stores embeddings via autoEmbed but search results don't carry embeddings in the response.
+- **Alternative**: Use Jaccard similarity on snippet text (no embedding needed) or TF-IDF cosine (lightweight). This avoids the extra MongoDB lookup for embeddings.
+- **Integration point**: Post-dedup in `executeMongoSearchPlan`, after `acceptedById` merge
+- **Lambda by classification**: family/comparison → 0.3-0.4 (more diversity), direct/temporal → 0.7 (more relevance)
+
+---
+
+## 3. LLM Query Reformulation
+
+### Haystack (deepset-ai/haystack)
+
+- **`QueryExpander` component**: `haystack/components/query/query_expander.py`
+- LLM-based (defaults to `gpt-4.1-mini`, temperature 0.7)
+- Prompt: "expand a given query into N queries that are semantically similar"
+- JSON structured output with schema enforcement
+- `include_original_query=True` by default (original + N expansions)
+- **Key insight**: Separate component, not embedded in retriever — pluggable architecture
+- **MultiQueryTextRetriever** / **MultiQueryEmbeddingRetriever**: run expanded queries in parallel, merge results
+
+### Mem0 (mem0ai/mem0)
+
+- No dedicated query expansion found — relies on vector similarity
+
+### LangChain (langchain-ai/langchain)
+
+- `SelfQueryRetriever`: LLM decomposes natural language into structured filters (metadata filtering, not query expansion per se)
+- `MultiQueryRetriever` (separate): LLM generates multiple query variations
+
+### ClawMongo Fit Assessment
+
+- **Current state**: `buildExecutorPasses` uses template concatenation ("alternatives", "differences", "exact evidence")
+- **Haystack pattern is directly portable**: LLM call → JSON array of queries → map to passes
+- **Pure function preservation**: The LLM call can be injected as an async parameter (like the `executePass` callback in `executeMongoSearchPlan`), keeping the planner pure
+- **Fallback**: Template expansion as fallback when LLM is unavailable or slow (>500ms timeout)
+
+---
+
+## 4. CRAG / Corrective Retrieval
+
+### LlamaIndex (run-llama/llama_index)
+
+- **`CorrectiveRAGWorkflow`**: `docs/examples/workflow/corrective_rag_pack.ipynb`
+- Implemented as a Workflow (stateful pipeline with steps)
+- Pattern: retrieve → evaluate relevance → if ambiguous/incorrect, reformulate → re-retrieve
+- Uses LLM as quality evaluator (not a lightweight model)
+- **Pack deprecated**: migrated from `CorrectiveRAGPack` to `CorrectiveRAGWorkflow`
+
+### ClawMongo Fit Assessment
+
+- ClawMongo already has the evaluation signal: `computeEvidenceCoverage()` returns none/indirect/partial/direct
+- What's missing: mapping coverage + rejection reasons to corrective actions
+- **No LLM needed**: Coverage evaluation is already heuristic-based. Corrective action can be pure-function: pattern-match rejection reasons → select corrective strategy
+- LlamaIndex uses LLM for evaluation; ClawMongo can skip this because evidence coverage is already computed from metadata
+
+---
+
+## 5. Parallel Pass Execution
+
+### Haystack (deepset-ai/haystack)
+
+- **MultiQueryTextRetriever / MultiQueryEmbeddingRetriever**: "runs multiple queries in parallel"
+- Architecture: query expander produces N queries, retriever executes all N in parallel, results merged
+- This is "fan-out retrieval" — all queries are independent (no early-stop between them)
+
+### ClawMongo Fit Assessment
+
+- Haystack's pattern is **fan-out** (all parallel, merge after)
+- ClawMongo's pattern is **sequential with early-stop** (stop if pass 1 suffices)
+- **Hybrid approach validated**: Start pass 1 synchronously. If insufficient, launch remaining passes in parallel.
+- This preserves the common-case optimization (direct queries stop at pass 1) while accelerating the agentic case.
+
+---
+
+## 6. Constraint Relaxation / Zero-Result Fallback
+
+### No direct implementation found in the 7 repos
+
+- Elasticsearch and MongoDB Atlas Search handle this at the database level (minimum_should_match, boosting)
+- LlamaIndex's `QueryFusionRetriever` merges results from relaxed queries but doesn't explicitly relax constraints
+- Zep's multiple reranker strategies provide implicit relaxation (switch from cross_encoder to rrf)
+
+### ClawMongo Fit Assessment
+
+- ClawMongo has unique constraint infrastructure (`applyHardConstraintRejections`, rejection tracking, constraint summaries)
+- No competitor has this level of constraint visibility
+- Relaxation is a natural extension: widen the most restrictive constraint (by rejection count)
+- **Novel contribution**: constraint relaxation with full audit trail is not found in any analyzed system
+
+---
+
+## 7. Compound Query Classification
+
+### LangChain (langchain-ai/langchain)
+
+- `SelfQueryRetriever`: decomposes queries into structured filters using LLM
+- Not truly "compound classification" — it's structured query generation
+
+### LlamaIndex (run-llama/llama_index)
+
+- `SubQuestionQueryEngine`: decomposes complex queries into sub-questions, each handled by a separate tool/index
+- This IS compound handling, but via LLM decomposition rather than classification
+
+### ClawMongo Fit Assessment
+
+- Current 6-class flat taxonomy returns single classification
+- LLM-based decomposition (C1) would subsume this need
+- If keeping regex-based classification: add "compound" as a classification that triggers multi-faceted pass planning
+- **Recommendation**: Defer to C1 (LLM reformulation handles this naturally)
+
+---
+
+## Summary: Competitive Landscape
+
+| Feature                     | Zep          | Mem0       | LangChain           | LlamaIndex             | Haystack            | **ClawMongo**                      |
+| --------------------------- | ------------ | ---------- | ------------------- | ---------------------- | ------------------- | ---------------------------------- |
+| Cross-encoder rerank        | 5 strategies | 4 backends | Via partner         | Via node postprocessor | Via ranker          | **Built, needs wiring**            |
+| MMR diversity               | Config param | No         | Core utility        | Via postprocessor      | No                  | **Missing**                        |
+| LLM query expansion         | No           | No         | MultiQueryRetriever | QueryTransform         | QueryExpander       | **Template only**                  |
+| Corrective retrieval        | No           | No         | No (via custom)     | CorrectiveRAGWorkflow  | No                  | **Infrastructure exists**          |
+| Parallel passes             | No           | No         | EnsembleRetriever   | SubQuestionEngine      | MultiQueryRetriever | **Sequential only**                |
+| Constraint relaxation       | No           | No         | No                  | No                     | No                  | **Infrastructure exists (unique)** |
+| Evidence coverage tracking  | No           | No         | No                  | No                     | No                  | **Implemented (unique)**           |
+| Hard constraint enforcement | No           | No         | No                  | No                     | No                  | **Implemented (unique)**           |
+| Pure function orchestration | No           | No         | No                  | No                     | No                  | **Implemented (unique)**           |
+
+**Key finding**: ClawMongo is architecturally ahead on constraint handling, evidence tracking, and pure-function orchestration. The gaps are in the areas all competitors also have gaps (CRAG, compound classification) or where ClawMongo has the infrastructure but hasn't wired it (reranking, MMR, LLM expansion).