/release

/release - Create Stable Release

Create a stable release using the automated justfile target with comprehensive validation.

Usage

/release <version>

**Parameters:**

• `version` (required): Release version like `v0.13.2`

Implementation

You are an expert release manager for the Basic Memory project. When the user runs `/release`, execute the following steps:

Step 1: Pre-flight Validation

Version Check

1. Check current version in `src/basic_memory/__init__.py` 2. Verify new version format matches `v\d+\.\d+\.\d+` pattern 3. Confirm version is higher than current version

Git Status

1. Check current git status for uncommitted changes 2. Verify we're on the `main` branch 3. Confirm no existing tag with this version

Documentation Validation

1. **Changelog Check**

• CHANGELOG.md contains entry for target version **already landed on `main`**

(main only accepts changes via PR, so the changelog entry must go through its own PR before running the release; the recipe pre-flight-checks for a `## vX.Y.Z` heading)

• Entry includes all major features and fixes
• Breaking changes are documented

Step 2: Use Justfile Automation

Execute the automated release process:

just release <version>

The justfile target handles:

• ✅ Version format validation
• ✅ Git status and branch checks
• ✅ Changelog entry check (must already be on `main`)
• ✅ Quality checks (`just lint` + `just typecheck`)
• ✅ Version update across all consolidated manifests via `just set-version` (Python

package + Claude Code plugin/marketplaces + Codex plugin + Hermes + OpenClaw)

• ✅ Release PR: commits the bump on a `release/vX.Y.Z` branch, opens a PR

(`chore(core): release vX.Y.Z`), and rebase-merges it — the `main` ruleset rejects direct pushes and the repo disallows merge commits

• ✅ Tags the rebased bump commit on `main` (found by commit subject, since

the rebase rewrites the SHA) and pushes the tag

• ✅ Release workflow trigger (automatic on tag push)

The GitHub Actions workflow (`.github/workflows/release.yml`) then:

• ✅ Builds the package using `uv build`
• ✅ Creates GitHub release with auto-generated notes
• ✅ Publishes to PyPI
• ✅ Updates Homebrew formula (stable releases only)

Step 3: Monitor Release Process

1. Verify tag push triggered the workflow (should start automatically within seconds) 2. Monitor workflow progress at: https://github.com/basicmachines-co/basic-memory/actions 3. Watch for successful completion of both jobs:

• `release` - Builds package and publishes to PyPI
• `homebrew` - Updates Homebrew formula (stable releases only)

4. Check for any workflow failures and investigate logs if needed

Step 4: Post-Release Validation

GitHub Release

1. Verify GitHub release is created at: https://github.com/basicmachines-co/basic-memory/releases/tag/<version> 2. Check that release notes are auto-generated from commits 3. Validate release assets (`.whl` and `.tar.gz` files are attached)

PyPI Publication

1. Verify package published at: https://pypi.org/project/basic-memory/<version>/ 2. Test installation: `uv tool install basic-memory --prerelease=allow` 3. Verify installed version: `basic-memory --version`

Homebrew Formula (Stable Releases Only)

1. Check formula update at: https://github.com/basicmachines-co/homebrew-basic-memory 2. Verify formula version matches release 3. Test Homebrew installation: `brew install basicmachines-co/basic-memory/basic-memory`

MCP Registry Publication

After PyPI release is published, update the MCP registry:

1. **Verify PyPI Release**

• Confirm package is live: https://pypi.org/project/basic-memory/<version>/
• The `server.json` version was auto-updated by `just release`

2. **Publish to MCP Registry**

   gh workflow run mcp-registry-publish.yml

The workflow authenticates with GitHub Actions OIDC. Do not run `mcp-publisher` locally; the manual `mcp-publisher login github` path is unreliable for this namespace.

3. **Verify Publication**

   curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=basic-memory"

Website Updates

**1. basicmemory.com** (sibling `basicmemory.com` repo — `basicmachines-co/basicmemory.com`, formerly `basicmachines.co`)

• **No version bump needed.** The marketing site is an Astro + React app and

carries **no hardcoded Basic Memory version number** anywhere in its UI (`hero.tsx` and the rest of the site have no version string). Release announcements are dated blog posts, not an in-place edit.

• **Skip entirely for patch releases.**
• **Significant releases only — optional announcement post**:

1. Pull latest from GitHub: `git pull origin main` 2. Create release branch: `git checkout -b release/v{VERSION}` 3. Add a dated post under `src/content/blog/` modeled on an existing release post (e.g. `basic-memory-v0-19-0-release.md`), summarizing 3–5 headline features from `CHANGELOG.md` 4. Commit (`git commit -s -m "..."`), push, and open a PR against `basicmachines-co/basicmemory.com`

• **Deploy**: follow that repo's deployment process.

**2. docs.basicmemory.com** (sibling `docs.basicmemory.com` repo)

• **Goal**: Add a What's New page for the release and bump the homepage badge
• **Site shape**: Nuxt/Docus content site. The changelog page

(`content/2.whats-new/*.changelog.md`) auto-fetches GitHub releases — no manual changelog update needed. See that repo's CLAUDE.md "Version Bump Checklist".

• **What to do**:

1. Pull latest from GitHub: `git pull origin main` 2. Create release branch: `git checkout -b release/v{VERSION}` 3. Read `CHANGELOG.md` in the `basic-memory` repo to get release content 4. **New minor/major release**: add `content/2.whats-new/1.v{VERSION}.md` modeled on the previous version page (frontmatter title/description, headline feature first, t