From 52c09612ebebb8c7a0900af8a10f463594dae461 Mon Sep 17 00:00:00 2001
From: Willi Budzinski <w.budzinski@telekom.de>
Date: Fri, 19 Jun 2026 05:49:55 +0200
Subject: [PATCH] fix: pin mcp shim to matching core

---
 AGENTS.md                                     |   2 +-
 CONTRIBUTING.md                               |   4 +-
 README.md                                     |   2 +-
 deploy/Dockerfile                             |   2 +-
 deploy/README.md                              |   4 +-
 deploy/coolify/Dockerfile                     |   2 +-
 deploy/coolify/README.md                      |   2 +-
 deploy/coolify/docker-compose.yml             |   2 +-
 deploy/fly/Dockerfile                         |   2 +-
 deploy/fly/README.md                          |   2 +-
 deploy/fly/fly.toml                           |   2 +-
 deploy/helm/agentmemory/Chart.yaml            |   2 +-
 deploy/helm/agentmemory/README.md             |   8 +-
 deploy/helm/agentmemory/values.yaml           |   2 +-
 deploy/railway/Dockerfile                     |   2 +-
 deploy/railway/README.md                      |   4 +-
 deploy/render/Dockerfile                      |   2 +-
 deploy/render/README.md                       |   2 +-
 deploy/render/render.yaml                     |   2 +-
 .../plan.md                                   | 105 ++++++++++++++++++
 .../todo.md                                   |  93 ++++++++++++++++
 integrations/openclaw/openclaw.plugin.json    |   2 +-
 integrations/openclaw/package.json            |   2 +-
 integrations/openclaw/plugin.yaml             |   2 +-
 package.json                                  |   2 +-
 packages/mcp/package.json                     |   4 +-
 plugin/.claude-plugin/plugin.json             |   2 +-
 plugin/.codex-plugin/plugin.json              |   2 +-
 plugin/.factory-plugin/plugin.json            |   2 +-
 plugin/plugin.json                            |   2 +-
 pnpm-lock.yaml                                |   2 +-
 src/functions/export-import.ts                |   2 +-
 src/types.ts                                  |   2 +-
 src/version.ts                                |   2 +-
 test/export-import.test.ts                    |   2 +-
 test/plugin-surface-contract.test.ts          |   5 +-
 test/quality-gates.test.ts                    |   4 +-
 37 files changed, 244 insertions(+), 43 deletions(-)
 create mode 100644 docs/todos/2026-06-19-issue-267-pin-mcp-core-version/plan.md
 create mode 100644 docs/todos/2026-06-19-issue-267-pin-mcp-core-version/todo.md

diff --git a/AGENTS.md b/AGENTS.md
index 40af4b601..b8a8c0bc4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -115,7 +115,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).
 - Test files go in `test/` with `.test.ts` extension
 - Follow existing patterns in `test/crystallize.test.ts` for function tests
 
-## Current Stats (v0.9.27)
+## Current Stats (v0.9.28)
 
 - 61 MCP tools (8 visible by default, `AGENTMEMORY_TOOLS=all` for all)
 - 134 REST endpoints
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1cde56b35..af3510702 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -98,13 +98,13 @@ Maintainers cut releases. Every bump touches 9 release surfaces in lockstep:
 2. `pnpm-lock.yaml` (resolved graph after the version bump)
 3. `plugin/.claude-plugin/plugin.json`
 4. `plugin/plugin.json`
-5. `packages/mcp/package.json` (self version; keep the source dependency as `workspace:~`)
+5. `packages/mcp/package.json` (self version; keep the source dependency as `workspace:*`)
 6. `src/version.ts` (extend the union, assign)
 7. `src/types.ts` (`ExportData.version` union)
 8. `src/functions/export-import.ts` (`supportedVersions` Set)
 9. `test/export-import.test.ts` (assertion)
 
-Then: `corepack pnpm install --lockfile-only --ignore-scripts`, package dry-runs, CHANGELOG section, PR, merge, tag, GitHub release. The `Publish to npm` workflow picks up the release trigger and publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance. The MCP shim is packed and published with pnpm so `workspace:~` is rewritten to the npm consumer semver range.
+Then: `corepack pnpm install --lockfile-only --ignore-scripts`, package dry-runs, CHANGELOG section, PR, merge, tag, GitHub release. The `Publish to npm` workflow picks up the release trigger and publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance. The MCP shim is packed and published with pnpm so `workspace:*` is rewritten to the exact matching npm dependency version.
 
 ## Security issues
 
diff --git a/README.md b/README.md
index 5401d34ad..b31fc83b0 100644
--- a/README.md
+++ b/README.md
@@ -872,7 +872,7 @@ npx -y @agentmemory/mcp
 <h2 id="deploy">Deploy</h2>
 
 Managed-host templates and setup guides run the shared
-`ghcr.io/wbugitlab1/agentmemory:0.9.27` image, built from the canonical
+`ghcr.io/wbugitlab1/agentmemory:0.9.28` image, built from the canonical
 `deploy/Dockerfile` after npm publication succeeds. Persistent storage
 mounts at `/data`; the first-boot entrypoint overwrites the
 npm-bundled iii config (which binds `127.0.0.1`) with a deploy-tuned
