feat(plugins): Claude Code plugin v0.4 — the memory bridge

.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
     {
       "name": "basic-memory",
       "source": "./plugins/claude-code",
-      "description": "Skills, agents, and hooks for Basic Memory MCP — placement-aware note writing and knowledge graph workflows",
+      "description": "The bridge between Claude's working memory and Basic Memory's durable knowledge graph — session briefings, pre-compaction checkpoints, and capture reflexes",
       "version": "0.3.13",
       "author": {
         "name": "Basic Machines"

.claude/commands/release/release.md

@@ -42,7 +42,7 @@ The justfile target handles:
 - ✅ Version format validation
 - ✅ Git status and branch checks
 - ✅ Quality checks (`just check` - lint, format, type-check, tests)
-- ✅ Version update in `src/basic_memory/__init__.py`
+- ✅ Version update across all consolidated manifests via `just set-version` (Python package + Claude Code plugin/marketplaces + Hermes + OpenClaw)
 - ✅ Automatic commit with proper message
 - ✅ Tag creation and pushing to GitHub
 - ✅ Release workflow trigger (automatic on tag push)
@@ -191,7 +191,13 @@ Users can now upgrade:
 - This creates production releases used by end users
 - Must pass all quality gates before proceeding
 - Uses the automated justfile target for consistency
-- Version is automatically updated in `__init__.py` and `server.json`
+- Version is automatically updated across **all** consolidated manifests via
+  `just set-version <version>` (which calls `scripts/update_versions.py`): the
+  Python package (`__init__.py`, `server.json`) **and** the plugin/agent artifacts
+  (Claude Code `plugin.json` + root/local marketplaces, Hermes `plugin.yaml` +
+  `__init__.py`, OpenClaw `package.json`). To bump only the plugin/agent artifacts
+  out of band, use `just set-packages-version <version>` (preview with
+  `just set-packages-version-dry-run <version>`).
 - Triggers automated GitHub release with changelog
 - Package is published to PyPI for `pip` and `uv` users
 - Homebrew formula is automatically updated for stable releases

AGENTS.md

@@ -68,7 +68,7 @@ If testmon is “cold,” the first run may be long. Subsequent runs get much fa
 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-claude-code` — validates the root and plugin-local Claude marketplace manifests, the SessionStart/PreCompact hooks, the bundled output style, and the seed schemas, then 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`.

README.md

@@ -197,7 +197,13 @@ just package-check-openclaw
 
 ### Claude Code plugin
 
-The Claude Code plugin bundles Basic Memory-aware skills, hooks, and an agent:
+The Claude Code plugin is the bridge between Claude's working memory and Basic
+Memory — session-start briefings, pre-compaction checkpoints, an opt-in capture
+output style, and `/basic-memory:setup` · `:remember` · `:share` · `:status`.
+
+**Connect the Basic Memory MCP server first** — see [Connect your AI
+client](#connect-your-ai-client). The plugin's hooks and skills call it, so it's a
+hard prerequisite. Then add the marketplace and install:
 
 ```bash
 claude plugin marketplace add basicmachines-co/basic-memory \
@@ -275,6 +281,10 @@ Restart Claude Desktop. Notes live in `~/basic-memory` by default.
 claude mcp add basic-memory -- uvx basic-memory mcp
 ```
 
+For the full memory bridge — session briefings, pre-compaction checkpoints, and
+the `/basic-memory:*` commands — also install the [Claude Code
+plugin](#claude-code-plugin) on top of this.
+
 ### Codex CLI
 
 Add to `~/.codex/config.toml`:

integrations/hermes/__init__.py

@@ -449,6 +449,9 @@ def _extract_mcp_text(result: Any) -> str:
     Returns a JSON string for the agent. If the result is itself JSON, returns it
     as-is. Otherwise wraps the text in `{"text": "..."}` for downstream parsing.
     """
+    # The `mcp` SDK is an unpinned dependency (see plugin.yaml), and its result
+    # shapes (CallToolResult, content blocks) have shifted across versions — read
+    # these fields defensively with getattr rather than direct attribute access.
     is_error = bool(getattr(result, "isError", False))
     parts: list[str] = []
     for c in getattr(result, "content", None) or []:
@@ -594,6 +597,9 @@ async def _main(self) -> None:
                     self._stop_future = asyncio.get_running_loop().create_future()
                     try:
                         listing = await session.list_tools()
+                        # Same unpinned-`mcp`-SDK reason as parse_result above:
+                        # ListToolsResult / Tool field shapes vary across SDK versions,
+                        # so read them defensively rather than by direct attribute access.
                         self._tools_cache = [
                             {
                                 "name": getattr(t, "name", ""),

justfile

@@ -295,9 +295,25 @@ package-check-openclaw:
 migration message:
     cd src/basic_memory/alembic && alembic revision --autogenerate -m "{{message}}"
 
+# Set the Basic Memory version across release manifests (scope: all | core | packages)
+set-version version scope="all":
+    python3 scripts/update_versions.py "{{version}}" --scope "{{scope}}"
+
+# Preview a version update without writing (scope: all | core | packages)
+set-version-dry-run version scope="all":
+    python3 scripts/update_versions.py "{{version}}" --scope "{{scope}}" --dry-run
+
+# Set the version for just the plugin/agent artifacts (plugin, marketplaces, Hermes, OpenClaw)
+set-packages-version version:
+    just set-version "{{version}}" packages
+
+# Preview a plugin/agent-artifact version update without writing
+set-packages-version-dry-run version:
+    just set-version-dry-run "{{version}}" packages
+
 # Preview the consolidated manifest version update without changing files
 release-dry-run version:
-    python3 scripts/update_versions.py "{{version}}" --dry-run
+    just set-version-dry-run "{{version}}"
 
 # Create a stable release (e.g., just release v0.13.2)
 release version:
@@ -340,7 +356,7 @@ release version:
 
     # Update all package manifests to the one Basic Memory product version.
     echo "📝 Updating consolidated package versions..."
-    python3 scripts/update_versions.py "{{version}}"
+    just set-version "{{version}}"
 
     # Commit version update
     git add \
@@ -413,7 +429,7 @@ beta version:
 
     # Update all package manifests to the one Basic Memory product version.
     echo "📝 Updating consolidated package versions..."
-    python3 scripts/update_versions.py "{{version}}"
+    just set-version "{{version}}"
 
     # Commit version update
     git add \

plugins/claude-code/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
     {
       "name": "basic-memory",
       "source": "./",
-      "description": "Skills, agents, and hooks for Basic Memory MCP — placement-aware note writing and knowledge graph workflows",
+      "description": "The bridge between Claude's working memory and Basic Memory's durable knowledge graph — session briefings, pre-compaction checkpoints, and capture reflexes",
       "version": "0.3.13",
       "author": {
         "name": "Basic Machines"

plugins/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "basic-memory",
-  "description": "Claude Code skills, agents, and hooks for Basic Memory — placement-aware note writing and knowledge graph workflows",
+  "description": "The bridge between Claude's working memory and Basic Memory's durable knowledge graph — session briefings, pre-compaction checkpoints, and capture reflexes",
   "version": "0.3.13",
   "author": {
     "name": "Basic Machines"

plugins/claude-code/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Changelog
 
+## Unreleased — v0.4 bridge redesign (Phases 1–4)
+
+The plugin is reframed as the **bridge between Claude's working memory and Basic
+Memory's durable graph**, rather than a memory layer of its own. See
+[DESIGN.md](./DESIGN.md) for the full rationale and roadmap.
+
+### Added
+
+- **Team workspace support** (Phase 4). SessionStart now reads **across** the primary
+  project plus configured shared/team projects — `secondaryProjects` (read-only recall
+  sources) and `teamProjects` (share targets) — querying open decisions from each in
+  parallel and folding them into the brief. Team refs use workspace-qualified names
+  (`my-team/notes`) or `external_id` UUIDs, since project names collide across
+  workspaces. Reads route over the user's OAuth session; capture **never** writes to a
+  shared project.
+- **`/basic-memory:share <note>`** (`skills/share/`) — the deliberate personal→team
+  write: copies a note from the primary project into a configured `teamProjects`
+  target's `promoteFolder`, with `shared_from` attribution and a confirmation step.
+  Preserves the note's type so shared decisions stay findable in the team's structured
+  recall. (Phase 4)
+- **`/basic-memory:setup`** (`skills/setup/`) — a short guided interview that
+  configures the project for the plugin: maps it to a Basic Memory project (picking
+  an existing one or creating a new one), seeds the `session`/`decision`/`task`
+  schemas into the project, installs the shared `memory-*` skills via
+  `npx skills add basicmachines-co/basic-memory --path skills` (the plugin doesn't
+  vendor its own copies — `skills/` is the single source of truth, shared with
+  OpenClaw), optionally learns the project's placement conventions, and enables the
+  capture reflexes. Writes the `basicMemory` block to
+  `.claude/settings.json` (or `settings.local.json`). The SessionStart hook nudges
+  toward this on first run; running it (writing the config) stops the nudge. (Phase 3)
+- **`/basic-memory:remember <text>`** (`skills/remember/`) — quick deliberate
+  capture. Writes the text verbatim to the `rememberFolder` (default `bm-remember`)
+  with a first-line title and a `manual-capture` tag, via the connected Basic Memory
+  MCP server. Also fires when the user says "remember that…". (Phase 2)
+- **`/basic-memory:status`** (`skills/status/`) — diagnostic that reports the active
+  project, capture/remember folders, output-style state, recent session checkpoints,
+  and active-task count. User-invoked only (`disable-model-invocation`). (Phase 2)
+
+  Both verified discoverable via `claude plugin details` — they surface as
+  plugin-namespaced commands (`/basic-memory:<name>`).
+
+
+- **SessionStart hook** (`hooks/session-start.sh`) — briefs Claude at session
+  start with active tasks from the graph (one structured `type: task` query) plus
+  an always-on recall prompt. Works against the default project with zero config;
+  pin a project via `basicMemory.primaryProject`. Plain-stdout output, capped well
+  under the 10k limit, and silent if Basic Memory isn't installed.
+- **PreCompact hook** (`hooks/pre-compact.sh`) — writes a `type: session`
+  checkpoint to the graph before context compaction (extractive in this phase;
+  LLM-summarized capture is the next step). Only writes when a `primaryProject` is
+  configured, so it never touches a graph the user hasn't opted in.
+- **Output style** (`output-styles/basic-memory.md`) — opt-in reflexes: search
+  before recalling, capture decisions as typed `decision` notes, cite permalinks.
+  Sets `keep-coding-instructions: true` so it composes with normal dev work.
+- **Seed schemas** (`schemas/{session,decision,task}.md`) — picoschema for the
+  note types the plugin writes, so recall via `search_notes` metadata filters is
+  precise. `task` mirrors the framework-agnostic `memory-tasks` skill. Validation
+  mode `warn` — advisory, never blocking.
+- **`settings.example.json`** — copyable configuration with sensible defaults.
+
+### Changed
+
+- **SessionStart hook now nudges toward `/basic-memory:setup` on first run** — when
+  no `basicMemory` config block is present in either settings file. The nudge
+  survives a failed/empty task query (so a brand-new user with no project yet still
+  sees it), and stops once setup writes the config. (Phase 3)
+
+### Removed (clean break)
+
+- The six bundled skills (`placement`, `knowledge-capture`, `knowledge-organize`,
+  `continue-conversation`, `research`, `edit-note`). Equivalent, framework-agnostic
+  workflows live in the top-level [`skills/`](../../skills) package
+  (`memory-notes`, `memory-research`, `memory-tasks`, `memory-schema`, …); install
+  those for the old capabilities.
+- The `basic-memory-manager` agent. The plugin ships no agent in v0.4 — memory is
+  handled in the main context via hooks and the output style, not delegated.
+- The `PreToolUse`/`PostToolUse` `write_note` hooks (placement advisory + save
+  confirmation). Placement guidance now lives in the `basicMemory` settings block
+  and the output style.
+- The `basic-memory` config-note convention, superseded by `.claude/settings.json`.
+- `PLUGIN.md`, replaced by a bridge-framed `README.md` and `DESIGN.md`.
+
+### Notes
+
+- Slash commands shipped by later phases (`/basic-memory:setup`,
+  `:remember`, `:status`) will be **plugin-namespaced** — Claude Code namespaces
+  all plugin skills as `/<plugin>:<skill>`.
+- Requires `basic-memory >= 0.19.0` (for `metadata_filters` / structured recall).
+
 ## 0.3.13
 
 ### Fixed