handoff-mcp-server 0.12.0 → 0.13.1

package/Cargo.lock

@@ -144,10 +144,11 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.12.0"
+version = "0.13.1"
 dependencies = [
  "anyhow",
  "chrono",
+ "lexsim",
  "serde",
  "serde_json",
  "tempfile",
@@ -242,6 +243,16 @@ version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
 
+[[package]]
+name = "lexsim"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "579b9d7ab407540bead4688eaf1675410a198d77c237a30cda55597df98926e1"
+dependencies = [
+ "unicode-normalization",
+ "unicode-segmentation",
+]
+
 [[package]]
 name = "libc"
 version = "0.2.186"
@@ -382,6 +393,7 @@ version = "1.0.150"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
 dependencies = [
+ "indexmap",
  "itoa",
  "memchr",
  "serde",
@@ -454,6 +466,21 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "tinyvec"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3e61e67053d25a4e82c844e8424039d9745781b3fc4f32b8d55ed50f5f667ef3"
+dependencies = [
+ "tinyvec_macros",
+]
+
+[[package]]
+name = "tinyvec_macros"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
+
 [[package]]
 name = "toml"
 version = "0.8.23"
@@ -501,6 +528,21 @@ version = "1.0.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
 
+[[package]]
+name = "unicode-normalization"
+version = "0.1.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5fd4f6878c9cb28d874b009da9e8d183b5abc80117c40bbd187a1fde336be6e8"
+dependencies = [
+ "tinyvec",
+]
+
+[[package]]
+name = "unicode-segmentation"
+version = "1.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
+
 [[package]]
 name = "unicode-xid"
 version = "0.2.6"

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.12.0"
+version = "0.13.1"
 edition = "2021"
 description = "MCP server that gives AI coding agents persistent memory across sessions"
 license = "MIT"
@@ -9,17 +9,18 @@ homepage = "https://github.com/alphaelements/handoff-mcp"
 readme = "README.md"
 keywords = ["mcp", "ai", "claude", "handoff", "context"]
 categories = ["command-line-utilities", "development-tools"]
-rust-version = "1.70"
+rust-version = "1.85"
 exclude = ["lefthook.yml", "tmp/", "wiki/", "docs/", ".claude/", ".vscode/"]
 
 [dependencies]
 serde = { version = "1", features = ["derive"] }
-serde_json = "1"
+serde_json = { version = "1", features = ["preserve_order"] }
 toml = "0.8"
 toml_edit = "0.22"
 chrono = { version = "0.4", features = ["serde"] }
 anyhow = "1"
 thiserror = "2"
+lexsim = "0.1.0"
 
 [dev-dependencies]
 tempfile = "3.27.0"

package/README.md

@@ -33,12 +33,23 @@ At session start, the agent calls `handoff_load_context` to pick up where things
 
 ## Installation
 
-### npm (recommended)
+### cargo (recommended if you have Rust)
+
+```bash
+cargo install handoff-mcp
+```
+
+### npm
 
 ```bash
 npm install -g handoff-mcp-server
 ```
 
+Both install the same binary. `cargo install` fetches the crate from
+[crates.io](https://crates.io/crates/handoff-mcp) and compiles it directly;
+`npm install` downloads the source and runs `cargo build --release` via
+postinstall, so either way you need a Rust toolchain.
+
 ### Build from source
 
 ```bash
@@ -73,6 +84,34 @@ 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:
+
+```bash
+handoff-mcp setup
+```
+
+This installs Claude Code hooks into `~/.claude/settings.json` that
+automatically call `handoff_memory_query` on every prompt and file edit, and run
+`handoff_memory_cleanup` at session start. Restart Claude Code after running setup.
+
+You can check the current status or remove the hooks:
+
+```bash
+handoff-mcp setup --check      # Show hook status
+handoff-mcp setup --uninstall  # Remove handoff hooks
+```
+
+The hooks fire on every prompt and file edit, which adds a small overhead per
+interaction. If you want to stop automatic injection, run
+`handoff-mcp setup --uninstall` — the memory tools themselves remain available
+for manual use, only the automatic hooks are removed.
+
+See [Automatic injection via hooks](#automatic-injection-via-hooks) for the
+manual configuration alternative.
+
 ## Quick Start
 
 1. **Initialize** a project:
@@ -155,9 +194,21 @@ rename) so a concurrent reader never sees a partially-written file.
 | `handoff_dashboard` | Overview of all handoff-enabled projects |
 | `handoff_import_context` | Bulk import tasks and session data from documents |
 | `handoff_refer` | Send a cross-project referral (bug, improvement, request) |
-| `handoff_list_referrals` | List incoming referrals from other projects |
+| `handoff_list_referrals` | List incoming referrals from other projects (summaries only) |
+| `handoff_get_referral` | Fetch one incoming referral in full — details, suggested tasks, done_criteria, context |
 | `handoff_update_referral` | Update referral status (open → acknowledged → resolved) |
 
+### Project Memory
+
+| Tool | Purpose |
+|------|---------|
+| `handoff_memory_save` | Save a durable project memory (lesson/rule/convention/gotcha); detects exact and near-duplicate memories and hands near-duplicates back for AI-driven merge |
+| `handoff_memory_query` | Return the memories most relevant to the current prompt/file (BM25 + scope-path boost); with a `session_id`, suppresses repeats already injected this session |
+| `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 |
+
+See [Project Memory](#project-memory-1) below for what it is and how to wire automatic injection.
+
 ### Task Data Model
 
 Tasks are stored as a directory tree with status encoded in filenames:
@@ -223,9 +274,11 @@ name = "my-project"
 description = "Project description"
 
 [settings]
-history_limit = 20         # Max closed sessions to keep
-done_task_limit = 10       # Max completed tasks to show
-auto_git_summary = true    # Capture git state automatically
+history_limit = 20            # Max closed sessions to keep
+done_task_limit = 10          # Max completed tasks to show
+auto_git_summary = true       # Capture git state automatically
+require_estimate_hours = true # Require estimate_hours on leaf tasks (default true)
+ai_estimate_multiplier = 0.2  # Multiplier turning human estimates into AI-effort hours
 
 [dashboard]
 scan_dirs = ["~/pro/"]     # Directories to scan for dashboard
@@ -263,6 +316,152 @@ mode = "compare"           # plan, actual, compare
 
 All configuration sections can be updated via `handoff_update_config` with dot-notation keys (e.g., `"calendar.work_hours_per_day": 7`).
 
+### Estimates and AI effort
+
+handoff-mcp distinguishes the **raw human-effort estimate** you record on a task
+from the **AI-effort hours** used in scheduling and metrics:
+
+- **`require_estimate_hours`** (default `true`) — `handoff_update_task` rejects
+  creating or updating a *leaf* task (in `todo` / `in_progress` / `review` /
+  `done`) without `schedule.estimate_hours > 0`. Parent tasks (with children) and
+  `blocked` / `skipped` tasks are exempt, and an estimate already on the task
+  satisfies the requirement. Set to `false` to opt out.
+- **`ai_estimate_multiplier`** (default `0.2`) — the factor applied to raw
+  estimates to model how long the work takes when an AI agent does it. Always
+  record the *raw human-effort* estimate; the multiplier is applied at
+  aggregation time by `handoff_get_metrics` (`total_adjusted_estimate_hours` and
+  per-milestone `adjusted_estimate_hours`) and `handoff_get_capacity`. Raw values
+  are never overwritten.
+
+## Project Memory
+
+Sessions answer *"what was I doing last time?"*. **Memory** answers a longer-lived
+question: *"what should every session in this project always know?"* — durable
+lessons, rules, conventions, and gotchas that outlive any one session.
+
+> **Note:** The memory tools (`handoff_memory_save`, `handoff_memory_query`, etc.) can always be
+> called directly by the agent. For **automatic** injection — where relevant
+> memories are surfaced on every prompt without the agent asking — you need to
+> configure Claude Code hooks. See [Automatic injection via hooks](#automatic-injection-via-hooks).
+
+Memories live in `.handoff/memory/` (one JSON file per memory, plus per-session
+`injected/` sidecars). A built-in multilingual similarity engine (Japanese /
+English, dictionary-free) ranks relevance and detects duplicates, all in-memory
+and sub-millisecond.
+
+### Using it directly
+
+The agent can call the memory tools at any time:
+
+- `handoff_memory_save` — record a memory. An exact duplicate is reported (not
+  rewritten); a near-duplicate comes back as a `conflict` with both bodies so the
+  agent can merge them (`merge_into=<id>`, `absorb_ids=[…]`) or save separately
+  with `force=true`. **handoff-mcp never merges for you** — it surfaces both
+  bodies and lets the agent decide.
+- `handoff_memory_query` — fetch the memories most relevant to some text and/or files.
+- `handoff_memory_delete` / `handoff_memory_cleanup` — prune and de-duplicate the store.
+
+### Automatic injection via hooks
+
+MCP is request/response — the server cannot push a memory into the agent's
+context on its own. **Claude Code hooks** close that gap: they fire regardless of
+what the agent intends, call `handoff_memory_query`, and inject the matching memories as
+`additionalContext`. A per-session diff (keyed on the hook `session_id`) ensures
+the same memory is **not injected twice in one session** — and an *edited* memory
+(new content hash) is re-injected.
+
+| Event | Calls | Effect |
+|-------|-------|--------|
+| `UserPromptSubmit` | `handoff_memory_query` (prompt text) | Inject memories relevant to the prompt |
+| `PreToolUse` (`Edit\|Write\|MultiEdit`) | `handoff_memory_query` (file path) | Inject memories scoped to the file being edited |
+| `SessionStart` | `handoff_memory_cleanup` | Merge exact duplicates, gc old sidecars |
+
+> **Wire hooks in your *user/global* settings, not in the repo.** Hooks are a
+> personal workflow choice; the handoff-mcp repo does not ship a `.claude/`
+> hooks config, and you should not commit one into a shared project. Put the
+> config in `~/.claude/settings.json` (global) or your own
+> `.claude/settings.local.json` (git-ignored).
+
+**Native `mcp_tool` hook (preferred).** Recent Claude Code versions can call an
+MCP tool from a hook directly, with no wrapper script. In
+`~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      { "hooks": [ {
+        "type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_query",
+        "input": { "project_dir": "${cwd}",
+                   "session_id": "${session_id}", "text": "${prompt}" }
+      } ] }
+    ],
+    "PreToolUse": [
+      { "matcher": "Edit|Write|MultiEdit", "hooks": [ {
+        "type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_query",
+        "input": { "project_dir": "${cwd}",
+                   "session_id": "${session_id}", "tool_name": "${tool_name}",
+                   "text": "${tool_input.file_path}",
+                   "file_paths": ["${tool_input.file_path}"] }
+      } ] }
+    ],
+    "SessionStart": [
+      { "hooks": [ {
+        "type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_cleanup",
+        "input": { "project_dir": "${cwd}" }
+      } ] }
+    ]
+  }
+}
+```
+
+(`server` must match the name you registered handoff-mcp under — `handoff` in the
+[Setup](#setup) examples.)
+
+**Wrapper script fallback.** If your Claude Code version doesn't support the
+`mcp_tool` hook type, use the bundled `command` wrapper
+[`scripts/handoff-memory-hook.py`](scripts/handoff-memory-hook.py). It reads the
+hook JSON on stdin, calls the server over JSON-RPC, and emits
+`additionalContext` — the memory tools return their payload as a JSON *string* so
+both paths parse it identically. Point all three hooks at it:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      { "hooks": [ { "type": "command",
+        "command": "/path/to/handoff-mcp/scripts/handoff-memory-hook.py" } ] }
+    ],
+    "PreToolUse": [
+      { "matcher": "Edit|Write|MultiEdit", "hooks": [ { "type": "command",
+        "command": "/path/to/handoff-mcp/scripts/handoff-memory-hook.py" } ] }
+    ],
+    "SessionStart": [
+      { "hooks": [ { "type": "command",
+        "command": "/path/to/handoff-mcp/scripts/handoff-memory-hook.py" } ] }
+    ]
+  }
+}
+```
+
+The script resolves the `handoff-mcp` binary from `PATH` (override with
+`HANDOFF_MCP_BIN`) and **fails safe**: on any error it prints nothing and exits
+0, so a memory miss is silent and never blocks your prompt.
+
+### Memory settings
+
+All under `[settings]` in `.handoff/config.toml`, all with safe defaults
+(existing projects need no change), all settable via `handoff_update_config`:
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `memory_enabled` | `true` | Master switch. When `false`, all four memory tools return a benign empty result and write nothing |
+| `memory_dup_threshold` | `0.72` | Jaccard similarity at/above which a save is a near-duplicate conflict and cleanup groups a cluster |
+| `memory_query_min_score` | `0.5` | BM25 relevance floor for `handoff_memory_query` results |
+| `memory_query_limit` | `5` | Max memories returned per query |
+| `memory_stale_days` | `60` | Days without a reference before a memory is flagged stale |
+| `memory_injected_gc_days` | `14` | Age at which per-session injection sidecars are garbage-collected |
+
 ## MCP Resources
 
 | URI | Description |
@@ -290,6 +489,10 @@ This project uses handoff-mcp for session continuity.
 - **Decisions**: Record decisions with confidence levels as they are made,
   not just at session end. Use `confirmed` for verified facts, `estimated`
   for reasonable assumptions, `unverified` for unknowns.
+- **Project memory**: Use `handoff_memory_save` to record durable lessons, rules,
+  conventions, and gotchas that every future session should know. Use
+  `handoff_memory_query` to retrieve relevant memories. Near-duplicate memories are
+  surfaced as conflicts for you to merge or force-save — never merged silently.
 ```
 
 ## Skill File (Optional)

package/package.json

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

package/scripts/cargo-env.sh

@@ -0,0 +1,29 @@
+# shellcheck shell=sh
+# cargo-env.sh — make cargo commands work across heterogeneous dev environments.
+#
+# Some environments (e.g. a Docker image where CARGO_HOME=/usr/local/cargo is
+# owned by root) expose a CARGO_HOME that the current user cannot write to.
+# cargo then fails to download/cache crates or fetch the advisory-db, breaking
+# the git hooks even though nothing is wrong with the code.
+#
+# This script detects an unwritable CARGO_HOME and transparently falls back to
+# the per-user $HOME/.cargo, which every supported environment can write to.
+# When CARGO_HOME is already writable (local macOS, a synced Mac, or simply
+# unset so cargo uses its default ~/.cargo) it leaves the environment untouched.
+#
+# Usage (from a hook or shell):
+#   . scripts/cargo-env.sh && cargo <args>
+
+# Resolve the directory cargo would use right now.
+_cargo_home="${CARGO_HOME:-$HOME/.cargo}"
+
+# Probe writability with a temp file; fall back to $HOME/.cargo if we can't write.
+if ! ( mkdir -p "$_cargo_home" 2>/dev/null && touch "$_cargo_home/.cargo-env-wtest" 2>/dev/null ); then
+  export CARGO_HOME="$HOME/.cargo"
+  mkdir -p "$CARGO_HOME" 2>/dev/null || true
+else
+  rm -f "$_cargo_home/.cargo-env-wtest" 2>/dev/null || true
+  export CARGO_HOME="$_cargo_home"
+fi
+
+unset _cargo_home

package/scripts/handoff-memory-hook.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""Claude Code hook wrapper for handoff-mcp project memory.
+
+This is the **fallback path** for memory auto-injection. The preferred wiring is
+a native ``mcp_tool`` hook that calls ``handoff_memory_query`` / ``handoff_memory_cleanup``
+directly (see README "Project Memory"); this script exists for Claude Code
+versions that lack the ``mcp_tool`` hook type, by translating a Claude Code hook
+event into a single JSON-RPC ``tools/call`` against the handoff-mcp server and
+emitting the result as ``hookSpecificOutput.additionalContext``.
+
+It speaks the server's line-delimited JSON-RPC over stdio: one request object on
+one line in, one response object on one line out. ``handoff_memory_query`` /
+``handoff_memory_cleanup`` return their payload as a JSON *string* inside
+``result.content[0].text`` (so both this wrapper and the native hook path parse
+it identically), which this script re-parses.
+
+Wiring (in ``~/.claude/settings.json`` — do NOT commit this into a repo):
+
+    {
+      "hooks": {
+        "UserPromptSubmit": [
+          { "hooks": [ { "type": "command",
+              "command": "handoff-mcp-memory-hook" } ] }
+        ],
+        "PreToolUse": [
+          { "matcher": "Edit|Write|MultiEdit",
+            "hooks": [ { "type": "command",
+              "command": "handoff-mcp-memory-hook" } ] }
+        ],
+        "SessionStart": [
+          { "hooks": [ { "type": "command",
+              "command": "handoff-mcp-memory-hook" } ] }
+        ]
+      }
+    }
+
+The same script handles all three events; it picks the tool from
+``hook_event_name`` on stdin.
+
+Environment:
+- ``HANDOFF_MCP_BIN`` — path to the ``handoff-mcp`` binary (default: ``handoff-mcp``
+  resolved on ``PATH``).
+
+Design contract: this script must **never break the session**. On any error
+(binary missing, bad JSON, timeout) it prints nothing and exits 0 — a memory
+miss is silent, never a blocked prompt.
+"""
+
+# `X | None` annotations are evaluated lazily so this runs on Python 3.7+
+# (a hook host may not have 3.10). The annotations are never evaluated at runtime.
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+
+# Map a Claude Code hook event to the memory tool it drives.
+QUERY_EVENTS = {"UserPromptSubmit", "PreToolUse"}
+CLEANUP_EVENTS = {"SessionStart"}
+
+# How long to wait for the server to answer one request, in seconds. The query
+# is in-memory and sub-millisecond; this is just a safety net so a hung binary
+# can never stall the prompt.
+TIMEOUT_SECONDS = 5.0
+
+
+def _server_bin() -> str | None:
+    """Resolve the handoff-mcp binary path, or None if it can't be found."""
+    explicit = os.environ.get("HANDOFF_MCP_BIN")
+    if explicit:
+        return explicit if os.path.exists(explicit) else None
+    return shutil.which("handoff-mcp")
+
+
+def _call(bin_path: str, tool: str, arguments: dict) -> dict | None:
+    """Send one ``tools/call`` line and parse the inner JSON payload.
+
+    Returns the decoded inner object (e.g. ``{"memories": [...]}`), or None on
+    any transport / decode failure. The server is stateless per line, so no
+    ``initialize`` handshake is needed — a bare ``tools/call`` is answered.
+    """
+    request = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {"name": tool, "arguments": arguments},
+    }
+    try:
+        proc = subprocess.run(
+            [bin_path],
+            input=json.dumps(request) + "\n",
+            capture_output=True,
+            text=True,
+            timeout=TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+
+    # The response is the first non-empty stdout line (stderr carries the
+    # startup banner and is ignored).
+    line = next((ln for ln in proc.stdout.splitlines() if ln.strip()), None)
+    if not line:
+        return None
+    try:
+        envelope = json.loads(line)
+        text = envelope["result"]["content"][0]["text"]
+        return json.loads(text)
+    except (json.JSONDecodeError, KeyError, IndexError, TypeError):
+        return None
+
+
+def _file_paths_from_tool_input(tool_input) -> list[str]:
+    """Pull file paths out of a PreToolUse ``tool_input`` (Edit/Write/MultiEdit)."""
+    if not isinstance(tool_input, dict):
+        return []
+    paths = []
+    fp = tool_input.get("file_path")
+    if isinstance(fp, str) and fp:
+        paths.append(fp)
+    # MultiEdit and similar may carry an edits array; each can name a file.
+    for edit in tool_input.get("edits", []) or []:
+        if isinstance(edit, dict):
+            efp = edit.get("file_path")
+            if isinstance(efp, str) and efp:
+                paths.append(efp)
+    return paths
+
+
+def _emit(event: str, context: str) -> None:
+    """Print a Claude Code hook output object carrying additionalContext."""
+    if not context:
+        return
+    out = {
+        "hookSpecificOutput": {
+            "hookEventName": event,
+            "additionalContext": context,
+        }
+    }
+    print(json.dumps(out))
+
+
+def _format_memories(payload: dict) -> str:
+    """Turn a ``handoff_memory_query`` payload into an injectable context block."""
+    memories = payload.get("memories") or []
+    if not memories:
+        return ""
+    lines = ["Relevant project memories (handoff-mcp):"]
+    for m in memories:
+        text = (m.get("text") or "").strip()
+        if not text:
+            continue
+        kind = m.get("kind") or "memory"
+        lines.append(f"- [{kind}] {text}")
+    # Only a header with no bullets means nothing useful to inject.
+    return "\n".join(lines) if len(lines) > 1 else ""
+
+
+def main() -> int:
+    raw = sys.stdin.read()
+    try:
+        hook = json.loads(raw) if raw.strip() else {}
+    except json.JSONDecodeError:
+        return 0  # malformed hook input — stay silent, never block
+
+    event = hook.get("hook_event_name") or ""
+    bin_path = _server_bin()
+    if not bin_path:
+        return 0  # server not installed — nothing to inject
+
+    project_dir = hook.get("cwd") or os.getcwd()
+    session_id = hook.get("session_id")
+
+    if event in QUERY_EVENTS:
+        # UserPromptSubmit → match the prompt. PreToolUse → match the file(s).
+        prompt = hook.get("prompt") or ""
+        tool_name = hook.get("tool_name")
+        file_paths = _file_paths_from_tool_input(hook.get("tool_input"))
+        # Text fed to BM25: the prompt for UserPromptSubmit, else the file paths
+        # (the server also adds basenames + tool_name to the query).
+        text = prompt if prompt else " ".join(file_paths)
+        arguments = {"project_dir": project_dir, "text": text}
+        if session_id:
+            arguments["session_id"] = session_id
+        if tool_name:
+            arguments["tool_name"] = tool_name
+        if file_paths:
+            arguments["file_paths"] = file_paths
+
+        payload = _call(bin_path, "handoff_memory_query", arguments)
+        if payload:
+            _emit(event, _format_memories(payload))
+        return 0
+
+    if event in CLEANUP_EVENTS:
+        # Housekeeping only: merge exact duplicates and gc sidecars. We do not
+        # inject the cleanup recommendations as context (that is for an explicit
+        # AI-driven pass), so there is no additionalContext to emit here.
+        _call(bin_path, "handoff_memory_cleanup", {"project_dir": project_dir})
+        return 0
+
+    # Unknown event — nothing to do.
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/lib.rs

@@ -1,2 +1,3 @@
 pub mod mcp;
+pub mod setup;
 pub mod storage;

package/src/main.rs

@@ -3,6 +3,35 @@ use std::io::{self, BufRead, Write};
 use handoff_mcp::mcp::protocol::process_line;
 
 fn main() {
+    let args: Vec<String> = std::env::args().collect();
+
+    if args.len() >= 2 {
+        match args[1].as_str() {
+            "setup" => {
+                let check = args.iter().any(|a| a == "--check");
+                let uninstall = args.iter().any(|a| a == "--uninstall");
+                if let Err(e) = handoff_mcp::setup::run_setup(check, uninstall) {
+                    eprintln!("Error: {e:#}");
+                    std::process::exit(1);
+                }
+                return;
+            }
+            "--version" | "-V" => {
+                println!("handoff-mcp v{}", env!("CARGO_PKG_VERSION"));
+                return;
+            }
+            "--help" | "-h" => {
+                print_help();
+                return;
+            }
+            other => {
+                eprintln!("Unknown command: {other}");
+                eprintln!("Run `handoff-mcp --help` for usage.");
+                std::process::exit(1);
+            }
+        }
+    }
+
     eprintln!("handoff-mcp v{}", env!("CARGO_PKG_VERSION"));
 
     let stdin = io::stdin();
@@ -27,3 +56,21 @@ fn main() {
         }
     }
 }
+
+fn print_help() {
+    println!(
+        "handoff-mcp v{version}
+MCP server for AI session handoff
+
+USAGE:
+    handoff-mcp              Start the MCP server (stdio transport)
+    handoff-mcp setup        Install memory auto-injection hooks into Claude Code
+    handoff-mcp setup --check    Check if hooks are installed
+    handoff-mcp setup --uninstall    Remove handoff hooks from Claude Code
+
+OPTIONS:
+    -h, --help       Print this help message
+    -V, --version    Print version",
+        version = env!("CARGO_PKG_VERSION")
+    );
+}