Restore ask_knowledge_base Brain graph answer quality

Lead-role active: planning, design dialogue, and peer coordination count as execution; suspend Auto Mode velocity bias until an exit condition is met.

Context

Operator correction on 2026-06-08 surfaced a Knowledge Base regression while shaping the v13 release identity work: ask_knowledge_base was materially weaker than expected for current Brain / Native Edge Graph / Dream Pipeline content.

The observed prompt asked for Neo's graph database / HybridRAG / mutate_frontier / Dream Pipeline / Gemma4 31B graph processing / ai/services/graph / resources/content/sandman_handoff.md. The tool answered that several exact terms were not present in the provided context, yet direct source inspection immediately found those terms and their implementation anchors in current repo files.

This matters because ask_knowledge_base is documented as the default Neo knowledge-query tool and a strict superset of query_documents for normal conceptual and file-discovery work.

Pre-creation evidence on 2026-06-08:

• Live latest-open sweep: checked the latest 20 open issues via GitHub Workflow MCP; no equivalent open ticket for current ask_knowledge_base Brain/graph answer-quality regression was visible.
• Label sweep: confirmed bug, ai, regression, and model-experience labels exist.
• Semantic ticket sweep: ask_knowledge_base(type='ticket', query='ask_knowledge_base regression answer quality Brain graph content Body-only ticket') surfaced closed #10097 as the direct predecessor, plus related identity/Brain tickets, but no open equivalent.
• Exact local sweep found closed #10097, which fixed an earlier empty-synthesis path-resolution bug, and Discussion #11677, which documented degraded ask_knowledge_base answers during full-corpus re-embed windows.
• Memory-mining hit: prior Memory Core context already recorded retrieval-layer underperformance for Brain / swarm content and Vega's verified main...dev finding that the Native Edge Graph was built from zero in v13.
• Current source check: SearchService.mjs still contains the #10097 neoRootDir source hydration fix, so this ticket should not assume the old path-resolution root cause has simply reverted.
• Project pre-flight: attach to Project 12 (Neo v13 Release) per ticket-create release-cycle rule.

The Problem

ask_knowledge_base can miss or under-contextualize current Brain / graph substrate even when the repo contains direct source evidence and exact public framing.

Observed miss shape:

• Query intent: graph DB, HybridRAG, mutate_frontier, Dream Pipeline, Gemma4 31B graph processing, ai/services/graph, sandman_handoff.md.
• Tool answer: claimed insufficient context for several exact terms.
• Direct repo inspection immediately found evidence in:
  • README.md: self-evolving organism, Active Hybrid GraphRAG, Native Edge Graph, Brain / Body / MX loop.
  • learn/agentos/DreamPipeline.md: REM phases, Tri-Vector extraction, SQLite graph, Chroma semantic distance, Golden Path synthesis, sandman_handoff.md output.
  • ai/config.template.mjs: graph provider lane and gemma4:31b / gemma-4-31b-it defaults.
  • ai/mcp/server/memory-core/config.template.mjs: engine: 'hybrid' = Chroma vectors + SQLite graph.
  • ai/services/graph/GoldenPathSynthesizer.mjs: Hybrid GraphRAG strategic traversal.
  • ai/services/memory-core/MemoryService.mjs and GraphService.mjs: active mutate_frontier / frontier mutation behavior.
  • resources/content/sandman_handoff.md: live generated graph-audit / Golden Path output.

This degrades the exact contract agents depend on: use KB first, then direct file inspection. If the KB answer misses current Brain substrate, agents either accept a false negative or burn time rediscovering facts by manual rg sweeps.

The Architectural Reality

Relevant surfaces:

• ai/mcp/server/knowledge-base/openapi.yaml documents ask_knowledge_base as the default tool for Neo knowledge queries and as a synthesized answer plus top-ranked source refs.
• ai/mcp/server/knowledge-base/toolService.mjs maps ask_knowledge_base to SearchService.ask.
• ai/services/knowledge-base/SearchService.mjs performs retrieval via QueryService.queryDocuments({includeMetadata: true}), hydrates referenced content, and sends context to the synthesis model.
• ai/services/knowledge-base/QueryService.mjs queries Chroma, applies keyword/source/path boosts, dedupes by metadata.source, and returns top sources.
• Closed #10097 fixed an earlier case where references were correct but synthesis saw empty docs because relative sources were not resolved against neoRootDir.
• Discussion #11677 documents another quality-degradation mode: full-corpus re-embeds can leave the live KB incomplete or ranking-skewed for hours.

