Migrate knowledge-base services to flatter SDK structure (M6 KB)

Context

First Tier-1 sub-ticket of M6 epic #10982. Knowledge Base server: 139 LOC Server.mjs, ~10 services + toolService — second-smallest substantive M6 lift, chosen as the pattern PR that establishes the SDK layout convention for the other 3 Tier-1 sub-tickets (MC, GH-WF, NL).

The Problem

KB services live under ai/mcp/server/knowledge-base/services/ and are imported into ai/services.mjs via that path. Per M6 design (v13-path.md §4 + D4), services flatten into SDK structure; KB Server.mjs shrinks from 139 LOC → <50 LOC thin endpoint wrapper consuming services via SDK.

The Architectural Reality

KB service inventory (verified 2026-05-08, dev ad952a10f):

ai/mcp/server/knowledge-base/services/
├── ChromaManager.mjs
├── DatabaseLifecycleService.mjs
├── DatabaseService.mjs
├── DocumentService.mjs
├── HealthService.mjs
├── KBRecorderService.mjs
├── QueryService.mjs
├── SearchService.mjs
├── VectorService.mjs
└── toolService.mjs

Current ai/services.mjs lines 30-37 use KB_* namespace prefixes:

import KB_DatabaseService           from './mcp/server/knowledge-base/services/DatabaseService.mjs';
import KB_LifecycleService          from './mcp/server/knowledge-base/services/DatabaseLifecycleService.mjs';
import KB_DocumentService           from './mcp/server/knowledge-base/services/DocumentService.mjs';
import KB_HealthService             from './mcp/server/knowledge-base/services/HealthService.mjs';
import KB_RecorderService           from './mcp/server/knowledge-base/services/KBRecorderService.mjs';
import KB_QueryService              from './mcp/server/knowledge-base/services/QueryService.mjs';
import KB_SearchService             from './mcp/server/knowledge-base/services/SearchService.mjs';
import KB_ChromaManager             from './mcp/server/knowledge-base/services/ChromaManager.mjs';

Preserving these post-migration is non-negotiable for SDK consumer compatibility (operator scripts, tests, daemons all import from ai/services.mjs).

Server.mjs (139 LOC) post-M2 already extends BaseServer (PR #10973). Remaining LOC is server-specific tool registration + service singleton wiring. Migration removes service singleton wiring (shifts to SDK) and leaves only tool registration + BaseServer extension boilerplate.

The Fix

Proposed SDK layout (subject to peer-review challenge in PR cycle):

ai/services/knowledge-base/
├── ChromaManager.mjs
├── DatabaseLifecycleService.mjs
├── DatabaseService.mjs
├── DocumentService.mjs
├── HealthService.mjs
├── KBRecorderService.mjs
├── QueryService.mjs
├── SearchService.mjs
├── VectorService.mjs
└── toolService.mjs

(per-domain subdirectory keeps namespacing implicit while flattening one level out of MCP server hosting.)

Sequence:

1. Move: git mv ai/mcp/server/knowledge-base/services/*.mjs ai/services/knowledge-base/
2. Update SDK imports: Edit ai/services.mjs lines 30-37 to point at new locations; preserve KB_* prefixes verbatim
3. Update Server.mjs: Edit ai/mcp/server/knowledge-base/Server.mjs to import services via ai/services.mjs rather than directly; remove now-unused local-services-singleton wiring
4. Shrink target: Server.mjs <50 LOC (target ~40 LOC of tool registration + BaseServer extension boilerplate only)
5. Verify Factory pattern intact: unit + integration suite passes; RequestContextService.run wraps dispatch unchanged
6. Capture LOC delta in PR body per M6 epic AC7

Acceptance Criteria

• AC1: All 9 KB services + toolService relocated from ai/mcp/server/knowledge-base/services/ to chosen SDK location
• AC2: ai/services.mjs imports updated; KB_* namespace prefixes preserved verbatim (no consumer-facing API change)
• AC3: ai/mcp/server/knowledge-base/Server.mjs shrunk to <50 LOC
• AC4: Cross-family review approval per swarm PR review routing (one peer review minimum)
• AC5: Unit row + integration row green on PR
• AC6: LOC delta captured in PR body (target: >30% LOC moved from MCP server tree → SDK tree per M6 epic AC7)
• AC7: Pattern PR — chosen SDK layout (per "The Fix" §) becomes the convention for MC/GH-WF/NL sub-tickets; if PR review challenges the layout, decision is documented in PR body for downstream subs

Out of Scope

• Service-internal refactors (separate tickets if needed)
• Adding new KB tools or service surfaces
• ChromaManager-specific architectural changes beyond relocation
• M2 BaseServer-extension regressions (out of scope; M2 substrate is stable)
• Other server migrations (separate sub-tickets per M6 epic)

Avoided Traps / Gold Standards Rejected

• Rejected: rename KB_* namespace prefixes during migration. Cascading breaking change for SDK consumers across the codebase; renaming is a separate concern.
• Rejected: bundle DocumentService rewrite into the migration. Service-internal cleanup is separate scope per feedback_substrate_scope_restraint.
• Rejected: flatten ALL way to ai/services/*.mjs (no per-domain subdir). Risks namespace collisions across servers (multiple HealthService.mjs, DatabaseService.mjs, toolService.mjs exist per server). Per-domain subdir resolves this without re-renaming.
• Rejected: skip the KB_ChromaManager namespace prefix. ChromaManager is consumed via KB_ChromaManager in ai/services.mjs; renaming has the same cascading-breaking-change cost as other services.

Related

• Parent: #10982 (M6 epic — SDK migration per-server)
• Strategic anchor: learn/agentos/v13-path.md §4 M6 + D4
• M2 BaseServer predecessor PR: #10973 (KB BaseServer migration, merged today)
• Sibling sub-tickets (forthcoming): MC, GH-WF, NL SDK migrations

Origin Session ID: 7da190eb-af19-4e98-a3e2-f21f94f676c1

Retrieval Hint: query_raw_memories(query="KB knowledge-base SDK migration M6 v13 flatter service structure pattern PR")