---
id: 10957
title: 'Document v13 architectural path — slim MCP servers, orchestrator daemon, SDK migration sequence'
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - architecture
assignees:
  - neo-opus-ada
createdAt: '2026-05-08T11:53:46Z'
updatedAt: '2026-06-07T17:08:38Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10957'
author: neo-opus-ada
commentsCount: 0
parentIssue: 9999
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-08T12:18:00Z'
---
# Document v13 architectural path — slim MCP servers, orchestrator daemon, SDK migration sequence

## Context

Authored 2026-05-08 in response to @tobiu's chief-architect mandate after two compounding architectural-hallucination errors over the prior session day:

1. **Factory pattern misread**: I initially conflated "remote multi-tenant Memory Core" with "high-availability primary/secondary deployment". Gemini correctly flagged this in [`MESSAGE:0ca25e5b-d59d-4cae-a66e-c6bfd669953e`](https://github.com/neomjs/neo) — the multi-tenant remote shape is ONE endpoint with per-request `RequestContextService` + `Mcp-Session-Id` binding, not multi-instance shared-substrate.
2. **NEO_MC_PRIMARY scoping over-correction**: my and Gemini's first reaction was "strip it entirely". @tobiu corrected: *"isPrimary => LOCAL mcp servers. if agent harnesses spawn multiple local server instances. however: we WANT to move summarization items into daemons."* The flag is still valid for LOCAL multi-harness fleets TODAY; it becomes obsolete only after daemonization lands.

@tobiu's chief-architect mandate: *"how do we get from right here to v13 => path. and this needs to get documented."*

## The Problem

The swarm has accumulated several architectural fragments without a coordinated path:

- 5 MCP servers with no shared base class (each `Server.mjs` independent, ~80% boilerplate duplication)
- Factory pattern adoption uneven (2 of 5 servers — memory-core direct, knowledge-base via `TransportService`)
- `ai/services.mjs` SDK boundary mature but underutilized (most service logic still in MCP server `services/` directories)
- Daemon-shaped services in `ai/daemons/` (DreamService, SwarmHeartbeatService, decomposed services from #10013/#10028) without an orchestrator-daemon process to schedule them
- Bridge-daemon (per-host singleton) specialized for wake-event delivery; no sibling daemon for summarization/sandman/golden-path
- Summarization gated off (#9942 daemon-collision fix); operator-runs only via `npm run ai:summarize-sessions`
- `NEO_MC_PRIMARY` in-process gate exists as workaround for the missing daemon — keeps LOCAL multi-harness fleets from racing on shared substrate

Without a documented path, the swarm risks:
- Iterating in conflicting directions (e.g., my Piece C in-process implementation vs the original ticket's bridge-daemon-or-sibling guidance)
- Losing context between sessions on which architectural decisions are load-bearing vs incidental
- Cowboy-coding without verifying the substrate (the failure mode of today's session)

## The Architectural Reality

Current substrate state (verified empirically 2026-05-08):

- `ai/mcp/server/{file-system,github-workflow,knowledge-base,memory-core,neural-link}/Server.mjs` — 5 MCP server entry points, no common base
- `ai/mcp/server/shared/services/RequestContextService.mjs` — Factory pattern (per-request identity binding via `AsyncLocalStorage`)
- `ai/mcp/server/shared/services/TransportService.mjs` — SSE transport setup; wraps dispatch in `RequestContextService.run(...)`
- `ai/services.mjs` — mature SDK boundary; consumed by scripts, tests, and MC server's `processPendingSummarizations`
- `ai/scripts/bridge-daemon.mjs` — standalone wake-event-delivery daemon, per-host singleton via PID file
- `ai/daemons/` — in-process daemon-shaped services (DreamService, SwarmHeartbeatService, services/* from #10013 decomposition)
- `ai/scripts/summarize-sessions.mjs` — operator-trigger script (calls `Memory_SessionService.summarizeSessions({})` via SDK)

The end-state vision (per @tobiu's mandate): **slim MCP servers + mature SDK + clean daemon architecture + single-source-of-truth for summaries/sandman/golden-path (daemon-driven)**.

## The Fix

Produce, peer-review, and merge `learn/agentos/v13-path.md` as the chief-architect document covering:

1. Vision (3 load-bearing properties — slim MCP, common base, orchestrator daemon)
2. Current State — empirically verified table comparing today vs v13 target
3. Critical Architectural Decisions — D1 Factory pattern eval (with challenge framing) / D2 common base server class / D3 orchestrator daemon architecture / D4 SDK migration boundary / D5 NEO_MC_PRIMARY retirement path
4. Sequenced Milestones — M1 substrate stabilization (current week) → M7 v13 release cut
5. Tickets to file/update
6. #9999 sub-issue audit (each open sub-issue triaged: on-trajectory / re-scope / verify)
7. Risks
8. Outcome Metrics (quantitative v13 readiness targets)
9. Provenance

Doc location: `learn/agentos/v13-path.md`. Linked from ROADMAP.md once reviewed.

## Acceptance Criteria

- [ ] **AC1:** `learn/agentos/v13-path.md` committed via PR; covers all 9 sections enumerated in The Fix
- [ ] **AC2:** Each "Critical Architectural Decision" (D1-D5) explicitly evaluated, including challenge framing (especially D1 Factory pattern — pros/cons/AsyncLocalStorage edge cases)
- [ ] **AC3:** #9999 sub-issue audit triages every open sub-issue with explicit on-trajectory / re-scope / verify markers
- [ ] **AC4:** Sequenced milestones M1-M7 each have: scope, owner-split (current week M1 only), exit gate
- [ ] **AC5:** Outcome metrics are quantitative (LOC moved, server count, latency, reference count) — not vague
- [ ] **AC6:** Peer-reviewed by @neo-gemini-pro and @neo-gpt cross-family (architectural pillar requires both)
- [ ] **AC7:** ROADMAP.md updated with link to v13-path.md and v13 milestone roll-up
- [ ] **AC8:** Linked from #9999 as the v13 umbrella reference; #9999's sub-issues that need re-scoping have follow-up comments per the audit

## Out of Scope

- Implementing any of the milestones (M2-M7 are separate epics/PRs)
- Re-scoping or closing individual sub-issues of #9999 (audit identifies them; per-ticket updates are separate work)
- Updating `learn/agentos/MX.md` or other foundational docs beyond ROADMAP.md cross-link
- Filing the M2/M3/M6 epics this ticket only enumerates them; their creation is downstream of doc approval
- Operator deployment cookbook updates (those land per-milestone, not in the doc itself)

## Avoided Traps / Gold Standards Rejected

- **Rejected: comprehensive 1000+-line specification.** Path docs that try to enumerate every detail become outdated within weeks. This doc is strategic (200-300 lines), not prescriptive — milestones link to per-ticket prescriptions.
- **Rejected: rubber-stamp the Factory pattern.** Per @tobiu's directive *"challenge the factory pattern (probably a reasonably good solution)"*, D1 explicitly evaluates pros/cons/edge cases rather than assuming. Recommendation is positive but with named caveats.
- **Rejected: "strip NEO_MC_PRIMARY immediately" framing** (the over-correction the swarm jumped to earlier today). D5 sequences retirement BEHIND the orchestrator landing, not parallel to it.
- **Rejected: extend bridge-daemon for summarization** (my initial wrong-shape proposal). D3 explicitly separates concerns — bridge stays specialized for wake-domain; orchestrator is its sibling for scheduled work.
- **Rejected: file 5+ tickets for each milestone immediately.** Milestone tickets land downstream of doc approval; pre-filing pollutes the backlog before the path is endorsed.

## Related

- **Parent epic:** [#9999](https://github.com/neomjs/neo/issues/9999) Cloud-Native Knowledge & Multi-Tenant Memory Core (v13 main epic)
- **Substrate triggers (today's correction chain):** A2A `MESSAGE:0ca25e5b-d59d-4cae-a66e-c6bfd669953e` (Gemini's CRITICAL flagging primary/secondary mental-model error)
- **Adjacent in-flight work referenced by the path:**
  - [#10813](https://github.com/neomjs/neo/issues/10813) Restore session summaries — re-scoped per D3/D5
  - [#10956](https://github.com/neomjs/neo/issues/10956) NEO_MC_PRIMARY removal — re-scoped per D5
  - [#10945](https://github.com/neomjs/neo/issues/10945) Deployment-pipeline integration coverage — M1 GPT lane
  - [#10939](https://github.com/neomjs/neo/issues/10939) Phase 3 unit-row re-add — M1 Gemini lane
  - [#10013](https://github.com/neomjs/neo/issues/10013) DreamService Decomposition — M4 prerequisite (already mostly shipped)
  - [#10028](https://github.com/neomjs/neo/issues/10028) Finalize DreamService Decomposition — M4 work
- **Referenced from ROADMAP.md** (post-approval cross-link)

Origin Session ID: `005b6edf-85d8-4980-9e17-486b6b8bed3f`

Retrieval Hint: `query_raw_memories(query="v13 architectural path slim MCP servers orchestrator daemon SDK migration NEO_MC_PRIMARY retirement Factory pattern common base server class")`

## Timeline

- 2026-05-08T11:53:48Z @neo-opus-ada added the `documentation` label
- 2026-05-08T11:53:48Z @neo-opus-ada added the `enhancement` label
- 2026-05-08T11:53:48Z @neo-opus-ada added the `ai` label
- 2026-05-08T11:53:48Z @neo-opus-ada added the `architecture` label
- 2026-05-08T11:54:01Z @neo-opus-ada added parent issue #9999
- 2026-05-08T11:54:04Z @neo-opus-ada assigned to @neo-opus-ada
- 2026-05-08T11:55:34Z @neo-opus-ada cross-referenced by PR #10958
- 2026-05-08T11:59:43Z @neo-opus-ada referenced in commit `c1d08b1` - "docs(agentos): incorporate Gemini's PR #10958 review depth-floor adds (#10957)

Cycle 1 review approved at commentId IC_kwDODSospM8AAAABBqGSkg with two
non-blocking considerations for M2/M3 implementation phases. Folding both
into the strategic doc rather than deferring to implementation memory:

D1 (AsyncLocalStorage edge cases) — explicit mention of:
- EventEmitter boundaries (handlers fire in emitter's own context)
- SSE streaming async generators (iterators yielding async to event loop
  can lose context across yield points)

D2 (Common Base Server Class) — added "Extension points the base must
expose" subsection enumerating registerTools / registerServices /
registerMiddleware / registerHealthChecks. The middleware/interceptor
pipeline (custom AuthMiddleware variants, parameter-validation
interceptors, per-server request hooks) was the specific concern Gemini
flagged — currently duplicated across the 2/5 servers that wrap dispatch;
base class makes it pluggable.

Co-Authored-By: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-08T12:05:24Z @neo-opus-ada referenced in commit `2015153` - "docs(agentos): incorporate Cycle 1 GPT review fixes + KB delta-update task (#10957)

@neo-gpt's PR #10958 Cycle 1 review at commentId IC_kwDODSospM8AAAABBqH6pg
flagged two blocking points; both addressed in this commit. Plus operator
added KB delta-update as another orchestrator-scoped task.

GPT RA1 — close-target / AC consistency:
- AC7 (ROADMAP.md cross-link) was deferred in original PR body; now satisfied
  inline in this commit. ROADMAP.md gains a new "v13 Architectural Path"
  section above "Current Focus: v12.2" linking to learn/agentos/v13-path.md
  and naming #9999 as the v13 main epic.
- AC8 native parent_child link was already done via update_issue_relationship
  immediately post-create (#9999 → #10957). Per-sub-issue follow-up comments
  remain post-merge work per ticket §"Out of Scope".

GPT RA2 — §6 audit completeness:
- Added #10945 row (open child of #9999, GPT's M1 lane; 5 valid sub-tickets
  #10947/#10949/#10950/#10951/#10952 with #10948 closed invalid post-correction)
- Added #10957 row (this very doc; meta — closes when this PR merges)

Operator addition (chief-architect input 2026-05-08):
- D3 Orchestrator scope expanded with Knowledge Base delta-update sync
  task. KB already supports delta updates via `npm run ai:sync-kb`;
  orchestrator schedules them on configurable cadence per the same
  per-host singleton pattern.

Co-Authored-By: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-08T12:18:00Z @tobiu referenced in commit `a77adf0` - "docs(agentos): v13 architectural path strategy document (#10957) (#10958)

* docs(agentos): add v13 architectural path strategy document (#10957)

Resolves #10957.

Authored 2026-05-08 per @tobiu's chief-architect mandate after today's
architectural-hallucination corrections (Factory-pattern partial-rollout
misread + NEO_MC_PRIMARY scoping over-correction).

Document covers the path from current substrate state (post-Bucket-G,
post-Factory-pattern, post-NEO_MC_PRIMARY-correction) to v13 release:

1. Vision — slim MCP servers + mature SDK + clean daemon architecture
2. Current State — empirically verified table comparing today vs target
3. Critical Architectural Decisions — D1 Factory eval (challenge-framed)
   / D2 common base server class / D3 orchestrator daemon architecture
   / D4 SDK migration boundary / D5 NEO_MC_PRIMARY retirement path
4. Sequenced Milestones M1-M7 — current week (M1 substrate stabilization
   with owner-split: Gemini unit-row, GPT integration, Claude doc) →
   v13 release cut
5. Tickets to file/update enumerated for each milestone
6. #9999 sub-issue audit — every open sub-issue triaged with
   on-trajectory / re-scope / verify markers
7. Risks + mitigations
8. Outcome metrics — quantitative v13 readiness targets
9. Provenance — citation chain back to today's correction

Strategic shape (~280 lines), not exhaustive specification. Per-milestone
prescriptions live in their own tickets/PRs; this doc is the chief-architect
anchor for swarm coordination across that work.

Co-Authored-By: tobiu <tobiasuhlig78@gmail.com>

* docs(agentos): incorporate Gemini's PR #10958 review depth-floor adds (#10957)

Cycle 1 review approved at commentId IC_kwDODSospM8AAAABBqGSkg with two
non-blocking considerations for M2/M3 implementation phases. Folding both
into the strategic doc rather than deferring to implementation memory:

D1 (AsyncLocalStorage edge cases) — explicit mention of:
- EventEmitter boundaries (handlers fire in emitter's own context)
- SSE streaming async generators (iterators yielding async to event loop
  can lose context across yield points)

D2 (Common Base Server Class) — added "Extension points the base must
expose" subsection enumerating registerTools / registerServices /
registerMiddleware / registerHealthChecks. The middleware/interceptor
pipeline (custom AuthMiddleware variants, parameter-validation
interceptors, per-server request hooks) was the specific concern Gemini
flagged — currently duplicated across the 2/5 servers that wrap dispatch;
base class makes it pluggable.

Co-Authored-By: tobiu <tobiasuhlig78@gmail.com>

* docs(agentos): incorporate Cycle 1 GPT review fixes + KB delta-update task (#10957)

@neo-gpt's PR #10958 Cycle 1 review at commentId IC_kwDODSospM8AAAABBqH6pg
flagged two blocking points; both addressed in this commit. Plus operator
added KB delta-update as another orchestrator-scoped task.

GPT RA1 — close-target / AC consistency:
- AC7 (ROADMAP.md cross-link) was deferred in original PR body; now satisfied
  inline in this commit. ROADMAP.md gains a new "v13 Architectural Path"
  section above "Current Focus: v12.2" linking to learn/agentos/v13-path.md
  and naming #9999 as the v13 main epic.
- AC8 native parent_child link was already done via update_issue_relationship
  immediately post-create (#9999 → #10957). Per-sub-issue follow-up comments
  remain post-merge work per ticket §"Out of Scope".

GPT RA2 — §6 audit completeness:
- Added #10945 row (open child of #9999, GPT's M1 lane; 5 valid sub-tickets
  #10947/#10949/#10950/#10951/#10952 with #10948 closed invalid post-correction)
- Added #10957 row (this very doc; meta — closes when this PR merges)

Operator addition (chief-architect input 2026-05-08):
- D3 Orchestrator scope expanded with Knowledge Base delta-update sync
  task. KB already supports delta updates via `npm run ai:sync-kb`;
  orchestrator schedules them on configurable cadence per the same
  per-host singleton pattern.

Co-Authored-By: tobiu <tobiasuhlig78@gmail.com>

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-08T12:18:00Z @tobiu closed this issue
- 2026-05-08T12:28:11Z @neo-opus-ada cross-referenced by #10960

