handoff-mcp-server 0.12.0 → 0.13.1

package/src/mcp/handlers/mod.rs

@@ -15,6 +15,7 @@ pub mod list_sessions;
 pub mod list_tasks;
 pub mod load_context;
 pub mod log_time;
+pub mod memory;
 pub mod metrics;
 pub mod milestones;
 pub mod refer;
@@ -74,6 +75,10 @@ pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {
         "handoff_update_calendar" => calendar::handle_update_calendar(arguments),
         "handoff_update_labels" => calendar::handle_update_labels(arguments),
         "handoff_start_project" => calendar::handle_start_project(arguments),
+        "handoff_memory_save" => memory::handle_save(arguments),
+        "handoff_memory_query" => memory::handle_query(arguments),
+        "handoff_memory_delete" => memory::handle_delete(arguments),
+        "handoff_memory_cleanup" => memory::handle_cleanup(arguments),
         _ => Err(anyhow::anyhow!("Tool not implemented: {name}")),
     };
 

package/src/mcp/tools.rs

@@ -1023,6 +1023,65 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 }
             }),
         },
+        ToolDefinition {
+            name: "handoff_memory_save".to_string(),
+            description: "Save a long-lived project memory (lesson/rule/convention/gotcha) that future sessions should respect. Detects exact and near-duplicate memories: an exact match is reported (not rewritten), a near-duplicate is returned as a 'conflict' with both bodies for you to merge (call again with merge_into=<id> and absorb_ids=[…]) or save separately with force=true. Returns a JSON string.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "text": { "type": "string", "description": "The memory body (any language). Required, non-empty." },
+                    "kind": { "type": "string", "description": "Memory kind.", "enum": ["lesson", "rule", "convention", "gotcha"], "default": "lesson" },
+                    "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional tags; also indexed for similarity." },
+                    "scope_paths": { "type": "array", "items": { "type": "string" }, "description": "Path prefixes this memory applies to (e.g. 'src/storage/'). Boosts relevance when a query touches a matching file." },
+                    "merge_into": { "type": "string", "description": "Commit an AI merge: overwrite this memory id with `text` and absorb `absorb_ids`." },
+                    "absorb_ids": { "type": "array", "items": { "type": "string" }, "description": "Memory ids to delete and record as superseded when merging." },
+                    "force": { "type": "boolean", "description": "Save even if a near-duplicate exists (skip the conflict response).", "default": false }
+                },
+                "required": ["text"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_memory_query".to_string(),
+            description: "Return the project memories most relevant to the given text/file (BM25 + scope-path boosting). Intended for automatic injection via hooks, but callable directly. Returns a JSON string {\"memories\":[{id,text,kind,score}],\"injected_count\"}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "session_id": { "type": "string", "description": "Hook session id. When given, memories already injected this session (same content hash) are filtered out; an edited memory is re-injected." },
+                    "text": { "type": "string", "description": "The current prompt or context text to match against." },
+                    "tool_name": { "type": "string", "description": "Name of the tool about to run (e.g. 'Edit'); added to the query." },
+                    "file_paths": { "type": "array", "items": { "type": "string" }, "description": "File paths in play; basenames are added to the query and scope_paths are matched against these." },
+                    "limit": { "type": "integer", "description": "Maximum memories to return.", "default": 5 },
+                    "mark_injected": { "type": "boolean", "description": "Record returned memories in the session sidecar and bump their hit_count/last_referenced_at. Requires session_id.", "default": true }
+                },
+                "required": ["text"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_memory_delete".to_string(),
+            description: "Delete a project memory by id (full id or unique prefix). Use for AI-driven cleanup of stale memories. Returns a JSON string {\"status\":\"deleted\",\"id\"}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "id": { "type": "string", "description": "Memory id to delete (full id or unique prefix)." }
+                },
+                "required": ["id"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_memory_cleanup".to_string(),
+            description: "Housekeep the project memory store (intended for SessionStart). Silently merges exact duplicates (lossless), then returns recommendations the AI should act on: near-duplicate clusters (merge with memory_save merge_into=…) and stale memories (consider memory_delete). Also garbage-collects old per-session injection sidecars. Returns a JSON string {\"auto_merged_exact\":n,\"cleanup_recommendations\":{\"similar_clusters\":[…],\"stale\":[…]},\"injected_sidecars_removed\":k}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "apply_exact_merges": { "type": "boolean", "description": "Auto-merge exact-duplicate memories (same content hash). Lossless and safe.", "default": true },
+                    "stale_days": { "type": "integer", "description": "Flag memories not referenced for this many days as stale recommendations.", "default": 60 }
+                }
+            }),
+        },
     ]
 }
 

