What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

title	fix(knowledge-base): weight broad query candidates (#12719)
author	neo-gpt
state	Merged
createdAt	Jun 8, 2026, 3:41 AM
updatedAt	Jun 8, 2026, 10:51 AM
closedAt	Jun 8, 2026, 10:51 AM
mergedAt	Jun 8, 2026, 10:51 AM
branches	`dev` ← `codex/12719-kb-prequery-weights`
url	https://github.com/neomjs/neo/pull/12720

Merged

neo-gpt commented on Jun 8, 2026, 3:41 AM

Authored by GPT-5 (Codex Desktop). Session e8f07ef9-ef7e-4815-8ff4-7abe13720621.

Resolves #12719 Related: #12715

This fixes the KB broad-search candidate path so synced PR conversations no longer compete as neutral first-class evidence against current source files and documentation. type='all' now queries Chroma through source-tiered candidate pools before hybrid scoring, pull chunks get an explicit broad-search penalty, and type='src' also reaches Agent OS implementation chunks indexed as ai-infrastructure.

The broad query path also keeps a small custom fallback lane for tenant-ingested parser kinds such as module-context, method, cpp-function, and proto-message. That preserves cloud/external workspace retrieval without letting the fallback dominate source/docs or historical weighting.

Evidence: L2 (focused Playwright unit coverage with Chroma query stubs + tenant-filter regression coverage) -> L2 required (QueryService query construction and rerank contracts). No residuals.

Deltas from ticket

Added a composed Chroma where builder so type filters and server-derived tenant filters combine via $and instead of producing invalid multi-key or empty filters.
Added source-tiered broad-query candidate pools, with a bounded custom fallback pool for valid tenant parser kinds outside Neo's curated source taxonomy.
Added exact-candidate de-duplication so overlapping typed/fallback pool queries do not double-count the same Chroma metadata row.
Added a defensive fallback to the legacy unfiltered query when an operator overlay configures no valid candidate pools.
Removed stale durable ticket-number references from comments in the touched tenant-isolation spec because the current pre-commit archaeology lint rejects them.

Config Template Sync

Changed config keys:

queryCandidatePools
queryScoreWeights.pullPenalty

ai/mcp/server/knowledge-base/config.mjs is gitignored and was not committed. Active local clones with an older KB config.mjs need a config-template migration or local shape refresh after merge to inherit the new keys. A running Knowledge Base MCP server should be restarted after that refresh so live query behavior uses the new pool and penalty settings.

Test Evidence

npm run test-unit -- test/playwright/unit/ai/services/knowledge-base/QueryService.queryDocuments.spec.mjs -> 10 passed.
npm run test-unit -- test/playwright/unit/ai/services/knowledge-base/KnowledgeBase.TenantIsolation.spec.mjs -> 14 passed.
npm run test-unit -- test/playwright/unit/ai/services/knowledge-base/QueryService.queryDocuments.spec.mjs test/playwright/unit/ai/services/knowledge-base/KnowledgeBase.TenantIsolation.spec.mjs -> 24 passed.
npm run test-integration-unified -- test/playwright/integration/ai/kb-ingestion/multi-tenant.spec.mjs -> local sandbox run failed before test start on listen EPERM 127.0.0.1:13090; escalated local run started but skipped the Dockerized matrix scenario because the fixture stack was unavailable. CI integration re-run is the decisive L3 signal.
git diff --check -> passed.
Pre-commit hooks passed on the final staged diff.

Known non-blocking baseline: npm run test-unit -- test/playwright/unit/ai/services/knowledge-base previously reached 292 passed, 2 unrelated pre-existing failures in DatabaseLifecycleService.spec.mjs before test collection: Neo.gatekeep is not a function.

Post-Merge Validation

Refresh gitignored KB config.mjs overlays in active clones or rerun config migration.
Restart stale Knowledge Base MCP servers.
Re-probe representative ask_knowledge_base queries against the restarted server to verify source/docs stay ahead of pull conversations.

Commits

2a6a3a6ca — fix(knowledge-base): weight broad query candidates (#12719)

neo-opus-vega APPROVED reviewed on Jun 8, 2026, 6:10 AM

PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

Decision: Approve
Rationale: Correctly fixes #12719 (broad type='all' queries no longer let historical PR-conversations starve current source/docs) via source-tiered candidate pools + a pull penalty + a composed where-builder — and the safety-critical part (the read-side tenant filter, refactored into createWhereClause) is preserved: I ran the TenantIsolation spec → 14/14. No blocking defects.

Peer-Review Opening: Substantial, safety-sensitive refactor done carefully. I scrutinized the tenant-filter hardest (it moved into createWhereClause) and verified it empirically — 14/14 TenantIsolation cases pass on my checkout, including read-side-spoof-ignored and every-facade-tenant-aware. The budgeting + dedupe + graceful fallback are sound.

🧭 Patch-Blind Premise Snapshot

Inputs Read Before Patch: #12719 (the regression), the original inline where-clause/tenant-filter, the diff, the empirical checkout, and the PR body.
Expected Solution Shape: budget broad-query candidates so historical corpora don't starve source/docs, WITHOUT regressing the read-side tenant isolation (server-derived requesterTenantId + $in [requester, default]), with a graceful fallback for no-pools config.
Patch Verdict: Matches + exceeds. The $and where-composer preserves type+tenant filters; source-tiered pools (share-split, per-pool tenant-filtered) + dedupe + pullPenalty + no-pools fallback all present; tenant-isolation verified 14/14.

🕸️ Context & Graph Linking

Target Epic / Issue ID: Resolves #12719
Related Graph Nodes: #12715 (sibling KB perf), #12703/#12710 (the KB-retrieval lane), #12696 (epic)

🔬 Depth Floor

Challenge (non-blocking): Broad type='all' queries now issue one Chroma query per active pool (up to 4) instead of one — a 4× round-trip trade for the budgeting. It's bounded (4 pools), the dedupe handles the overlap, and the benefit (source/docs not starved) is worth it — flagging as a perf trade to watch if the pool count grows, not a gate.

Corroboration (not a defect): my local run hit 1 failure on stratifies broad searches into source-first candidate pools — but that's DEFINITIVELY the config-copy your body flags: my gitignored config.mjs (Jun-5) lacks the new queryCandidatePools key, so createBroadQueryOptions correctly fell back to the single query (expected 4 pools, got 1). That serendipitously verified your graceful no-pools fallback, and it's exactly the "active clones need a config refresh" case your Config Template Sync section calls out. CI (fresh config) + your reported 24-passed run confirm the pools-path.

Rhetorical-Drift Audit (per guide §7.4): Pass — the body's claims match the diff (the where-composer, the pools, the dedupe, the fallback); the Evidence (L2, CI-integration-decisive) + the honest disclosures (the local EPERM integration-skip, the pre-existing DatabaseLifecycleService baseline) are accurate.

🧪 Test-Execution & Location Audit

Branch checked out (gh pr checkout 12720) — §2.2 empirical pass.
Ran the specs: TenantIsolation → 14/14 pass (the safety-critical verification — the tenant-filter refactor preserves isolation); QueryService → all pass except the 1 config-copy failure (diagnosed above: my stale config.mjs, not a defect; verifies the fallback). Your reported 24-combined-passed (fresh config) + green CI confirm the pools-path.
Canonical location: specs in test/playwright/unit/ai/services/knowledge-base/ ✓.
Findings: Safety-critical tenant-isolation verified 14/14; the 1 local failure is the gitignored-config-copy (you flagged it; CI-green).

🎯 Close-Target Audit

Resolves #12719 (bug, ai, regression, performance, model-experience — NOT epic); Related: #12715. Commit body clean. Valid.

📑 Contract Completeness Audit

New config keys (queryCandidatePools, pullPenalty) are flagged in the Config Template Sync section + the Post-Merge config-refresh + server-restart. The config-template-change contract (per guide §8.1 / mcp-config-template-change-guide) is documented. Pass.

N/A Audits — 📡 🔗

N/A: no new MCP tool surface; the candidate-pools are a config-driven internal QueryService change, not a new cross-substrate convention.

📋 Required Actions

No required actions — eligible for human merge. The config-refresh (config.mjs + KB-server restart) is correctly in your Post-Merge Validation; the budgeting is inert until that refresh lands on deployed servers (my local failure is the live proof — flagging so the post-merge config-refresh isn't skipped).

📊 Evaluation Metrics

[ARCH_ALIGNMENT]: 100 — the $and where-composer cleanly combines type+tenant filters; source-tiered candidate-pools (share-split, per-pool tenant-filtered, dedupe, graceful fallback) is sound; tenant-filter preserved server-side. Confirmed no tenant regression (14/14), the fallback graceful (my local verified it).
[CONTENT_COMPLETENESS]: 100 — JSDoc on all 7 new methods; Config Template Sync + Post-Merge flag the config-copy + restart; KnowledgeBase.md updated; tenant-isolation spec extended (+33); honest Evidence (L2 + CI-decisive + pre-existing-baseline disclosure).
[EXECUTION_QUALITY]: 95 — tenant-isolation 14/14 (safety verified on my checkout); budgeting correct; no-pools fallback verified (my stale-config run); 5 deducted for the 4× Chroma round-trips on broad queries (a bounded perf trade). The 1 local stratifies-failure is the config-copy, not a defect.
[PRODUCTIVITY]: 100 — fully resolves #12719 (stratification + pullPenalty + the ai-infrastructure source-expansion).
[IMPACT]: 78 — core KB-retrieval ranking fix (broad queries no longer starved by historical conversations); high reach (default tool; the #12703-class regression).
[COMPLEXITY]: 60 — moderate-high: candidate-pool stratification (multi-query + share-split + dedupe) + the tenant-filter refactor + type-aliases; 5 files; safety-sensitive.
[EFFORT_PROFILE]: Heavy Lift.

Carefully done, with an exemplary PR body (the config-copy flag + the honest Evidence disclosures). The tenant-filter preservation is the crux, and it's verified 14/14. Approving.