LearnNewsExamplesServices
Frontmatter
id11500
titleCleanup Memory Core 8001 substrate residuals post-ADR 0003
stateClosed
labels
enhancementaiarchitecture
assigneesneo-gemini-3-1-pro
createdAtMay 16, 2026, 11:22 PM
updatedAtMay 17, 2026, 11:59 PM
githubUrlhttps://github.com/neomjs/neo/issues/11500
authorneo-gemini-3-1-pro
commentsCount3
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMay 17, 2026, 11:59 PM

Cleanup Memory Core 8001 substrate residuals post-ADR 0003

Closedenhancementaiarchitecture
neo-gemini-3-1-pro
neo-gemini-3-1-pro commented on May 16, 2026, 11:22 PM

Context

During the resolution of the memoryCoreChroma daemon regression (#11496 / PR #11499), it was identified that while the runtime daemon and client config were fixed to respect ADR 0003 (unified Chroma on port 8000), there are still structural residuals in the ai:server-memory substrate pointing to the retired port 8001.

The Problem

The ai/mcp/server/memory-core/openapi.yaml still references http://localhost:8001 in its server URL. This is doubly wrong: it uses the retired Chroma port, and it maps the MCP transport coordinates to the database daemon coordinates. Additionally, active docs, scripts, and skills still contain obsolete instructions referencing ai:server-memory or port 8001.

The Architectural Reality

Per ADR 0003 (learn/agentos/decisions/0003-chroma-topology-unified-only.md), there is only one unified Chroma instance running on port 8000. Memory Core no longer owns a standalone Chroma daemon. Furthermore, normal MCP usage is stdio; optional HTTP/SSE uses mcpHttpPort (default 3001) via TransportService.

The Fix

  1. MCP OpenAPI metadata: Do not map servers.url to Chroma 8000. Align it with the optional HTTP/SSE transport (http://localhost:3001) and describe it as optional transport metadata, or remove/neutralize the servers block entirely if stdio-only semantics are preferred.
  2. Chroma/runtime operator guidance: Remove retired ai:server-memory, standalone Memory Core Chroma, and 8001 instructions from active docs/skills (e.g., .agents/skills/self-repair, .codex/HARNESS_RESTART.md, buildScripts/README.md, learn/agentos/tooling/RestorationRunbook.md, and relevant tests).
  3. Historical fixtures / archived content: Do NOT rewrite generated resources/content archives or legacy backup fixtures just because they contain the number 8001. Focus only on active surfaces.

Contract Ledger Matrix

Target Surface Source of Authority Proposed Behavior Fallback Docs Evidence
memory-core/openapi.yaml ADR 0003 Replaces 8001 with 3001 (MCP HTTP transport) or removes servers N/A ADR 0003 OpenAPI reflects transport, not backing DB
Active Docs & Skills ADR 0003 Removes references to 8001, ai:server-memory, memoryCoreChroma N/A ADR 0003 Docs align with unified Chroma topology

Acceptance Criteria

  • ai/mcp/server/memory-core/openapi.yaml distinguishes MCP transport coordinates from database daemon coordinates (no Chroma port in the servers block).
  • Active documentation, scripts, and skills are swept to remove instructions for ai:server-memory and 8001 without modifying historical fixtures or archived content.

Out of Scope

  • Runtime daemon topology (already fixed in #11499).
  • Modifying legacy resources/content archives or backup fixtures.

Related

  • #11496 — Orchestrator still starts Memory Core Chroma after ADR 0003
  • ADR 0003 — learn/agentos/decisions/0003-chroma-topology-unified-only.md

Origin Session ID: fc8abc96-ce88-407e-9d92-7fcc494f8236 Retrieval Hint: Cleanup Memory Core 8001 substrate residuals post-ADR 0003

tobiu referenced in commit e0de741 - "chore: cleanup Memory Core 8001 substrate residuals post-ADR 0003 (#11500) (#11526) on May 17, 2026, 11:59 PM
tobiu closed this issue on May 17, 2026, 11:59 PM