test(mcp): add cross-transport parity harness for remote vs stdio MCP

[jack-arturo]

Problem

#224 fixed one symptom: the remote bridge's compact recall block dropped the memory's stored date, so an agent replaying that text read a two-week-old itinerary as today's plan. AutoHub's parser already looked for a Created: line — the remote transport simply never emitted one, while the stdio package always had.

That single missing line is one instance of a much wider split. mcp-automem's server.json publishes stdio, streamable-HTTP, and SSE as one server with one shared 6-tool array. A client picking "AutoMem" out of the registry should get the same tools and the same output regardless of transport. It currently does not.

A manual schema sync was already attempted once — d99b86d fix(mcp-sse): sync tool schemas for SSE/MCP parity (#104) — and has since drifted again.

What this PR adds

It does not close the gap. It documents the gap and makes it machine-checkable, so the fix (collapsing both transports onto one shared implementation) lands against a red-to-green target instead of a hand-maintained checklist.

• docs/MCP_TRANSPORT_PARITY.md — the full divergence audit, plus an accepted transport-level differences table that is the live contract the harness allowlists against.
• mcp-sse-server/parity/ — connects one MCP client to each transport (bridge in-process over streamable HTTP, published stdio package as a child process), both pointed at the same live AutoMem, so any difference is the transports and not the data.
• make test-parity — brings the stack up and diffs them in one command. make test now also chains the bridge's node suite, which was previously only reachable in CI and invisible locally.
• .github/workflows/mcp-parity.yml — runs on PRs touching the bridge or the HTTP API, plus weekly as a drift alarm against newly published mcp-automem versions.

What the harness asserts

1. tools/list deep-equal after key-order normalization.
2. Server capabilities and instructions match; serverInfo.name is allowlisted to differ, but each side must report its own package version.
3. 19 tools/call scenarios render identically — covering batch and supersede store, ranked/detailed/items/json/empty recall, id fetch, tag enumeration, relation-prop and batch association, update, single and bulk delete, health, and three error paths.

Each transport writes under its own uuid4 tag namespace so neither sees the other's memories. UUIDs, timestamps, scores, query_time_ms, global service counters and the allowlisted request_id suffix are redacted before comparison. Cleanup deletes both namespaces by tag.

Current result: intentionally red

All 19 scenarios differ, which is the finding, not a failure of the harness:

19/19 scenarios differ: store single, store batch, store supersede,
recall ranked text, recall detailed, recall items, recall json, recall empty,
recall id fetch, recall exhaustive, associate single,
associate batch partial failure, update, delete single, delete by tag, health,
error: exhaustive without tags, error: store content over hard limit,
error: unknown tool

tools/list differs on _meta, title, outputSchema, two annotation hints and all six descriptions; getInstructions() is undefined on the remote side. The remote is also missing recall_memory's id-fetch and exhaustive modes, store_memory's batch and supersede modes, delete_memory's bulk-by-tag, and all nine of associate_memories' relation-specific properties.

The workflow is continue-on-error: true for exactly this reason and flips to blocking in the change that closes the gap.

Test plan

make test          # 656 python unit + 22 node; 3 parity tests skip cleanly
make test-parity   # brings the stack up, reproduces the red baseline

• Without AUTOMEM_RUN_PARITY_TESTS=1 the parity tests skip, which is what CI's existing node-test job sees — verified.
• The harness leaves no residue: memory_count returned to exactly 6000 after repeated runs.

Notes

• Size: 2132 changed lines, but 1502 of those are package-lock.json — 89 transitive dependency entries from adding the stdio package as a devDependency. 630 lines are reviewable code. The lockfile has to ship with the harness because CI runs npm ci, so splitting would not reduce the reviewable surface.
• @modelcontextprotocol/sdk is pinned to 1.20.0 exact. Adding the devDependency otherwise hoists the newer SDK over the deployed bridge's — a production runtime bump riding in on a test-only change. Pinning makes the devDependency nest its own copy instead.
• No behavior change to the bridge itself: this PR adds tests, docs and CI only.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9ac5b4eeb6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 89346e9c87

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[jack-arturo]

Babysit — ready. Verified green at fa458b0004.

👍 Codex all clear on the current head. 2 review rounds, 4 findings, all fixed and resolved; 0 unresolved threads.

One check is red on purpose: parity. That job is the deliverable — it diffs the two MCP transports and they currently differ in all 19 scenarios. Its workflow run concludes success via job-level continue-on-error, develop has no required-check protection, and mergeStateStatus is UNSTABLE, not BLOCKED. Nothing about it blocks merge. It flips to blocking in the change that collapses the transports onto one shared implementation.

Round-by-round:

Round	Finding	Outcome
1	clients.js leaked the HTTP listener when the stdio child failed to spawn	fixed 89346e9
2	closer registered after the handshake await, so a child that started then failed the handshake still leaked	fixed fa458b0
2	scenarios shared one tag namespace, so a write-capability gap corrupted every later recall comparison	fixed fa458b0
2	weekly cron could not distinguish "same known gaps" from new drift — an alarm that cannot alarm	removed fa458b0

Two more were caught locally before this ever reached GitHub (the weekly job reinstalling the pinned version; /health comparing global counters), plus one found while verifying (structuredContent re-parsed after redaction, which is deliberately not valid JSON).

make test-parity now runs on port 8011, not 8001 — the harness writes fixtures and bulk-deletes by tag, and a developer running a local AutoMem install holds 8001. That collision happened during this run.

Agent did not merge.