@jaguilar87/gaia 5.0.0-rc.2

package/dist/gaia-ops/tools/memory/git_invalidator.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""
+Git Invalidation Module for GAIA-OPS Episodic Memory
+
+Scans recent git commits for migration/deprecation patterns and weakens
+matching episodic memories by reducing their relevance_score.
+
+Inspired by hippo-memory's invalidation.ts patterns.
+"""
+
+import json
+import re
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Any, Optional
+
+
+# Patterns that signal a tool/library/concept has changed or been removed.
+# Each entry is a (compiled_regex, group_extractor_fn) tuple.
+# The extractor receives a re.Match and returns a list of affected term strings.
+_PATTERNS: List[tuple] = []
+
+def _build_patterns() -> List[tuple]:
+    """Build compiled pattern list once."""
+    raw = [
+        # "migrate from X" / "migrated from X to Y"
+        (
+            re.compile(r'\bmigrate(?:d)?\s+from\s+([\w\-./]+)', re.IGNORECASE),
+            lambda m: [m.group(1)],
+        ),
+        # "deprecate X" / "deprecated X"
+        (
+            re.compile(r'\bdeprecate[sd]?\s+([\w\-./]+)', re.IGNORECASE),
+            lambda m: [m.group(1)],
+        ),
+        # "remove X" (at least 3-char word to skip noise)
+        (
+            re.compile(r'\bremove[sd]?\s+([\w\-./]{3,})', re.IGNORECASE),
+            lambda m: [m.group(1)],
+        ),
+        # "replace X with Y"
+        (
+            re.compile(r'\breplace\s+([\w\-./]+)\s+with\s+([\w\-./]+)', re.IGNORECASE),
+            lambda m: [m.group(1), m.group(2)],
+        ),
+        # "upgrade from X" / "upgraded from X to Y"
+        (
+            re.compile(r'\bupgrade[sd]?\s+from\s+([\w\-./]+)', re.IGNORECASE),
+            lambda m: [m.group(1)],
+        ),
+        # "drop support for X" / "drop X"
+        (
+            re.compile(r'\bdrop(?:\s+support(?:\s+for)?)?\s+([\w\-./]{3,})', re.IGNORECASE),
+            lambda m: [m.group(1)],
+        ),
+        # version bump: "v3 to v4" or "3.x to 4.x"
+        (
+            re.compile(r'\bv?(\d+)(?:\.\w+)?\s+to\s+v?(\d+)(?:\.\w+)?\b', re.IGNORECASE),
+            lambda m: [f"v{m.group(1)}", f"v{m.group(2)}"],
+        ),
+    ]
+    return raw
+
+
+_COMPILED_PATTERNS = _build_patterns()
+
+
+def _get_git_log(commit_count: int, cwd: Optional[Path] = None) -> Optional[str]:
+    """
+    Run git log and return stdout, or None if not in a git repo.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "log", "--oneline", f"-{commit_count}", "--no-merges"],
+            capture_output=True,
+            text=True,
+            cwd=str(cwd) if cwd else None,
+        )
+        if result.returncode != 0:
+            return None
+        return result.stdout
+    except FileNotFoundError:
+        # git not available
+        return None
+
+
+def _scan_commits(log_output: str) -> tuple:
+    """
+    Scan git log output for migration/deprecation patterns.
+
+    Returns:
+        (patterns_detected, affected_terms) where patterns_detected is a list
+        of matched pattern strings and affected_terms is a set of lowercased
+        affected tool/library names.
+    """
+    patterns_detected: List[str] = []
+    affected_terms: set = set()
+
+    for line in log_output.splitlines():
+        # Strip the short SHA prefix (7-char hex + space)
+        message = re.sub(r'^[0-9a-f]{7,}\s+', '', line).strip()
+        if not message:
+            continue
+
+        for regex, extractor in _COMPILED_PATTERNS:
+            match = regex.search(message)
+            if match:
+                terms = extractor(match)
+                patterns_detected.append(message)
+                for term in terms:
+                    affected_terms.add(term.lower())
+                break  # one pattern per commit line is enough
+
+    return patterns_detected, affected_terms
+
+
+def _find_index_json() -> Optional[Path]:
+    """
+    Locate episodic memory index.json relative to the cwd.
+    Checks the canonical path: .claude/project-context/episodic-memory/index.json
+    """
+    candidate = Path(".claude/project-context/episodic-memory/index.json")
+    if candidate.exists():
+        return candidate
+    return None
+
+
+def _episode_mentions_terms(episode: Dict[str, Any], terms: set) -> bool:
+    """
+    Return True if the episode's searchable text overlaps with any affected term.
+    Checks: keywords, tags, title.
+    """
+    if not terms:
+        return False
+
+    searchable: List[str] = []
+
+    keywords = episode.get("keywords", [])
+    if isinstance(keywords, list):
+        searchable.extend(str(k).lower() for k in keywords)
+
+    tags = episode.get("tags", [])
+    if isinstance(tags, list):
+        searchable.extend(str(t).lower() for t in tags)
+
+    title = episode.get("title", "")
+    if title:
+        searchable.extend(re.split(r'\W+', title.lower()))
+
+    for word in searchable:
+        for term in terms:
+            # term could be "v3" etc — use substring match for flexibility
+            if term and (term in word or word in term):
+                return True
+    return False
+
+
+def check_recent_commits(
+    dry_run: bool = True,
+    commit_count: int = 20,
+) -> Dict[str, Any]:
+    """
+    Scan recent git commits for migration/deprecation patterns and weaken
+    matching episodic memories.
+
+    Args:
+        dry_run: If True, identify affected episodes but do NOT modify index.json.
+        commit_count: Number of recent commits to scan (default 20).
+
+    Returns:
+        dict with keys:
+            affected_episodes: list of episode IDs that match
+            patterns_detected: list of commit message strings that matched a pattern
+            would_modify: count of episodes that would be (or were) modified
+            commits_scanned: number of commits examined
+    """
+    empty_result: Dict[str, Any] = {
+        "affected_episodes": [],
+        "patterns_detected": [],
+        "would_modify": 0,
+        "commits_scanned": 0,
+    }
+
+    # Step 1: get git log
+    log_output = _get_git_log(commit_count)
+    if log_output is None:
+        return empty_result
+
+    commits_scanned = len([l for l in log_output.splitlines() if l.strip()])
+
+    # Step 2: detect patterns
+    patterns_detected, affected_terms = _scan_commits(log_output)
+
+    # If nothing matched, short-circuit
+    if not affected_terms:
+        return {
+            "affected_episodes": [],
+            "patterns_detected": patterns_detected,
+            "would_modify": 0,
+            "commits_scanned": commits_scanned,
+        }
+
+    # Step 3: load index.json
+    index_path = _find_index_json()
+    if index_path is None:
+        return {
+            "affected_episodes": [],
+            "patterns_detected": patterns_detected,
+            "would_modify": 0,
+            "commits_scanned": commits_scanned,
+        }
+
+    try:
+        index_data = json.loads(index_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {
+            "affected_episodes": [],
+            "patterns_detected": patterns_detected,
+            "would_modify": 0,
+            "commits_scanned": commits_scanned,
+        }
+
+    episodes: List[Dict[str, Any]] = index_data.get("episodes", [])
+
+    # Step 4: find matching episodes
+    affected_ids: List[str] = []
+    for ep in episodes:
+        if _episode_mentions_terms(ep, affected_terms):
+            ep_id = ep.get("id") or ep.get("episode_id", "")
+            if ep_id:
+                affected_ids.append(ep_id)
+
+    would_modify = len(affected_ids)
+
+    # Step 5: apply changes if not dry_run
+    if not dry_run and affected_ids:
+        affected_set = set(affected_ids)
+        for ep in episodes:
+            ep_id = ep.get("id") or ep.get("episode_id", "")
+            if ep_id in affected_set:
+                current_score = ep.get("relevance_score", 1.0)
+                ep["relevance_score"] = current_score * 0.5
+
+        index_data["episodes"] = episodes
+        index_path.write_text(
+            json.dumps(index_data, indent=2, ensure_ascii=False),
+            encoding="utf-8",
+        )
+
+    return {
+        "affected_episodes": affected_ids,
+        "patterns_detected": patterns_detected,
+        "would_modify": would_modify,
+        "commits_scanned": commits_scanned,
+    }
+
+
+if __name__ == "__main__":
+    import sys
+    dry = "--apply" not in sys.argv
+    result = check_recent_commits(dry_run=dry)
+    print(json.dumps(result, indent=2))

package/dist/gaia-ops/tools/memory/paths.py

@@ -0,0 +1,102 @@
+"""
+Shared path-resolution helpers for Gaia episodic memory.
+
+The central function, ``find_highest_claude_root``, walks upward from a
+starting directory and returns the ``.claude/``-bearing ancestor that is
+*closest to HOME* and looks like a Gaia instance — i.e. the top-most one
+that has Gaia-specific subdirectories under ``.claude/``.
+
+This prevents two classes of problems:
+1. A nested ``.claude/`` in a sub-repository or dev checkout (e.g.
+   ``gaia-ops-dev/.claude/``) shadowing the real Gaia instance.
+2. Claude Code's own user settings dir (``$HOME/.claude/``) being mistaken
+   for a Gaia instance — it has a ``.claude/`` but no Gaia-specific layout.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+# Subdirectories that signal "this .claude/ belongs to a Gaia instance".
+# Claude Code's own $HOME/.claude/ never has hooks/ or agents/.
+_GAIA_MARKERS = ("hooks", "agents", "skills")
+
+
+def _is_gaia_instance(directory: Path) -> bool:
+    """Return True if *directory*/.claude/ looks like a Gaia instance.
+
+    A directory qualifies as a Gaia instance root if its ``.claude/``
+    subdirectory contains at least one of the Gaia-specific marker dirs
+    (``hooks/``, ``agents/``, ``skills/``).  This distinguishes Gaia
+    instance roots from Claude Code's own ``$HOME/.claude/`` which only
+    contains user settings.
+
+    Parameters
+    ----------
+    directory:
+        The candidate root directory (the parent of ``.claude/``).
+    """
+    claude_dir = directory / ".claude"
+    if not claude_dir.is_dir():
+        return False
+    return any((claude_dir / marker).is_dir() for marker in _GAIA_MARKERS)
+
+
+def find_highest_claude_root(start: Optional[Path] = None) -> Optional[Path]:
+    """Return the highest Gaia instance root at or above *start*.
+
+    Walk from *start* (defaults to ``Path.cwd()``) up to ``Path.home()``
+    (inclusive).  Every directory that has a ``.claude/`` child **and**
+    passes the Gaia-instance check (has ``hooks/``, ``agents/``, or
+    ``skills/`` under ``.claude/``) is collected; the one *closest to HOME*
+    (highest in the hierarchy) is returned.
+
+    If no Gaia-qualified ``.claude/`` is found anywhere in the walk, the
+    function falls back to returning the highest plain ``.claude/`` ancestor
+    (matching the original semantics), so callers that don't have a full
+    Gaia layout still get a reasonable result.
+
+    Edge cases
+    ----------
+    - If no ``.claude/`` directory is found at all, returns ``None``.
+    - If *start* is already above ``Path.home()`` the walk is bounded at
+      ``Path.home()``; if that yields no candidates the function returns
+      ``None``.
+    - Symlinks in the path are **not** resolved — the walk uses the logical
+      path reported by the OS, consistent with the rest of the project.
+
+    Parameters
+    ----------
+    start:
+        Directory from which to begin the upward walk.  Defaults to
+        ``Path.cwd()``.
+
+    Returns
+    -------
+    Path or None
+        The ancestor path (not the ``.claude/`` child itself) that should
+        be used as the Gaia instance root, or ``None`` if no such ancestor
+        exists within the walk range.
+    """
+    if start is None:
+        start = Path.cwd()
+
+    home = Path.home()
+
+    # Walk from start up to home (inclusive).
+    candidates: list[Path] = [start, *start.parents]
+
+    highest_gaia: Optional[Path] = None   # best match: Gaia-qualified
+    highest_any: Optional[Path] = None    # fallback: any .claude/
+
+    for directory in candidates:
+        if (directory / ".claude").is_dir():
+            highest_any = directory  # keep updating — last = highest
+            if _is_gaia_instance(directory):
+                highest_gaia = directory  # keep updating — last = highest
+
+        # Stop at HOME; don't traverse system directories above it.
+        if directory == home:
+            break
+
+    # Prefer a Gaia-qualified root; fall back to any .claude/ if none found.
+    return highest_gaia if highest_gaia is not None else highest_any

package/dist/gaia-ops/tools/memory/scoring.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""
+Memory Scoring Module for GAIA-OPS
+
+Provides strength-based scoring for episodic memories using a decay formula
+inspired by the hippo-memory model. Memories decay over time (recency bias)
+and are strengthened by repeated retrieval (usage reinforcement).
+
+Formula:
+    strength = base_strength * (0.5 ^ (days_old / half_life))
+               * (1 + log(1 + retrieval_count) * boost_factor)
+
+Functions:
+    score_memory    -- compute strength score for a single memory
+    rank_episodes   -- rank a list of episode dicts by combined relevance + strength
+"""
+
+import math
+import re
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Core scoring
+# ---------------------------------------------------------------------------
+
+def score_memory(
+    days_old: float,
+    retrieval_count: int,
+    half_life: float = 7.0,
+    boost_factor: float = 0.3,
+    base_strength: float = 1.0,
+) -> float:
+    """Compute a strength score for a single memory.
+
+    Parameters
+    ----------
+    days_old:
+        Age of the memory in days (>= 0).
+    retrieval_count:
+        Number of times the memory has been retrieved (>= 0).
+    half_life:
+        Number of days after which unaccessed memory retains 50% strength.
+        Default: 7.0 days.
+    boost_factor:
+        Multiplier that scales the logarithmic retrieval boost.
+        Default: 0.3.
+    base_strength:
+        Starting strength before decay and boost are applied.
+        Default: 1.0.
+
+    Returns
+    -------
+    float
+        Strength score in the range (0, base_strength * (1 + boost)].
+        A higher value means the memory is more relevant/fresh.
+
+    Examples
+    --------
+    >>> score_memory(days_old=0, retrieval_count=0)
+    1.0
+    >>> score_memory(days_old=7, retrieval_count=0)   # half-life point
+    0.5
+    """
+    if half_life <= 0:
+        raise ValueError("half_life must be positive")
+    if days_old < 0:
+        raise ValueError("days_old must be non-negative")
+    if retrieval_count < 0:
+        raise ValueError("retrieval_count must be non-negative")
+
+    decay = 0.5 ** (days_old / half_life)
+    retrieval_boost = 1.0 + math.log(1 + retrieval_count) * boost_factor
+    return base_strength * decay * retrieval_boost
+
+
+# ---------------------------------------------------------------------------
+# Episode ranking
+# ---------------------------------------------------------------------------
+
+def _extract_text(episode: Dict[str, Any]) -> str:
+    """Combine all text fields from an episode into a single string for matching."""
+    parts: List[str] = []
+    for key in ("prompt", "enriched_prompt", "title", "type"):
+        value = episode.get(key)
+        if isinstance(value, str) and value:
+            parts.append(value)
+    tags = episode.get("tags")
+    if isinstance(tags, list):
+        parts.extend(t for t in tags if isinstance(t, str))
+    keywords = episode.get("keywords")
+    if isinstance(keywords, list):
+        parts.extend(k for k in keywords if isinstance(k, str))
+    return " ".join(parts)
+
+
+def _tokenize(text: str) -> set:
+    """Return a set of lowercase word tokens from *text*."""
+    return set(re.findall(r"[a-z0-9]+", text.lower()))
+
+
+def _keyword_overlap(episode_text: str, user_task: str) -> float:
+    """Compute a normalised keyword overlap score in [0, 1].
+
+    Uses the Jaccard-like formula:
+        overlap_count / max(1, len(task_tokens))
+
+    This measures what fraction of the user's task words appear in the
+    episode text, so short tasks aren't penalised.
+    """
+    task_tokens = _tokenize(user_task)
+    if not task_tokens:
+        return 0.0
+    episode_tokens = _tokenize(episode_text)
+    common = task_tokens & episode_tokens
+    return len(common) / len(task_tokens)
+
+
+def _days_old_from_episode(episode: Dict[str, Any]) -> float:
+    """Derive days_old from the episode's 'timestamp' field.
+
+    Falls back to 0.0 if the field is absent or unparseable.
+    """
+    ts = episode.get("timestamp")
+    if not ts:
+        return 0.0
+    try:
+        # Support ISO-8601 strings with or without timezone info.
+        if ts.endswith("Z"):
+            ts = ts[:-1] + "+00:00"
+        recorded = datetime.fromisoformat(ts)
+        if recorded.tzinfo is None:
+            recorded = recorded.replace(tzinfo=timezone.utc)
+        now = datetime.now(tz=timezone.utc)
+        delta = now - recorded
+        return max(0.0, delta.total_seconds() / 86400.0)
+    except (ValueError, AttributeError):
+        return 0.0
+
+
+def rank_episodes(
+    episodes: List[Dict[str, Any]],
+    user_task: str,
+    half_life: float = 7.0,
+    boost_factor: float = 0.3,
+) -> List[Dict[str, Any]]:
+    """Rank episodes by combined keyword relevance and memory strength.
+
+    The composite score is:
+        final_score = keyword_overlap * score_memory(...)
+
+    Episodes with no keyword overlap receive a score of 0 and are still
+    included so the caller can decide whether to filter them.
+
+    Parameters
+    ----------
+    episodes:
+        List of episode dicts. Each dict may contain: ``prompt``,
+        ``enriched_prompt``, ``timestamp``, ``retrieval_count``, ``title``,
+        ``type``, ``tags``, ``keywords``.
+    user_task:
+        Free-text description of what the user is trying to accomplish.
+    half_life:
+        Forwarded to :func:`score_memory`.
+    boost_factor:
+        Forwarded to :func:`score_memory`.
+
+    Returns
+    -------
+    list
+        A new list of episode dicts sorted by ``_score`` descending.
+        Each returned dict has an additional ``_score`` key (float) for
+        inspection and debugging.
+    """
+    scored: List[Dict[str, Any]] = []
+    for episode in episodes:
+        days_old = _days_old_from_episode(episode)
+        retrieval_count = int(episode.get("retrieval_count", 0))
+        strength = score_memory(
+            days_old=days_old,
+            retrieval_count=retrieval_count,
+            half_life=half_life,
+            boost_factor=boost_factor,
+        )
+        overlap = _keyword_overlap(_extract_text(episode), user_task)
+        final_score = overlap * strength
+        entry = dict(episode)
+        entry["_score"] = final_score
+        scored.append(entry)
+
+    scored.sort(key=lambda e: e["_score"], reverse=True)
+    return scored