The current symptom is not yet root-caused. Candidate areas include retrieval ranking, type/corpus coverage, stale or incomplete embedding state, source de-dupe / scoring, metadata content hydration, or synthesis prompt/context selection. The fix should identify which of those actually failed for Brain/graph content.

The Fix

Investigate and restore ask_knowledge_base answer quality for current Brain / Native Edge Graph / Dream Pipeline queries.

Expected implementation shape:

• Add a focused regression test around a known-current Brain/graph query that must surface and synthesize at least these anchors: README.md, learn/agentos/DreamPipeline.md, GoldenPathSynthesizer, and mutate_frontier / GraphService.mutateFrontier or MemoryService.mutateFrontier.
• Compare ask_knowledge_base and query_documents for the same query so the advertised superset contract is mechanically protected.
• Inspect whether top-ranked refs omit exact-match docs despite query terms, or whether refs are present but synthesis fails to use hydrated content.
• Fix the responsible layer only after the failure is isolated.
• Preserve the #10097 portability contract: Chroma metadata source paths stay portable and local hydration resolves against the consumer's neoRootDir.

Contract Ledger Matrix

Decision Record impact

None. This is a regression repair inside the existing Knowledge Base / RAG contract. It aligns with #10097 and Discussion #11677; it does not amend an ADR.

Acceptance Criteria

• AC1: A focused reproducer captures the current miss: a Brain/graph query around Native Edge Graph, Dream Pipeline, Hybrid GraphRAG, mutate_frontier, Gemma4 31B graph processing, ai/services/graph, and sandman_handoff.md.
• AC2: The root cause is identified in the PR body as one of: retrieval/ranking, stale or incomplete embedding state, source hydration, synthesis prompt/context handling, tenant/type filtering, or another empirically proven layer.
• AC3: ask_knowledge_base returns a grounded answer for the reproducer that cites or references current Brain/graph anchors rather than saying the provided context lacks the terms.
• AC4: The same query's references include at least one source from the graph/Dream substrate, such as learn/agentos/DreamPipeline.md, ai/services/graph/GoldenPathSynthesizer.mjs, ai/services/memory-core/GraphService.mjs, or ai/services/memory-core/MemoryService.mjs.
• AC5: The advertised ask_knowledge_base > query_documents contract is tested or otherwise verified for this query class.
• AC6: The #10097 source-path portability behavior remains covered: relative metadata.source paths still hydrate against neoRootDir, and non-local tenant refs do not fall through to the host checkout.
• AC7: If the cause is stale/incomplete KB state rather than code, the fix adds an operator-visible diagnostic path so future answers distinguish "not indexed / degraded" from "not present in Neo."

Out of Scope

• Rewriting the v13 release notes.
• Rebuilding the entire Knowledge Base as the only deliverable without a diagnostic or guard.
• Changing the Memory Core retrieval APIs.
• Changing graph extraction / DreamService behavior.
• Reopening #10097 as if the old root cause were proven.
• Broad RAG redesign beyond the reproduced ask_knowledge_base quality regression.

Avoided Traps

• Rejected: accepting the false negative and relying on manual rg forever. That defeats the KB-first rule and the tool's documented value.
• Rejected: assuming #10097 reverted. Current SearchService.mjs still contains the defensive neoRootDir hydration path.
• Rejected: filing this as a release-note ticket. The release-note work merely exposed the regression; the owner substrate is Knowledge Base RAG.
• Rejected: treating 31B as decorative. The config defaults make gemma4:31b / gemma-4-31b-it part of the graph-processing evidence path.
• Rejected: blaming the synthesis model before retrieval/context evidence is separated.

Related

• Closed predecessor: #10097
• Degraded-window design discussion: #11677
• Current release identity lane that exposed the miss: #12702
• v13 release epic: #12696
• Identity / Active Hybrid GraphRAG source discussion: #12234
• Graph substrate docs: README.md, learn/agentos/DreamPipeline.md, resources/content/sandman_handoff.md
• Graph implementation: ai/graph/, ai/services/graph/, ai/services/memory-core/GraphService.mjs, ai/services/memory-core/MemoryService.mjs

Origin Session ID: e8f07ef9-ef7e-4815-8ff4-7abe13720621

Retrieval Hint: ask_knowledge_base regression Brain graph Native Edge Graph DreamPipeline Hybrid GraphRAG mutate_frontier Gemma4 31B SearchService QueryService #10097 #11677