handoff-mcp-server 0.15.0 → 0.16.0

package/Cargo.lock

@@ -136,7 +136,7 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.15.0"
+version = "0.16.0"
 edition = "2021"
 description = "MCP server that gives AI coding agents persistent memory across sessions"
 license = "MIT"

package/README.md

@@ -33,7 +33,37 @@ At session start, the agent calls `handoff_load_context` to pick up where things
 
 ## Installation
 
-### cargo (recommended if you have Rust)
+### Claude Code Plugin (recommended)
+
+The easiest way to install handoff-mcp is as a Claude Code plugin:
+
+```bash
+# 1. Install the binary (required — the plugin calls it)
+npm install -g handoff-mcp-server
+# or: cargo install handoff-mcp
+
+# 2. Add the marketplace
+/plugin marketplace add alphaelements/handoff-mcp
+
+# 3. Install the plugin (MCP server + skills)
+/plugin install handoff-mcp@handoff-mcp-marketplace
+```
+
+This registers the MCP server and all skills automatically — no manual
+`.mcp.json` or skill file setup needed.
+
+**Optional: memory auto-injection hooks**
+
+```bash
+/plugin install handoff-mcp-hooks@handoff-mcp-marketplace
+/plugin enable handoff-mcp-hooks
+```
+
+This adds hooks that inject relevant project memories on every prompt and file
+edit. Disable anytime with `/plugin disable handoff-mcp-hooks` — the MCP server
+and skills remain active.
+
+### cargo
 
 ```bash
 cargo install handoff-mcp
@@ -58,9 +88,10 @@ cd handoff-mcp
 cargo build --release
 ```
 
-## Setup
+## Setup (non-plugin)
 
-Register handoff-mcp as an MCP server in Claude Code:
+If you installed via cargo/npm (without the plugin), register handoff-mcp as an
+MCP server in Claude Code manually:
 
 **Option A** — CLI (recommended):
 
@@ -86,8 +117,9 @@ The `-s user` flag registers it globally (available in all projects). Verify wit
 
 ### Enable automatic memory injection (optional)
 
-If you want project memories to be automatically injected into your context
-(instead of calling `handoff_memory_query` manually every time), run:
+If you installed via the plugin, use `handoff-mcp-hooks` instead (see above).
+
+For non-plugin installs, run:
 
 ```bash
 handoff-mcp setup
@@ -215,6 +247,7 @@ rename) so a concurrent reader never sees a partially-written file.
 | `handoff_memory_delete` | Delete a memory by id (full id or unique prefix) |
 | `handoff_memory_cleanup` | Housekeeping (for SessionStart): silently merge exact duplicates, return near-duplicate/stale recommendations, gc old injection sidecars |
 
+For usage best practices (granularity, scope_paths, conflict handling, cleanup), see `skills/handoff-memory/SKILL.md`.
 See [Project Memory](#project-memory-1) below for what it is and how to wire automatic injection.
 
 ### Task Data Model
@@ -549,16 +582,26 @@ This project uses handoff-mcp for session continuity.
   surfaced as conflicts for you to merge or force-save — never merged silently.
 ```
 
-## Skill File (Optional)
+## Skills
 
-This repository includes a skill file at [`skills/handoff/SKILL.md`](skills/handoff/SKILL.md) that makes handoff behavior automatic in Claude Code. Copy it to your user skills directory:
+This repository includes skill files that make handoff behavior automatic in Claude Code:
+
+| Skill | Purpose |
+|-------|---------|
+| `handoff` | Core session lifecycle, task management, metrics, scheduling |
+| `handoff-load` | Quick session-start procedure |
+| `handoff-memory` | Memory CRUD, conflict handling, cleanup |
+| `handoff-refer` | Cross-project referrals |
+| `handoff-import` | Bulk import from documents |
+
+**Plugin users**: all skills are included automatically.
+
+**Manual setup**: copy the skills to your user skills directory:
 
 ```bash
-cp -r skills/handoff ~/.claude/skills/
+cp -r skills/* ~/.claude/skills/
 ```
 