package/src/setup.rs

@@ -0,0 +1,424 @@
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use anyhow::{Context, Result};
+use serde_json::Value;
+
+const HOOK_SERVER: &str = "handoff";
+const HOOK_TOOL_QUERY: &str = "handoff_memory_query";
+const HOOK_TOOL_CLEANUP: &str = "handoff_memory_cleanup";
+
+fn settings_path() -> Result<PathBuf> {
+    let home = std::env::var("HOME")
+        .or_else(|_| std::env::var("USERPROFILE"))
+        .context("cannot determine home directory (HOME / USERPROFILE not set)")?;
+    Ok(Path::new(&home).join(".claude").join("settings.json"))
+}
+
+fn read_settings(path: &Path) -> Result<Value> {
+    if path.exists() {
+        let text = std::fs::read_to_string(path)
+            .with_context(|| format!("failed to read {}", path.display()))?;
+        serde_json::from_str(&text).with_context(|| format!("failed to parse {}", path.display()))
+    } else {
+        Ok(Value::Object(serde_json::Map::new()))
+    }
+}
+
+fn write_settings(path: &Path, value: &Value) -> Result<()> {
+    let parent = path
+        .parent()
+        .context("settings path has no parent directory")?;
+    std::fs::create_dir_all(parent)
+        .with_context(|| format!("failed to create {}", parent.display()))?;
+
+    let text = serde_json::to_string_pretty(value)?;
+    let tmp = parent.join(".settings.json.tmp");
+    std::fs::write(&tmp, text + "\n")
+        .with_context(|| format!("failed to write {}", tmp.display()))?;
+    std::fs::rename(&tmp, path)
+        .with_context(|| format!("failed to rename {} -> {}", tmp.display(), path.display()))
+}
+
+fn mcp_tool_hook(tool: &str, input: Value) -> Value {
+    serde_json::json!({
+        "type": "mcp_tool",
+        "server": HOOK_SERVER,
+        "tool": tool,
+        "input": input
+    })
+}
+
+fn build_hooks_config() -> BTreeMap<&'static str, Value> {
+    let mut hooks = BTreeMap::new();
+
+    hooks.insert(
+        "UserPromptSubmit",
+        serde_json::json!([{
+            "hooks": [mcp_tool_hook(HOOK_TOOL_QUERY, serde_json::json!({
+                "project_dir": "${cwd}",
+                "session_id": "${session_id}",
+                "text": "${prompt}"
+            }))]
+        }]),
+    );
+
+    hooks.insert(
+        "PreToolUse",
+        serde_json::json!([{
+            "matcher": "Edit|Write|MultiEdit",
+            "hooks": [mcp_tool_hook(HOOK_TOOL_QUERY, serde_json::json!({
+                "project_dir": "${cwd}",
+                "session_id": "${session_id}",
+                "tool_name": "${tool_name}",
+                "text": "${tool_input.file_path}",
+                "file_paths": ["${tool_input.file_path}"]
+            }))]
+        }]),
+    );
+
+    hooks.insert(
+        "SessionStart",
+        serde_json::json!([{
+            "hooks": [mcp_tool_hook(HOOK_TOOL_CLEANUP, serde_json::json!({
+                "project_dir": "${cwd}"
+            }))]
+        }]),
+    );
+
+    hooks
+}
+
+fn has_handoff_hook(arr: &Value) -> bool {
+    let Some(entries) = arr.as_array() else {
+        return false;
+    };
+    for entry in entries {
+        let Some(hooks) = entry.get("hooks").and_then(|v| v.as_array()) else {
+            continue;
+        };
+        for hook in hooks {
+            if hook.get("server").and_then(|v| v.as_str()) == Some(HOOK_SERVER) {
+                return true;
+            }
+        }
+    }
+    false
+}
+
+pub fn run_setup(check_only: bool, uninstall: bool) -> Result<()> {
+    anyhow::ensure!(
+        !(check_only && uninstall),
+        "--check and --uninstall cannot be used together"
+    );
+
+    let path = settings_path()?;
+    let mut settings = read_settings(&path)?;
+
+    if check_only {
+        return run_check(&settings, &path);
+    }
+
+    if uninstall {
+        return run_uninstall(&mut settings, &path);
+    }
+
+    run_install(&mut settings, &path)
+}
+
+fn run_check(settings: &Value, path: &Path) -> Result<()> {
+    println!("Settings file: {}", path.display());
+
+    let hooks_obj = settings.get("hooks");
+    let desired = build_hooks_config();
+    let mut all_ok = true;
+
+    for event in desired.keys() {
+        let installed = hooks_obj
+            .and_then(|h| h.get(*event))
+            .map(has_handoff_hook)
+            .unwrap_or(false);
+
+        if installed {
+            println!("  {event}: installed");
+        } else {
+            println!("  {event}: NOT installed");
+            all_ok = false;
+        }
+    }
+
+    if all_ok {
+        println!("\nAll hooks are configured. Memory auto-injection is active.");
+    } else {
+        println!("\nSome hooks are missing. Run `handoff-mcp setup` to install them.");
+    }
+
+    Ok(())
+}
+
+fn run_install(settings: &mut Value, path: &Path) -> Result<()> {
+    let obj = settings
+        .as_object_mut()
+        .context("settings.json root is not an object")?;
+
+    let hooks_val = obj
+        .entry("hooks")
+        .or_insert_with(|| Value::Object(serde_json::Map::new()));
+    let hooks_obj = hooks_val
+        .as_object_mut()
+        .context("settings.json 'hooks' is not an object")?;
+
+    let desired = build_hooks_config();
+    let mut installed = 0u32;
+    let mut skipped = 0u32;
+
+    for (event, config) in desired {
+        let existing = hooks_obj.get(event);
+        if existing.map(has_handoff_hook).unwrap_or(false) {
+            println!("  {event}: already installed, skipping");
+            skipped += 1;
+            continue;
+        }
+
+        match existing {
+            Some(Value::Array(arr)) => {
+                let mut merged = arr.clone();
+                if let Some(new_entries) = config.as_array() {
+                    merged.extend(new_entries.iter().cloned());
+                }
+                hooks_obj.insert(event.to_string(), Value::Array(merged));
+                println!("  {event}: merged with existing hooks");
+            }
+            _ => {
+                hooks_obj.insert(event.to_string(), config);
+                println!("  {event}: installed");
+            }
+        }
+        installed += 1;
+    }
+
+    if installed > 0 {
+        write_settings(path, settings)?;
+        println!("\nWrote {path}", path = path.display());
+        println!("{installed} hook(s) installed, {skipped} already present.");
+        println!("\nRestart Claude Code for hooks to take effect.");
+    } else {
+        println!("\nAll hooks already installed. Nothing to do.");
+    }
+
+    Ok(())
+}
+
+fn run_uninstall(settings: &mut Value, path: &Path) -> Result<()> {
+    let Some(hooks_obj) = settings.get_mut("hooks").and_then(|v| v.as_object_mut()) else {
+        println!("No hooks configured. Nothing to remove.");
+        return Ok(());
+    };
+
+    let events: Vec<String> = hooks_obj.keys().cloned().collect();
+    let mut removed = 0u32;
+
+    for event in &events {
+        let Some(arr) = hooks_obj.get_mut(event).and_then(|v| v.as_array_mut()) else {
+            continue;
+        };
+
+        let before = arr.len();
+        arr.retain(|entry| {
+            let Some(hooks) = entry.get("hooks").and_then(|v| v.as_array()) else {
+                return true;
+            };
+            !hooks
+                .iter()
+                .any(|h| h.get("server").and_then(|v| v.as_str()) == Some(HOOK_SERVER))
+        });
+
+        let after = arr.len();
+        if before != after {
+            println!("  {event}: removed handoff hook(s)");
+            removed += 1;
+        }
+
+        if arr.is_empty() {
+            hooks_obj.remove(event);
+        }
+    }
+
+    if hooks_obj.is_empty() {
+        if let Some(obj) = settings.as_object_mut() {
+            obj.remove("hooks");
+        }
+    }
+
+    if removed > 0 {
+        write_settings(path, settings)?;
+        println!("\nWrote {path}", path = path.display());
+        println!("{removed} hook event(s) cleaned up.");
+        println!("\nRestart Claude Code for changes to take effect.");
+    } else {
+        println!("No handoff hooks found. Nothing to remove.");
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn build_hooks_has_three_events() {
+        let hooks = build_hooks_config();
+        assert_eq!(hooks.len(), 3);
+        assert!(hooks.contains_key("UserPromptSubmit"));
+        assert!(hooks.contains_key("PreToolUse"));
+        assert!(hooks.contains_key("SessionStart"));
+    }
+
+    #[test]
+    fn has_handoff_hook_detects_presence() {
+        let arr = serde_json::json!([{
+            "hooks": [{"type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_query"}]
+        }]);
+        assert!(has_handoff_hook(&arr));
+    }
+
+    #[test]
+    fn has_handoff_hook_returns_false_for_other_server() {
+        let arr = serde_json::json!([{
+            "hooks": [{"type": "mcp_tool", "server": "other", "tool": "other_tool"}]
+        }]);
+        assert!(!has_handoff_hook(&arr));
+    }
+
+    #[test]
+    fn has_handoff_hook_returns_false_for_empty() {
+        assert!(!has_handoff_hook(&serde_json::json!([])));
+    }
+
+    #[test]
+    fn install_into_empty_settings() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        let mut settings = Value::Object(serde_json::Map::new());
+        run_install(&mut settings, &path).unwrap();
+
+        let written: Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        let hooks = written.get("hooks").unwrap().as_object().unwrap();
+        assert!(hooks.contains_key("UserPromptSubmit"));
+        assert!(hooks.contains_key("PreToolUse"));
+        assert!(hooks.contains_key("SessionStart"));
+    }
+
+    #[test]
+    fn install_merges_with_existing_hooks() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        let mut settings = serde_json::json!({
+            "hooks": {
+                "UserPromptSubmit": [{
+                    "hooks": [{"type": "command", "command": "my-other-hook"}]
+                }]
+            }
+        });
+
+        run_install(&mut settings, &path).unwrap();
+
+        let written: Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        let user_prompt = written["hooks"]["UserPromptSubmit"].as_array().unwrap();
+        assert_eq!(user_prompt.len(), 2);
+        assert!(has_handoff_hook(&written["hooks"]["UserPromptSubmit"]));
+    }
+
+    #[test]
+    fn install_skips_if_already_present() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        let mut settings = Value::Object(serde_json::Map::new());
+        run_install(&mut settings, &path).unwrap();
+
+        let mut settings2 = serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        run_install(&mut settings2, &path).unwrap();
+
+        let written: Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        let user_prompt = written["hooks"]["UserPromptSubmit"].as_array().unwrap();
+        assert_eq!(user_prompt.len(), 1);
+    }
+
+    #[test]
+    fn uninstall_removes_handoff_hooks() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        let mut settings = Value::Object(serde_json::Map::new());
+        run_install(&mut settings, &path).unwrap();
+
+        let mut settings2: Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        run_uninstall(&mut settings2, &path).unwrap();
+
+        let written: Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        assert!(written.get("hooks").is_none());
+    }
+
+    #[test]
+    fn check_and_uninstall_conflict_is_rejected() {
+        assert!(run_setup(true, true).is_err());
+    }
+
+    #[test]
+    fn install_preserves_key_order() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        let original = r#"{
+  "env": {"A": "1", "B": "2"},
+  "model": "opus",
+  "permissions": {"defaultMode": "auto"}
+}
+"#;
+        std::fs::write(&path, original).unwrap();
+
+        let mut settings: Value = serde_json::from_str(original).unwrap();
+        run_install(&mut settings, &path).unwrap();
+
+        let written = std::fs::read_to_string(&path).unwrap();
+        let env_pos = written.find("\"env\"").unwrap();
+        let hooks_pos = written.find("\"hooks\"").unwrap();
+        let model_pos = written.find("\"model\"").unwrap();
+        assert!(env_pos < model_pos, "env should come before model");
+        assert!(
+            hooks_pos > env_pos,
+            "hooks should be appended after existing keys"
+        );
+    }
+
+    #[test]
+    fn uninstall_preserves_other_hooks() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        let mut settings = serde_json::json!({
+            "hooks": {
+                "UserPromptSubmit": [
+                    {"hooks": [{"type": "command", "command": "my-hook"}]},
+                    {"hooks": [{"type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_query"}]}
+                ]
+            }
+        });
+        run_uninstall(&mut settings, &path).unwrap();
+
+        let written: Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        let user_prompt = written["hooks"]["UserPromptSubmit"].as_array().unwrap();
+        assert_eq!(user_prompt.len(), 1);
+        assert!(!has_handoff_hook(&written["hooks"]["UserPromptSubmit"]));
+    }
+}

