basicmachines-co-basic-memory/plugins/claude-code/CHANGELOG.md

# 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:bm-share <note>`** (`skills/bm-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:bm-setup`** (`skills/bm-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/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:bm-remember <text>`** (`skills/bm-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:bm-status`** (`skills/bm-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:bm-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:bm-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

- **`knowledge-capture` thread lookup uses `metadata_filters` instead of `query`.** The previous instructions told the skill to find an existing thread note via `search_notes(query="<uuid>")` — a full-text search. In practice this doesn't find the note even though `thread_id` is in the frontmatter: full-text indexing apparently doesn't surface YAML frontmatter custom fields, or scores those matches too low.

  The reliable lookup is `search_notes(metadata_filters={"thread_id": "<uuid>"})` — direct query against the metadata field. This consistently returns the matching note (with score 0.0 — direct match) when one exists.

- **Skill instructions now show `overwrite=True`** for the update path, since `write_note` requires it to replace an existing note at the same path.

### Discovery

This bug was found by exercising the skill in real-world conditions: invoking `/knowledge-capture` a second time in the same thread, expecting the existing note to be found and rewritten. Search returned weak unrelated matches; the existing note was missed; the update flow couldn't proceed without manual intervention.

## 0.3.12

### Fixed

- **`knowledge-capture` session UUID detection.** The previous bash command used `pwd` to scope the JSONL lookup to a single project directory:
  ```bash
  ls -t ~/.claude/projects/$(pwd | sed 's:/:-:g')/*.jsonl | head -1 | ...
  ```
  This fails when the shell has `cd`'d into a subdirectory of the Claude Code session's project root — the encoded path no longer matches a real `~/.claude/projects/<project>` directory, and the lookup returns no matches. The skill then can't determine the session UUID and falls back to creating a new note instead of finding/updating an existing one.

  The fix is a cross-project glob: `ls -t ~/.claude/projects/*/*.jsonl` — picks the most recently-modified jsonl across all project dirs. The active session is continuously appending to its jsonl, so it's reliably the most-recent.

## 0.3.11

### Changed

- **`knowledge-capture` skill rewritten** with new semantics:
  - **Purpose** clarified: capture the meaningful context of a Claude Code thread as a single coherent note about where the thread has landed — not a running log.
  - **Same-thread detection.** The skill now derives a stable session UUID from the JSONL transcript filename (`~/.claude/projects/<encoded-cwd>/<uuid>.jsonl`) and stores it as `thread_id` in the note's frontmatter. Subsequent invocations in the same thread find and **rewrite** the existing note rather than creating a new one.
  - **Synthesis, not append.** When updating, the skill produces a fresh coherent version that integrates the latest understanding. Superseded decisions are replaced inline; brief prose acknowledges material revisions where relevant. There is no appended changelog at the bottom of the note.
  - **Escape hatch.** If the user explicitly requests a separate note, the skill skips the same-thread lookup and creates a fresh note without a `thread_id`.
  - **Examples updated** with preceding-conversation context, showing both a first capture and a subsequent update in the same thread (a brand design conversation that revises colors and fonts).

## 0.3.10

### Removed

- **All slash commands** (`/remember`, `/organize`, `/research`) and the entire `commands/` directory.

### Why

Claude Code auto-exposes every skill as a slash command (e.g., `/knowledge-organize`, `/research`). The plugin's explicit commands duplicated their corresponding skills, producing two entries for the same workflow in the slash-command picker. The skills are the richer primitive; the commands were thin wrappers.

This drops three files and ~200 lines of duplicate content. The Basic Memory MCP server still provides `continue_conversation`, `recent_activity`, `search`, and `ai_assistant_guide` as native slash commands.

### Updated

- `marketplace.json`, `plugin.json`, `README.md`, `PLUGIN.md` — descriptions and structure references updated to reflect skills+hooks (no commands).

## 0.3.9

### Removed

- **`/context` slash command** — collided with Claude Code's built-in `/context` (which shows context window usage). The plugin command was a thin wrapper around the MCP `build_context` tool; users can invoke that tool conversationally with the same effect.