-This teaches the agent to automatically load context at session start, track tasks during work, and save context at session end.
-
 ## Compatibility
 
 - **Claude Code** — fully supported (stdio transport)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-mcp-server",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "MCP server that gives AI coding agents persistent memory across sessions",
   "license": "MIT",
   "author": "AlphaElements <66808803+alphaelements@users.noreply.github.com>",

package/scripts/sync-plugin-skills.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Sync skills/ -> plugin/skills/ for plugin distribution.
+# Run before release to ensure the plugin has the latest skills.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(dirname "$SCRIPT_DIR")"
+
+rm -rf "$ROOT/plugin/skills"
+cp -a "$ROOT/skills" "$ROOT/plugin/skills"
+
+echo "Synced skills/ -> plugin/skills/"
+diff -rq "$ROOT/skills/" "$ROOT/plugin/skills/" && echo "No differences." || echo "WARNING: differences remain after sync."

package/skills/handoff-memory/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: handoff-memory
+description: "Project memory — save, query, merge, and clean up durable project knowledge (lessons, rules, conventions, gotchas). Triggers on 'メモリ保存', 'これ覚えて', '知見を残して', '過去の知見', 'memory save', 'memory query', 'remember this', 'recall', 'cleanup memories', or when recording post-incident learnings, recurring NG patterns, or project-specific conventions."
+---
+
+# Handoff Memory Skill
+
+## When to use
+
+- The user says "メモリ保存", "これ覚えて", "知見を残して", "remember this", "save this as a memory"
+- The user asks "過去の知見を確認", "recall", "what do we know about X"
+- You discover a reusable lesson, recurring NG pattern, or project-specific convention worth persisting across sessions
+- Post-incident feedback or investigation results should be captured
+- Existing memories need merging, updating, or pruning
+- Session start — run cleanup to keep the memory store healthy
+
+## Granularity Rule
+
+**One memory = one piece of knowledge.** Do not bundle multiple unrelated lessons
+into a single memory. Each memory should be independently searchable and
+independently deletable. If two ideas always travel together, save them together;
+if they could be relevant in different contexts, split them.
+
+## Saving a Memory
+
+Call `handoff_memory_save` with:
+
+| Param | Required | Description |
+|---|---|---|
+| `text` | yes | The memory content. Be specific and actionable — "always use X because Y", not "X is important" |
+| `kind` | no (default: `lesson`) | One of: `lesson` (something learned), `rule` (a mandated practice), `convention` (an agreed pattern), `gotcha` (a non-obvious trap) |
+| `scope_paths` | no | Path prefixes this memory applies to (e.g. `["src/storage/", "src/mcp/handlers/"]`). Memories with matching scope_paths get a relevance boost when the user edits files under those paths |
+| `tags` | no | Free-form tags for searchability (e.g. `["atomic-write", "config"]`). Tags are included in the similarity index |
+| `force` | no | `true` to skip near-duplicate detection and save unconditionally |
+| `merge_into` | no | ID of an existing memory to overwrite with merged content (see Merging below) |
+| `absorb_ids` | no | IDs of memories to delete after merging into the target |
+
+### scope_paths Best Practices
+
+- Use directory-level substrings, not full file paths: `"src/storage/"` not `"src/storage/config.rs"`. The matching is substring-based (`file_path.contains(scope)`), so `"storage/"` will match any file whose path contains that segment
+- Scope broadly enough to catch related files, narrowly enough to avoid noise
+- A memory with no scope_paths relies purely on text similarity for injection — fine for project-wide rules, but file-specific gotchas benefit from scoping
+
+### tags Best Practices
+
+- Use lowercase, hyphenated terms: `"atomic-write"`, `"json-rpc"`, `"config-toml"`
+- Tags supplement the body text for search — add tags for synonyms or concepts not explicitly mentioned in the body
+
+## Handling Near-Duplicate Conflicts
+
+When `handoff_memory_save` returns `status: "conflict"`, it means the new memory
+is similar to one or more existing memories (Jaccard similarity >= threshold). The
+response includes both the new text and the similar existing memories.
+
+**Decision flow:**
+
+1. **Read both texts carefully.** Are they expressing the same knowledge?
+2. **If yes — merge:** Write a combined text that captures both perspectives, then call `handoff_memory_save` again with:
+   - `text`: the merged content
+   - `merge_into`: ID of the existing memory to keep
+   - `absorb_ids`: IDs of any other similar memories to absorb
+   - Update `kind`, `tags`, `scope_paths` as needed
+3. **If no — force-save:** The memories are genuinely distinct despite textual similarity. Call `handoff_memory_save` with `force: true` to save the new one separately.
+
+Do not ignore conflicts — they indicate the memory store may have redundancy that degrades injection quality.
+
+## Querying Memories
+
+Call `handoff_memory_query` with:
+
+| Param | Description |
+|---|---|
+| `text` | The prompt or question to match against (BM25 relevance ranking) |
+| `file_paths` | Files being worked on — memories scoped to these paths get a boost |
+| `session_id` | Current session ID — suppresses re-injection of memories already seen this session |
+| `limit` | Max memories to return (default from config, typically 5) |
+| `tool_name` | Tool being used (adds context tokens for matching) |
+| `mark_injected` | Whether to record injection for dedup (default: true) |
+
+The query engine uses BM25 text similarity plus a scope_path bonus. Passing
+`session_id` enables per-session diff injection: a memory already injected this
+session (same content hash) is filtered out, but an edited memory (new hash) is
+re-injected.
+
+## Cleanup
+
+### When to Run
+
+Run `handoff_memory_cleanup` at the start of each session (the SessionStart hook
+does this automatically if configured). Optional arguments:
+
+| Param | Default | Description |
+|---|---|---|
+| `apply_exact_merges` | `true` | Set `false` to skip auto-merging and only return recommendations |
+| `stale_days` | from config (default 60) | Override the staleness threshold in days |
+
+It performs three passes:
+
+1. **Exact duplicates** — silently auto-merged (lossless; oldest entry kept, others absorbed). Skipped when `apply_exact_merges` is `false`
+2. **Near-duplicate clusters** — returned as recommendations for AI-driven merge
+3. **Stale memories** — memories not referenced for `stale_days`, returned as recommendations
+
+### Acting on Cleanup Recommendations
+
+- **similar_clusters**: Review each cluster. If the memories are truly redundant, merge them with `handoff_memory_save(merge_into=..., absorb_ids=[...])`. If distinct, leave them.
+- **stale**: Consider whether the memory is obsolete (delete with `handoff_memory_delete`) or simply rarely triggered (leave it — low hit_count doesn't mean low value).
+
+### Manual Deletion
+
+Call `handoff_memory_delete` with the memory `id` (full ID or unique prefix). Use
+this for memories that are confirmed obsolete, wrong, or superseded by a code
+change.
+
+## Memory Hooks (Optional Auto-Injection)
+
+Memory tools can be called manually, but for automatic injection without AI
+initiative, configure Claude Code hooks:
+
+| Hook | Tool Call | Purpose |
+|---|---|---|
+| `UserPromptSubmit` | `handoff_memory_query` (prompt text) | Inject memories relevant to each user prompt |
+| `PreToolUse` (`Edit\|Write\|MultiEdit`) | `handoff_memory_query` (file path) | Inject memories scoped to the file being edited |
+| `SessionStart` | `handoff_memory_cleanup` | Auto-merge exact duplicates, surface recommendations |
+
+Run `handoff-mcp setup` to install these hooks automatically, or
+`handoff-mcp setup --uninstall` to remove them. See the README for the full hook
+JSON configuration.
+
+## Memory vs Session vs CLAUDE.md
+
+| Layer | Lifespan | Purpose |
+|---|---|---|
+| Sessions (`.handoff/sessions/`) | Per-conversation | "What was I doing last time?" |
+| Memory (`.handoff/memory/`) | Cross-session, long-lived | "What has this project learned?" |
+| `CLAUDE.md` | Permanent | Foundational rules, build commands, repo structure |
+| `.claude/skills/` | Permanent | Operational procedures triggered by intent |
+
+Rule changes: discover via memory → codify in skills/CLAUDE.md. Memory is the
+source of evidence; skills and CLAUDE.md are the source of authority.