diff --git a/deploy/Dockerfile b/deploy/Dockerfile
index ae42e10b8..839d380d0 100644
--- a/deploy/Dockerfile
+++ b/deploy/Dockerfile
@@ -4,7 +4,7 @@ FROM iiidev/iii:${III_VERSION} AS iii-image
 
 FROM node:22-slim
 
-ARG AGENTMEMORY_VERSION=0.9.27
+ARG AGENTMEMORY_VERSION=0.9.28
 ARG III_VERSION=0.11.2
 ARG III_SDK_VERSION=0.11.2
 
diff --git a/deploy/README.md b/deploy/README.md
index 08117fb92..9e3403250 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -3,7 +3,7 @@
 Stand up agentmemory on managed infrastructure without rolling your own
 Docker host, or bring the same runtime model to Kubernetes with Helm.
 The managed-platform templates run the shared
-`ghcr.io/wbugitlab1/agentmemory:0.9.27` image built from
+`ghcr.io/wbugitlab1/agentmemory:0.9.28` image built from
 `deploy/Dockerfile` after npm publication succeeds. Storage mounts at
 `/data`; an HMAC secret is generated by the first-boot entrypoint and
 persisted to the volume. The entrypoint overwrites the npm-bundled iii
@@ -56,7 +56,7 @@ before exec'ing the agentmemory CLI.
 - Pick **Kubernetes / Helm** if you already operate a cluster and want
   a chart-managed Deployment, PVC, Service, optional Ingress, and
   NetworkPolicy. The chart defaults to
-  `ghcr.io/wbugitlab1/agentmemory:0.9.27`; override
+  `ghcr.io/wbugitlab1/agentmemory:0.9.28`; override
   `image.repository` only for a private fork image.
 
 All deployments give you the same agentmemory API at the same port
diff --git a/deploy/coolify/Dockerfile b/deploy/coolify/Dockerfile
index ae42e10b8..839d380d0 100644
--- a/deploy/coolify/Dockerfile
+++ b/deploy/coolify/Dockerfile
@@ -4,7 +4,7 @@ FROM iiidev/iii:${III_VERSION} AS iii-image
 
 FROM node:22-slim
 
-ARG AGENTMEMORY_VERSION=0.9.27
+ARG AGENTMEMORY_VERSION=0.9.28
 ARG III_VERSION=0.11.2
 ARG III_SDK_VERSION=0.11.2
 
diff --git a/deploy/coolify/README.md b/deploy/coolify/README.md
index 147d62ac5..18c983ef2 100644
--- a/deploy/coolify/README.md
+++ b/deploy/coolify/README.md
@@ -5,7 +5,7 @@ Heroku/Render alternative that you run on your own VPS. This template
 deploys agentmemory as a Coolify *Application* backed by a Docker
 Compose stack — Coolify handles TLS termination, persistent volume
 provisioning, log aggregation, and the deploy webhook for you. The
-compose file pulls `ghcr.io/wbugitlab1/agentmemory:0.9.27`.
+compose file pulls `ghcr.io/wbugitlab1/agentmemory:0.9.28`.
 
 ## What you get
 
diff --git a/deploy/coolify/docker-compose.yml b/deploy/coolify/docker-compose.yml
index ab3680ba1..e24eab410 100644
--- a/deploy/coolify/docker-compose.yml
+++ b/deploy/coolify/docker-compose.yml
@@ -1,6 +1,6 @@
 services:
   agentmemory:
-    image: ghcr.io/wbugitlab1/agentmemory:0.9.27
+    image: ghcr.io/wbugitlab1/agentmemory:0.9.28
     restart: unless-stopped
     environment:
       SERVICE_FQDN_AGENTMEMORY_3111: ${SERVICE_FQDN_AGENTMEMORY_3111}
diff --git a/deploy/fly/Dockerfile b/deploy/fly/Dockerfile
index d96b76869..50053429d 100644
--- a/deploy/fly/Dockerfile
+++ b/deploy/fly/Dockerfile
@@ -4,7 +4,7 @@ FROM iiidev/iii:${III_VERSION} AS iii-image
 
 FROM node:22-slim
 
-ARG AGENTMEMORY_VERSION=0.9.27
+ARG AGENTMEMORY_VERSION=0.9.28
 ARG III_VERSION=0.11.2
 ARG III_SDK_VERSION=0.11.2
 
diff --git a/deploy/fly/README.md b/deploy/fly/README.md
index 6c43f1ace..50b2742dd 100644
--- a/deploy/fly/README.md
+++ b/deploy/fly/README.md
@@ -4,7 +4,7 @@ This template runs agentmemory on a single fly.io machine with a 1 GB
 persistent volume mounted at `/data`. The HMAC secret is generated on
 first boot and persisted to the volume. Retrieve it through `fly ssh`;
 the secret value is not printed to deploy logs. The default Fly config
-deploys `ghcr.io/wbugitlab1/agentmemory:0.9.27`.
+deploys `ghcr.io/wbugitlab1/agentmemory:0.9.28`.
 
 ## What you get
 
diff --git a/deploy/fly/fly.toml b/deploy/fly/fly.toml
index da992471f..8e13e48f1 100644
--- a/deploy/fly/fly.toml
+++ b/deploy/fly/fly.toml
@@ -12,7 +12,7 @@ app = "agentmemory"
 primary_region = "iad"
 
 [build]
-  image = "ghcr.io/wbugitlab1/agentmemory:0.9.27"
+  image = "ghcr.io/wbugitlab1/agentmemory:0.9.28"
 
 [[mounts]]
   source = "agentmemory_data"