## 0.3.8

### Removed

- **`/continue` slash command** — duplicates the Basic Memory MCP server's `continue_conversation` prompt. Use that instead.
- **`/recent` slash command** — duplicates the Basic Memory MCP server's `recent_activity` prompt. Use that instead.

### Why

The MCP server exposes prompts that surface as slash commands in Claude clients. The plugin's `/continue` and `/recent` were independent implementations of the same workflows, doubling user-visible commands and creating confusion about which one to use. The MCP versions are upstream-maintained and authoritative.

The plugin still ships unique commands that don't have MCP equivalents: `/remember`, `/context`, `/organize`, `/research`.

## 0.3.7

### Removed

- **`spec-driven-development` skill**. The skill encoded one team's internal spec workflow (specific SPEC-N numbering, "Why/What/How/How to Evaluate" structure, a `specs` project assumption). It's not generally useful for other users, and the surrounding plugin already covers the building blocks (notes, observations, relations) that anyone could use to implement their own spec workflow without skill-level guidance.

### Migration

If you relied on the skill, the underlying capabilities are still available via:
- `knowledge-capture` for writing structured notes
- `edit-note` for updating progress
- `continue-conversation` for resuming spec implementations

You can also keep your own copy of the skill locally — it just won't ship with the plugin.

## 0.3.6

### Changed

- **`continue-conversation` skill** — removed the hardcoded "common projects" list (`basic-memory-llc`, `getting-started`, etc.) which were author-specific names with no meaning to new users. The skill now points to `list_memory_projects()` for discovery and `~/.basic-memory/basic-memory.md` for routing rules.
- **`spec-driven-development` skill** — removed the "Using with Slash Commands" section referencing a `/spec` command. That command does not exist in this plugin; documenting it was misleading.

## 0.3.5

### Fixed

- **PreToolUse hook switched from `type: "prompt"` to `type: "command"`.** The prompt-type variant has no documented decision semantics for PreToolUse — the model's response is not parsed for an explicit allow/block decision, so the tool call was blocked even when the model said "proceed." The command-type variant outputs JSON with `permissionDecision: "allow"` and an `additionalContext` reminder, making the hook advisory rather than gate-keeping. The placement skill still runs; it just doesn't gate the write call any more.

### Why

The previous approach treated the hook as a binding gate on the tool call. In practice, that meant any model response shy of an explicit approval keyword was treated as a block — and there's no documented format for what such an approval looks like in a prompt-type PreToolUse hook. Switching to command-type with a known-good JSON shape removes the ambiguity.

The cost: the hook can no longer enforce that placement was considered. The model could in theory ignore the reminder. In practice, the `additionalContext` injection is enough nudge — the placement skill runs reliably in real-world conversations.

## 0.3.4

### Fixed

- **PreToolUse hook re-fired on every `write_note` retry** — the original prompt unconditionally demanded the placement skill be invoked, so when a write retry came after a user confirmation, the model interpreted the hook as a fresh demand and re-ran the skill (asking the user again). The prompt now allows "placement already settled for this write" as a valid state.
- **Placement skill asked too eagerly when there was clear precedent.** Previously, "no topic-matching folder" was treated as ambiguity → ask. Now the skill follows precedent (similar notes already at root or a folder) without asking, even when no folder is a perfect topic match. The skill only asks when there's no config rule, no topic match, *and* no precedent.

## 0.3.3

### Removed

- **Stop hook** that suggested `/remember` at conversation end. The hook entered an infinite re-entry loop in real-world testing: when the model finished its turn awaiting user input, the Stop hook fired with a "consider suggesting /remember" prompt; the model evaluated and decided no action was needed; the model tried to stop again; the hook fired again; and so on, with the user effectively unable to take their turn until interrupting manually.

### Why