package/src/storage/config.rs

@@ -58,6 +58,28 @@ pub struct SettingsConfig {
     pub ai_estimate_multiplier: f64,
     #[serde(default)]
     pub context_files: Vec<String>,
+    /// Master switch for the memory feature (save/query/cleanup). Default true.
+    #[serde(default = "default_memory_enabled")]
+    pub memory_enabled: bool,
+    /// Jaccard threshold above which `memory_save` treats a save as a
+    /// near-duplicate `conflict` for the AI to merge. Default 0.72.
+    #[serde(default = "default_memory_dup_threshold")]
+    pub memory_dup_threshold: f64,
+    /// BM25 relevance floor for `memory_query`; scores below are not returned.
+    /// Default 0.5.
+    #[serde(default = "default_memory_query_min_score")]
+    pub memory_query_min_score: f64,
+    /// Maximum number of memories `memory_query` returns per call. Default 5.
+    #[serde(default = "default_memory_query_limit")]
+    pub memory_query_limit: u32,
+    /// Days after which an un(re)referenced memory is flagged `stale` by
+    /// `memory_cleanup`. Default 60.
+    #[serde(default = "default_memory_stale_days")]
+    pub memory_stale_days: i64,
+    /// Age (days) past which `memory_cleanup` garbage-collects a per-session
+    /// `injected/` sidecar. Default 14.
+    #[serde(default = "default_memory_injected_gc_days")]
+    pub memory_injected_gc_days: i64,
     #[serde(default)]
     pub custom_fields: HashMap<String, toml::Value>,
 }
