feat(release): standardize package tags and add release automation

.github/workflows/build.yml

@@ -297,22 +297,38 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Extract metadata
-        id: meta
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=raw,value=latest,enable={{is_default_branch}}
-            type=sha,format=long
+      - name: Compute image tags
+        id: prep
+        run: |
+          image="$(printf '%s' "${REGISTRY}/${IMAGE_NAME}" | tr '[:upper:]' '[:lower:]')"
+          sha_tag="${image}:sha-${GITHUB_SHA}"
+          raw_version="$(sed -n 's/^ARG UPSTREAM_VERSION=//p' Dockerfile | head -n1)"
+          upstream_version="${raw_version%%@*}"
+          aio_track="aio-v1"
+
+          {
+            echo "upstream_version=${upstream_version}"
+            echo "tags<<EOF"
+            echo "${image}:latest"
+            if [[ -n "${upstream_version}" ]]; then
+              echo "${image}:${upstream_version}"
+              echo "${image}:${upstream_version}-${aio_track}"
+            fi
+            echo "${sha_tag}"
+            echo "EOF"
+          } >> "${GITHUB_OUTPUT}"
 
       - name: Build and push Docker image
         uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
         with:
           context: .
           push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
+          tags: ${{ steps.prep.outputs.tags }}
+          labels: |
+            org.opencontainers.image.source=https://github.com/JSONbored/mem0-aio
+            org.opencontainers.image.title=mem0-aio
+            org.opencontainers.image.version=${{ steps.prep.outputs.upstream_version || '' }}
+            io.jsonbored.upstream.name=Mem0
           platforms: ${{ env.PUBLISH_PLATFORMS }}
           cache-from: type=gha
           cache-to: type=gha,mode=max

.github/workflows/release.yml

@@ -0,0 +1,96 @@
+name: Release / mem0-aio
+
+on:
+  workflow_dispatch:
+  pull_request_target:
+    types: [closed]
+
+jobs:
+  prepare-release:
+    if: ${{ github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+      - name: Install git-cliff
+        env:
+          GIT_CLIFF_VERSION: 2.12.0
+        run: |
+          archive="git-cliff-${GIT_CLIFF_VERSION}-x86_64-unknown-linux-gnu.tar.gz"
+          curl -fsSL -o "/tmp/${archive}" "https://github.com/orhun/git-cliff/releases/download/v${GIT_CLIFF_VERSION}/${archive}"
+          tar -xzf "/tmp/${archive}" -C /tmp
+          install "/tmp/git-cliff-${GIT_CLIFF_VERSION}/git-cliff" /usr/local/bin/git-cliff
+      - name: Compute release version
+        id: version
+        run: echo "release_version=$(python3 scripts/release.py next-version)" >> "${GITHUB_OUTPUT}"
+      - name: Generate changelog
+        env:
+          GITHUB_REPO: ${{ github.repository }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_VERSION: ${{ steps.version.outputs.release_version }}
+        run: git-cliff --config cliff.toml --tag "${RELEASE_VERSION}" --output CHANGELOG.md
+      - name: Create release PR
+        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
+        with:
+          commit-message: "chore(release): ${{ steps.version.outputs.release_version }}"
+          title: "chore(release): ${{ steps.version.outputs.release_version }}"
+          body: |
+            This PR prepares `${{ steps.version.outputs.release_version }}`.
+          branch: "release/${{ steps.version.outputs.release_version }}"
+          delete-branch: true
+
+  publish-release-on-merge:
+    if: "${{ github.event_name == 'pull_request_target' && github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'main' && startsWith(github.event.pull_request.title, 'chore(release): ') }}"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout merge commit
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ github.event.pull_request.merge_commit_sha }}
+          fetch-depth: 0
+      - name: Determine release version
+        id: version
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          release_version="${PR_TITLE#chore(release): }"
+          echo "release_version=${release_version}" >> "${GITHUB_OUTPUT}"
+          test "$(python3 scripts/release.py latest-changelog-version)" = "${release_version}"
+      - name: Extract release notes
+        id: notes
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.release_version }}
+        run: |
+          {
+            echo "release_notes<<EOF"
+            python3 scripts/release.py extract-release-notes "${RELEASE_VERSION}"
+            echo "EOF"
+          } >> "${GITHUB_OUTPUT}"
+      - name: Create Git tag if missing
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.release_version }}
+          MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
+        run: |
+          if git rev-parse "${RELEASE_VERSION}" >/dev/null 2>&1; then exit 0; fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag "${RELEASE_VERSION}" "${MERGE_SHA}"
+          git push origin "${RELEASE_VERSION}"
+      - name: Publish GitHub release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_VERSION: ${{ steps.version.outputs.release_version }}
+          RELEASE_NOTES: ${{ steps.notes.outputs.release_notes }}
+          MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
+        run: |
+          if gh release view "${RELEASE_VERSION}" >/dev/null 2>&1; then exit 0; fi
+          notes_file="$(mktemp)"
+          printf '%s\n' "${RELEASE_NOTES}" > "${notes_file}"
+          gh release create "${RELEASE_VERSION}" --title "${RELEASE_VERSION}" --notes-file "${notes_file}" --target "${MERGE_SHA}"

AGENTS.md

@@ -1,29 +1,40 @@
-# mem0-aio Agent Notes
+# AGENTS.md
 
-`mem0-aio` packages OpenMemory / Mem0 as a single Unraid container with an embedded Qdrant vector store.
+This repository is part of a broader portfolio of Unraid-first AIO projects.
 
