handoff-mcp-server 0.13.1 → 0.15.1

package/Cargo.lock

@@ -13,9 +13,9 @@ dependencies = [
 
 [[package]]
 name = "anyhow"
-version = "1.0.102"
+version = "1.0.103"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
+checksum = "2a4385e2e34eb35d6b3efe798b9eb88096925d87726c0798709bf56d9ed84af3"
 
 [[package]]
 name = "autocfg"
@@ -37,9 +37,9 @@ checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
 [[package]]
 name = "cc"
-version = "1.2.64"
+version = "1.2.65"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dad887fd958be91b5098c0248def011f4523ab786cd411be668777e55063501f"
+checksum = "e228eec9be7c17ccb640b59b36a5cd805ea2a564a4c5e162c2f659fea30d3b96"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -99,12 +99,6 @@ version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
 
-[[package]]
-name = "foldhash"
-version = "0.1.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
-
 [[package]]
 name = "futures-core"
 version = "0.3.32"
@@ -131,20 +125,18 @@ dependencies = [
 
 [[package]]
 name = "getrandom"
-version = "0.4.2"
+version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0de51e6874e94e7bf76d726fc5d13ba782deca734ff60d5bb2fb2607c7406555"
+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
 dependencies = [
  "cfg-if",
  "libc",
  "r-efi",
- "wasip2",
- "wasip3",
 ]
 
 [[package]]
 name = "handoff-mcp"
-version = "0.13.1"
+version = "0.15.1"
 dependencies = [
  "anyhow",
  "chrono",
@@ -157,27 +149,12 @@ dependencies = [
  "toml_edit",
 ]
 
-[[package]]
-name = "hashbrown"
-version = "0.15.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
-dependencies = [
- "foldhash",
-]
-
 [[package]]
 name = "hashbrown"
 version = "0.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
 
-[[package]]
-name = "heck"
-version = "0.5.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
-
 [[package]]
 name = "iana-time-zone"
 version = "0.1.65"
@@ -202,12 +179,6 @@ dependencies = [
  "cc",
 ]
 
-[[package]]
-name = "id-arena"
-version = "2.3.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954"
-
 [[package]]
 name = "indexmap"
 version = "2.14.0"
@@ -215,9 +186,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
  "equivalent",
- "hashbrown 0.17.1",
- "serde",
- "serde_core",
+ "hashbrown",
 ]
 
 [[package]]
@@ -228,21 +197,15 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
 [[package]]
 name = "js-sys"
-version = "0.3.102"
+version = "0.3.103"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "03d04c30968dffe80775bd4d7fb676131cd04a1fb46d2686dbffbaec2d9dfd31"
+checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102"
 dependencies = [
  "cfg-if",
  "futures-util",
  "wasm-bindgen",
 ]
 
-[[package]]
-name = "leb128fmt"
-version = "0.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
-
 [[package]]
 name = "lexsim"
 version = "0.1.0"
@@ -267,9 +230,9 @@ checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
 
 [[package]]
 name = "log"
-version = "0.4.32"
+version = "0.4.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "953f07c43838f8e6f9758cab68bf5bed85465e7587ebe0b823f1bcd81978ad3a"
+checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 
 [[package]]
 name = "memchr"
@@ -298,16 +261,6 @@ version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
-[[package]]
-name = "prettyplease"
-version = "0.2.37"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
-dependencies = [
- "proc-macro2",
- "syn",
-]
-
 [[package]]
 name = "proc-macro2"
 version = "1.0.106"
@@ -319,9 +272,9 @@ dependencies = [
 
 [[package]]
 name = "quote"
-version = "1.0.45"
+version = "1.0.46"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
 dependencies = [
  "proc-macro2",
 ]
@@ -351,12 +304,6 @@ version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
 
-[[package]]
-name = "semver"
-version = "1.0.28"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
-
 [[package]]
 name = "serde"
 version = "1.0.228"
@@ -424,9 +371,9 @@ checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
 
 [[package]]
 name = "syn"
-version = "2.0.117"
+version = "2.0.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -543,35 +490,11 @@ version = "1.13.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
 
-[[package]]
-name = "unicode-xid"
-version = "0.2.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
-
-[[package]]
-name = "wasip2"
-version = "1.0.4+wasi-0.2.12"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
-dependencies = [
- "wit-bindgen 0.57.1",
-]
-
-[[package]]
-name = "wasip3"
-version = "0.4.0+wasi-0.3.0-rc-2026-01-06"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5428f8bf88ea5ddc08faddef2ac4a67e390b88186c703ce6dbd955e1c145aca5"
-dependencies = [
- "wit-bindgen 0.51.0",
-]
-
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.125"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8ddb3f79143bced6de84270411622a2699cee572fc0875aeaf1e7867cf9fca1a"
+checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4"
 dependencies = [
  "cfg-if",
  "once_cell",
@@ -582,9 +505,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.125"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4e21a184b13fb19e157296e2c46056aec9092264fab83e4ba59e68c61b323c3d"
+checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -592,9 +515,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.125"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fecefd9c35bd935a20fc3fc344b5f29138961e4f47fb03297d88f2587afb5ebd"
+checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e"
 dependencies = [
  "bumpalo",
  "proc-macro2",
@@ -605,47 +528,13 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.125"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "23939e44bb9a5d7576fa2b563dc2e136628f1224e88a8deed09e04858b77871f"
+checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24"
 dependencies = [
  "unicode-ident",
 ]
 
-[[package]]
-name = "wasm-encoder"
-version = "0.244.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "990065f2fe63003fe337b932cfb5e3b80e0b4d0f5ff650e6985b1048f62c8319"
-dependencies = [
- "leb128fmt",
- "wasmparser",
-]
-
-[[package]]
-name = "wasm-metadata"
-version = "0.244.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bb0e353e6a2fbdc176932bbaab493762eb1255a7900fe0fea1a2f96c296cc909"
-dependencies = [
- "anyhow",
- "indexmap",
- "wasm-encoder",
- "wasmparser",
-]
-
-[[package]]
-name = "wasmparser"
-version = "0.244.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe"
-dependencies = [
- "bitflags",
- "hashbrown 0.15.5",
- "indexmap",
- "semver",
-]
-
 [[package]]
 name = "windows-core"
 version = "0.62.2"
@@ -723,100 +612,6 @@ dependencies = [
  "memchr",
 ]
 
-[[package]]
-name = "wit-bindgen"
-version = "0.51.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d7249219f66ced02969388cf2bb044a09756a083d0fab1e566056b04d9fbcaa5"
-dependencies = [
- "wit-bindgen-rust-macro",
-]
-
-[[package]]
-name = "wit-bindgen"
-version = "0.57.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
-
-[[package]]
-name = "wit-bindgen-core"
-version = "0.51.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ea61de684c3ea68cb082b7a88508a8b27fcc8b797d738bfc99a82facf1d752dc"
-dependencies = [
- "anyhow",
- "heck",
- "wit-parser",
-]
-
-[[package]]
-name = "wit-bindgen-rust"
-version = "0.51.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b7c566e0f4b284dd6561c786d9cb0142da491f46a9fbed79ea69cdad5db17f21"
-dependencies = [
- "anyhow",
- "heck",
- "indexmap",
- "prettyplease",
- "syn",
- "wasm-metadata",
- "wit-bindgen-core",
- "wit-component",
-]
-
-[[package]]
-name = "wit-bindgen-rust-macro"
-version = "0.51.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0c0f9bfd77e6a48eccf51359e3ae77140a7f50b1e2ebfe62422d8afdaffab17a"
-dependencies = [
- "anyhow",
- "prettyplease",
- "proc-macro2",
- "quote",
- "syn",
- "wit-bindgen-core",
- "wit-bindgen-rust",
-]
-
-[[package]]
-name = "wit-component"
-version = "0.244.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2"
-dependencies = [
- "anyhow",
- "bitflags",
- "indexmap",
- "log",
- "serde",
- "serde_derive",
- "serde_json",
- "wasm-encoder",
- "wasm-metadata",
- "wasmparser",
- "wit-parser",
-]
-
-[[package]]
-name = "wit-parser"
-version = "0.244.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ecc8ac4bc1dc3381b7f59c34f00b67e18f910c2c0f50015669dde7def656a736"
-dependencies = [
- "anyhow",
- "id-arena",
- "indexmap",
- "log",
- "semver",
- "serde",
- "serde_derive",
- "serde_json",
- "unicode-xid",
- "wasmparser",
-]
-
 [[package]]
 name = "zmij"
 version = "1.0.21"

package/Cargo.toml

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

package/README.md

@@ -198,6 +198,14 @@ rename) so a concurrent reader never sees a partially-written file.
 | `handoff_get_referral` | Fetch one incoming referral in full — details, suggested tasks, done_criteria, context |
 | `handoff_update_referral` | Update referral status (open → acknowledged → resolved) |
 
+### Timer Coordination
+
+| Tool | Purpose |
+|------|---------|
+| `handoff_timer_start` | Start tracking time for a task — delegates to VSCode extension if alive, otherwise starts MCP fallback timer |
+| `handoff_timer_stop` | Stop the timer and log elapsed hours to `actual_hours` — delegates to VSCode if alive |
+| `handoff_timer_get_time` | Get current timer state (elapsed, authority, projected total) without stopping |
+
 ### Project Memory
 
 | Tool | Purpose |
@@ -207,6 +215,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
@@ -279,6 +288,9 @@ 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
+timer_provider = "auto"       # "auto" | "vscode" | "mcp" | "off"
+timer_authority_ttl_secs = 30 # Heartbeat freshness TTL for authority.json
+timer_idle_timeout_minutes = 10 # Idle pause threshold for MCP fallback timer
 
 [dashboard]
 scan_dirs = ["~/pro/"]     # Directories to scan for dashboard
@@ -462,6 +474,45 @@ All under `[settings]` in `.handoff/config.toml`, all with safe defaults
 | `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 |
 
+## CLI API
+
+Since v0.15.0, every MCP tool is also callable directly from the shell:
+
+```bash
+handoff-mcp <group> <action> [--key value ...]
+```
+
+All output is JSON on stdout, suitable for scripting and programmatic use
+(e.g. `child_process.execFile` from a VSCode extension).
+
+**Examples:**
+
+```bash
+# Memory operations
+handoff-mcp memory save --text "Always use atomic_write" --kind lesson --tags safety,io
+handoff-mcp memory query --text "atomic" --limit 5
+handoff-mcp memory delete --id m-20260630-...
+
+# Task management
+handoff-mcp task list --status-filter todo
+handoff-mcp task update --id t1 --title "New task" --status todo --estimate-hours 2
+handoff-mcp task log-time --task-id t1 --hours 0.5
+
+# Session and metrics
+handoff-mcp session load
+handoff-mcp metrics
+handoff-mcp dashboard
+```
+
+**Available groups:** `init`, `task`, `session`, `config`, `memory`,
+`referral`, `assignee`, `milestone`, `calendar`, `labels`, `project`,
+`metrics`, `capacity`, `schedule`, `dashboard`, `timer`.
+
+Run `handoff-mcp --help` to see all groups, or `handoff-mcp <group> --help`
+for actions within a group. See the
+[CLI API Reference](https://github.com/alphaelements/handoff-mcp/wiki/CLI-API-Reference)
+on the wiki for the full command list.
+
 ## MCP Resources
 
 | URI | Description |
@@ -489,6 +540,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.
+- **Timer**: Use `handoff_timer_start` / `handoff_timer_stop` to track task time.
+  When the VSCode extension is running, the timer delegates to it automatically.
+  When the extension is absent, MCP runs a fallback timer and logs hours on stop.
+  Use `handoff_timer_get_time` to check elapsed time without stopping.
 - **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

package/package.json

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

package/skills/handoff/SKILL.md

@@ -105,6 +105,23 @@ Use `handoff_log_time` to record hours worked on a task:
   `schedule: { milestone: "v2" }` updates only the milestone and preserves
   `actual_hours`/`remaining_hours`. It never replaces the whole schedule object.
 
+### Timer Coordination (MCP ⇄ VSCode)
+
+Use `handoff_timer_start` / `handoff_timer_stop` / `handoff_timer_get_time` to
+track task time with automatic VSCode extension coordination:
+
+- **`handoff_timer_start`** — if the VSCode extension is running (live authority
+  heartbeat), the request is delegated via `.handoff/timer/requests/`. If absent,
+  MCP starts a fallback internal timer.
+- **`handoff_timer_stop`** — if delegated, creates a stop request for the extension.
+  If MCP is the fallback, stops the timer and atomically logs elapsed hours to
+  `actual_hours` (same as `handoff_log_time`).
+- **`handoff_timer_get_time`** — reads `.handoff/timer/state.json` to show
+  elapsed time, state (tracking/paused/stopped), and current authority (vscode/mcp).
+- The `timer_provider` config setting controls behavior: `"auto"` (default) uses
+  the authority protocol, `"vscode"` always delegates, `"mcp"` always uses
+  fallback, `"off"` disables timer tools entirely.
+
 ### Metrics & Project Health
 
 Check project health with `handoff_get_metrics` at session start:

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.