The Stop hook predates 0.3.0 and was not modified by the placement work, but the v0.3.2 smoke test made the loop visible (since 0.3.2 was the first release whose hooks actually fired for the test environment — see 0.3.2 notes). Rather than ship a broken hook, removing it is the right call. Users can still invoke `/remember` manually.

A guarded re-entry-safe version may return in a later release once the Claude Code Stop-hook semantics (`stop_hook_active` and similar) are understood and can be wired in safely.

## 0.3.2

### Fixed

- **Hook matchers now use regex** — `mcp__.*__write_note` instead of the literal `mcp__basic-memory__write_note`. The previous matcher only fired for users running a locally-installed Basic Memory MCP server. Users on the claude.ai Basic Memory Cloud connector (or any other MCP server name) had hooks that silently never fired. The regex catches all variants.

### Changed

- Hook prompt body and skill/PLUGIN.md descriptions updated to be tool-name-agnostic, matching the new matcher.

### Known limitations

- Slash commands (`/remember`, `/research`, etc.) and the `basic-memory-manager` agent still have `allowed-tools` frontmatter that lists exact tool names (`mcp__basic-memory__*`). Users on alternative MCP server names may find these commands have no tool access. Pattern support in `allowed-tools` is being investigated for a follow-up release.

## 0.3.1

### Changed

- **Marketplace renamed** from `basicmachines` to `basicmachines-co` so the install identifier matches the GitHub org slug. Install command is now `/plugin install basic-memory@basicmachines-co` (was `basic-memory@basicmachines`).

### Migration

If you installed the plugin before 0.3.1:
1. Remove the old reference from `.claude/settings.json` (`basic-memory@basicmachines` in `enabledPlugins` or `installed`).
2. Re-install with the new identifier: `/plugin install basic-memory@basicmachines-co`.

The `extraKnownMarketplaces` block (if you used one) also needs the key updated from `"basicmachines"` to `"basicmachines-co"`.

## 0.3.0

### Added

- **`placement` skill** — decides which folder a new note belongs in. Runs automatically before every `mcp__basic-memory__write_note` call via a `PreToolUse` hook. Reads project conventions from a unified config file and applies a short-circuit decision flow (config → tree → search → ask).
- **Unified config file** (`basic-memory.md`) — a single config surface for project conventions. Lives as a Basic Memory note at the project root or as a global file at `~/.basic-memory/basic-memory.md`. Reserved sections: `## Projects`, `## Placements`, `## Formats`, `## Schemas`. H3 sub-sections provide project-specific overrides; bare H2 content is the default. Section-level fallback between project, global, and built-in defaults.
- **Bootstrap pattern** — documented conversational flow for generating a starter `basic-memory.md` from an existing project's structure. No new command; just ask Claude.

### Removed

- **`validate-memo` skill** and the entire integration with `basic-memory-hooks` (the external validation server). The model-driven approach replaces external validation.
- **`edit-note-local` skill** — its core dependency (`basic-memory sync --watch` running as a separate process) no longer exists; sync now runs automatically inside the MCP server. `edit-note` covers the remaining use cases.
- All references to `localhost:8000` / `localhost:4665`, `basic-memory-hooks`, and `.basic-memory/format.md` across docs and skills.

### Changed

- **`hooks/hooks.json`** — `PreToolUse` on `write_note` now invokes the `placement` skill instead of validate-memo.
- **`commands/remember.md`** — placement is automatic; `[folder]` argument is now an explicit override.
- **`PLUGIN.md`** — new "Configuration" section documenting the unified config schema, precedence, and bootstrap.
- **`README.md`** — removed hooks server quick-start; added pointer to the new configuration model.

### Migration

If you were using `basic-memory-hooks` for memo validation:
- Format rules previously kept in `.basic-memory/format.md` move to a `## Formats` section in `basic-memory.md`. They are now guidance for the model rather than externally enforced.
- The `basic-memory-hooks` server is no longer needed; you can remove it.

If you were using `edit-note-local`:
- Use `edit-note` instead. MCP `edit_note` operations (`append`, `prepend`, `find_replace`, `replace_section`) cover the same workflows.