diff --git a/deploy/helm/agentmemory/Chart.yaml b/deploy/helm/agentmemory/Chart.yaml
index 3675c6992..f03b11226 100644
--- a/deploy/helm/agentmemory/Chart.yaml
+++ b/deploy/helm/agentmemory/Chart.yaml
@@ -3,7 +3,7 @@ name: agentmemory
 description: Kubernetes Helm chart for agentmemory
 type: application
 version: 0.1.0
-appVersion: "0.9.27"
+appVersion: "0.9.28"
 home: https://github.com/wbugitlab1/agentmemory
 sources:
   - https://github.com/wbugitlab1/agentmemory
diff --git a/deploy/helm/agentmemory/README.md b/deploy/helm/agentmemory/README.md
index 376cca274..bd74d313d 100644
--- a/deploy/helm/agentmemory/README.md
+++ b/deploy/helm/agentmemory/README.md
@@ -2,13 +2,13 @@
 
 This chart deploys agentmemory on Kubernetes with the same single-container model used by the Fly, Railway, Render, and Coolify templates.
 
-By default the chart uses `ghcr.io/wbugitlab1/agentmemory:0.9.27`, the same image as the managed-platform templates. Override `image.repository` only when your cluster should pull a private fork image.
+By default the chart uses `ghcr.io/wbugitlab1/agentmemory:0.9.28`, the same image as the managed-platform templates. Override `image.repository` only when your cluster should pull a private fork image.
 
 ## Prerequisites
 
 - Helm 3
 - Kubernetes cluster with `ReadWriteOnce` persistent volume support
-- Access to pull `ghcr.io/wbugitlab1/agentmemory:0.9.27`, or a private image you set in `image.repository`
+- Access to pull `ghcr.io/wbugitlab1/agentmemory:0.9.28`, or a private image you set in `image.repository`
 
 ## Install
 
@@ -107,7 +107,7 @@ Upgrade by setting the new image tag:
 
 ```bash
 helm upgrade agentmemory deploy/helm/agentmemory \
-  --set image.tag=0.9.28
+  --set image.tag=<version>
 ```
 
 By default, Helm deletes chart-managed PVCs on uninstall. To keep memories after uninstalling the release, either use `persistence.existingClaim` or preserve the chart-created claim with a Helm resource-policy annotation:
@@ -126,7 +126,7 @@ Keep a separate backup of the PVC before destructive cluster or storage operatio
 | --- | --- | --- |
 | `replicaCount` | `1` | Must remain `1`; file-backed SQLite state supports one writer. |
 | `image.repository` | `ghcr.io/wbugitlab1/agentmemory` | Image repository; override for private fork images. |
-| `image.tag` | `0.9.27` | Agentmemory image tag. |
+| `image.tag` | `0.9.28` | Agentmemory image tag. |
 | `service.port` | `3111` | REST API Service port. |
 | `persistence.enabled` | `true` | Create a PVC for `/data`. |
 | `persistence.mountPath` | `/data` | Must remain `/data`; deploy images and iii config use this directory. |
diff --git a/deploy/helm/agentmemory/values.yaml b/deploy/helm/agentmemory/values.yaml
index d16a536a9..a47fea520 100644
--- a/deploy/helm/agentmemory/values.yaml
+++ b/deploy/helm/agentmemory/values.yaml
@@ -2,7 +2,7 @@ replicaCount: 1
 
 image:
   repository: "ghcr.io/wbugitlab1/agentmemory"
-  tag: "0.9.27"
+  tag: "0.9.28"
   pullPolicy: IfNotPresent
   pullSecrets: []
 
diff --git a/deploy/railway/Dockerfile b/deploy/railway/Dockerfile
index d96b76869..50053429d 100644
--- a/deploy/railway/Dockerfile
+++ b/deploy/railway/Dockerfile
@@ -4,7 +4,7 @@ FROM iiidev/iii:${III_VERSION} AS iii-image
 
 FROM node:22-slim
 
-ARG AGENTMEMORY_VERSION=0.9.27
+ARG AGENTMEMORY_VERSION=0.9.28
 ARG III_VERSION=0.11.2
 ARG III_SDK_VERSION=0.11.2
 
diff --git a/deploy/railway/README.md b/deploy/railway/README.md
index d3b10be6c..237d1e8d2 100644
--- a/deploy/railway/README.md
+++ b/deploy/railway/README.md
@@ -4,7 +4,7 @@ This template runs agentmemory on a single Railway service with a
 persistent volume mounted at `/data`. The HMAC secret is generated on
 first boot and persisted to the volume. Retrieve it through Railway
 shell access; the secret value is not printed to deploy logs. Use the
-published `ghcr.io/wbugitlab1/agentmemory:0.9.27` image as the service
+published `ghcr.io/wbugitlab1/agentmemory:0.9.28` image as the service
 source.
 
 ## What you get
@@ -23,7 +23,7 @@ source.
 ## Deploy via Railway dashboard
 
 1. Create a service from the image
-   `ghcr.io/wbugitlab1/agentmemory:0.9.27`.
+   `ghcr.io/wbugitlab1/agentmemory:0.9.28`.
 2. Set the **Config-as-Code Path** under the service Settings to
    `deploy/railway/railway.json` if the service is linked to the fork
    repository for deploy settings.
