# Codemem Versioning Policy Codemem uses one shared semantic version stream across its npm packages. ## Canonical packages - npm: `codemem` (CLI) - npm: `@codemem/opencode-plugin` (OpenCode plugin) - npm: `@codemem/pi-extension` (pi coding-agent extension) ## Policy - Release tags `vX.Y.Z` represent the product version. - npm packages publish the same `X.Y.Z`. - GitHub Release notes are shared per version. Keep notable changes in the root [CHANGELOG.md](../CHANGELOG.md), following Keep a Changelog: collect pending entries under `Unreleased`, group them by Added, Changed, Deprecated, Removed, Fixed, or Security, and move them under a dated version heading in the release PR. Omit empty categories, link versions to tag comparisons, and include compatibility or migration details when needed. Do not create per-version release-note documents or copy release announcements into the changelog. GitHub release announcements remain separate. The release workflow uses GitHub's generated PR list, contributor credits, and comparison link, configured by `.github/release.yml`; a human summary can be added to the GitHub release after publication. The comparison link shows the changes between tags, not a curated changelog. Retrying an older tag does not require changelog tooling in that tagged checkout. ## Release workflow Version bumps are prepared on `main`. A maintenance version bump is prepared through a PR into the matching `release/X.Y` branch and touches these files: - `packages/core/package.json` (`version`) - `packages/embeddings/package.json` (`version`) - `packages/cli/package.json` (`version`) - `packages/opencode-plugin/package.json` (`version`) - `packages/pi-extension/package.json` (`version`) - `packages/mcp-server/package.json` (`version`) - `packages/viewer-server/package.json` (`version`) - `packages/core/src/index.ts` (`VERSION` export) - `packages/core/src/index.test.ts` (version assertion) - `packages/cli/.opencode/plugins/codemem.js` (`PINNED_BACKEND_VERSION`) - `packages/opencode-plugin/.opencode/lib/runtime.js` (`PINNED_BACKEND_VERSION`) - `.claude-plugin/marketplace.json` (marketplace metadata version and codemem plugin entry version) - `plugins/claude/.claude-plugin/plugin.json` (Claude plugin metadata version and exact MCP `--package` pins for `codemem` and `@codemem/embeddings`) - `plugins/codex/.codex-plugin/plugin.json` (Codex plugin metadata version; also pins the `npx -y codemem@` fallback used by Codex hook scripts) - `plugins/codex/.mcp.json` (exact MCP `--package` pins for `codemem` and `@codemem/embeddings`) Both checked-in MCP launchers use the shared release version for both packages, including prereleases. Plugin metadata alone does not select an npm version: unversioned package specs resolve the registry's `latest` tag, which may still point to the previous stable release. The release helper checks these four pins and repairs unversioned specs even when the manifest already has the target version. It changes only the package specs in launcher arguments; the plain `codemem mcp` executable, timeouts, and unrelated arguments stay intact. Malformed launchers fail validation before any managed files are written. These pins apply only to the shipped Claude and Codex launchers, not user CLI setup or global configuration. Use the release version helper to verify or apply the bump: - `pnpm run release:version -- check` - `pnpm run release:version -- set X.Y.Z` Regenerate release artifacts before opening the release PR: - `pnpm install` (lockfile and generated artifacts when applicable) - `pnpm build` (viewer UI bundle/assets) Keep `.opencode/.npmrc` pinned to the public npm registry: - `registry=https://registry.npmjs.org/` ### First publication of a new package npm sets `latest` on a package's first-ever version regardless of `--tag`. A new package whose debut is a prerelease therefore exposes that prerelease to untagged installs (`npm install `). The release workflow cannot fix this automatically: OIDC trusted publishing grants `publish` only, not dist-tag mutation. Instead, a post-publish step runs `scripts/release-latest-guard.mjs` in verify mode and reports any package whose `latest` points at a prerelease. Attempt the cleanup from a machine with an npm login: ```fish node scripts/release-latest-guard.mjs --apply ``` The guard only removes; it never adds or moves `latest`, so an established package's stable `latest` is untouched. npm may reject removal when the prerelease is the package's only `latest` version; in that case, keep prerelease installs on explicit channel tags until the first stable release moves `latest`. The verify step is `continue-on-error` while any package is still dirty; flip it to a hard gate once the guard reports clean. ## Release tag preflight Before creating or pushing a release tag, run: ```bash pnpm run release:preflight-tag ``` This verifies release tagging safety in two contexts: - local preflight accepts a clean `main` checkout only when `HEAD` equals the freshly fetched `origin/main` HEAD. It also accepts a clean `release/X.Y` checkout only when `HEAD` equals the freshly fetched `origin/release/X.Y` HEAD and the package and tag versions share that `X.Y` series. - CI tag workflow accepts a tagged commit that is reachable from remote `main`, or from the exact remote branch `release/X.Y` matching the `RELEASE_TAG` major/minor series. The branch may have advanced since the tag was pushed. When `RELEASE_TAG` is supplied, its version must equal the core package version at the tagged commit. Cached remote-tracking refs do not authorize a missing remote branch. Feature branches, unmerged commits, stale branch heads, and release branches for another version series fail preflight. The maintenance branch name is exact: use `release/0.47`, not `release/0.47.0`. For a stable release, merge the release PR into `main`, verify that `HEAD` is the merged release commit, and then tag it. For a maintenance release, prepare aligned versions in a PR targeting the matching `release/X.Y` branch. After the PR passes CI and merges, update that branch locally, run preflight, and tag the merged commit. After a successful stable `vX.Y.0` publication, the workflow creates `release/X.Y` at the tagged commit when that branch is absent. It never moves an existing branch and does not create branches for patch or prerelease publications. This automation starts with the updated workflow. It does not apply retroactively to existing branches, including the separately created `release/0.47` branch. When a higher stable version is already tagged, an older maintenance release publishes under the npm tag `maintenance-X.Y` and is not marked Latest on GitHub. For example, after `v0.48.0` is tagged, `v0.47.4` publishes under `maintenance-0.47` so it does not move npm's `latest` backward. Install that maintenance version explicitly or use its series tag. Run stable releases one at a time across version series. Finish the newer stable release before tagging an older maintenance release so its workflow sees the newer tag when choosing an npm channel. Stable publication requires the tagged checkout to contain the history-aware dist-tag helper. A retry of an older stable tag without that helper stops before publishing packages. Prepare a new maintenance release with the updated tooling rather than moving an existing tag. ## Release discovery `codemem update check` derives the release channel from the installed version and queries the fixed public npm registry endpoint for the matching dist-tag: alpha uses `alpha`, beta uses `beta`, release candidates use `rc`, and a stable version uses `latest`. Registry responses, status output, guidance, and cache records must match that channel. Results are cached locally for six hours; use `--refresh` to bypass a fresh cache and `--json` for the additive automation contract. Existing stable-only cache records remain valid for stable installations, but no cache or in-process result is reused across channels. If a refresh fails, a previously validated same-channel cache may be returned as stale guidance. A running process backs off failed registry checks for 15 minutes, while `--refresh` bypasses that backoff. `codemem update check` remains informational. It detects a semver-qualified `mise/installs/npm-codemem//` layout from the resolved CLI entry path, or the equivalent layout beneath a normalized `MISE_DATA_DIR`, and reports `mise use -g npm:codemem@` for that installation kind. It also recognizes canonical pnpm global virtual-store entries from resolved paths and reports the exact paired `pnpm add -g codemem@ @codemem/embeddings@` command. Those path markers do not prove pnpm package ownership. `codemem update install` separately requires fresh validated status. Proven npm-global installations retain the 24-hour first-seen delay and install exact matching `codemem` and `@codemem/embeddings` versions with an argv-only npm command. Before mutation, proven mise installations compare bounded machine-readable active and global source records and require current install-path ownership. A recognized user-level `~/.config/mise.toml` source may migrate when the bounded global query succeeds with an empty result. The matching source must resolve within the user's home directory; system, unresolved, and ambiguous custom paths fail closed. Matching evidence authorizes codemem to execute the exact reported `mise use -g` command without a shell, inherited environment, and pinned public default and `@codemem` registries; Linux also sets `ONNXRUNTIME_NODE_INSTALL=skip`. This writes the exact release into the primary global config, so a declaration may move from user `conf.d` or `~/.config/mise.toml` to `config.toml`. Mise verification re-reads bounded global state, requires an exact target `version` or `requested_version` value, and runs `mise exec -- codemem --version` outside the invoking project; npm-global verification uses the active CLI. For pnpm-global installations, the explicit installer uses bounded, no-shell `pnpm root -g`, `pnpm bin -g`, and `pnpm list -g --depth 0 --json` calls from a neutral directory immediately before mutation. It requires `pnpm root -g` to equal the list root (pnpm 12) or its `node_modules` directory (pnpm 9–11), the canonical registered Codemem package to remain under that list root, and that package to own the resolved JavaScript entry. It then installs exact matching paired packages using public default and scoped registry flags and verifies exact registered package versions plus the specific pnpm-bin launcher. The updater never runs a build-approval command; pnpm 9 still runs install scripts by default, while newer releases apply their configured build-script policy. Bare `codemem update` remains non-mutating. Installing an alpha, beta, or release candidate is explicit opt-in, so the existing auto-update policy may install a delayed eligible update within that installed channel. Installation refuses pinned, cross-channel, unsupported-prerelease, downgrade, development, stale, Docker, and unknown states. The npm-global updater always installs exact matching `codemem` and `@codemem/embeddings` versions. The npm operation runs the packages' installation scripts for native CPU dependencies, just as a manual global install does. Mise remains ineligible for background auto-update because its command changes declarative global tool configuration; only a direct user install command may authorize that change, and a local source that overrides the global source is refused with manual global-update guidance. pnpm-global is also never eligible for plugin background auto-install; it supports notifications and the direct `codemem update install` path only. Release discovery compares the running product version with the latest release on its channel. It is separate from the compatibility-floor check below: discovering a newer release does not change whether the current CLI satisfies the plugin's minimum supported version. ## Compatibility-floor check The OpenCode 1 plugin performs a runtime CLI version check and warns if the local CLI is below `CODEMEM_MIN_VERSION` (default `0.9.20`). The compatibility reaction is controlled by `CODEMEM_BACKEND_UPDATE_POLICY`: - `notify` (default): warn with an upgrade hint - `auto`: attempt a best-effort same-channel update for eligible npm runners and delayed releases, then re-check - `off`: suppress compatibility toasts This check enforces a minimum supported CLI version. It does not query the npm registry or report the latest available release, and its existing policy and update behavior are unchanged by release discovery. ## OpenCode host compatibility Codemem 0.45 raises the minimum supported OpenCode 1 host to 1.18.29. The `@codemem/opencode-plugin` package records this floor through `engines.opencode`, which OpenCode checks when loading npm plugins, and CI runs the V1 plugin suite against that exact SDK release. The packed-artifact smoke also installs OpenCode 1.18.30 and requires the dual entrypoint to complete the host's non-pure startup path. The package default export changes from a callable V1 plugin function to the documented dual-host object; named V1 exports remain available for integrations that invoke the function directly. This is a breaking host-compatibility change from Codemem 0.44; upgrade OpenCode before installing the 0.45 plugin. Dependabot continues to propose SDK updates, but accepting one requires updating all checked-in SDK pins together. The published dependency and both nested runtime manifests use the same exact SDK version; that version can be newer than the supported host floor. CI explicitly installs the minimum SDK with `--no-save` and keeps the minimum host gate and `engines.opencode` fixed at 1.18.29 until the documented compatibility floor changes. The ignored `.opencode/package.json` is only a local contributor runtime and is not a release pin. Refresh it when testing the minimum host locally: ```fish npm install --prefix .opencode --save-exact @opencode-ai/plugin@1.18.29 ``` The same 0.45 package also runs on OpenCode 2 through its `setup()` entrypoint. Codemem validates that path against the exact stable `@opencode/cli@2.0.24` and `@opencode/plugin@2.0.24` releases and labels its OpenCode 2 integration beta. `codemem setup --opencode-only` keeps writing the singular `plugin` key because OpenCode 1 requires it and OpenCode 2 translates it. Required CI gates run only against the 1.18.29 floor and the exact 2.0.24 pin; any compatibility run against a newer or moving OpenCode release is advisory and never blocks a Codemem change until the pin moves in its own reviewed PR. Rollback is a host-edge change: disable the V2 path with `CODEMEM_PLUGIN_IGNORE=1` or return to OpenCode 1 without any database migration. The OpenCode 2 contract separately pins matching `@opencode/cli@2.0.24` and `@opencode/plugin@2.0.24` packages. The workspace allows the CLI package's postinstall because it installs the matching platform binary used by the packed-host smoke test. The 2.0.24 postinstall is byte-identical to the independently reviewed 2.0.2 script. It selects an exact optional platform package, detects AVX2 support with `sysctl` on macOS or PowerShell on Windows, and hard-links or copies its binary. If the optional package is absent, it installs that exact package in a temporary directory before copying and verifying the binary. Re-review the postinstall whenever the exact pin changes. Update both revisions together and rerun the executable checks documented in [the OpenCode 2 contract](opencode-v2-contract.md); do not replace these pins with a moving tag or semver range. The approved minimum-release-age exception covers only the exact OpenCode 2.0.24 packages listed in `pnpm-workspace.yaml`. Remove those exceptions once the versions clear the configured release-age window. Override for testing: ```bash export CODEMEM_MIN_VERSION=0.9.20 ``` ## Pi host compatibility Codemem requires Pi 1.1.0 or newer, below 2.0. The `@codemem/pi-extension` package records this floor as its declared host peer (`@earendil-works/pi-coding-agent` `>=1.1.0 <2`). This is a breaking host-compatibility change from the previous `>=0.84.1 <1` peer: Pi 0.x hosts must upgrade before installing. `pi update` replaces the Pi host; `pi update --extensions` only reconciles installed packages. A Nix installation cannot update itself with `pi update`; use the official installer flow or `nix profile upgrade pi`. Native tools stay the setup default with 15 `memory_*` tools, and the explicit `native` and `mcp-adapter` modes are unchanged. ## Transition notes - `codemem` is the CLI package on npm. - `@codemem/opencode-plugin` is the OpenCode plugin identifier.