---
id: 11922
title: Clean Memory Core source-comment archaeology
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - refactoring
  - architecture
  - model-experience
assignees:
  - neo-gpt
createdAt: '2026-05-24T20:48:30Z'
updatedAt: '2026-06-07T17:15:21Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11922'
author: neo-gpt
commentsCount: 1
parentIssue: 11912
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-06-01T05:51:32Z'
---
# Clean Memory Core source-comment archaeology

Parent epic: #11912

## Context

#11912 started as a single cleanup ticket, but the current `ai/**/*.mjs` diagnostic is broad enough that it should be managed as an epic. This subissue owns the Memory Core group instead of splitting work per file.

Current grouped baseline on `origin/dev`:

- `ai/services/memory-core/**/*.mjs`: 171 diagnostic matches.
- `ai/mcp/server/memory-core/**/*.mjs`: 36 diagnostic matches.
- Top files include `MailboxService.mjs`, `HealthService.mjs`, `GraphService.mjs`, `MemoryService.mjs`, `SessionService.mjs`, `DatabaseService.mjs`, `WakeSubscriptionService.mjs`, and Memory Core MCP server/config files.

## The Problem

Memory Core source comments carry dense ticket, PR, AC, cycle, and phase archaeology. These comments often describe the origin story of a behavior rather than the durable runtime contract a maintainer needs when editing Memory Core.

## The Architectural Reality

Memory Core is the highest-risk `ai/` surface for this cleanup because it owns mailbox coordination, graph persistence, Chroma migration observability, memory/session retrieval, wake subscriptions, and MCP server configuration. Comments must preserve local invariants and failure modes while removing snapshot references that belong in tickets, PRs, ADRs, or release notes.

## The Fix

Clean Memory Core source comments and JSDoc in grouped batches:

1. Rewrite ticket/PR/AC/cycle/phase references into durable contracts, stable symbols, and local service boundaries.
2. Preserve behavior and runtime strings unless a comment exposes a separate executable bug.
3. Document before/after counts per batch, including false positives left untouched.
4. Use this subissue as the close target only after the Memory Core group is clean; individual PRs may reference it while contributing partial batches.

## Contract Ledger Matrix

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| `ai/services/memory-core/**/*.mjs` comments/JSDoc | #11912 source-comment cleanup epic | Source comments explain Memory Core invariants without historical ticket anchors | Keep runtime strings unchanged and document as false positives | PR bodies | Before/after focused diagnostics |
| `ai/mcp/server/memory-core/**/*.mjs` comments/JSDoc | #11912 source-comment cleanup epic | MCP server/config comments explain stable operator contracts | Defer generated/openapi surfaces outside `.mjs` unless separately scoped | PR bodies | Before/after focused diagnostics |

## Decision Record Impact

Aligned with ADR 0005 and ADR 0008. No ADR amendment expected; this is cleanup under the already-graduated why-first source-comment contract.

## Acceptance Criteria

- [ ] Clean Memory Core service comments/JSDoc so the focused diagnostic returns only documented false positives, if any.
- [ ] Clean Memory Core MCP server/config `.mjs` comments/JSDoc under the same rule.
- [ ] Preserve runtime behavior; any executable bug discovered during cleanup is filed separately.
- [ ] PR evidence includes before/after focused counts and `git diff --check`.
- [ ] Parent #11912 remains open until all grouped subissues are complete.

## Out of Scope

- Knowledge Base, Graph, GitHub Workflow, daemon, script, and residual config groups.
- Generated resource mirrors, tests, PR bodies, issue bodies, and ADR/discussion archaeology.
- Runtime behavior changes.

## Related

- Parent epic: #11912
- Existing contribution: PR #11920 cleaned `MailboxService.mjs` as the first Memory Core batch.

Origin Session ID: 019e5bac-15f3-7830-a59c-72772c757f9a

Handoff Retrieval Hint: `query_raw_memories("11912 Memory Core source-comment archaeology MailboxService HealthService GraphService")`

## Timeline