diff --git a/deploy/render/Dockerfile b/deploy/render/Dockerfile
index d96b76869..50053429d 100644
--- a/deploy/render/Dockerfile
+++ b/deploy/render/Dockerfile
@@ -4,7 +4,7 @@ FROM iiidev/iii:${III_VERSION} AS iii-image
 
 FROM node:22-slim
 
-ARG AGENTMEMORY_VERSION=0.9.27
+ARG AGENTMEMORY_VERSION=0.9.28
 ARG III_VERSION=0.11.2
 ARG III_SDK_VERSION=0.11.2
 
diff --git a/deploy/render/README.md b/deploy/render/README.md
index 90945c483..ee37782f2 100644
--- a/deploy/render/README.md
+++ b/deploy/render/README.md
@@ -4,7 +4,7 @@ This template runs agentmemory on a single Render Web Service with a
 persistent disk mounted at `/data`. The HMAC secret is generated on
 first boot and persisted to the disk. Retrieve it through Render SSH;
 the secret value is not printed to deploy logs. The Blueprint pulls
-`ghcr.io/wbugitlab1/agentmemory:0.9.27`.
+`ghcr.io/wbugitlab1/agentmemory:0.9.28`.
 
 ## What you get
 
diff --git a/deploy/render/render.yaml b/deploy/render/render.yaml
index 26b2aa939..868324db7 100644
--- a/deploy/render/render.yaml
+++ b/deploy/render/render.yaml
@@ -4,7 +4,7 @@ services:
     runtime: image
     plan: starter
     image:
-      url: ghcr.io/wbugitlab1/agentmemory:0.9.27
+      url: ghcr.io/wbugitlab1/agentmemory:0.9.28
     healthCheckPath: /agentmemory/livez
     autoDeploy: false
     disk:
