thedotmack-claude-mem/plans/2026-06-07-ship-cmem-sdk.md

# 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)

| Need | Command / location | Source |
|---|---|---|
| Build (full, incl. SDK + guard) | `npm run build` = sync-manifests → build-hooks → build:sdk → check:sdk-bundle | `package.json:65` |
| Build + test + local marketplace sync | `npm run build-and-sync` | `package.json:68` |
| Typecheck | `npm run typecheck` (`tsc --noEmit` ×2) | `package.json:103` |
| SDK bundle import guard | `node 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-bump` | skill 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 claude-mem@13.5.0 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 claude-mem@13.5.0
   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.