eon-memory 1.1.0 → 1.2.1

package/templates/hooks/eon_client.py

@@ -0,0 +1,565 @@
+#!/usr/bin/env python3
+"""
+EON Memory API Client - Production Grade
+==========================================
+Zero-dependency Python client for EON Memory hooks and agents.
+Uses only Python stdlib (urllib, json, logging, threading, uuid, time).
+
+Features:
+  - Retry with exponential backoff (3 attempts)
+  - Request correlation IDs for debugging/support
+  - Structured error handling (EONAPIError)
+  - Connection timeout management
+  - Response validation
+  - Thread-safe singleton
+  - Optional file logging
+
+Config: ~/.claude/eon_config.json
+  {
+    "api_key": "eon_xxx...",
+    "endpoint": "https://app.ai-developer.ch",
+    "tier": "starter|business|enterprise",
+    "log_file": "~/.claude/logs/eon_client.log"  // optional
+  }
+
+Version: 1.0.0 (2026-04-11)
+License: Proprietary - EON Memory System
+"""
+
+import json
+import logging
+import os
+import threading
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+__version__ = "1.0.0"
+
+# ============================================================
+# Configuration
+# ============================================================
+
+DEFAULT_CONFIG_PATH = Path.home() / ".claude" / "eon_config.json"
+DEFAULT_ENDPOINT = "https://app.ai-developer.ch"
+CONNECT_TIMEOUT = 5  # seconds
+READ_TIMEOUT = 30  # seconds
+MAX_RETRIES = 3
+BACKOFF_BASE = 1.0  # seconds (1s, 2s, 4s)
+
+
+# ============================================================
+# Exceptions
+# ============================================================
+
+class EONAPIError(Exception):
+    """Structured API error with status, message, and request correlation ID."""
+
+    def __init__(self, message: str, status: int = 0, request_id: str = "",
+                 response_body: str = ""):
+        super().__init__(message)
+        self.status = status
+        self.request_id = request_id
+        self.response_body = response_body
+
+    def __str__(self):
+        parts = [f"EONAPIError: {self.args[0]}"]
+        if self.status:
+            parts.append(f"status={self.status}")
+        if self.request_id:
+            parts.append(f"request_id={self.request_id}")
+        return " | ".join(parts)
+
+
+class EONConfigError(EONAPIError):
+    """Raised when configuration is missing or invalid."""
+    pass
+
+
+class EONAuthError(EONAPIError):
+    """Raised on 401/403 authentication failures."""
+    pass
+
+
+class EONRateLimitError(EONAPIError):
+    """Raised on 429 rate limit responses."""
+
+    def __init__(self, message: str, retry_after: float = 0, **kwargs):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+# ============================================================
+# Data Classes (plain dicts with typed accessors)
+# ============================================================
+
+class Memory(dict):
+    """Memory record with typed accessors."""
+
+    @property
+    def id(self) -> Optional[int]:
+        return self.get("id") or self.get("memory_id")
+
+    @property
+    def title(self) -> str:
+        return self.get("title", "")
+
+    @property
+    def content(self) -> str:
+        return self.get("content", "")
+
+    @property
+    def project_id(self) -> str:
+        return self.get("project_id", "")
+
+    @property
+    def category(self) -> str:
+        return self.get("category", "")
+
+    @property
+    def quality_score(self) -> float:
+        return float(self.get("quality_score", 0.0))
+
+
+class ProjectContext(dict):
+    """Project context with typed accessors."""
+
+    @property
+    def recent_memories(self) -> List[Dict]:
+        return self.get("recent_memories", [])
+
+    @property
+    def projects(self) -> List[str]:
+        return self.get("projects", [])
+
+    @property
+    def stats(self) -> Dict:
+        return self.get("stats", {})
+
+
+class HealthStatus(dict):
+    """Health check result."""
+
+    @property
+    def ok(self) -> bool:
+        return self.get("status") == "ok"
+
+    @property
+    def service(self) -> str:
+        return self.get("service", "")
+
+
+class AgentConfig(dict):
+    """Tier-based agent configuration."""
+
+    @property
+    def tier(self) -> str:
+        return self.get("tier", "starter")
+
+    @property
+    def agents(self) -> List[str]:
+        return self.get("agents", [])
+
+    @property
+    def hooks(self) -> List[str]:
+        return self.get("hooks", [])
+
+    @property
+    def skills(self) -> List[str]:
+        return self.get("skills", [])
+
+
+# ============================================================
+# EON Client - Thread-safe Singleton
+# ============================================================
+
+class EONClient:
+    """
+    Production-grade EON Memory API client.
+
+    Thread-safe, retries with backoff, structured errors,
+    correlation IDs for every request.
+
+    Usage:
+        client = EONClient()  # loads config from ~/.claude/eon_config.json
+        results = client.search("database migration")
+        client.create("Fix Applied", "Details...", project_id="myproject")
+    """
+
+    _instance = None
+    _lock = threading.Lock()
+
+    def __new__(cls, config_path: Optional[str] = None):
+        """Thread-safe singleton - one client per process."""
+        with cls._lock:
+            if cls._instance is None:
+                cls._instance = super().__new__(cls)
+                cls._instance._initialized = False
+            return cls._instance
+
+    def __init__(self, config_path: Optional[str] = None):
+        if self._initialized:
+            return
+        self._initialized = True
+        self._request_lock = threading.Lock()
+
+        # Load config
+        path = Path(config_path) if config_path else DEFAULT_CONFIG_PATH
+        self._config = self._load_config(path)
+        self._api_key = self._config.get("api_key", "")
+        self._endpoint = self._config.get("endpoint", DEFAULT_ENDPOINT).rstrip("/")
+        self._tier = self._config.get("tier", "starter")
+
+        if not self._api_key:
+            raise EONConfigError(
+                f"No api_key found in {path}. Run 'npx eon-memory init' to configure."
+            )
+
+        # Setup logging
+        self._logger = logging.getLogger("eon_client")
+        log_file = self._config.get("log_file", "")
+        if log_file:
+            log_path = Path(os.path.expanduser(log_file))
+            log_path.parent.mkdir(parents=True, exist_ok=True)
+            handler = logging.FileHandler(str(log_path), encoding="utf-8")
+            handler.setFormatter(logging.Formatter(
+                "%(asctime)s [%(levelname)s] %(message)s"
+            ))
+            self._logger.addHandler(handler)
+            self._logger.setLevel(logging.DEBUG)
+
+    @staticmethod
+    def _load_config(path: Path) -> Dict[str, Any]:
+        """Load config from JSON file."""
+        if not path.exists():
+            raise EONConfigError(
+                f"Config not found: {path}. Run 'npx eon-memory init' to set up."
+            )
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError) as e:
+            raise EONConfigError(f"Invalid config at {path}: {e}")
+
+    # --------------------------------------------------------
+    # HTTP Layer
+    # --------------------------------------------------------
+
+    def _request(self, method: str, path: str, body: Optional[Dict] = None,
+                 timeout: float = READ_TIMEOUT) -> Dict[str, Any]:
+        """
+        Make an HTTP request with retry, backoff, and correlation ID.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE)
+            path: API path (e.g., "/api/hooks/search")
+            body: JSON body for POST/PUT
+            timeout: Read timeout in seconds
+
+        Returns:
+            Parsed JSON response as dict
+
+        Raises:
+            EONAPIError: On non-retryable errors
+            EONAuthError: On 401/403
+            EONRateLimitError: On 429
+        """
+        url = f"{self._endpoint}{path}"
+        request_id = str(uuid.uuid4())[:8]
+
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "X-Request-ID": request_id,
+            "X-Client-Version": __version__,
+        }
+
+        data = json.dumps(body).encode("utf-8") if body else None
+        last_error = None
+
+        for attempt in range(1, MAX_RETRIES + 1):
+            try:
+                req = Request(url, data=data, headers=headers, method=method)
+                self._logger.debug(
+                    f"[{request_id}] {method} {path} attempt={attempt}"
+                )
+
+                with urlopen(req, timeout=timeout) as resp:
+                    resp_body = resp.read().decode("utf-8")
+                    result = json.loads(resp_body) if resp_body else {}
+                    self._logger.debug(
+                        f"[{request_id}] {resp.status} OK ({len(resp_body)}B)"
+                    )
+                    return result
+
+            except HTTPError as e:
+                resp_body = ""
+                try:
+                    resp_body = e.read().decode("utf-8", errors="replace")
+                except Exception:
+                    pass
+
+                self._logger.warning(
+                    f"[{request_id}] HTTP {e.code} on attempt {attempt}: {resp_body[:200]}"
+                )
+
+                # Non-retryable errors
+                if e.code == 401 or e.code == 403:
+                    raise EONAuthError(
+                        f"Authentication failed ({e.code})",
+                        status=e.code,
+                        request_id=request_id,
+                        response_body=resp_body,
+                    )
+
+                if e.code == 429:
+                    retry_after = float(e.headers.get("Retry-After", "5"))
+                    if attempt < MAX_RETRIES:
+                        time.sleep(retry_after)
+                        continue
+                    raise EONRateLimitError(
+                        "Rate limit exceeded",
+                        retry_after=retry_after,
+                        status=429,
+                        request_id=request_id,
+                    )
+
+                if e.code == 400 or e.code == 404 or e.code == 422:
+                    detail = ""
+                    try:
+                        detail = json.loads(resp_body).get("detail", resp_body)
+                    except Exception:
+                        detail = resp_body
+                    raise EONAPIError(
+                        f"Client error: {detail}",
+                        status=e.code,
+                        request_id=request_id,
+                        response_body=resp_body,
+                    )
+
+                # Server errors (5xx) - retry
+                last_error = EONAPIError(
+                    f"Server error ({e.code})",
+                    status=e.code,
+                    request_id=request_id,
+                    response_body=resp_body,
+                )
+
+            except URLError as e:
+                self._logger.warning(
+                    f"[{request_id}] Network error on attempt {attempt}: {e.reason}"
+                )
+                last_error = EONAPIError(
+                    f"Network error: {e.reason}",
+                    request_id=request_id,
+                )
+
+            except Exception as e:
+                self._logger.warning(
+                    f"[{request_id}] Unexpected error on attempt {attempt}: {e}"
+                )
+                last_error = EONAPIError(
+                    f"Unexpected error: {e}",
+                    request_id=request_id,
+                )
+
+            # Exponential backoff before retry
+            if attempt < MAX_RETRIES:
+                wait = BACKOFF_BASE * (2 ** (attempt - 1))
+                self._logger.debug(f"[{request_id}] Retrying in {wait}s...")
+                time.sleep(wait)
+
+        # All retries exhausted
+        raise last_error or EONAPIError(
+            "Request failed after all retries",
+            request_id=request_id,
+        )
+
+    # --------------------------------------------------------
+    # Public API Methods
+    # --------------------------------------------------------
+
+    def search(self, query: str, project_id: Optional[str] = None,
+               n_results: int = 5) -> List[Memory]:
+        """
+        Semantic search across memories.
+
+        Args:
+            query: Search query string
+            project_id: Optional project filter
+            n_results: Number of results (1-20)
+
+        Returns:
+            List of Memory objects sorted by relevance
+        """
+        body = {"query": query, "n_results": min(max(n_results, 1), 20)}
+        if project_id:
+            body["project_id"] = project_id
+
+        resp = self._request("POST", "/api/hooks/search", body)
+        return [Memory(r) for r in resp.get("results", [])]
+
+    def create(self, title: str, content: str, project_id: str = "default",
+               category: str = "update") -> Memory:
+        """
+        Create a new memory.
+
+        Args:
+            title: Memory title (min 3 chars)
+            content: Memory content (min 20 chars)
+            project_id: Project to store in
+            category: One of: update, context, decision, error, roadmap
+
+        Returns:
+            Created Memory object with id
+        """
+        body = {
+            "title": title,
+            "content": content,
+            "project_id": project_id,
+            "category": category,
+        }
+        resp = self._request("POST", "/api/hooks/create", body)
+        return Memory(resp)
+
+    def update(self, memory_id: int, **updates) -> Memory:
+        """
+        Update an existing memory.
+
+        Args:
+            memory_id: ID of memory to update
+            **updates: Fields to update (title, content, project_id, category)
+
+        Returns:
+            Updated Memory object
+        """
+        body = {"memory_id": memory_id, **updates}
+        resp = self._request("POST", "/api/hooks/update", body)
+        return Memory(resp)
+
+    def get(self, memory_id: int) -> Memory:
+        """Get a single memory by ID."""
+        resp = self._request("POST", "/api/hooks/search",
+                             {"query": f"id:{memory_id}", "n_results": 1})
+        results = resp.get("results", [])
+        if not results:
+            raise EONAPIError(f"Memory {memory_id} not found", status=404)
+        return Memory(results[0])
+
+    def list(self, project_id: Optional[str] = None,
+             limit: int = 50) -> List[Memory]:
+        """
+        List memories, optionally filtered by project.
+
+        Args:
+            project_id: Optional project filter
+            limit: Maximum results (1-100)
+
+        Returns:
+            List of Memory objects
+        """
+        body = {"query": "*", "n_results": min(max(limit, 1), 100)}
+        if project_id:
+            body["project_id"] = project_id
+        resp = self._request("POST", "/api/hooks/search", body)
+        return [Memory(r) for r in resp.get("results", [])]
+
+    def get_context(self, project_id: Optional[str] = None) -> ProjectContext:
+        """
+        Get project context (recent memories, projects, stats).
+
+        Args:
+            project_id: Optional project filter
+
+        Returns:
+            ProjectContext with recent_memories, projects, stats
+        """
+        resp = self._request("POST", "/api/hooks/context")
+        return ProjectContext(resp)
+
+    def save_session(self, summary: Optional[str] = None,
+                     decisions: Optional[List[str]] = None,
+                     blockers: Optional[List[str]] = None) -> Dict[str, Any]:
+        """
+        End and save the current session.
+
+        Args:
+            summary: Session summary text
+            decisions: List of decisions made
+            blockers: List of blockers encountered
+
+        Returns:
+            Session save confirmation
+        """
+        body = {"action": "end"}
+        if summary:
+            body["summary"] = summary
+        if decisions:
+            body["decisions"] = decisions
+        if blockers:
+            body["blockers"] = blockers
+
+        return self._request("POST", "/api/hooks/session", body)
+
+    def get_agent_config(self) -> AgentConfig:
+        """
+        Get tier-based agent/hook/skill configuration.
+
+        Returns:
+            AgentConfig with tier, agents, hooks, skills lists
+        """
+        resp = self._request("GET", "/api/hooks/config")
+        return AgentConfig(resp)
+
+    def health(self) -> HealthStatus:
+        """
+        Quick health check (< 100ms target).
+
+        Returns:
+            HealthStatus with ok flag and service name
+        """
+        resp = self._request("GET", "/api/hooks/health", timeout=CONNECT_TIMEOUT)
+        return HealthStatus(resp)
+
+    # --------------------------------------------------------
+    # Convenience
+    # --------------------------------------------------------
+
+    @property
+    def tier(self) -> str:
+        """Current subscription tier."""
+        return self._tier
+
+    @property
+    def endpoint(self) -> str:
+        """API endpoint URL."""
+        return self._endpoint
+
+    def __repr__(self):
+        return f"EONClient(endpoint={self._endpoint!r}, tier={self._tier!r})"
+
+
+# ============================================================
+# Module-level convenience function
+# ============================================================
+
+_default_client: Optional[EONClient] = None
+
+
+def get_client(config_path: Optional[str] = None) -> EONClient:
+    """
+    Get or create the singleton EON client.
+
+    Returns EONClient instance, creating it on first call.
+    Safe to call from hooks - returns quickly if already initialized.
+    """
+    global _default_client
+    if _default_client is None:
+        try:
+            _default_client = EONClient(config_path)
+        except EONConfigError:
+            return None
+    return _default_client