- 2026-05-24T20:48:31Z @neo-gpt assigned to @neo-gpt
- 2026-05-24T20:48:32Z @neo-gpt added the `documentation` label
- 2026-05-24T20:48:32Z @neo-gpt added the `enhancement` label
- 2026-05-24T20:48:32Z @neo-gpt added the `ai` label
- 2026-05-24T20:48:32Z @neo-gpt added the `refactoring` label
- 2026-05-24T20:48:32Z @neo-gpt added the `architecture` label
- 2026-05-24T20:48:32Z @neo-gpt added the `model-experience` label
- 2026-05-24T20:49:52Z @neo-gpt added parent issue #11912
- 2026-05-24T20:50:56Z @neo-gpt cross-referenced by PR #11920
- 2026-05-24T20:53:08Z @neo-gpt referenced in commit `f995ca1` - "chore(ai): clean health source comments (#11922)"
- 2026-05-24T20:55:32Z @neo-gpt referenced in commit `cbf324c` - "chore(ai): clean memory-core source comments (#11922)"
- 2026-05-24T20:56:12Z @neo-gpt cross-referenced by PR #11927
- 2026-05-24T21:08:30Z @neo-gpt cross-referenced by #11912
- 2026-05-24T21:37:09Z @tobiu referenced in commit `13447af` - "chore(ai): clean memory-core source comments (#11922) (#11927)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-25T01:08:30Z @neo-gpt cross-referenced by PR #11944
- 2026-05-25T01:29:38Z @neo-opus-ada cross-referenced by PR #11947
- 2026-05-25T02:03:19Z @neo-gpt cross-referenced by #11924
- 2026-05-25T02:11:32Z @neo-opus-ada cross-referenced by PR #11949
- 2026-05-25T05:22:49Z @tobiu referenced in commit `1f42721` - "chore(ai): clean memory-core helper comments (#11922) (#11944)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-25T13:19:09Z @neo-gpt cross-referenced by PR #11975
- 2026-05-25T13:56:29Z @tobiu referenced in commit `96a9f05` - "chore(ai): clean memory core service comments (#11922) (#11975)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
### @neo-gpt - 2026-05-28T05:57:17Z

**Input from GPT-5 (Codex Desktop):**

> ● ## Ticket Intake Classification — residual batch
> 
> Verdict: `valid-as-written`; ROI positive for one more focused residual cleanup batch.
> 
> Evidence before branch/code work:
> - Live issue metadata: OPEN, assigned to `neo-gpt`, created `2026-05-24T20:48:30Z`, updated `2026-05-24T20:48:31Z`; no `stale` / `no auto close` labels. Age state: `pre-stale` under `.github/workflows/close-inactive-issues.yml` (`90d` stale + `14d` close).
> - Parent epic #11912 has prior @neo-gpt epic-review: https://github.com/neomjs/neo/issues/11912#issuecomment-4529966118.
> - Existing #11922 contributions are merged (#11920, #11927, #11944, #11975), but current `dev` still has residual Memory Core comment archaeology candidates.
> - Current focused diagnostic over `ai/services/memory-core` + `ai/mcp/server/memory-core` finds residual issue/phase anchors. This batch will stay comment/JSDoc-only and target stable-contract rewrites where the anchors are historical rather than current API.
> - Out of scope remains unchanged: runtime behavior, runtime strings, generated mirrors, and non-Memory-Core cleanup groups.
> 
> Branch: `codex/11922-memory-core-residual-comments`.
> 
> lane-state: next-lane (working #11922 residual Memory Core comments).

- 2026-05-28T06:01:46Z @neo-gpt cross-referenced by PR #12127
- 2026-05-28T07:35:31Z @tobiu referenced in commit `0aebc26` - "chore(ai): clean residual memory-core comments (#11922) (#12127)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-01T04:03:41Z @neo-gpt cross-referenced by PR #12283
- 2026-06-01T05:51:33Z @tobiu closed this issue
- 2026-06-01T05:51:33Z @tobiu referenced in commit `e3cc70f` - "chore(ai): clean memory-core comment archaeology (#11922) (#12283)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"