@@ -205,6 +227,30 @@ fn default_ai_estimate_multiplier() -> f64 {
     0.2
 }
 
+fn default_memory_enabled() -> bool {
+    true
+}
+
+fn default_memory_dup_threshold() -> f64 {
+    0.72
+}
+
+fn default_memory_query_min_score() -> f64 {
+    0.5
+}
+
+fn default_memory_query_limit() -> u32 {
+    5
+}
+
+fn default_memory_stale_days() -> i64 {
+    60
+}
+
+fn default_memory_injected_gc_days() -> i64 {
+    14
+}
+
 fn default_scan_dirs() -> Vec<String> {
     vec!["~/pro/".to_string()]
 }
@@ -218,6 +264,12 @@ impl Default for SettingsConfig {
             require_estimate_hours: default_require_estimate_hours(),
             ai_estimate_multiplier: default_ai_estimate_multiplier(),
             context_files: Vec::new(),
+            memory_enabled: default_memory_enabled(),
+            memory_dup_threshold: default_memory_dup_threshold(),
+            memory_query_min_score: default_memory_query_min_score(),
+            memory_query_limit: default_memory_query_limit(),
+            memory_stale_days: default_memory_stale_days(),
+            memory_injected_gc_days: default_memory_injected_gc_days(),
             custom_fields: HashMap::new(),
         }
     }