package/templates/hooks/eon_memory_search.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""
+EON Memory Search Hook - Semantic Context Injection
+======================================================
+Searches EON Memory on every user prompt and injects relevant
+context into the conversation.
+
+Uses eon_client.py for API calls to the EON backend.
+
+Hook Type: UserPromptSubmit
+Version: 1.0.0
+"""
+
+import json
+import sys
+from pathlib import Path
+
+# Add hooks directory for eon_client import
+HOOKS_DIR = str(Path(__file__).parent)
+if HOOKS_DIR not in sys.path:
+    sys.path.insert(0, HOOKS_DIR)
+
+# Common greetings to skip (no search needed)
+SKIP_MESSAGES = {
+    "hi", "hello", "hey", "ok", "okay", "yes", "no",
+    "thanks", "thank you", "bye", "quit", "exit",
+}
+
+# Minimum message length for search
+MIN_LENGTH = 15
+
+# Maximum results to inject
+MAX_RESULTS = 5
+
+
+def extract_keywords(text: str) -> str:
+    """Extract meaningful keywords from text for search."""
+    # Remove common stop words
+    stop_words = {
+        "the", "a", "an", "is", "are", "was", "were", "be", "been",
+        "being", "have", "has", "had", "do", "does", "did", "will",
+        "would", "could", "should", "may", "might", "can", "to",
+        "of", "in", "for", "on", "with", "at", "by", "from", "as",
+        "into", "through", "during", "before", "after", "and", "but",
+        "or", "not", "no", "so", "if", "then", "than", "too", "very",
+        "just", "about", "up", "out", "how", "what", "which", "who",
+        "when", "where", "why", "all", "each", "every", "both", "few",
+        "more", "most", "other", "some", "such", "only", "own", "same",
+        "that", "this", "it", "i", "me", "my", "we", "our", "you",
+        "your", "he", "she", "they", "them", "please", "help",
+    }
+
+    words = text.lower().split()
+    keywords = [w for w in words if w not in stop_words and len(w) > 2]
+    return " ".join(keywords[:10])
+
+
+def format_results(results: list) -> str:
+    """Format search results as context string."""
+    if not results:
+        return ""
+
+    lines = [
+        "============================================================",
+        "EON MEMORY CONTEXT",
+        "============================================================",
+        "",
+    ]
+
+    for r in results:
+        memory_id = r.get("memory_id", "?")
+        title = r.get("title", "Untitled")
+        preview = r.get("content_preview", "")[:80]
+        project = r.get("project_id", "")
+        similarity = r.get("similarity", 0)
+
+        lines.append(f"[#{memory_id}] {title}")
+        if project:
+            lines.append(f"  Project: {project} | Relevance: {similarity:.2f}")
+        if preview:
+            lines.append(f"  Preview: {preview}")
+        lines.append("")
+
+    lines.extend([
+        "============================================================",
+        "Use this context to inform your response.",
+        "============================================================",
+    ])
+
+    return "\n".join(lines)
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)
+
+    prompt = input_data.get("prompt", "")
+
+    # Skip short messages and greetings
+    stripped = prompt.strip().lower().rstrip("!.,?")
+    if not prompt or len(prompt) < MIN_LENGTH or stripped in SKIP_MESSAGES:
+        sys.exit(0)
+
+    # Try to search via eon_client
+    try:
+        from eon_client import get_client
+
+        client = get_client()
+        if not client:
+            sys.exit(0)
+
+        # Extract keywords for better search
+        query = extract_keywords(prompt)
+        if not query:
+            query = prompt[:100]
+
+        results = client.search(query, n_results=MAX_RESULTS)
+
+        if not results:
+            sys.exit(0)
+
+        # Convert Memory objects to dicts for formatting
+        result_dicts = [dict(r) for r in results]
+        context = format_results(result_dicts)
+
+        if not context:
+            sys.exit(0)
+
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": context,
+            }
+        }
+
+        print(json.dumps(output))
+
+    except Exception:
+        pass  # Fail silently - don't block the user
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()