ContextQMD
Back to Claude Mem

Ship cmem-sdk — Release Plan

plans/2026-06-07-ship-cmem-sdk.md

13.9.115.0 KB
Original Source

Ship cmem-sdk — Release Plan

Status: implementation plan Date: 2026-06-07 Branch: mutual-aardvark Implements release of: plans/2026-05-25-cmem-sdk-and-server-rename.md (all 9 phases built + audited, verdict SHIP)

Goal

Get the already-built, already-verified cmem-sdk published and merged to main. The code is feature-complete (62/62 SDK tests green in audit, 2094 full-suite passing, build + typecheck + import-guard all pass). What remains is purely release mechanics: commit the audit cleanup, rebase onto a moved main, get CI green, merge, then cut version 13.5.0 via the /version-bump skill off main.

Locked decisions (from user, 2026-06-07)

  1. Version: MINOR → 13.5.0. New public claude-mem/sdk export is additive; server-beta→server rename preserves back-compat (audit obs 2533/2534).
  2. Publish: via the /claude-mem:version-bump skill, run off main. Do NOT npm publish by hand and do NOT push a tag manually — the skill drives manifests, build-and-sync, commit, tag, push, npm publish, changelog, and GitHub release. (npm-publish.yml auto-publishes on v* tag push; the skill's tag push is what triggers it. Avoid pushing a tag twice.)
  3. Reconcile: REBASE mutual-aardvark onto origin/main (not merge).
  4. Tests: a live Postgres IS available. Run the full SDK suite green locally before relying on CI. uvx/chroma also required for the 5 Chroma-backed tests.

Current state (verified in Phase 0)

  • Branch: 30 ahead, 11 behind origin/main. No PR exists yet.
  • Uncommitted audit cleanup (must be committed before rebase):
    • package.json — runtime deps trimmed 22→5 (pg, zod, @modelcontextprotocol/sdk, better-auth, @better-auth/api-key); rest moved to devDependencies; //dependencies-note added.
    • src/sdk/index.ts — stale "Phase N stub" comments rewritten (doc-only).
    • 8 modified tests/sdk/*.test.ts — migrated to the new isolation helper.
    • tests/sdk/pg-isolation.ts — untracked new helper (libpq search_path in pool URL).
  • Rebase conflicts expected (~7 files): driven by the server-beta→server rename vs. ongoing main work. Split into two kinds:
    • Source conflicts (hand-resolve): package.json, src/server/runtime/create-server-service.ts.
    • Build-artifact conflicts (do NOT hand-merge — regenerate via build): plugin/scripts/context-generator.cjs, plugin/scripts/mcp-server.cjs, plugin/scripts/server-service.cjs, plugin/scripts/worker-service.cjs, plugin/ui/viewer-bundle.js.
  • CI (.github/workflows/): ci.yml runs on PR + push-to-main (typecheck, build w/ bundle-size guardrails, Bun tests, server-runtime e2e in Docker+Postgres+Valkey). npm-publish.yml publishes on v* tag push. windows.yml build-only on PR.

Phase 0: Documentation Discovery — COMPLETE

Consolidated findings (sources: package.json, tsup.config.ts, scripts/check-sdk-bundle.cjs, scripts/generate-changelog.js, .github/workflows/*, the version-bump SKILL.md, git/gh state).

Allowed APIs / commands (cited)

NeedCommand / locationSource
Build (full, incl. SDK + guard)npm run build = sync-manifests → build-hooks → build:sdk → check:sdk-bundlepackage.json:65
Build + test + local marketplace syncnpm run build-and-syncpackage.json:68
Typechecknpm run typecheck (tsc --noEmit ×2)package.json:103
SDK bundle import guardnode scripts/check-sdk-bundle.cjs (forbidden: express, bullmq, ioredis, better-auth, react, bun:sqlite, @anthropic-ai/claude-agent-sdk)scripts/check-sdk-bundle.cjs:22-30
Changelog (auto)npm run changelog:generate (reads gh release data)package.json:75, scripts/generate-changelog.js
Version bump skill/claude-mem:version-bumpskill SKILL.md

Version manifests that bump in lockstep (7) — current 13.4.0

package.json:3 · plugin/package.json:3 · .claude-plugin/marketplace.json:13 · .claude-plugin/plugin.json:3 · plugin/.claude-plugin/plugin.json:3 · .codex-plugin/plugin.json:3 · openclaw/openclaw.plugin.json:6 (The version-bump skill edits all 7. Verify with git grep -n '"version": "13.5.0"' = 7 hits, '"version": "13.4.0"' = 0.)

Build output contract (verified present)

tsup.config.ts entry ['src/index.ts','src/sdk/index.ts'], dts:true, outDir:dist, clean:false, external ['pg','@anthropic-ai/sdk',/^node:/]. Emits dist/sdk/index.js + dist/sdk/index.d.ts. exports["./sdk"] → ./dist/sdk/index.js (+ types). files[] ships dist.

Test preconditions

export CLAUDE_MEM_TEST_POSTGRES_URL=postgres://… (fallback CLAUDE_MEM_SERVER_DATABASE_URL). uvx on PATH for the 5 Chroma tests (capture/generate/search/close + create-cmem-client uses PG only). Helper: tests/sdk/pg-isolation.ts pins search_path via libpq options in the pool URL.

Anti-patterns to avoid (do NOT)

  • Do NOT npm publish manually or git tag/git push a tag by hand — the version-bump skill owns that (decision #2).
  • Do NOT hand-merge the 5 build-artifact conflicts — regenerate with npm run build.
  • Do NOT promote any dep back into dependencies without re-running check-sdk-bundle + the dep scan (see //dependencies-note in package.json).
  • Do NOT run the version bump on the mutual-aardvark branch — run /version-bump on main after the merge (decision #2).

Phase 1: Commit the audit cleanup on mutual-aardvark

What to implement: turn the uncommitted audit work into one clean commit so the rebase has a stable base. No code logic changes — this is the May 29 audit output.

Tasks:

  1. Confirm the working tree matches the expected audit cleanup (the 9 modified files + untracked tests/sdk/pg-isolation.ts listed in "Current state"). If anything unexpected appears, stop and report.
  2. Run the local verification gate (Postgres available, decision #4):
    bash
    export CLAUDE_MEM_TEST_POSTGRES_URL="postgres://…/cmem_test"   # your test DB
which uvx                                                       # must resolve
npm run typecheck
npm run build            # includes check:sdk-bundle — must print "dist/sdk/index.js is clean"
npm test -- tests/sdk    # or the repo's test runner scoped to tests/sdk
  3. Stage and commit (include the untracked helper):
    bash
    git add package.json src/sdk/index.ts tests/sdk/
git commit -m "chore(sdk): finalize cmem-sdk audit cleanup — dep reclassification, pg-isolation test harness, stale-comment removal"

Verification checklist:

  • git status clean (no modified, no untracked under tests/sdk/).
  • npm run typecheck exits 0.
  • npm run build prints check-sdk-bundle: dist/sdk/index.js is clean.
  • Full tests/sdk suite green (0 skips for the DB/Chroma tests, since PG + uvx present).
  • git grep -n "Phase 5 stub\|Phase 6 stub\|not implemented yet" src/sdk/index.ts → 0 hits.

Anti-pattern guards: don't reorder/squash the existing 30 commits here; this is a single additive commit. Don't git add -A blindly — only the audit files.

Phase 2: Rebase mutual-aardvark onto origin/main

What to implement: replay this branch's commits on top of the 11 new main commits (decision #3), resolving the rename conflicts.

Tasks:

  1. git fetch origin && git rebase origin/main
  2. For each conflict, resolve by class:
    • Source — hand-resolve, keep the rename:
      • package.json — keep the audit dep split (5 runtime deps + //dependencies-note) AND any new deps/scripts main added. Re-verify the exports["./sdk"] and files entries survive.
      • src/server/runtime/create-server-service.ts — keep server naming (the rename); fold in any main-side logic changes.
    • Build artifacts — DO NOT edit by hand, take either side then regenerate: plugin/scripts/{context-generator,mcp-server,server-service,worker-service}.cjs, plugin/ui/viewer-bundle.js. Resolve with git checkout --theirs (or ours) just to unblock, then npm run build / npm run build-and-sync regenerates them correctly.
  3. After the rebase completes: npm run build (regenerates all bundles from reconciled source) and re-run the Phase 1 verification gate.
  4. Re-run git grep -in 'serverbeta\|server-beta' across code identifiers — expect only intentional back-compat references (settings-key aliases, legacy job-name handling per audit obs 2534), not new ones reintroduced by main.

Verification checklist:

  • Rebase finishes with no remaining conflict markers (git grep -n '<<<<<<<' = 0).
  • npm run typecheck + npm run build + tests/sdk all green post-rebase.
  • dist/sdk/index.js import guard still clean.
  • git log --oneline origin/main..HEAD shows the branch commits replayed cleanly atop main.
  • No accidental re-introduction of server-beta naming beyond the documented back-compat surface.

Anti-pattern guards: never resolve a .cjs/viewer-bundle.js conflict by manually editing minified output — always regenerate. Don't drop main's 11 commits' changes while resolving (read each hunk; keep both sides' intent).

Phase 3: Open PR and drive CI green

What to implement: force-push the rebased branch, open the PR, get all checks green.

Tasks:

  1. git push --force-with-lease origin mutual-aardvark
  2. Open the PR against main:
    bash
    gh pr create --base main --head mutual-aardvark \
  --title "feat(sdk): ship cmem-sdk (claude-mem/sdk export) + server runtime rename" \
  --body "<summary of the 9-phase build + audit verdict SHIP + dep reclassification>"
    Body should reference plans/2026-05-25-cmem-sdk-and-server-rename.md and the audit (62/62 SDK tests, 2094 full-suite, import guard clean).
  3. Watch CI: gh pr checks --watch. The gates are typecheck, build (bundle-size guardrails), Bun tests, and the Docker+Postgres+Valkey server-runtime e2e (ci.yml), plus Windows build (windows.yml).
  4. If a check fails, fix on the branch and push; re-run the local gate first. (Optional: the /claude-mem:babysit skill can monitor the PR until green.)

Verification checklist:

  • PR exists and targets main.
  • gh pr checks all green (ci.yml + windows.yml).
  • No bundle-size guardrail regression flagged.
  • PR description links the plan + audit.

Anti-pattern guards: don't merge with a red or pending required check. Don't disable the e2e gate to "save time."

Phase 4: Merge to main

What to implement: land the branch on main so the release can be cut from there.

Tasks:

  1. Merge the PR (squash vs merge-commit per repo norm — recent history shows merge commits for PRs, e.g. 84636894; default to the repo's standard merge button).
  2. Locally sync main:
    bash
    git checkout main && git pull origin main
  3. Sanity re-verify on main: npm run build && npm run typecheck (fast confidence check that the merged main builds before bumping).

Verification checklist:

  • PR shows merged; branch commits present in git log origin/main.
  • dist/sdk/index.js + dist/sdk/index.d.ts build on main; guard clean.
  • git status on main clean.

Anti-pattern guards: do not start the version bump until main contains the merge.

Phase 5: Cut release 13.5.0 via /version-bump (on main)

What to implement: invoke the version-bump skill to drive the full release. This is decision #2 — the skill owns manifests, build, commit, tag, push, publish, changelog, GitHub release.

Tasks:

  1. On main, run the skill: /claude-mem:version-bump and select minor → 13.5.0.
  2. The skill performs (confirm each as it goes):
    • Edit all 7 version manifests to 13.5.0.
    • npm run build-and-sync (build + bundle guard + local marketplace sync).
    • Commit chore: bump version to 13.5.0.
    • Tag v13.5.0 and git push origin main && git push origin v13.5.0.
    • Tag push triggers npm-publish.yml → npm publish (let CI publish; do not also npm publish locally).
    • gh release create v13.5.0 + npm run changelog:generate + commit/push CHANGELOG.
  3. Provide release notes highlighting the new claude-mem/sdk export (in-process capture→compress→semantic-search, no worker) and the server-beta→server rename (back-compat preserved).

Verification checklist:

  • git grep -n '"version": "13.5.0"' → 7 hits; '"version": "13.4.0"' → 0.
  • npm-publish.yml run for tag v13.5.0 succeeded.
  • npm view [email protected] version → 13.5.0.
  • GitHub release v13.5.0 exists; CHANGELOG.md updated and pushed.
  • Working tree on main clean.

Anti-pattern guards: do NOT manually npm publish (avoid double-publish with npm-publish.yml). Do NOT bump only package.json — all 7 manifests or the marketplace/ plugin installs drift. Do not run the skill on mutual-aardvark.

Phase 6: Final verification — prove it shipped

What to implement: confirm a real consumer can install and use claude-mem/sdk, and that docs are live.

Tasks:

  1. Scratch consumer install (prod-only, mirrors a real SDK consumer):
    bash
    mkdir /tmp/cmem-sdk-smoke && cd /tmp/cmem-sdk-smoke && npm init -y
npm install [email protected]
node -e "import('claude-mem/sdk').then(m => console.log('exports:', Object.keys(m)))"
    Expect createCmemClient (+ exported types) present; no install of express/bullmq/ ioredis/react in the tree (npm ls bullmq → absent).
  2. Run the plain-Node example examples/sdk-node/ against the test Postgres + uvx (per its README) — confirm it prints generated observations + search hits with no worker process running (this is the headline requirement from the original plan, Phase 9 gate #5).
  3. Docs: confirm docs/public/sdk.mdx is in the published nav (docs.json) and the Mintlify site auto-deployed from the main push (https://docs.claude-mem.ai/sdk).
  4. Clean up the scratch dir.

Verification checklist:

  • import('claude-mem/sdk') resolves from a fresh prod-only install of @13.5.0.
  • Heavy deps absent from the consumer tree (dep reclassification holds in the wild).
  • examples/sdk-node runs end-to-end (capture→compress→search) with no worker.
  • SDK docs page live at docs.claude-mem.ai.
  • npm view claude-mem dist-tags.latest = 13.5.0.

Anti-pattern guards: don't declare "shipped" off a local build — verify against the published @13.5.0 from the registry. Don't skip the no-worker example; it's the defining claim of the SDK.

One-glance ship sequence

  1. Phase 1 — commit audit cleanup on branch; local gate green (PG + uvx).
  2. Phase 2 — rebase onto origin/main; hand-resolve source, regenerate artifacts; re-verify.
  3. Phase 3 — force-push, open PR, CI green (Docker e2e + Windows).
  4. Phase 4 — merge to main; sync local main.
  5. Phase 5 — /version-bump minor → 13.5.0 (7 manifests, tag → CI publish, changelog, GH release).
  6. Phase 6 — prod-only scratch install of @13.5.0, run no-worker example, confirm docs live.