diff --git a/docs/todos/2026-06-19-issue-267-pin-mcp-core-version/plan.md b/docs/todos/2026-06-19-issue-267-pin-mcp-core-version/plan.md
new file mode 100644
index 000000000..d458f0850
--- /dev/null
+++ b/docs/todos/2026-06-19-issue-267-pin-mcp-core-version/plan.md
@@ -0,0 +1,105 @@
+# Pin MCP Core Version Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Publish future `@agentmemory/mcp` packages with an exact dependency on the matching `@agentmemory/agentmemory` version.
+
+**Architecture:** Keep the MCP package as a pnpm workspace shim, but switch its source dependency from `workspace:~` to `workspace:*` so pnpm packs it as an exact dependency. Bump the coordinated current version to `0.9.28` because `0.9.27` is already published with bad npm metadata and the publish workflow correctly skips existing versions.
+
+**Tech Stack:** TypeScript, pnpm 11 workspace protocol, Vitest, npm package tarball inspection, GitHub Actions release workflow metadata.
+
+---
+
+## Files
+
+- Modify: `packages/mcp/package.json`
+- Modify: `pnpm-lock.yaml`
+- Modify: `package.json`
+- Modify: `src/version.ts`
+- Modify: `src/types.ts`
+- Modify: `src/functions/export-import.ts`
+- Modify: `test/export-import.test.ts`
+- Modify: `test/quality-gates.test.ts`
+- Modify: `test/plugin-surface-contract.test.ts`
+- Modify: plugin manifests with the current package version
+- Modify: OpenClaw manifests with the current package version
+- Modify: deploy Dockerfiles, Helm values/chart, managed-platform image references, deploy docs, `README.md`
+- Modify: `CONTRIBUTING.md`
+- Modify: `AGENTS.md`
+
+## Task 1: Write Failing Package Contract Tests
+
+- [ ] Change `test/quality-gates.test.ts` so the MCP dependency test expects `workspace:*` and names the exact-publish intent.
+- [ ] Change `test/plugin-surface-contract.test.ts` so the MCP package contract expects `workspace:*` and asserts the MCP package version equals root `package.json` version.
+- [ ] Run `corepack pnpm exec vitest run test/quality-gates.test.ts test/plugin-surface-contract.test.ts`.
+- [ ] Expected RED: tests fail because current source still uses `workspace:~`; no implementation files changed yet.
+
+## Task 2: Implement Exact Workspace Dependency
+
+- [ ] Change `packages/mcp/package.json` dependency `@agentmemory/agentmemory` from `workspace:~` to `workspace:*`.
+- [ ] Run `corepack pnpm install --lockfile-only --ignore-scripts`.
+- [ ] Confirm `pnpm-lock.yaml` records `specifier: workspace:*` for `packages/mcp`.
+- [ ] Rerun `corepack pnpm exec vitest run test/quality-gates.test.ts test/plugin-surface-contract.test.ts`.
+- [ ] Expected GREEN: package contract tests pass.
+
+## Task 3: Bump Coordinated Version To 0.9.28
+
+- [ ] Update root and MCP package versions to `0.9.28`.
+- [ ] Update `src/version.ts`, `src/types.ts`, `src/functions/export-import.ts`, and `test/export-import.test.ts` for current export version `0.9.28` while keeping older import versions supported.
+- [ ] Update plugin and OpenClaw current-version manifests that track the root version.
+- [ ] Update deploy image defaults, Helm app version/tag, and deploy docs from `0.9.27` to `0.9.28`.
+- [ ] Update `AGENTS.md` current stats heading from `v0.9.27` to `v0.9.28`.
+- [ ] Leave independently versioned packages alone: `integrations/filesystem-watcher/package.json`, `website/package.json`, and `plugin/opencode/plugin.json`.
+
+## Task 4: Update Release Process Docs
+
+- [ ] Update `CONTRIBUTING.md` so the release checklist says the MCP source dependency stays `workspace:*`.
+- [ ] Update the release-process explanation so pnpm publish rewrites `workspace:*` to an exact npm dependency.
+- [ ] Review `deploy/helm/agentmemory/README.md` so the upgrade example does not merely repeat the default image tag.
+
+## Task 5: Verify Package Metadata And Tests
+
+- [ ] Run focused tests:
+
+```bash
+corepack pnpm exec vitest run \
+  test/quality-gates.test.ts \
+  test/plugin-surface-contract.test.ts \
+  test/consistency.test.ts \
+  test/export-import.test.ts \
+  test/deploy-version-contract.test.ts \
+  test/copilot-plugin.test.ts \
+  test/codex-plugin.test.ts \
+  test/factory-plugin.test.ts
+```
+
+- [ ] Pack and inspect the MCP tarball:
+
+```bash
+PACK_DIR="$(mktemp -d)"
+corepack pnpm --dir packages/mcp pack --pack-destination "$PACK_DIR" --json
+tar -xOf "$PACK_DIR"/agentmemory-mcp-0.9.28.tgz package/package.json \
+  | jq -r '.version, .dependencies["@agentmemory/agentmemory"]'
+```
+
+- [ ] Expected pack output:
+
+```text
+0.9.28
+0.9.28
+```
+
+- [ ] Run `corepack pnpm test` if dependency setup allows it.
+
+## Task 6: Security And Handoff
+
+- [ ] Run `rg -n 'workspace:~|0\.9\.27|0\.9\.28'` over touched surfaces and classify remaining historical fixtures.
+- [ ] Run `git diff --check`.
+- [ ] Run `osv-scanner scan source .`.
+- [ ] Run `semgrep scan --config p/default --error --metrics=off .`.
+- [ ] Before any commit, stage only intended files and run `gitleaks protect --staged --redact`.
+- [ ] Update `docs/todos/2026-06-19-issue-267-pin-mcp-core-version/todo.md` with verification evidence, caveats, and final matrix status.
+
+## Approval Boundaries
+
+- Do not push, publish, create a PR, tag, deprecate npm packages, change npm dist-tags, deploy, merge, close the issue, or archive this thread without explicit current-turn approval.
diff --git a/docs/todos/2026-06-19-issue-267-pin-mcp-core-version/todo.md b/docs/todos/2026-06-19-issue-267-pin-mcp-core-version/todo.md
new file mode 100644
index 000000000..01b1bae47
--- /dev/null
+++ b/docs/todos/2026-06-19-issue-267-pin-mcp-core-version/todo.md
@@ -0,0 +1,93 @@
+# Issue 267 Pin MCP Core Version
+
+## Scope
+
+- Worktree: `/Users/A1538552/.codex/worktrees/424b/agentmemory`
+- Branch: `issue/267-pin-mcp-core-version`
+- Base inspected: `eacce17e`
+- Remote target: `origin` (`https://github.com/wbugitlab1/agentmemory.git`)
+- Issue: GitHub issue #267, `@agentmemory/mcp does not pin the matching core version, allowing fixed MCP behavior to regress`
+
+## Sprint Contract
+
+- Goal: ensure every newly published `@agentmemory/mcp@X.Y.Z` depends on exactly `@agentmemory/agentmemory@X.Y.Z`.
+- Scope: MCP shim package metadata, lockfile importer, version-aligned release surfaces for the next patch release, tests, and release-process docs that describe the MCP dependency rewrite.
+- Non-goals: no publishing, push, PR creation, tag, npm deprecation, dist-tag change, deployment, or remote project/account state change.
+- Acceptance criteria:
+  - `packages/mcp/package.json` uses `workspace:*` for `@agentmemory/agentmemory`.
+  - Packed MCP package metadata rewrites that dependency to exact `0.9.28`.
+  - The coordinated current version is bumped from `0.9.27` to `0.9.28` on repo surfaces required by AGENTS.md and current tests.
+  - Tests guard exact MCP/core version alignment.
+  - Release docs no longer tell maintainers to keep `workspace:~`.
+- Intended verification:
+  - Focused Vitest contract/version tests.
+  - `corepack pnpm --dir packages/mcp pack --pack-destination ... --json` plus tarball manifest inspection.
+  - `corepack pnpm test` if dependencies are available.
+  - Required security scans for manifest/lockfile/config/instruction changes.
+- Known boundaries:
+  - Remote writes and credentialed GitHub/npm state changes require explicit current-turn approval.
+  - If chosen version `0.9.28` is already published, stop and choose the next unpublished patch only after recording evidence.
+  - Do not touch parent checkout or issue 821-830 worktrees.
+- Stop conditions:
+  - Any branch creation conflict, unexpected unrelated dirty files in task-owned paths, repeated verification failure without a diagnosed cause, or required scanner finding not accepted by the user.
+
+## Validity Evidence
+
+- Local source at start had `packages/mcp/package.json` dependency `"@agentmemory/agentmemory": "workspace:~"`.
+- Local tests `test/quality-gates.test.ts` and `test/plugin-surface-contract.test.ts` also expected `workspace:~`.
+- Public unauthenticated GitHub API confirmed issue #267 is open and describes `@agentmemory/mcp@0.9.22` depending on `~0.9.0`.
+- Public npm metadata check showed `npm view @agentmemory/mcp@0.9.27 dependencies --json` returns `{"@agentmemory/agentmemory":"~0.9.0"}`.
+- `.github/workflows/publish.yml` skips already-published MCP package versions, so a source-only fix at `0.9.27` would not repair npm consumers.
+
+## Arena Synthesis
+
+- Candidates: `/tmp/arena-issue267/candidate-1/strategy.md`, `/tmp/arena-issue267/candidate-2/strategy.md`, `/tmp/arena-issue267/candidate-3/strategy.md`.
+- Judge report: `/tmp/arena-issue267/judge.md`.
+- Base: Candidate 2.
+- Grafts:
+  - Candidate 3: explicit non-goal for npm deprecation and unrelated packages not to bump.
+  - Candidate 1: review Helm README examples so override text does not just repeat the new default image tag.
+- Rejected:
+  - Keeping `workspace:~`, because pnpm publishes it as a range.
+  - Literal source dependency on `0.9.28`, because local workspace installs should keep linking the local root package.
+  - Rewriting publish skip behavior, because npm package versions are immutable and the skip is correct.
+
+## Feature / Verification Matrix
+
+| Change | Verification method | Status | Evidence |
+| --- | --- | --- | --- |
+| Exact MCP/core dependency | Pack tarball manifest and focused package tests | Done | RED: focused tests failed on `workspace:~`; GREEN: `corepack pnpm exec vitest run test/quality-gates.test.ts test/plugin-surface-contract.test.ts` passed after `workspace:*`. Pack tarball inspection printed `0.9.28` and dependency `0.9.28`. |
+| Coordinated version bump | Consistency/export/deploy/plugin tests and stale-string search | Done | `corepack pnpm exec vitest run test/quality-gates.test.ts test/plugin-surface-contract.test.ts test/consistency.test.ts test/export-import.test.ts test/deploy-version-contract.test.ts test/copilot-plugin.test.ts test/codex-plugin.test.ts test/factory-plugin.test.ts` passed: 8 files, 83 tests. Stale-string search found no active `workspace:~` or `0.9.27` in source/release surfaces; remaining `0.9.27` is backward-compatible export/import support or task evidence. |
+| Release-process docs | Read diff and search for `workspace:~` | Done | `CONTRIBUTING.md` now documents `workspace:*` and exact npm dependency rewrite; `deploy/helm/agentmemory/README.md` upgrade example now uses `<version>` instead of repeating the new default tag. |
+| Full repo behavior | `corepack pnpm test` or closest targeted substitute | Done | `corepack pnpm test` passed: 202 files, 2,797 tests. |
+| Security gates | OSV, Semgrep, staged Gitleaks before commit | Done | `git diff --check` passed. `osv-scanner scan source .` passed with the repo's existing GHSA-8988-4f7v-96qf waiver applied and no unfiltered issues. `semgrep scan --config p/default --error --metrics=off .` passed with 0 findings. `gitleaks protect --staged --redact` passed with no leaks found. |
+
+## Subagent Ledger
+
+| Workstream | Scope | Edits allowed | Expected output | Result | Residual risk |
+| --- | --- | --- | --- | --- | --- |
+| Arena candidate 1 | Strategy for issue #267 | No repo edits | `/tmp/arena-issue267/candidate-1/strategy.md` | Recommended `workspace:*` plus `0.9.28` | Missed some plugin surfaces |
+| Arena candidate 2 | Strategy for issue #267 | No repo edits | `/tmp/arena-issue267/candidate-2/strategy.md` | Chosen base; included `CONTRIBUTING.md` | Broader verification than minimum |
+| Arena candidate 3 | Strategy for issue #267 | No repo edits | `/tmp/arena-issue267/candidate-3/strategy.md` | Strong scope/non-goals grafted | Missed `CONTRIBUTING.md` |
+| Arena judge | Score strategies | No repo edits | `/tmp/arena-issue267/judge.md` | Candidate 2 base, grafts from 1 and 3 | None known |
+| Final security review | Security and supply-chain diff review | No repo edits | ACCEPT or High/Medium findings | ACCEPT; no High/Medium findings | Did not rerun already-passed commands |
+| Final test coverage review | Test and verification evidence review | No repo edits | ACCEPT or High/Medium findings | Medium finding: task record still showed pending verification | Fixed in this task-record update |
+| Final maintainability review | Scope and release consistency review | No repo edits | ACCEPT or High/Medium findings | Medium finding duplicated task-record evidence gap | Fixed in this task-record update |
+
+## Progress
+
+- 2026-06-19: Created and switched to branch `issue/267-pin-mcp-core-version` from detached `eacce17e`.
+- 2026-06-19: Validated issue as still relevant for npm consumers using public issue metadata and public npm metadata.
+- 2026-06-19: Ran arena strategy phase and recorded synthesis.
+- 2026-06-19: Implemented `workspace:*` MCP dependency, `0.9.28` coordinated version bump, release-process docs, deploy/plugin/OpenClaw/version surfaces, and package contract tests.
+- 2026-06-19: Verification passed: focused RED/GREEN package tests, focused version/deploy/plugin suite, MCP tarball exact dependency inspection, full `corepack pnpm test`, `git diff --check`, OSV, and Semgrep.
+- 2026-06-19: Final review passed after task-record evidence gap was fixed. Security review accepted the diff; test coverage and maintainability reviewers found only this task-record update requirement.
+
+## Review Notes And Caveats
+
+- Dependency setup: first `corepack pnpm exec vitest ...` auto-install was blocked by pnpm ignored-build hardening. Per AGENTS.md, `corepack pnpm install --frozen-lockfile --ignore-scripts` was run and completed. It emitted the expected pre-build `packages/mcp` bin-link warning for missing `dist/cli.mjs`.
+- OSV: the repository's existing `osv-scanner.toml` filtered GHSA-8988-4f7v-96qf for the known transitive `iii-sdk@0.11.2` OpenTelemetry 1.x issue; no unfiltered issues were found.
+- `website/lib/generated-meta.json` still reports `0.9.27`; maintainability review inspected it and did not classify it as a blocking finding because website scripts regenerate metadata during normal website dev/build. It is outside this issue-scoped release-package fix.
+- Staged Gitleaks passed after staging the intended issue-owned files.
+- Remote writes, issue closure, PR creation, PR merge, npm publish/deprecation, tags, deployment, and thread archival have not been approved or performed.
+- Mandatory archival contract from parent triage: if this valid issue later reaches a PR merge request, the approval request must bundle PR merge into `origin/main` and archiving this Codex thread after successful merge. Only after a successful merge should `set_thread_archived({ archived: true })` be called for this current thread.
diff --git a/integrations/openclaw/openclaw.plugin.json b/integrations/openclaw/openclaw.plugin.json
index 3e4c7e44e..91df5f1fd 100644
--- a/integrations/openclaw/openclaw.plugin.json
+++ b/integrations/openclaw/openclaw.plugin.json
@@ -3,7 +3,7 @@
   "kind": "memory",
   "name": "agentmemory",
   "description": "Persistent cross-session memory for OpenClaw via agentmemory.",
