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
- 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.
- 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).
- 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
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
Context
During the resolution of the
memoryCoreChromadaemon regression (#11496 / PR #11499), it was identified that while the runtime daemon and client config were fixed to respect ADR 0003 (unified Chroma on port8000), there are still structural residuals in theai:server-memorysubstrate pointing to the retired port8001.The Problem
The
ai/mcp/server/memory-core/openapi.yamlstill referenceshttp://localhost:8001in 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 referencingai:server-memoryor port8001.The Architectural Reality
Per ADR 0003 (
learn/agentos/decisions/0003-chroma-topology-unified-only.md), there is only one unified Chroma instance running on port8000. Memory Core no longer owns a standalone Chroma daemon. Furthermore, normal MCP usage is stdio; optional HTTP/SSE usesmcpHttpPort(default3001) viaTransportService.The Fix
servers.urlto Chroma8000. Align it with the optional HTTP/SSE transport (http://localhost:3001) and describe it as optional transport metadata, or remove/neutralize theserversblock entirely if stdio-only semantics are preferred.ai:server-memory, standalone Memory Core Chroma, and8001instructions 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).resources/contentarchives or legacy backup fixtures just because they contain the number8001. Focus only on active surfaces.Contract Ledger Matrix
memory-core/openapi.yaml8001with3001(MCP HTTP transport) or removesservers8001,ai:server-memory,memoryCoreChromaAcceptance Criteria
ai/mcp/server/memory-core/openapi.yamldistinguishes MCP transport coordinates from database daemon coordinates (no Chroma port in theserversblock).ai:server-memoryand8001without modifying historical fixtures or archived content.Out of Scope
resources/contentarchives or backup fixtures.Related
learn/agentos/decisions/0003-chroma-topology-unified-only.mdOrigin Session ID: fc8abc96-ce88-407e-9d92-7fcc494f8236 Retrieval Hint:
Cleanup Memory Core 8001 substrate residuals post-ADR 0003