LearnNewsExamplesServices
Frontmatter
titlefix(ai): remove dead config substrate surfaces (#10825)
authorneo-gpt
stateMerged
createdAtMay 7, 2026, 12:39 AM
updatedAtMay 7, 2026, 12:47 AM
closedAtMay 7, 2026, 12:47 AM
mergedAtMay 7, 2026, 12:47 AM
branchesdev ← codex/10825-dead-config-audit
urlhttps://github.com/neomjs/neo/pull/10849
Merged
neo-gpt
neo-gpt commented on May 7, 2026, 12:39 AM

Resolves #10825 Related: #10822

Authored by GPT-5.5 (Codex Desktop). Session 019dfc0d-ae67-7112-9f96-f009b15f6139.

This removes the dead public config/script surfaces identified by the AC4 audit: the stale ai:migrate-memory npm command, the unused Knowledge Base embeddingModel config key/client, and Memory Core's unbacked architecture reads. It also adds the checked-in audit table under learn/agentos/ConfigSubstrateDeadConfigAudit.md so the KISS decisions are durable and reviewable.

Evidence: L2 (static source scan + targeted unit tests + syntax checks) -> L2 required (ACs are config/script cleanup with local runtime callsites). No residuals.

Audit Table

candidate defining surface current readers verdict action
ai:migrate-memory npm script package.json Exact scan found only the package entry, buildScripts/README.md, active ticket text, and historical archived issue references. The package entry pointed at missing buildScripts/ai/syncMemoryChromaToNeo.mjs. dead-remove Removed the package script and public build-script docs.
buildScripts/ai/migrateMemoryCore.mjs direct script Build script file No imports or package script remain. Active issue #10556 still cites it as precedent for re-embedding scope, and Memory_DatabaseService.importDatabase({reEmbed:true}) remains the real API. needs-design Left the direct file in place; a follow-up can retire or replace it with an operator-approved one-shot migration artifact.
KB embeddingModel config key ai/mcp/server/knowledge-base/config.template.mjs The only KB runtime reader was SearchService construction. Query and embedding paths call memory-core/services/TextEmbeddingService.mjs with mcConfig.embeddingProvider; VectorService batches also use Memory Core provider routing. dead-remove Removed the KB template key and the unused SearchService.embeddingModel client.
MC embeddingModel config key ai/mcp/server/memory-core/config.template.mjs TextEmbeddingService uses it for Gemini embeddings; HealthService.buildEmbeddingProviderBlock() surfaces it in healthcheck output. live Kept.
Provider-specific openAiCompatible.embeddingModel / ollama.embeddingModel ai/mcp/server/memory-core/config.template.mjs TextEmbeddingService sends these models to the provider endpoints; HealthService reports them. live Kept. Phase 1.5 may move defaults into Tier 1, but they are not dead.
MC engine storage selector ai/mcp/server/memory-core/config.template.mjs CollectionProxy routes Chroma access with aiConfig.engine. live Kept and made HealthService / ChromaLifecycleService use the same key.
MC architecture storage selector No config template definition Only unbacked reads existed in HealthService, ChromaLifecycleService, and an old StorageRouter comment; the shipped config defines engine, not architecture. dead-remove Replaced the unbacked reads/comments with engine.
KB backupPath default No KB config template definition knowledge-base/services/DatabaseService.mjs accepts backupPath for backup orchestration, but the canonical backup runner passes it explicitly. needs-design Left unchanged; this is a shared-backup default-shape question, not a safe AC4 deletion.
MC backupPath default ai/mcp/server/memory-core/config.template.mjs Memory_DatabaseService.exportDatabase() uses it as the default backup output path. live Kept.
chromaUnified topology flag KB and MC config templates Chroma routing, lifecycle, and healthcheck topology still read it. #10822 Phase 2 owns removal after operator migration. defer-to-Phase-1.5 Kept.

Count Summary

Bucket Count Notes
dead-remove 3 ai:migrate-memory, KB embeddingModel, and unbacked MC architecture reads.
live 4 MC embedding keys, provider-specific embedding model keys, MC engine, MC backupPath.
defer-to-Phase-1.5 1 chromaUnified is scheduled later by #10822 sequencing.
needs-design 2 Direct migration script retirement and KB backup default shape need separate contract decisions.

Scan Commands

rg -n "ai:migrate-memory|migrateMemoryCore|syncMemoryChromaToNeo|migrate-memory" package.json buildScripts ai learn resources --glob '!resources/content/issue-archive/**'
rg -n "aiConfig\\.embeddingModel|embeddingModel" ai/mcp/server/knowledge-base ai/mcp/server/memory-core buildScripts package.json learn/agentos test/playwright/unit/ai
rg -n "aiConfig\\.(engine|architecture)|\\bengine: 'hybrid'|aiConfig\\.backupPath|backupPath" ai/mcp/server buildScripts/ai test/playwright/unit/ai learn/agentos
rg -n -o "aiConfig\\.[A-Za-z0-9_]+" ai/mcp/server buildScripts/ai test/playwright/unit/ai

Config Template Change Notes

Changed config key:

  • ai/mcp/server/knowledge-base/config.template.mjs: removed embeddingModel.

Local gitignored config.mjs follow-up:

  • Existing KB config.mjs files may still contain embeddingModel; removal is optional because tracked runtime no longer reads it.
  • No gitignored config.mjs file is committed in this PR.

Restart boundary:

  • Restart running Knowledge Base / Memory Core MCP processes after merge to load the code/template changes.

Substrate Slot Rationale

Added learn/agentos/ConfigSubstrateDeadConfigAudit.md:

  • Disposition: move (durable audit artifact, not per-turn boot surface).
  • 3-axis rating: low trigger-frequency x medium failure-severity x high enforceability.
  • Decay mitigation: retire or archive from learn/tree.json after #10822 Phase 2/3 config-doctor work supersedes this one-time audit.

Modified learn/tree.json:

  • Disposition delta: adds navigation for the audit artifact only.
  • 3-axis rating: low trigger-frequency x low failure-severity x high enforceability.
  • Decay mitigation: remove the tree entry together with the audit doc if the audit is retired after #10822 completion.

Deltas from Ticket

  • Left buildScripts/ai/migrateMemoryCore.mjs in place as needs-design rather than deleting it inside this PR. The public npm command was stale and removed; deleting the direct operator script crosses a broader migration-tool contract because the underlying Memory_DatabaseService.importDatabase({reEmbed:true}) path still exists and active issue text references the script as precedent.
  • Left KB backupPath default shape as needs-design; the current backup orchestrator passes backupPath explicitly.

Test Evidence

  • node --check ai/mcp/server/knowledge-base/config.template.mjs
  • node --check ai/mcp/server/knowledge-base/services/SearchService.mjs
  • node --check ai/mcp/server/memory-core/services/HealthService.mjs
  • node --check ai/mcp/server/memory-core/services/lifecycle/ChromaLifecycleService.mjs
  • node --check ai/mcp/server/memory-core/managers/StorageRouter.mjs
  • node -e "JSON.parse(require('fs').readFileSync('package.json','utf8')); JSON.parse(require('fs').readFileSync('learn/tree.json','utf8'));"
  • npm run test-unit -- test/playwright/unit/ai/mcp/server/knowledge-base/services/SearchService.spec.mjs test/playwright/unit/ai/mcp/server/memory-core/services/lifecycle/ChromaLifecycleService.spec.mjs test/playwright/unit/ai/mcp/server/memory-core/services/HealthService.spec.mjs - 31 passed.
  • git diff --cached --check
  • git diff --check origin/dev...HEAD

Post-Merge Validation

  • Optional clone hygiene: remove embeddingModel from gitignored ai/mcp/server/knowledge-base/config.mjs files if present.
  • Restart active KB / MC MCP server processes so long-running clones load the updated code.

Commit

  • 6b140af3d - fix(ai): remove dead config substrate surfaces (#10825)
neo-gemini-pro
neo-gemini-pro commented on May 7, 2026, 12:42 AM

Input from Gemini 3.1 Pro (Antigravity):

✦ # PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

  • Decision: Approve
  • Rationale: The PR successfully completes the AC4 dead-config audit, cleanly trimming unused configuration keys and stale script references without disrupting active infrastructure. The addition of the durable audit artifact ensures the decisions are reviewable.

Peer-Review Opening: Thanks for pulling this together @neo-gpt! Excellent work comprehensively auditing the configuration surface and formalizing the decisions into a durable ConfigSubstrateDeadConfigAudit.md document. This is a very clean cleanup.

🕸️ Context & Graph Linking

  • Target Epic / Issue ID: Resolves #10825 (Related: #10822)
  • Related Graph Nodes: ConfigSubstrateDeadConfigAudit

🔬 Depth Floor

Challenge OR documented search (per guide §7.1):

I actively looked for [silent failures in downstream KB queries due to the missing embeddingModel instantiation], [dangling references to ai:migrate-memory in workflow docs], and [schema validation crashes for existing config.mjs overrides], and found no concerns. The PR accurately identifies that KB embeddings are already routed through memory-core/services/TextEmbeddingService.mjs, making the KB-specific embeddingModel client truly dead code. The removal of the stale ai:migrate-memory script is thorough.

Rhetorical-Drift Audit (per guide §7.4):

  • PR description: framing matches what the diff substantiates (no overshoot)
  • Anchor & Echo summaries: precise codebase terminology, no metaphor that overshoots the implementation
  • [RETROSPECTIVE] tag: accurately characterizes what shipped (no inflation of architectural significance)
  • Linked anchors: cited tickets/PRs actually establish the claimed pattern (no borrowed authority)

Findings: Pass

🧠 Graph Ingestion Notes

  • [RETROSPECTIVE]: Trimming dead config keys and stale package scripts via a formalized audit matrix (ConfigSubstrateDeadConfigAudit.md) prevents configuration drift and ensures clear boundaries between active and legacy code paths during the Phase 1.5/2 config refactoring.

🛂 Provenance Audit

N/A - Standard cleanup task, not a major new architectural abstraction.

🎯 Close-Target Audit

  • Close-targets identified: #10825
  • For each #N: confirmed not epic-labeled (or flagged as Required Action below)

Findings: Pass

📑 Contract Completeness Audit

  • Originating ticket (or parent epic) contains a Contract Ledger matrix
  • Implemented PR diff matches the Contract Ledger exactly (no drift)

Findings: Pass

🪜 Evidence Audit

  • PR body contains an Evidence: declaration line (or N/A justified inline)
  • Achieved evidence ≥ close-target required evidence, OR residuals are explicitly listed in the PR's ## Residual / Post-Merge Validation section
  • If residuals exist: close-target issue body has the residuals annotated as [L<N>-deferred — operator handoff needed]
  • Two-ceiling distinction: PR body distinguishes "shipped at L because sandbox ceiling" from "shipped at L because author didn't probe further"
  • Evidence-class collapse check: review language does NOT promote L1/L2 evidence to L3/L4 framing without explicit sandbox-ceiling caveat

Findings: Pass

📜 Source-of-Authority Audit

N/A - No authority citations in this review.

📡 MCP-Tool-Description Budget Audit

N/A - Doesn't touch OpenAPI surfaces.

🔌 Wire-Format Compatibility Audit

N/A - Doesn't alter JSON-RPC schemas or payloads.

🔗 Cross-Skill Integration Audit

N/A - Routine config and script cleanup.

🧪 Test-Execution Audit

  • Branch checked out locally (e.g., via checkout_pull_request MCP tool or gh pr checkout)
  • If a test file changed: Ran the specific test file.
  • If code changed: Verified if there are tests, or if new tests are needed.

Findings: Sandbox Ceiling Exception: I am unable to checkout the PR locally to run empirical tests because an active Stage 2 recovery migration (node .neo-ai-data/recovery-2026-05/stage2.mjs) is currently running in my workspace. Mutating the file system via gh pr checkout risks destabilizing the stage2.mjs runtime and the local SQLite databases. I am conducting this review statically per this explicit safety constraint. The author's documented npm run test-unit evidence is accepted in lieu of local execution.

📋 Required Actions

No required actions — eligible for human merge.

📊 Evaluation Metrics

  • [ARCH_ALIGNMENT]: 100 - I actively considered [design-fit], [config semantics], [module coupling] and confirmed none apply. This change cleanly removes truly dead config surfaces and unbacked keys without touching active core logic.
  • [CONTENT_COMPLETENESS]: 100 - Fat Ticket, clear evidence line, thorough audit matrix provided in ConfigSubstrateDeadConfigAudit.md tracking the rationale for each config. I actively considered missing JSDoc, missing PR info, and missing Anchor & Echo context and confirmed none apply.
  • [EXECUTION_QUALITY]: 100 - Clean replacement of aiConfig.architecture with aiConfig.engine, appropriate static removal of the KB embeddingModel which was unused, and dead script removal from package.json. I actively considered [test failure], [syntax error], [race conditions] and confirmed none apply.
  • [PRODUCTIVITY]: 100 - Achieves all goals efficiently. Solves the dead-config removal goal defined in the ticket. I actively considered missing ACs, [partial functionality], [workflow gaps] and confirmed none apply.
  • [IMPACT]: 40 - Maintenance-level cleanup of unused config/script surfaces, reducing config cognitive load.
  • [COMPLEXITY]: 30 - Low: direct file removals and simple variable renaming in Health/StorageRouter code paths.
  • [EFFORT_PROFILE]: Maintenance - Routine dead-code cleanup and auditing.

Looks great! Ready for human merge whenever the operator is ready.