chore(integrations): consolidate agent packages

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

.claude-plugin/marketplace.json

@@ -0,0 +1,23 @@
+{
+  "name": "basicmachines-co",
+  "owner": {
+    "name": "Basic Machines",
+    "email": "hello@basicmachines.co"
+  },
+  "metadata": {
+    "description": "Official Basic Memory plugins from the canonical basic-memory repository",
+    "version": "0.3.13"
+  },
+  "plugins": [
+    {
+      "name": "basic-memory",
+      "source": "./plugins/claude-code",
+      "description": "Skills, agents, and hooks for Basic Memory MCP — placement-aware note writing and knowledge graph workflows",
+      "version": "0.3.13",
+      "author": {
+        "name": "Basic Machines"
+      },
+      "keywords": ["memory", "knowledge", "mcp", "specs", "context"]
+    }
+  ]
+}

.github/workflows/consolidated-packages.yml

@@ -0,0 +1,102 @@
+name: Consolidated Packages
+
+on:
+  pull_request:
+    paths:
+      - ".claude-plugin/**"
+      - "plugins/**"
+      - "skills/**"
+      - "integrations/**"
+      - "scripts/update_versions.py"
+      - "scripts/validate_*.py"
+      - "justfile"
+      - ".github/workflows/consolidated-packages.yml"
+  push:
+    branches:
+      - main
+    paths:
+      - ".claude-plugin/**"
+      - "plugins/**"
+      - "skills/**"
+      - "integrations/**"
+      - "scripts/update_versions.py"
+      - "scripts/validate_*.py"
+      - "justfile"
+      - ".github/workflows/consolidated-packages.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  claude-code:
+    name: Claude Code marketplace
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: extractions/setup-just@v4
+
+      - name: Validate manifests, agent, and bundled skills
+        run: just --justfile plugins/claude-code/justfile --working-directory plugins/claude-code ci-check
+
+      - name: Verify shared version dry run
+        run: just release-dry-run v0.99.0
+
+  skills:
+    name: Shared skills
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: extractions/setup-just@v4
+
+      - name: Validate SKILL.md source
+        run: just --justfile skills/justfile --working-directory skills check
+
+  hermes:
+    name: Hermes unit tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: integrations/hermes
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: extractions/setup-just@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Validate manifest and run unit tests
+        run: just check
+
+  openclaw:
+    name: OpenClaw package
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: integrations/openclaw
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: extractions/setup-just@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.8"
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Release readiness
+        run: just release-check

.github/workflows/pr-title.yml

@@ -40,5 +40,8 @@ jobs:
             ui
             deps
             installer
+            plugins
+            skills
+            integrations
           # Allow breaking changes (needs "!" after type/scope)
           requireScopeForBreakingChange: true

.github/workflows/release.yml

@@ -56,6 +56,46 @@ jobs:
         with:
           password: ${{ secrets.PYPI_TOKEN }}
 
