dhee 3.2.0__tar.gz → 3.3.0__tar.gz

{dhee-3.2.0 → dhee-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dhee
-Version: 3.2.0
+Version: 3.3.0
 Summary: Cognition layer for AI agents — persistent memory, performance tracking, and insight synthesis
 Author: Sankhya AI Labs
 License: MIT
@@ -75,10 +75,10 @@ Requires-Dist: twine>=5.0.0; extra == "dev"
 Dynamic: license-file
 
 <p align="center">
-  <img src="docs/dhee-logo.png" alt="Dhee" width="80">
+  <img src="docs/dhee-logo.png" alt="Dhee" width="80"> <h1 align="center">Dhee</h1>
 </p>
 
-<h1 align="center">Dhee</h1>
+
 
 <h3 align="center">The cognition layer that turns your agent into a HyperAgent.</h3>
 
@@ -154,12 +154,42 @@ d.context("fixing auth bug")
 d.checkpoint("Fixed it", what_worked="git blame first")
 ```
 
+### Claude Code — Native Hooks (v3.3.0)
+
+One command. Every Claude Code session becomes self-evolving.
+
+```bash
+dhee install
+```
+
+That's it. Dhee hooks into Claude Code's lifecycle — no CLAUDE.md bloat, no SKILL.md files, no markdown accumulation. Structured XML context injection, budgeted to ~630 tokens regardless of how much memory you have.
+
+**What happens automatically:**
+
+| Hook | When | What Dhee does |
+|:-----|:-----|:---------------|
+| `SessionStart` | Session opens | Injects last session, insights, performance trends, relevant memories |
+| `UserPromptSubmit` | Every prompt | Surfaces memories relevant to what you just asked |
+| `PostToolUse` | After Edit/Write/Bash | Captures what Claude did (secrets auto-stripped) |
+| `PreCompact` | Before context compaction | Checkpoints state so nothing is lost |
+| `Stop` | Session ends | Records outcomes — what worked, what failed, learnings |
+
+Or start Claude Code directly with context:
+
+```bash
+dhee task "fix the flaky auth test"
+```
+
+**Why not CLAUDE.md?** Markdown files are static. After 6 months of accumulated knowledge, they rot — stale patterns sit at equal weight to current ones, no retrieval ranking, no forgetting. Dhee uses vector memory with strength-based decay. Relevant memories surface. Irrelevant ones fade. The context budget stays constant at ~630 tokens whether you have 50 memories or 50,000.
+
 ### CLI
 
 ```bash
 dhee remember "User prefers Python"
 dhee recall "programming language"
 dhee checkpoint "Fixed auth bug" --what-worked "checked logs"
+dhee install          # install Claude Code hooks
+dhee uninstall-hooks  # remove them
 ```
 
 ### Docker
@@ -295,8 +325,18 @@ These are surfaced through `context()` and `checkpoint()` automatically when ena
 ## Architecture
 
 ```
-Agent (Claude, GPT, Cursor, custom)
+Claude Code (or any agent)
   │
+  ├── SessionStart hook ──→ dhee.context() ──→ XML renderer ──→ system prompt injection
+  ├── UserPromptSubmit ───→ dhee.recall()  ──→ ranked memories ──→ per-turn context
+  ├── PostToolUse ────────→ dhee.remember() ─→ privacy filter ──→ stored (0 LLM)
+  ├── PreCompact ─────────→ dhee.checkpoint() + re-inject context
+  └── Stop ───────────────→ dhee.checkpoint(what_worked, what_failed, outcome_score)
+```
+
+The 4-operation API under the hooks:
+
+```
   ├── remember(content)     → Engram: embed + store (0 LLM)
   ├── recall(query)         → Engram: embed + vector search (0 LLM)
   ├── context(task)         → Buddhi: performance + insights + intentions + memories

{dhee-3.2.0 → dhee-3.3.0}/README.md

@@ -1,8 +1,8 @@
 <p align="center">
-  <img src="docs/dhee-logo.png" alt="Dhee" width="80">
+  <img src="docs/dhee-logo.png" alt="Dhee" width="80"> <h1 align="center">Dhee</h1>
 </p>
 
-<h1 align="center">Dhee</h1>
+
 
 <h3 align="center">The cognition layer that turns your agent into a HyperAgent.</h3>
 
@@ -78,12 +78,42 @@ d.context("fixing auth bug")
 d.checkpoint("Fixed it", what_worked="git blame first")
 ```
 
+### Claude Code — Native Hooks (v3.3.0)
+
+One command. Every Claude Code session becomes self-evolving.
+
+```bash
+dhee install
+```
+
+That's it. Dhee hooks into Claude Code's lifecycle — no CLAUDE.md bloat, no SKILL.md files, no markdown accumulation. Structured XML context injection, budgeted to ~630 tokens regardless of how much memory you have.
+
+**What happens automatically:**
+
+| Hook | When | What Dhee does |
+|:-----|:-----|:---------------|
+| `SessionStart` | Session opens | Injects last session, insights, performance trends, relevant memories |
+| `UserPromptSubmit` | Every prompt | Surfaces memories relevant to what you just asked |
+| `PostToolUse` | After Edit/Write/Bash | Captures what Claude did (secrets auto-stripped) |
+| `PreCompact` | Before context compaction | Checkpoints state so nothing is lost |
+| `Stop` | Session ends | Records outcomes — what worked, what failed, learnings |
+
+Or start Claude Code directly with context:
+
+```bash
+dhee task "fix the flaky auth test"
+```
+
+**Why not CLAUDE.md?** Markdown files are static. After 6 months of accumulated knowledge, they rot — stale patterns sit at equal weight to current ones, no retrieval ranking, no forgetting. Dhee uses vector memory with strength-based decay. Relevant memories surface. Irrelevant ones fade. The context budget stays constant at ~630 tokens whether you have 50 memories or 50,000.
+
 ### CLI
 
 ```bash
 dhee remember "User prefers Python"
 dhee recall "programming language"
 dhee checkpoint "Fixed auth bug" --what-worked "checked logs"
+dhee install          # install Claude Code hooks
+dhee uninstall-hooks  # remove them
 ```
 
 ### Docker
@@ -219,8 +249,18 @@ These are surfaced through `context()` and `checkpoint()` automatically when ena
 ## Architecture
 
 ```
-Agent (Claude, GPT, Cursor, custom)
+Claude Code (or any agent)
   │
+  ├── SessionStart hook ──→ dhee.context() ──→ XML renderer ──→ system prompt injection
+  ├── UserPromptSubmit ───→ dhee.recall()  ──→ ranked memories ──→ per-turn context
+  ├── PostToolUse ────────→ dhee.remember() ─→ privacy filter ──→ stored (0 LLM)
+  ├── PreCompact ─────────→ dhee.checkpoint() + re-inject context
+  └── Stop ───────────────→ dhee.checkpoint(what_worked, what_failed, outcome_score)
+```
+
+The 4-operation API under the hooks:
+
+```
   ├── remember(content)     → Engram: embed + store (0 LLM)
   ├── recall(query)         → Engram: embed + vector search (0 LLM)
   ├── context(task)         → Buddhi: performance + insights + intentions + memories

{dhee-3.2.0 → dhee-3.3.0}/dhee/__init__.py

@@ -32,7 +32,7 @@ from dhee.configs.base import MemoryConfig, FadeMemConfig, EchoMemConfig, Catego
 # Default: CoreMemory (lightest, zero-config)
 Memory = CoreMemory
 
-__version__ = "3.2.0"
+__version__ = "3.3.0"
 __all__ = [
     # Memory classes
     "Engram",

{dhee-3.2.0 → dhee-3.3.0}/dhee/cli.py

@@ -318,6 +318,58 @@ def cmd_uninstall(args: argparse.Namespace) -> None:
         print("Cancelled.")
 
 
+def cmd_task(args: argparse.Namespace) -> None:
+    """Start Claude Code with Dhee cognition hooks."""
+    from dhee.hooks.claude_code.install import ensure_installed
+
+    result = ensure_installed()
+    if result.already_installed:
+        pass  # hooks already in place
+    elif result.created or result.updated:
+        print(f"  Dhee hooks installed → {result.settings_path}")
+
+    # Find claude executable
+    claude_bin = shutil.which("claude")
+    if not claude_bin:
+        print("Error: 'claude' not found in PATH. Install Claude Code first.", file=sys.stderr)
+        sys.exit(1)
+
+    # Build command
+    cmd = [claude_bin]
+    if args.print_mode:
+        cmd.append("--print")
+    if args.description:
+        cmd.append(args.description)
+
+    # Replace current process with claude
+    os.execvp(claude_bin, cmd)
+
+
+def cmd_install_hooks(args: argparse.Namespace) -> None:
+    """Install Dhee hooks into Claude Code."""
+    from dhee.hooks.claude_code.install import install_hooks
+
+    result = install_hooks(force=args.force)
+    if result.already_installed and not args.force:
+        print("  Dhee hooks already installed.")
+    else:
+        action = "Created" if result.created else "Updated"
+        print(f"  {action} {result.settings_path}")
+        print(f"  Hooks: {', '.join(result.events)}")
+        if result.backed_up:
+            print(f"  Backup: {result.backed_up}")
+
+
+def cmd_uninstall_hooks(args: argparse.Namespace) -> None:
+    """Remove Dhee hooks from Claude Code."""
+    from dhee.hooks.claude_code.install import uninstall_hooks
+
+    if uninstall_hooks():
+        print("  Dhee hooks removed.")
+    else:
+        print("  No Dhee hooks found.")
+
+
 def cmd_benchmark(args: argparse.Namespace) -> None:
     """Run performance benchmarks."""
     import time
@@ -458,6 +510,19 @@ def build_parser() -> argparse.ArgumentParser:
     p_status = sub.add_parser("status", help="Show version, config, and agents")
     p_status.add_argument("--json", action="store_true", help="JSON output")
 
+    # task
+    p_task = sub.add_parser("task", help="Start Claude Code with Dhee cognition")
+    p_task.add_argument("description", nargs="?", default="", help="Task description")
+    p_task.add_argument("--user-id", default="default", help="User ID")
+    p_task.add_argument("--print", dest="print_mode", action="store_true", help="One-shot mode")
+
+    # install (hooks)
+    p_install = sub.add_parser("install", help="Install Dhee hooks into Claude Code")
+    p_install.add_argument("--force", action="store_true", help="Overwrite existing hooks")
+
+    # uninstall-hooks
+    sub.add_parser("uninstall-hooks", help="Remove Dhee hooks from Claude Code")
+
     # benchmark
     sub.add_parser("benchmark", help="Run performance benchmarks")
 
@@ -481,6 +546,9 @@ COMMAND_MAP = {
     "export": cmd_export,
     "import": cmd_import,
     "status": cmd_status,
+    "task": cmd_task,
+    "install": cmd_install_hooks,
+    "uninstall-hooks": cmd_uninstall_hooks,
     "benchmark": cmd_benchmark,
     "uninstall": cmd_uninstall,
 }

dhee-3.3.0/dhee/hooks/claude_code/__init__.py

@@ -0,0 +1,2 @@
+from dhee.hooks.claude_code.install import ensure_installed, install_hooks, uninstall_hooks
+from dhee.hooks.claude_code.renderer import estimate_tokens, render_context

dhee-3.3.0/dhee/hooks/claude_code/__main__.py

@@ -0,0 +1,256 @@
+"""Dhee Claude Code hook dispatch.
+
+Usage::
+
+    python -m dhee.hooks.claude_code <event_name>
+
+Reads the Claude Code hook payload from stdin (JSON).
+Writes JSON response to stdout.
+On any error, outputs ``{}`` — never fails the host agent.
+
+Events handled:
+    SessionStart      — inject full Dhee context (session + memories + insights)
+    UserPromptSubmit  — inject relevant memories for the current prompt
+    PostToolUse       — capture tool outcomes into Dhee memory
+    PreCompact        — checkpoint state, re-inject context to survive compaction
+    Stop / SessionEnd — checkpoint session with outcomes
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+_MAX_REMEMBER_CHARS = 2000
+_MAX_QUERY_CHARS = 200
+
+
+def _get_dhee():
+    from dhee import Dhee
+
+    return Dhee(
+        user_id=os.environ.get("DHEE_USER_ID", "default"),
+        auto_context=False,
+        auto_checkpoint=False,
+    )
+
+
+def _render(ctx: dict[str, Any], **kwargs: Any) -> str:
+    from dhee.hooks.claude_code.renderer import render_context
+
+    return render_context(ctx, **kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Handlers — each returns a dict for stdout JSON
+# ---------------------------------------------------------------------------
+
+
+def handle_session_start(payload: dict[str, Any]) -> dict[str, Any]:
+    dhee = _get_dhee()
+
+    task_desc = (
+        payload.get("task_description")
+        or payload.get("initial_prompt")
+        or payload.get("prompt")
+        or ""
+    )
+
+    ctx = dhee.context(
+        task_description=task_desc or None,
+        user_id=os.environ.get("DHEE_USER_ID", "default"),
+    )
+
+    if not ctx:
+        return {}
+
+    has_content = (
+        ctx.get("memories")
+        or ctx.get("last_session")
+        or ctx.get("insights")
+        or ctx.get("intentions")
+        or ctx.get("performance")
+    )
+    if not has_content:
+        return {}
+
+    xml = _render(ctx, task_description=task_desc or None)
+    return {"systemMessage": xml}
+
+
+def handle_user_prompt(payload: dict[str, Any]) -> dict[str, Any]:
+    if isinstance(payload, dict):
+        prompt = str(payload.get("prompt", payload.get("content", "")))
+    elif isinstance(payload, str):
+        prompt = payload
+    else:
+        prompt = str(payload)
+
+    if not prompt.strip():
+        return {}
+
+    dhee = _get_dhee()
+    results = dhee.recall(query=prompt[:_MAX_QUERY_CHARS], limit=5)
+    if not results:
+        return {}
+
+    xml = _render({"memories": results}, max_tokens=500)
+    return {"systemMessage": xml}
+
+
+def handle_post_tool(payload: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        return {}
+
+    tool_name = payload.get("tool_name", "")
+    tool_input = payload.get("tool_input", {})
+    tool_result = payload.get("tool_result", "")
+    success = payload.get("success", True)
+
+    if not tool_name:
+        return {}
+
+    write_tools = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
+    shell_tools = {"Bash", "BashOutput"}
+    if tool_name not in write_tools and tool_name not in shell_tools:
+        return {}
+
+    if tool_name in write_tools:
+        path = ""
+        if isinstance(tool_input, dict):
+            path = tool_input.get("file_path", tool_input.get("path", ""))
+        content = f"edited {path}" if path else f"used {tool_name}"
+        if not success:
+            content = f"failed to edit {path}: {str(tool_result)[:100]}"
+    else:
+        cmd = ""
+        if isinstance(tool_input, dict):
+            cmd = tool_input.get("command", "")[:150]
+        content = f"ran: {cmd}" if cmd else f"used {tool_name}"
+        if not success:
+            stderr = str(tool_result)[:200] if tool_result else "unknown error"
+            content = f"command failed: {cmd[:80]} — {stderr}"
+
+    from dhee.hooks.claude_code.privacy import filter_secrets
+
+    content = filter_secrets(content)
+    if len(content) < 10:
+        return {}
+
+    try:
+        dhee = _get_dhee()
+        dhee.remember(
+            content=content[:_MAX_REMEMBER_CHARS],
+            metadata={"source": "claude_code_hook", "tool": tool_name, "success": success},
+        )
+    except Exception:
+        pass
+
+    return {}
+
+
+def handle_pre_compact(payload: dict[str, Any]) -> dict[str, Any]:
+    dhee = _get_dhee()
+
+    summary = "session compacted"
+    if isinstance(payload, dict):
+        summary = payload.get("summary", summary)
+
+    try:
+        dhee.checkpoint(summary=summary, status="compacted")
+    except Exception:
+        pass
+
+    ctx = dhee.context(user_id=os.environ.get("DHEE_USER_ID", "default"))
+    if not ctx:
+        return {}
+    xml = _render(ctx)
+    return {"systemMessage": xml}
+
+
+def handle_stop(payload: dict[str, Any]) -> dict[str, Any]:
+    dhee = _get_dhee()
+
+    summary = "session ended"
+    task_type = None
+    outcome_score = None
+    what_worked = None
+    what_failed = None
+
+    if isinstance(payload, dict):
+        summary = payload.get("summary", payload.get("task_description", summary))
+        task_type = payload.get("task_type")
+        if payload.get("outcome_score") is not None:
+            try:
+                outcome_score = float(payload["outcome_score"])
+            except (TypeError, ValueError):
+                pass
+        what_worked = payload.get("what_worked")
+        what_failed = payload.get("what_failed")
+
+    try:
+        dhee.checkpoint(
+            summary=summary,
+            task_type=task_type,
+            outcome_score=outcome_score,
+            what_worked=what_worked,
+            what_failed=what_failed,
+            status="completed",
+            repo=os.getcwd(),
+        )
+    except Exception:
+        pass
+
+    return {}
+
+
+# ---------------------------------------------------------------------------
+# Dispatch
+# ---------------------------------------------------------------------------
+
+_HANDLERS = {
+    "SessionStart": handle_session_start,
+    "UserPromptSubmit": handle_user_prompt,
+    "PostToolUse": handle_post_tool,
+    "PreCompact": handle_pre_compact,
+    "Stop": handle_stop,
+    "SessionEnd": handle_stop,
+}
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        sys.stderr.write("usage: python -m dhee.hooks.claude_code <event>\n")
+        sys.stdout.write("{}\n")
+        return 1
+
+    event = sys.argv[1]
+    handler = _HANDLERS.get(event)
+    if not handler:
+        sys.stdout.write("{}\n")
+        return 0
+
+    try:
+        raw = sys.stdin.read() or "{}"
+    except Exception:
+        raw = "{}"
+
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        payload = {"prompt": raw, "raw": raw}
+
+    try:
+        result = handler(payload)
+        sys.stdout.write(json.dumps(result or {}) + "\n")
+    except Exception as exc:
+        sys.stderr.write(f"dhee hook {event}: {exc}\n")
+        sys.stdout.write("{}\n")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dhee-3.3.0/dhee/hooks/claude_code/install.py

@@ -0,0 +1,173 @@
+"""Install Dhee hooks into Claude Code settings.
+
+Writes hook entries into ``~/.claude/settings.json`` so that every Claude Code
+session automatically gets Dhee cognition: memory injection on start, learning
+on tool use, checkpoint on exit. No markdown files, no SKILL.md, no plugins
+directory — just Python hooks in the agent's native lifecycle.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+HOOK_EVENTS: tuple[str, ...] = (
+    "SessionStart",
+    "UserPromptSubmit",
+    "PostToolUse",
+    "PreCompact",
+    "Stop",
+    "SessionEnd",
+)
+
+TOOL_MATCHERS: dict[str, str] = {
+    "PostToolUse": "Edit|Write|MultiEdit|Bash",
+}
+
+
+@dataclass
+class InstallResult:
+    settings_path: Path
+    events: tuple[str, ...]
+    created: bool = False
+    updated: bool = False
+    already_installed: bool = False
+    backed_up: Path | None = None
+
+
+def _settings_path() -> Path:
+    return Path.home() / ".claude" / "settings.json"
+
+
+def _python_cmd() -> str:
+    return sys.executable or "python3"
+
+
+def _build_entry(event: str) -> dict[str, Any]:
+    cmd = f"{_python_cmd()} -m dhee.hooks.claude_code {event}"
+    entry: dict[str, Any] = {
+        "hooks": [{"type": "command", "command": cmd, "timeout": 10}],
+    }
+    if event in TOOL_MATCHERS:
+        entry["matcher"] = TOOL_MATCHERS[event]
+    return entry
+
+
+def _has_dhee_hook(entries: list[dict[str, Any]]) -> bool:
+    for entry in entries:
+        for hook in entry.get("hooks", []):
+            if "dhee.hooks.claude_code" in hook.get("command", ""):
+                return True
+    return False
+
+
+def _all_installed(hooks: dict[str, Any], events: tuple[str, ...]) -> bool:
+    for event in events:
+        entries = hooks.get(event, [])
+        if not isinstance(entries, list) or not _has_dhee_hook(entries):
+            return False
+    return True
+
+
+def install_hooks(
+    *,
+    force: bool = False,
+    events: tuple[str, ...] = HOOK_EVENTS,
+) -> InstallResult:
+    """Install Dhee hooks into ``~/.claude/settings.json``."""
+    path = _settings_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    settings: dict[str, Any] = {}
+    if path.exists():
+        try:
+            settings = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, Exception):
+            settings = {}
+
+    existing_hooks = settings.get("hooks", {})
+
+    if not force and _all_installed(existing_hooks, events):
+        return InstallResult(
+            settings_path=path,
+            events=events,
+            already_installed=True,
+        )
+
+    backed_up = None
+    if path.exists():
+        backup = path.with_suffix(".json.dhee-backup")
+        shutil.copy2(path, backup)
+        backed_up = backup
+
+    hooks = dict(existing_hooks)
+    for event in events:
+        our_entry = _build_entry(event)
+        if event in hooks and not force:
+            existing = hooks[event]
+            if isinstance(existing, list) and _has_dhee_hook(existing):
+                continue
+            if isinstance(existing, list):
+                existing.append(our_entry)
+            else:
+                hooks[event] = [our_entry]
+        else:
+            hooks[event] = [our_entry]
+
+    settings["hooks"] = hooks
+
+    created = not path.exists()
+    path.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+
+    return InstallResult(
+        settings_path=path,
+        events=events,
+        created=created,
+        updated=not created,
+        backed_up=backed_up,
+    )
+
+
+def ensure_installed() -> InstallResult:
+    """Install hooks if not already present."""
+    return install_hooks()
+
+
+def uninstall_hooks() -> bool:
+    """Remove Dhee hooks from settings.json."""
+    path = _settings_path()
+    if not path.exists():
+        return False
+
+    try:
+        settings = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return False
+
+    hooks = settings.get("hooks", {})
+    changed = False
+
+    for event in list(hooks.keys()):
+        entries = hooks[event]
+        if not isinstance(entries, list):
+            continue
+        filtered = [
+            e for e in entries
+            if not any("dhee.hooks.claude_code" in h.get("command", "") for h in e.get("hooks", []))
+        ]
+        if len(filtered) != len(entries):
+            changed = True
+        if filtered:
+            hooks[event] = filtered
+        else:
+            del hooks[event]
+
+    if changed:
+        settings["hooks"] = hooks
+        path.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+
+    return changed