Releasing the SDK

@memory-soda/sdk is the only published package. The API and dashboard are deployed, not published; @memory-soda/types is private and bundled into the SDK’s declarations.

What ships

{
  "name": "@memory-soda/sdk",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist", "README.md"],
  "engines": { "node": ">=18" },
  "sideEffects": false,
  "publishConfig": { "access": "public" }
}

Built with tsup into dual ESM/CJS plus declarations. Zero runtime dependencies, it uses global fetch and AbortSignal.timeout, which is why Node 18 is the floor.

npm run sdk:build
ls packages/sdk/dist
# index.js  index.cjs  index.d.ts  index.d.cts  + maps

Publishing

Local, from the repo root (npm will prompt for your OTP):

# bump the version in packages/sdk/package.json first
npm run sdk:publish          # builds, then publishes @memory-soda/sdk
npm run installer:publish    # publishes create-memory-soda
git commit -am "chore(sdk): v0.3.0" && git tag v0.3.0 && git push origin main --tags

Check the tarball first:

cd packages/sdk && npm pack --dry-run

dist/ and README.md only. If src/ or node_modules/ appear, the files field has been broken.

Versioning

Semver, pre-1.0, so a minor bump may still break.

Change	Bump
New method or optional parameter	minor
Bug fix, docs, types	patch
Removed or renamed method	minor while `0.x`, major after
Changed response shape	minor while `0.x`, major after
Required parameter added	minor while `0.x`, major after

Coupling to the API

The SDK is a thin wrapper, so it is only compatible with an API that serves the endpoints it calls. There is no version negotiation and no capability discovery.

State the minimum API version in the changelog for any release that depends on a new endpoint or field. A self-hoster running an older API with a newer SDK will get a 404 or a silently missing field, with nothing to explain it.

Checklist

Smoke test

npm run sdk:build
npm link --workspace=packages/sdk

mkdir /tmp/sdk-smoke && cd /tmp/sdk-smoke && npm init -y
npm link @memory-soda/sdk

cat > test.mjs <<'EOF'
import { MemorySoda } from '@memory-soda/sdk';
const m = new MemorySoda({ baseUrl: 'http://localhost:3004', apiKey: process.env.KEY });
console.log(await m.health());
const { threadId } = await m.createThread({ dataset: 'smoke_test' });
await m.addMessage(threadId, { role: 'user', content: 'hello' });
console.log(await m.prepare(threadId));
console.log(await m.recall({ dataset: 'smoke_test' }));
EOF

KEY=ms_… node test.mjs

Check CJS too, since it is a separate build output:

node -e "const { MemorySoda } = require('@memory-soda/sdk'); console.log(typeof MemorySoda)"

Documentation

The SDK’s JSDoc is the source of truth for method behaviour, and developer-docs/sdk/ is written against it. When you change a signature, update:

The JSDoc block
The relevant SDK page
The type reference
The HTTP API page if the endpoint changed

Docs drifting from code is how a README ends up documenting three methods that do not exist. It has happened here before.

Deprecating

While 0.x, removal in a minor is permitted, but be kind:

/**
 * @deprecated Use `recall()` instead. Removed in 0.3.0.
 */
async oldMethod() {
  console.warn('[memory-soda] oldMethod() is deprecated; use recall(). Removed in 0.3.0.');
  return this.recall(/* … */);
}

Keep the alias for one minor release, note it in the changelog, then remove it.

Releasing the API and dashboard

Not published to a registry, deployed from source.

git pull && npm ci && npm run build
# restart the API; migrations run on boot with MIGRATE_ON_START=true

Take a database backup first. Migrations have no down path. See Migrations.

If a release includes a migration and you run several replicas, set MIGRATE_ON_START=false and migrate as an explicit deploy step.