-## Runtime Shape
+## Repository intent
 
-- OpenMemory web UI
-- OpenMemory API / MCP service
-- Internal Qdrant for vector storage
-- Same-origin UI-to-API default flow for simple Unraid installs
+- This repo packages an opinionated, beginner-friendly Unraid AIO deployment.
+- Default behavior should optimize for a reliable first boot on Unraid.
+- Advanced users should retain escape hatches where supported.
 
-## Important Behavior
+## Engineering expectations
 
-- The vendored `openmemory` submodule is part of the upstream tracking story here.
-- `upstream.toml` uses `submodule_path = "openmemory"`.
-- Beginner installs should work with internal Qdrant by default.
-- A placeholder `OPENAI_API_KEY` fallback exists only to keep startup stable; real memory generation still needs a valid provider.
+- Prefer consistency with `unraid-aio-template` over one-off repo behavior.
+- Keep CI and release behavior aligned with the rest of the AIO fleet.
+- Respect protected branches and use PR-based automation for external sync flows.
+- Favor operational clarity over cleverness.
 
-## CI And Publish Policy
+## Release model
 
-- Validation and smoke tests should run on PRs and branch pushes.
-- Publish should happen only from the default branch.
-- GHCR image naming must stay lowercase.
+- Container packages publish automatically from `main`.
+- Formal changelog updates and GitHub Releases are release-driven.
+- Releases use `upstream version + aio revision`, for example `v1.0.9-aio.1`.
+- Keep changelog-friendly Conventional Commit titles and PR titles.
 
-## What To Preserve
+## Unraid expectations
 
-- Keep the browser experience single-origin by default.
-- Keep Qdrant internal unless a user explicitly overrides storage strategy.
-- Smoke tests should validate restart and persistence, not just the first boot.
+- Unraid-facing XML/icon assets should stay aligned with `awesome-unraid`.
+- User-facing metadata should remain accurate:
+  - `Project`
+  - `Support`
+  - `TemplateURL`
+  - `Icon`
+  - `Overview`
+  - `Category`
+
+## Documentation expectations
+
+- Be explicit about operational tradeoffs.
+- Do not imply the AIO model removes inherent complexity from the upstream software.
+- Keep beginner defaults simple, but document power-user override paths where they exist.

README.md

@@ -54,6 +54,14 @@ Local validation completed on March 29, 2026:
 - restart and persistence smoke coverage added
 - workflow hardening added with pinned action SHAs, dependency review, and upstream release tracking
 
+## Releases
+
+`mem0-aio` uses upstream-version-plus-AIO-revision releases such as `v1.0.9-aio.1`.
+
+Every `main` build publishes `latest`, the exact pinned upstream version, an explicit packaging line tag, and `sha-<commit>`.
+
+See [docs/releases.md](/Users/shadowbook/Documents/mem0-aio/docs/releases.md) for the release workflow details.
+
 ## Support
 
 - Issues: [JSONbored/mem0-aio issues](https://github.com/JSONbored/mem0-aio/issues)

cliff.toml

@@ -0,0 +1,46 @@
+[changelog]
+header = """
+# Changelog
+
+All notable changes to this project will be documented in this file.
+"""
+body = """
+{% if version %}## {{ version }} - {{ timestamp | date(format="%Y-%m-%d") }}{% else %}## Unreleased{% endif %}
+{% for group, commits in commits | group_by(attribute="group") -%}
+### {{ group }}
+{% for commit in commits -%}
+- {{ commit.message | split(pat="\n") | first | trim | upper_first }}
+{% endfor %}
+{% if not loop.last %}\n{% endif -%}
+{% endfor -%}
+"""
+trim = true
+footer = "<!-- generated by git-cliff -->"
+
+[git]
+conventional_commits = true
+filter_unconventional = false
+require_conventional = false
+split_commits = false
+protect_breaking_commits = true
+tag_pattern = '^v?[0-9].*-aio\\.[0-9]+$'
+sort_commits = "oldest"
+commit_preprocessors = [
+  { pattern = " \\(#\\d+\\)$", replace = "" },
+]
+commit_parsers = [
+  { message = "^Merge pull request", skip = true },
+  { message = "^chore\\(release\\):", skip = true },
+  { message = "^feat", group = "Features" },
+  { message = "^fix", group = "Fixes" },
+  { message = "^perf", group = "Performance" },
+  { message = "^refactor", group = "Refactors" },
+  { message = "^docs?", group = "Documentation" },
+  { message = "^ci", group = "CI" },
+  { message = "^test", group = "Tests" },
+  { message = "^build", group = "Build" },
+  { message = "^chore\\(deps", group = "Dependency Updates" },
+  { message = "^chore", group = "Maintenance" },
+  { message = "^revert", group = "Reverts" },
+  { message = "^[A-Z].*", group = "Other Changes" },
+]

docs/releases.md

@@ -0,0 +1,19 @@
+# Releases
+
+`mem0-aio` uses upstream-version-plus-AIO-revision releases such as `v1.0.9-aio.1`.
+
+## Published image tags
+
+Every `main` build publishes:
+
+- `latest`
+- the exact pinned upstream version
+- an explicit packaging line tag like `v1.0.9-aio-v1`
+- `sha-<commit>`
+
+## Release flow
+
+1. Trigger **Release / mem0-aio** from `main`.
+2. The workflow computes the next `upstream-aio.N` version and opens a release PR.
+3. Merge that PR into `main`.
+4. After merge, the workflow creates the Git tag and GitHub Release automatically.