fix: update hooks to nested format for Claude Code schema compatibility

elvismdev · elvismdev · commit 2f86dee99c3f · 2026-02-28T12:31:55.000-08:00
Migrate hook installer from the deprecated flat format to the current
nested schema (matcher group -&gt; hooks array -&gt; handler objects).  Add
legacy format detection and auto-migration so existing users upgrading
do not end up with duplicate or broken entries.
diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@ Uses the `mem0ai` package directly as a library, supports both Claude's OAT toke
 
 Python >= 3.10 and [uv](https://docs.astral.sh/uv/getting-started/installation/).
 
-> **Authentication:** The default setup uses Claude (Anthropic) as the LLM for fact extraction. No API key needed — the server automatically uses your Claude Code session token. For fully local setups, set `MEM0_PROVIDER=ollama`. See [Authentication](#authentication) for advanced options.
+> **Authentication:** The default setup uses Claude (Anthropic) as the LLM for fact extraction. No API key needed, the server automatically uses your Claude Code session token. For fully local setups, set `MEM0_PROVIDER=ollama`. See [Authentication](#authentication) for advanced options.
 
 ## Quick Start
 
@@ -31,9 +31,9 @@ claude mcp add --scope user --transport stdio mem0 \
 
 All defaults work out of the box: Qdrant on `localhost:6333`, Ollama embeddings on `localhost:11434` with `bge-m3` (1024 dims). Override any default via `--env` (see [Configuration](#configuration)).
 
-`uvx` automatically downloads, installs, and runs the server in an isolated environment — no manual installation needed. Claude Code launches it on demand when the MCP connection starts.
+`uvx` automatically downloads, installs, and runs the server in an isolated environment, no manual installation needed. Claude Code launches it on demand when the MCP connection starts.
 
-The server auto-reads your OAT token from `~/.claude/.credentials.json` — no manual token configuration needed.
+The server auto-reads your OAT token from `~/.claude/.credentials.json`, no manual token configuration needed.
 
 ### Fully Local (Ollama)
 
@@ -84,21 +84,21 @@ Add these rules to your project's `CLAUDE.md` (or `~/.claude/CLAUDE.md` for glob
 ```markdown
 # MCP Servers
 
-- **mem0**: Persistent memory across sessions. At the start of each session, `search_memories` for relevant context before asking the user to re-explain anything. Use `add_memory` whenever you discover project architecture, coding conventions, debugging insights, key decisions, or user preferences. Use `update_memory` when prior context changes. Save information like: "This project uses PostgreSQL with Prisma", "Tests run with pytest -v", "Auth uses JWT validated in middleware". When in doubt, save it — future sessions benefit from over-remembering.
+- **mem0**: Persistent memory across sessions. At the start of each session, `search_memories` for relevant context before asking the user to re-explain anything. Use `add_memory` whenever you discover project architecture, coding conventions, debugging insights, key decisions, or user preferences. Use `update_memory` when prior context changes. Save information like: "This project uses PostgreSQL with Prisma", "Tests run with pytest -v", "Auth uses JWT validated in middleware". When in doubt, save it, future sessions benefit from over-remembering.
 ```
 
-This gives Claude Code behavioral instructions to actively search and save memories during the session. For best results, combine with [Claude Code Hooks](#claude-code-hooks) — the CLAUDE.md rules tell Claude *how to use* memory tools mid-session, while hooks handle the *automatic* injection and saving at session boundaries.
+This gives Claude Code behavioral instructions to actively search and save memories during the session. For best results, combine with [Claude Code Hooks](#claude-code-hooks), the CLAUDE.md rules tell Claude *how to use* memory tools mid-session, while hooks handle the *automatic* injection and saving at session boundaries.
 
 ## Claude Code Hooks
 
-Session hooks automate memory at session boundaries — injecting memories on startup and saving summaries on exit. This happens automatically without manual tool calls.
+Session hooks automate memory at session boundaries, injecting memories on startup and saving summaries on exit. This happens automatically without manual tool calls.
 
 | Hook | Event | What it does |
 |------|-------|--------------|
 | `mem0-hook-context` | SessionStart (`startup`, `compact`) | Searches mem0 for project-relevant memories and injects them as `additionalContext` |
 | `mem0-hook-stop` | Stop | Reads the last ~3 user/assistant exchanges from the transcript and saves a summary to mem0 via `infer=True` |
 
-Both hooks are non-fatal — if mem0 is unreachable or any error occurs, Claude Code continues normally.
+Both hooks are non-fatal, if mem0 is unreachable or any error occurs, Claude Code continues normally.
 
 ### Install
 
@@ -114,7 +114,7 @@ Or install globally (all projects):
 mem0-install-hooks --global
 ```
 
-This adds the hook entries to `.claude/settings.json`. The installer is idempotent — running it twice won't create duplicates.
+This adds the hook entries to `.claude/settings.json`. The installer is idempotent, running it twice won't create duplicates.
 
 ### How it works
 
@@ -136,10 +136,10 @@ Hooks and CLAUDE.md are complementary layers that work best together:
 
 | Layer | Role | When |
 |-------|------|------|
-| **Hooks** | Automated data flow — injects stored memories on startup, saves session summaries on exit | Session boundaries (start/stop) |
-| **CLAUDE.md** | Behavioral instructions — tells Claude to actively search and save memories during the session | Throughout the session |
+| **Hooks** | Automated data flow, injects stored memories on startup, saves session summaries on exit | Session boundaries (start/stop) |
+| **CLAUDE.md** | Behavioral instructions, tells Claude to actively search and save memories during the session | Throughout the session |
 
-Hooks alone give you passive recall (memories appear at startup) and passive saving (summaries saved at exit). CLAUDE.md instructions add active mid-session behavior — Claude searches for relevant memories when encountering new topics, and saves important discoveries immediately rather than waiting for session end.
+Hooks alone give you passive recall (memories appear at startup) and passive saving (summaries saved at exit). CLAUDE.md instructions add active mid-session behavior, Claude searches for relevant memories when encountering new topics, and saves important discoveries immediately rather than waiting for session end.
 
 For the best experience, use both. Hooks ensure memories flow in and out automatically at session boundaries, while CLAUDE.md ensures Claude actively engages with memory tools during the session.
 
@@ -154,9 +154,9 @@ The server resolves an Anthropic token using a prioritized fallback chain:
 | 3 | `ANTHROPIC_API_KEY` env var | Standard pay-per-use API key |
 | 4 | Disabled | Warns and disables Anthropic LLM features |
 
-**In Claude Code, priority 2 always wins** — the credentials file exists as long as you're logged in. This means `ANTHROPIC_API_KEY` (priority 3) is never reached. To override the OAT token in Claude Code, use `MEM0_ANTHROPIC_TOKEN` (priority 1). `ANTHROPIC_API_KEY` is only useful for non-Claude-Code deployments (Docker, CI, standalone).
+**In Claude Code, priority 2 always wins**, the credentials file exists as long as you're logged in. This means `ANTHROPIC_API_KEY` (priority 3) is never reached. To override the OAT token in Claude Code, use `MEM0_ANTHROPIC_TOKEN` (priority 1). `ANTHROPIC_API_KEY` is only useful for non-Claude-Code deployments (Docker, CI, standalone).
 
-**OAT tokens** (`sk-ant-oat...`) use your Claude subscription. The server automatically detects the token type and configures the SDK accordingly. OAT tokens are automatically refreshed before expiry: the server proactively checks the token lifetime and refreshes via the Anthropic OAuth endpoint when nearing expiry (default: 30 minutes). On authentication failures, a 3-step defensive strategy kicks in — piggybacking on Claude Code's credentials file, self-refreshing via OAuth, and wait-and-retry — so long-running sessions survive token rotation seamlessly.
+**OAT tokens** (`sk-ant-oat...`) use your Claude subscription. The server automatically detects the token type and configures the SDK accordingly. OAT tokens are automatically refreshed before expiry: the server proactively checks the token lifetime and refreshes via the Anthropic OAuth endpoint when nearing expiry (default: 30 minutes). On authentication failures, a 3-step defensive strategy kicks in, piggybacking on Claude Code's credentials file, self-refreshing via OAuth, and wait-and-retry, so long-running sessions survive token rotation seamlessly.
 
 **API keys** (`sk-ant-api...`) use standard pay-per-use billing.
 
diff --git a/src/mem0_mcp_selfhosted/hooks.py b/src/mem0_mcp_selfhosted/hooks.py
@@ -286,8 +286,63 @@ def stop_main() -> None:
 
 
 def _has_hook(hooks_list: list, command: str) -> bool:
-    """Check if a hook with the given command already exists."""
-    return any(isinstance(h, dict) and h.get("command") == command for h in hooks_list)
+    """Check if a hook with the given command already exists.
+
+    Searches both the current nested format and the legacy flat format::
+
+        Nested:  [{"matcher": "...", "hooks": [{"type": "command", "command": "..."}]}]
+        Legacy:  [{"matcher": "...", "command": "..."}]
+    """
+    for group in hooks_list:
+        if not isinstance(group, dict):
+            continue
+        # Current nested format
+        for handler in group.get("hooks") or []:
+            if isinstance(handler, dict) and handler.get("command") == command:
+                return True
+        # Legacy flat format (pre-nested schema)
+        if group.get("command") == command:
+            return True
+    return False
+
+
+_HANDLER_KEYS = {"command", "timeout"}
+_GROUP_KEYS = {"matcher"}
+
+
+def _migrate_legacy_hooks(hooks_list: list) -> list:
+    """Convert legacy flat-format hooks to the nested format.
+
+    Flat entries (``{"command": "...", "timeout": ...}``) are converted to
+    nested format (``{"hooks": [{"type": "command", ...}]}``).  Already-nested
+    entries are kept as-is.  Non-dict entries are discarded.  Unknown keys are
+    forwarded to preserve any extra properties the user may have set.
+    """
+    migrated = []
+    for group in hooks_list:
+        if not isinstance(group, dict):
+            continue
+        if "hooks" in group:
+            # Already in nested format
+            migrated.append(group)
+        elif "command" in group:
+            # Legacy flat format — convert, forwarding unknown keys to
+            # group level so no user data is silently dropped.
+            handler: dict = {"type": "command"}
+            new_group: dict = {}
+            for k, v in group.items():
+                if k in _HANDLER_KEYS:
+                    handler[k] = v
+                elif k in _GROUP_KEYS:
+                    new_group[k] = v
+                else:
+                    new_group[k] = v
+            new_group["hooks"] = [handler]
+            migrated.append(new_group)
+        else:
+            # Unknown format — preserve as-is
+            migrated.append(group)
+    return migrated
 
 
 def install_main() -> None:
@@ -338,6 +393,12 @@ def install_main() -> None:
         settings["hooks"] = {}
 
     hooks = settings["hooks"]
+
+    # Migrate any legacy flat-format hooks to nested format
+    for event_key in ("SessionStart", "Stop"):
+        if isinstance(hooks.get(event_key), list):
+            hooks[event_key] = _migrate_legacy_hooks(hooks[event_key])
+
     installed: list[str] = []
     skipped: list[str] = []
 
@@ -349,8 +410,11 @@ def install_main() -> None:
     else:
         hooks["SessionStart"].append({
             "matcher": "startup|compact",
-            "command": _HOOK_CONTEXT_CMD,
-            "timeout": 15000,
+            "hooks": [{
+                "type": "command",
+                "command": _HOOK_CONTEXT_CMD,
+                "timeout": 15000,
+            }],
         })
         installed.append(f"SessionStart ({_HOOK_CONTEXT_CMD})")
 
@@ -361,8 +425,11 @@ def install_main() -> None:
         skipped.append(f"Stop ({_HOOK_STOP_CMD})")
     else:
         hooks["Stop"].append({
-            "command": _HOOK_STOP_CMD,
-            "timeout": 30000,
+            "hooks": [{
+                "type": "command",
+                "command": _HOOK_STOP_CMD,
+                "timeout": 30000,
+            }],
         })
         installed.append(f"Stop ({_HOOK_STOP_CMD})")
 
diff --git a/tests/unit/test_hooks.py b/tests/unit/test_hooks.py
@@ -526,7 +526,7 @@ def test_mem_add_raises_returns_nonfatal(self, tmp_path):
 
 class TestInstallMain:
     def test_fresh_install(self, tmp_path):
-        """Fresh install creates settings.json with both hook entries."""
+        """Fresh install creates settings.json with both hook entries in nested format."""
         project_dir = tmp_path / "myproject"
         project_dir.mkdir()
 
@@ -538,13 +538,23 @@ def test_fresh_install(self, tmp_path):
 
         settings = json.loads(settings_path.read_text())
         assert "hooks" in settings
+
+        # SessionStart: matcher group with nested hooks array
         assert len(settings["hooks"]["SessionStart"]) == 1
-        assert settings["hooks"]["SessionStart"][0]["command"] == "mem0-hook-context"
-        assert settings["hooks"]["SessionStart"][0]["matcher"] == "startup|compact"
-        assert settings["hooks"]["SessionStart"][0]["timeout"] == 15000
+        ss_group = settings["hooks"]["SessionStart"][0]
+        assert ss_group["matcher"] == "startup|compact"
+        assert len(ss_group["hooks"]) == 1
+        assert ss_group["hooks"][0]["type"] == "command"
+        assert ss_group["hooks"][0]["command"] == "mem0-hook-context"
+        assert ss_group["hooks"][0]["timeout"] == 15000
+
+        # Stop: matcher group with nested hooks array
         assert len(settings["hooks"]["Stop"]) == 1
-        assert settings["hooks"]["Stop"][0]["command"] == "mem0-hook-stop"
-        assert settings["hooks"]["Stop"][0]["timeout"] == 30000
+        stop_group = settings["hooks"]["Stop"][0]
+        assert len(stop_group["hooks"]) == 1
+        assert stop_group["hooks"][0]["type"] == "command"
+        assert stop_group["hooks"][0]["command"] == "mem0-hook-stop"
+        assert stop_group["hooks"][0]["timeout"] == 30000
 
     def test_idempotent_reinstall(self, tmp_path, capsys):
         """Running install twice doesn't create duplicate entries."""
@@ -635,8 +645,8 @@ def test_existing_hooks_with_different_commands_not_matched(self, tmp_path):
 
         existing = {
             "hooks": {
-                "SessionStart": [{"command": "other-hook", "timeout": 5000}],
-                "Stop": [{"command": "another-stop-hook", "timeout": 10000}],
+                "SessionStart": [{"hooks": [{"type": "command", "command": "other-hook", "timeout": 5000}]}],
+                "Stop": [{"hooks": [{"type": "command", "command": "another-stop-hook", "timeout": 10000}]}],
             }
         }
         (claude_dir / "settings.json").write_text(json.dumps(existing))
@@ -645,10 +655,15 @@ def test_existing_hooks_with_different_commands_not_matched(self, tmp_path):
             hooks.install_main()
 
         settings = json.loads((claude_dir / "settings.json").read_text())
-        # Both the original and new hooks should be present
+        # Both the original and new matcher groups should be present
         assert len(settings["hooks"]["SessionStart"]) == 2
         assert len(settings["hooks"]["Stop"]) == 2
-        commands = [h["command"] for h in settings["hooks"]["SessionStart"]]
+        # Extract commands from nested hooks arrays
+        commands = [
+            handler["command"]
+            for group in settings["hooks"]["SessionStart"]
+            for handler in group.get("hooks", [])
+        ]
         assert "other-hook" in commands
         assert "mem0-hook-context" in commands
 
@@ -694,3 +709,76 @@ def test_nonexistent_project_dir_exits_with_error(self, tmp_path, capsys):
         assert exc_info.value.code == 1
         captured = capsys.readouterr()
         assert "does not exist" in captured.err
+
+    def test_legacy_flat_format_migrated_on_reinstall(self, tmp_path, capsys):
+        """Old flat-format hooks are migrated to nested format without duplicates."""
+        project_dir = tmp_path / "proj"
+        claude_dir = project_dir / ".claude"
+        claude_dir.mkdir(parents=True)
+
+        # Old flat format from previous package version
+        existing = {
+            "hooks": {
+                "SessionStart": [{"command": "mem0-hook-context", "matcher": "startup|compact", "timeout": 15000}],
+                "Stop": [{"command": "mem0-hook-stop", "timeout": 30000}],
+            }
+        }
+        (claude_dir / "settings.json").write_text(json.dumps(existing))
+
+        with patch("sys.argv", ["mem0-install-hooks", "--project-dir", str(project_dir)]):
+            hooks.install_main()
+
+        settings = json.loads((claude_dir / "settings.json").read_text())
+
+        # Should have exactly 1 entry per event (migrated, not duplicated)
+        assert len(settings["hooks"]["SessionStart"]) == 1
+        assert len(settings["hooks"]["Stop"]) == 1
+
+        # Migrated to nested format
+        ss = settings["hooks"]["SessionStart"][0]
+        assert ss["matcher"] == "startup|compact"
+        assert ss["hooks"][0]["type"] == "command"
+        assert ss["hooks"][0]["command"] == "mem0-hook-context"
+        assert ss["hooks"][0]["timeout"] == 15000
+
+        stop = settings["hooks"]["Stop"][0]
+        assert stop["hooks"][0]["type"] == "command"
+        assert stop["hooks"][0]["command"] == "mem0-hook-stop"
+        assert stop["hooks"][0]["timeout"] == 30000
+
+        captured = capsys.readouterr()
+        assert "Already installed" in captured.out
+
+    def test_legacy_mixed_with_other_hooks_preserved(self, tmp_path):
+        """Migration preserves non-mem0 hooks alongside legacy mem0 hooks."""
+        project_dir = tmp_path / "proj"
+        claude_dir = project_dir / ".claude"
+        claude_dir.mkdir(parents=True)
+
+        existing = {
+            "hooks": {
+                "SessionStart": [
+                    {"command": "other-hook", "timeout": 5000},
+                    {"command": "mem0-hook-context", "matcher": "startup|compact", "timeout": 15000},
+                ],
+            }
+        }
+        (claude_dir / "settings.json").write_text(json.dumps(existing))
+
+        with patch("sys.argv", ["mem0-install-hooks", "--project-dir", str(project_dir)]):
+            hooks.install_main()
+
+        settings = json.loads((claude_dir / "settings.json").read_text())
+        # Both hooks migrated, no duplicates for mem0-hook-context
+        assert len(settings["hooks"]["SessionStart"]) == 2
+        commands = [
+            handler["command"]
+            for group in settings["hooks"]["SessionStart"]
+            for handler in group.get("hooks", [])
+        ]
+        assert "other-hook" in commands
+        assert "mem0-hook-context" in commands
+
+        # Stop hook auto-installed since it wasn't in the original settings
+        assert len(settings["hooks"]["Stop"]) == 1
+        assert settings["hooks"]["Stop"][0]["hooks"][0]["command"] == "mem0-hook-stop"