+  openclaw:
+    name: Publish OpenClaw npm Package
+    needs: release
+    # npm publishes only for stable product tags. Pre-release Python tags use
+    # versions like 0.21.3b1, which are not valid npm pre-release semver.
+    if: ${{ !contains(github.ref_name, 'dev') && !contains(github.ref_name, 'b') && !contains(github.ref_name, 'rc') }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    defaults:
+      run:
+        working-directory: integrations/openclaw
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: extractions/setup-just@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.8"
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Release readiness
+        run: just release-check
+
+      - name: Publish to npm
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
   homebrew:
     name: Update Homebrew Formula
     needs: release

.gitignore

@@ -58,3 +58,9 @@ claude-output
 .mcpregistry_*
 /.testmondata
 .benchmarks/
+
+# Consolidated package build artifacts
+/integrations/openclaw/node_modules/
+/integrations/openclaw/dist/
+/integrations/openclaw/skills/
+/integrations/openclaw/*.tgz

AGENTS.md

@@ -26,6 +26,12 @@ See the [README.md](README.md) file for a project overview.
 - Run MCP smoke test: `just test-smoke`
 - Fast local loop: `just fast-check` (default iteration flow)
 - Local consistency check: `just doctor`
+- Run all consolidated agent package checks: `just package-check`
+- Run Claude Code plugin checks: `just package-check-claude-code`
+- Run shared skills checks: `just package-check-skills`
+- Run Hermes plugin checks: `just package-check-hermes`
+- Run OpenClaw plugin checks: `just package-check-openclaw`
+- Run host-native agent harness checks: `just agent-harness-check`
 - Generate HTML coverage: `just coverage`
 - Single test: `pytest tests/path/to/test_file.py::test_function_name`
 - Run benchmarks: `pytest test-int/test_sync_performance_benchmark.py -v -m "benchmark and not slow"`
@@ -50,20 +56,34 @@ See the [README.md](README.md) file for a project overview.
 1) **Code:** make changes.
 2) **Test:** `just fast-check` (lint/format/typecheck + pytest-testmon impacted tests for changed code).
 3) **Verify:** `just doctor` (end-to-end file ↔ DB loop in a temp project).
-4) **Full gate (when needed):** `just test` or `just check` for SQLite + Postgres.
+4) **Package verify:** `just package-check` when changes touch `plugins/`, `skills/`, `integrations/`, package metadata, or release wiring.
+5) **Full gate (when needed):** `just test` or `just check` for SQLite + Postgres.
 
 Run `just test-smoke` when you specifically need the MCP smoke flow.
 
 If testmon is “cold,” the first run may be long. Subsequent runs get much faster.
 
+### Consolidated Agent Package Checks
+
+The monorepo ships several host-native packages alongside the Python core. Use the root justfile as the canonical entry point:
+
+- `just package-check` — validates every copied package and generated bundle path.
+- `just package-check-claude-code` — validates the root and plugin-local Claude marketplace manifests, bundled Claude Code skills, hooks, `basic-memory-manager` agent, and runs `claude plugin validate . --strict`.
+- `just package-check-skills` — validates every top-level `skills/memory-*/SKILL.md` frontmatter block.
+- `just package-check-hermes` — validates `integrations/hermes/plugin.yaml`, the Hermes provider entrypoint, bundled skill, and runs the hermetic unit suite.
+- `just package-check-openclaw` — runs the OpenClaw package install, copies top-level skills into the generated bundle, typechecks, lints, builds `dist/`, runs Bun tests, and performs `npm pack --dry-run`.
+- `just agent-harness-check` — checks the host-specific harnesses without the shared markdown-only skills target.
+
+Package-local justfiles live in `plugins/claude-code/`, `skills/`, `integrations/hermes/`, and `integrations/openclaw/`. Prefer the root targets for PR verification so command names stay stable as package internals evolve.
+
 ### PR CI Gate
 
 Before opening or updating a PR, run the checks that mirror the common required CI failures:
 
 - Run `just typecheck` in addition to targeted `ruff` and `pytest` commands when tests were added or changed.
 - Sign commits with `git commit -s` so DCO passes. If a PR branch already has unsigned commits, rewrite the branch with signed-off commits before asking for review.
 - Use a semantic PR title accepted by `.github/workflows/pr-title.yml`: `type(scope): summary`.
-- Use one of the allowed scopes: `core`, `cli`, `api`, `mcp`, `sync`, `ui`, `deps`, `installer`.
+- Use one of the allowed scopes: `core`, `cli`, `api`, `mcp`, `sync`, `ui`, `deps`, `installer`, `plugins`, `skills`, `integrations`.
 
 ### Test Structure
 
@@ -162,6 +182,10 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed architecture docum
 - `/schemas` - Pydantic models for validation
 - `/services` - Business logic layer
 - `/sync` - File synchronization services + `coordinator.py` for lifecycle management
+- `/plugins/claude-code` - Claude Code plugin marketplace package, hooks, skills, and agent harness
+- `/skills` - Canonical framework-agnostic Basic Memory `SKILL.md` source
+- `/integrations/hermes` - Hermes memory-provider plugin
+- `/integrations/openclaw` - OpenClaw npm/TypeScript plugin
 
 **Composition Roots:**
 Each entrypoint (API, MCP, CLI) has a composition root that:
@@ -263,10 +287,12 @@ Releases are driven by `just release` / `just beta` — never by a bare `git tag
 just release v0.21.3
 ```
 
-The recipe runs `just lint` + `just typecheck`, then updates `__version__` in `src/basic_memory/__init__.py` and `"version"` in `server.json` (MCP registry metadata), commits as `chore: update version to X.Y.Z for vX.Y.Z release`, creates the `vX.Y.Z` tag, and pushes both the commit and the tag to `origin/main`. After the tag lands, the `Release` workflow builds the package, publishes to PyPI, creates the GitHub release with auto-generated notes, and updates the Homebrew formula. The recipe finishes by printing the post-release tasks the workflow doesn't cover.
+The recipe runs `just lint` + `just typecheck`, then updates every release manifest through `scripts/update_versions.py`: `src/basic_memory/__init__.py`, `server.json`, the root Claude marketplace, the Claude Code plugin manifest and local marketplace, the Hermes `plugin.yaml`, and the OpenClaw `package.json`. It commits as `chore: update version to X.Y.Z for vX.Y.Z release`, creates the `vX.Y.Z` tag, and pushes both the commit and the tag to `origin/main`. After the tag lands, the `Release` workflow builds the Python package, publishes to PyPI, creates the GitHub release with auto-generated notes, publishes the OpenClaw npm package, and updates the Homebrew formula. The recipe finishes by printing the post-release tasks the workflow doesn't cover.
 
 **Beta release:** `just beta v0.21.3b1` — same flow with a beta-suffixed tag. PyPI consumers install with `pip install basic-memory --pre`.
 
+**Release dry run:** `just release-dry-run v0.21.4` previews the consolidated version update without writing files.
+
 **Development builds:** every commit to `main` publishes a `0.21.3.dev26+468a22f`-style version to PyPI automatically via `.github/workflows/dev-release.yml`. No human action.
 
 **Do not tag releases by hand.** A bare `git tag vX.Y.Z` skips the in-code version bump. Package metadata is still correct (uv-dynamic-versioning derives it from the git tag) but `basic-memory --version` reports the previous release, which is what happened with v0.21.2 → v0.21.3.
@@ -480,7 +506,7 @@ With GitHub integration, the development workflow includes:
 5. **Code Commits**: ALWAYS sign off commits with `git commit -s`
 6. **Pull Request Titles**: PR titles must follow the semantic format enforced by `.github/workflows/pr-title.yml`: `type(scope): summary`
    - Allowed types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`
-   - Allowed scopes: `core`, `cli`, `api`, `mcp`, `sync`, `ui`, `deps`, `installer`
+   - Allowed scopes: `core`, `cli`, `api`, `mcp`, `sync`, `ui`, `deps`, `installer`, `plugins`, `skills`, `integrations`
    - Example: `fix(cli): propagate cloud workspace routing`
 
 This level of integration represents a new paradigm in AI-human collaboration, where the AI assistant becomes a full-fledged team member rather than just a tool for generating code snippets.

CHANGELOG.md

@@ -1,5 +1,46 @@
 # CHANGELOG
 
+## Unreleased
+
+### Core
+
+- Consolidated the Basic Memory satellite repositories into the main
+  `basic-memory` tree as the canonical source, discovery, documentation,
+  issue, and release home.
+- Added root marketplace/package validation for the consolidated repository
+  layout while keeping Phase 1 focused on parity.
+- Added root and package-local justfile targets so Claude Code, skills,
+  Hermes, and OpenClaw builds can be verified from the monorepo.
+
+### Skills
+
+- Added the shared Basic Memory `SKILL.md` collection under top-level
+  `skills/`.
+- Updated skills documentation to point at `basicmachines-co/basic-memory`
+  and document manual copy as the temporary fallback when subpath installs are
+  unavailable.
+
+### Claude Code
+
+- Added the Claude Code plugin under `plugins/claude-code/` with its native
+  `.claude-plugin`, hooks, skills, agent, changelog, and docs.
+- Added the root Claude marketplace manifest pointing `basic-memory` to
+  `./plugins/claude-code`.
+
+### Hermes
+
+- Added the Hermes memory provider plugin under `integrations/hermes/` with
+  its native Python module, `plugin.yaml`, skill, tests, docs, and release
+  metadata.
+- Updated Hermes install and development docs for monorepo subpath usage.
+
+### OpenClaw
+
+- Added the OpenClaw plugin under `integrations/openclaw/` with its native
+  npm/TypeScript package shape, tests, docs, and release metadata.
+- Updated OpenClaw package metadata to point at the monorepo subdirectory and
+  changed skill bundling to copy from the top-level `skills/` source.
+
 ## v0.21.5 (2026-05-26)
 
 Workspace/project routing fixes for MCP, plus a SQLite vector reindex stability fix.