-  "version": "0.9.27",
+  "version": "0.9.28",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
diff --git a/integrations/openclaw/package.json b/integrations/openclaw/package.json
index aef780b8d..5d7f3bfb9 100644
--- a/integrations/openclaw/package.json
+++ b/integrations/openclaw/package.json
@@ -1,6 +1,6 @@
 {
   "name": "agentmemory",
-  "version": "0.9.27",
+  "version": "0.9.28",
   "type": "module",
   "packageManager": "pnpm@11.6.0",
   "openclaw": {
diff --git a/integrations/openclaw/plugin.yaml b/integrations/openclaw/plugin.yaml
index fe711d5d9..666a63c4d 100644
--- a/integrations/openclaw/plugin.yaml
+++ b/integrations/openclaw/plugin.yaml
@@ -1,5 +1,5 @@
 name: agentmemory
-version: 0.9.27
+version: 0.9.28
 description: "Persistent cross-session memory for OpenClaw via agentmemory. 95.2% retrieval accuracy on LongMemEval-S."
 author: "Rohit Ghumare"
 homepage: "https://github.com/rohitg00/agentmemory"
diff --git a/package.json b/package.json
index 08fb9c810..74e0ddd9f 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@agentmemory/agentmemory",
-  "version": "0.9.27",
+  "version": "0.9.28",
   "description": "Persistent memory for AI coding agents, powered by iii-engine's three primitives",
   "type": "module",
   "packageManager": "pnpm@11.6.0",
diff --git a/packages/mcp/package.json b/packages/mcp/package.json
index 464aeb69c..4dda32820 100644
--- a/packages/mcp/package.json
+++ b/packages/mcp/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@agentmemory/mcp",
-  "version": "0.9.27",
+  "version": "0.9.28",
   "description": "Standalone MCP server for agentmemory — thin shim that re-exposes @agentmemory/agentmemory's MCP entrypoint",
   "type": "module",
   "packageManager": "pnpm@11.6.0",
@@ -29,7 +29,7 @@
   "homepage": "https://github.com/rohitg00/agentmemory#readme",
   "bugs": "https://github.com/rohitg00/agentmemory/issues",
   "dependencies": {
-    "@agentmemory/agentmemory": "workspace:~"
+    "@agentmemory/agentmemory": "workspace:*"
   },
   "publishConfig": {
     "access": "public",
diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json
index 729efd19d..1a92af19c 100644
--- a/plugin/.claude-plugin/plugin.json
+++ b/plugin/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "agentmemory",
-  "version": "0.9.27",
+  "version": "0.9.28",
   "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 61 MCP tools, 15 skills, real-time viewer.",
   "author": {
     "name": "Rohit Ghumare",
diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json
index 826398bbe..e3294f972 100644
--- a/plugin/.codex-plugin/plugin.json
+++ b/plugin/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "agentmemory",
-  "version": "0.9.27",
+  "version": "0.9.28",
   "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 6 hooks, 61 MCP tools, 15 skills, real-time viewer.",
   "author": {
     "name": "Rohit Ghumare",
diff --git a/plugin/.factory-plugin/plugin.json b/plugin/.factory-plugin/plugin.json
index feb1a8299..5731c2282 100644
--- a/plugin/.factory-plugin/plugin.json
+++ b/plugin/.factory-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "agentmemory",
-  "version": "0.9.27",
+  "version": "0.9.28",
   "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 61 MCP tools, 15 skills, real-time viewer.",
   "author": {
     "name": "Rohit Ghumare",
diff --git a/plugin/plugin.json b/plugin/plugin.json
index ffaffead0..1f08d30c0 100644
--- a/plugin/plugin.json
+++ b/plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "agentmemory",
-  "version": "0.9.27",
+  "version": "0.9.28",
   "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 11 hooks, 61 MCP tools, 15 skills, real-time viewer.",
   "author": {
     "name": "Rohit Ghumare",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d23395130..d2b982067 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -83,7 +83,7 @@ importers:
   packages/mcp:
     dependencies:
       '@agentmemory/agentmemory':
-        specifier: workspace:~
+        specifier: workspace:*
         version: link:../..
 
   website:
diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts
index 1c6dacad7..8d2bbb53f 100644
--- a/src/functions/export-import.ts
+++ b/src/functions/export-import.ts
@@ -177,7 +177,7 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void {
       const strategy = data.strategy || "merge";
       const importData = data.exportData;
 
-      const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27"]);
+      const supportedVersions = new Set(["0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.7.0", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.9", "0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8", "0.8.9", "0.8.10", "0.8.11", "0.8.12", "0.8.13", "0.9.0", "0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5", "0.9.6", "0.9.7", "0.9.8", "0.9.9", "0.9.10", "0.9.11", "0.9.12", "0.9.13", "0.9.14", "0.9.15", "0.9.16", "0.9.17", "0.9.18", "0.9.19", "0.9.20", "0.9.21", "0.9.22", "0.9.23", "0.9.24", "0.9.25", "0.9.26", "0.9.27", "0.9.28"]);
       if (!supportedVersions.has(importData.version)) {
         return {
           success: false,
diff --git a/src/types.ts b/src/types.ts
index 08b045ad5..5054ecbfc 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -441,7 +441,7 @@ export interface ExportPagination {
 }
 
 export interface ExportData {
-  version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27";
+  version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28";
   exportedAt: string;
   sessions: Session[];
   observations: Record<string, CompressedObservation[]>;
diff --git a/src/version.ts b/src/version.ts
index 927846096..6d09f4f4a 100644
--- a/src/version.ts
+++ b/src/version.ts
@@ -1 +1 @@
-export const VERSION = "0.9.27";
+export const VERSION = "0.9.28";
diff --git a/test/export-import.test.ts b/test/export-import.test.ts
index 394986269..39c17cab8 100644
--- a/test/export-import.test.ts
+++ b/test/export-import.test.ts
@@ -119,7 +119,7 @@ describe("Export/Import Functions", () => {
   it("export produces valid ExportData structure", async () => {
     const result = (await sdk.trigger("mem::export", {})) as ExportData;
 
-    expect(result.version).toBe("0.9.27");
+    expect(result.version).toBe("0.9.28");
     expect(result.exportedAt).toBeDefined();
     expect(result.sessions.length).toBe(1);
     expect(result.sessions[0].id).toBe("ses_1");
diff --git a/test/plugin-surface-contract.test.ts b/test/plugin-surface-contract.test.ts
index e85b89836..3e823bd87 100644
--- a/test/plugin-surface-contract.test.ts
+++ b/test/plugin-surface-contract.test.ts
@@ -117,17 +117,20 @@ describe("Package and integration manifests", () => {
     const pkg = readJson<{
       name: string;
       type: string;
+      version: string;
       bin: Record<string, string>;
       files: string[];
       dependencies: Record<string, string>;
       publishConfig: { access: string; provenance: boolean };
     }>(join(repoRoot, "packages/mcp/package.json"));
+    const rootPkg = readJson<{ version: string }>(join(repoRoot, "package.json"));
 
     expect(pkg.name).toBe("@agentmemory/mcp");
+    expect(pkg.version).toBe(rootPkg.version);
     expect(pkg.type).toBe("module");
     expect(pkg.bin["agentmemory-mcp"]).toBe("./bin.mjs");
     expect(pkg.files).toEqual(expect.arrayContaining(["bin.mjs", "README.md", "LICENSE"]));
-    expect(pkg.dependencies["@agentmemory/agentmemory"]).toBe("workspace:~");
+    expect(pkg.dependencies["@agentmemory/agentmemory"]).toBe("workspace:*");
     expect(pkg.publishConfig).toMatchObject({ access: "public", provenance: true });
     expect(existsSync(join(repoRoot, "packages/mcp", pkg.bin["agentmemory-mcp"]))).toBe(true);
   });
diff --git a/test/quality-gates.test.ts b/test/quality-gates.test.ts
index 430a3ba6c..6717171c5 100644
--- a/test/quality-gates.test.ts
+++ b/test/quality-gates.test.ts
@@ -392,10 +392,10 @@ describe("root quality gates", () => {
     expect(readText("website/.gitignore")).not.toMatch(/^pnpm-lock\.yaml$/m);
   });
 
-  it("uses a pnpm workspace dependency for the MCP shim source package", () => {
+  it("uses an exact pnpm workspace dependency for the MCP shim source package", () => {
     const mcp = JSON.parse(readText("packages/mcp/package.json")) as PackageJson;
 
-    expect(mcp.dependencies?.["@agentmemory/agentmemory"]).toBe("workspace:~");
+    expect(mcp.dependencies?.["@agentmemory/agentmemory"]).toBe("workspace:*");
   });
 
   it("keeps published Node engine guidance aligned with package manifests", () => {