code-context-control 2.28.0__py3-none-any.whl

services/memory_scorer.py

@@ -0,0 +1,246 @@
+"""Memory Scoring Engine — composite salience scores for facts.
+
+Replaces raw relevance_count with a multi-signal score that captures
+recency, frequency, cross-session spread, co-activation strength,
+source authority, confirmation history, and contradiction penalties.
+
+Each signal is normalized to [0, 1] and combined via weighted sum.
+The final salience score determines recall ranking, consolidation
+priority, and pruning eligibility.
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import datetime, timezone
+from typing import Any
+
+# ── Signal weights (sum to 1.0) ─────────────────────────────────────
+DEFAULT_WEIGHTS = {
+    "recency":        0.20,
+    "frequency":      0.15,
+    "cross_session":  0.20,
+    "co_activation":  0.10,
+    "source_auth":    0.10,
+    "confirmation":   0.15,
+    "contradiction":  0.10,
+}
+
+# ── Tier thresholds ─────────────────────────────────────────────────
+TIER_CORE      = 0.70   # immune to pruning
+TIER_ACTIVE    = 0.40   # normal retention
+TIER_DORMANT   = 0.20   # candidate for archival
+# below DORMANT = ephemeral, auto-pruned
+
+
+class MemoryScorer:
+    """Computes and caches composite salience scores for memory facts."""
+
+    _CACHE_MAX = 512
+
+    def __init__(self, weights: dict[str, float] | None = None):
+        w = {**DEFAULT_WEIGHTS, **(weights or {})}
+        total = sum(w.values())
+        # Normalize so weights always sum to 1.0
+        self.weights = {k: v / total for k, v in w.items()}
+        # Bounded score cache keyed on fact state. Natural invalidation via
+        # relevance-bucket and signal-count keys; no explicit busting needed
+        # except on graph-wide mutations (see invalidate_all).
+        self._score_cache: dict[tuple, dict] = {}
+
+    # ── Public API ──────────────────────────────────────────────────
+
+    def _cache_key(self, fact: dict) -> tuple:
+        """Cache key tolerates log-scale rc drift (every 5 recalls → new entry)."""
+        rc = int(fact.get("relevance_count", 0))
+        return (
+            fact.get("id", ""),
+            rc // 5,
+            len(fact.get("recall_sessions") or []),
+            int(fact.get("confirmation_count", 0)),
+            int(fact.get("contradiction_count", 0)),
+            fact.get("source_quality", ""),
+        )
+
+    def invalidate(self, fact_id: str) -> None:
+        """Drop cached scores for a single fact (called on update/delete)."""
+        for key in [k for k in self._score_cache if k and k[0] == fact_id]:
+            self._score_cache.pop(key, None)
+
+    def invalidate_all(self) -> None:
+        """Drop the entire cache (called on graph-wide mutations)."""
+        self._score_cache.clear()
+
+    def score(self, fact: dict, graph: Any = None) -> dict:
+        """Compute all signals and return a scoring breakdown.
+
+        Args:
+            fact: A fact dict from MemoryStore.
+            graph: Optional MemoryGraph for co-activation lookups.
+
+        Returns:
+            dict with per-signal scores, weighted total, and tier.
+        """
+        key = self._cache_key(fact)
+        cached = self._score_cache.get(key)
+        if cached is not None:
+            return cached
+
+        signals = {
+            "recency":        self._recency(fact),
+            "frequency":      self._frequency(fact),
+            "cross_session":  self._cross_session(fact),
+            "co_activation":  self._co_activation(fact, graph),
+            "source_auth":    self._source_authority(fact),
+            "confirmation":   self._confirmation(fact),
+            "contradiction":  self._contradiction(fact),
+        }
+
+        salience = sum(
+            self.weights[k] * v for k, v in signals.items()
+        )
+        salience = round(max(0.0, min(1.0, salience)), 4)
+
+        tier = self._tier(salience)
+
+        result = {
+            "salience": salience,
+            "tier": tier,
+            "signals": {k: round(v, 4) for k, v in signals.items()},
+        }
+
+        if len(self._score_cache) >= self._CACHE_MAX:
+            # Drop oldest ~20% (dict is insertion-ordered)
+            victims = list(self._score_cache.keys())[: self._CACHE_MAX // 5]
+            for v in victims:
+                self._score_cache.pop(v, None)
+        self._score_cache[key] = result
+        return result
+
+    def score_batch(self, facts: list[dict], graph: Any = None) -> list[dict]:
+        """Score a list of facts. Returns list of (fact_id, score_dict) pairs."""
+        results = []
+        for f in facts:
+            s = self.score(f, graph)
+            results.append({"id": f.get("id", ""), **s})
+        results.sort(key=lambda x: x["salience"], reverse=True)
+        return results
+
+    def tier_partition(self, facts: list[dict], graph: Any = None) -> dict[str, list[dict]]:
+        """Partition facts into tier buckets."""
+        buckets: dict[str, list[dict]] = {
+            "core": [], "active": [], "dormant": [], "ephemeral": [],
+        }
+        for f in facts:
+            s = self.score(f, graph)
+            f_with_score = {**f, "_score": s}
+            buckets[s["tier"]].append(f_with_score)
+        return buckets
+
+    # ── Signal functions (each returns 0.0 - 1.0) ──────────────────
+
+    def _recency(self, fact: dict) -> float:
+        """Exponential decay based on last access or creation time."""
+        ref = fact.get("last_accessed_at") or fact.get("timestamp")
+        if not ref:
+            return 0.0
+        try:
+            dt = datetime.fromisoformat(ref)
+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=timezone.utc)
+            age_days = (datetime.now(timezone.utc) - dt).total_seconds() / 86400
+        except (ValueError, TypeError):
+            return 0.0
+        # Half-life of 14 days: score halves every 14 days of inactivity
+        half_life = 14.0
+        return math.exp(-0.693 * age_days / half_life)
+
+    def _frequency(self, fact: dict) -> float:
+        """Log-scaled recall count with diminishing returns."""
+        count = int(fact.get("relevance_count", 0))
+        if count <= 0:
+            return 0.0
+        # log2(count+1) / log2(max_expected+1), capped at 1.0
+        # 32 recalls = score 1.0
+        return min(1.0, math.log2(count + 1) / 5.0)
+
+    def _cross_session(self, fact: dict) -> float:
+        """How many distinct sessions have recalled this fact."""
+        sessions = fact.get("recall_sessions", [])
+        if isinstance(sessions, list):
+            n = len(set(sessions))
+        else:
+            n = 0
+        # Also count source session
+        if fact.get("source_session"):
+            n = max(n, 1)
+        # 5+ sessions = max score
+        return min(1.0, n / 5.0)
+
+    def _co_activation(self, fact: dict, graph: Any = None) -> float:
+        """Strength of connections to other facts in the graph."""
+        if graph is None:
+            return 0.5  # neutral when no graph available
+        fact_id = fact.get("id", "")
+        if not fact_id:
+            return 0.0
+        edges = graph.get_edges(fact_id)
+        if not edges:
+            return 0.0
+        # Sum of edge weights, capped
+        total_weight = sum(e.get("weight", 1) for e in edges)
+        # 10+ total weight = max score
+        return min(1.0, total_weight / 10.0)
+
+    def _source_authority(self, fact: dict) -> float:
+        """User-provided facts score higher than auto-extracted."""
+        quality = fact.get("source_quality", "user")
+        authority_map = {
+            "user":       1.0,
+            "validated":  0.9,
+            "inferred":   0.6,
+            "auto":       0.4,
+            "auto:search": 0.3,
+            "auto:session": 0.2,
+        }
+        # Also check category prefix for auto-categorized facts
+        cat = fact.get("category", "")
+        if quality in authority_map:
+            base = authority_map[quality]
+        elif cat.startswith("auto:"):
+            base = authority_map.get(cat, 0.4)
+        else:
+            base = 0.5
+        return base
+
+    def _confirmation(self, fact: dict) -> float:
+        """How many times this fact has been confirmed/validated."""
+        count = int(fact.get("confirmation_count", 0))
+        if count <= 0:
+            return 0.0
+        # 3 confirmations = max score
+        return min(1.0, count / 3.0)
+
+    def _contradiction(self, fact: dict) -> float:
+        """Inverse penalty — contradictions reduce this score.
+
+        Returns 1.0 for no contradictions, 0.0 for heavily contradicted.
+        This is inverted so that the weighted sum penalizes contradictions.
+        """
+        count = int(fact.get("contradiction_count", 0))
+        if count <= 0:
+            return 1.0  # no contradictions = full score
+        # Each contradiction halves the score
+        return max(0.0, 1.0 / (1.0 + count))
+
+    # ── Tier classification ─────────────────────────────────────────
+
+    @staticmethod
+    def _tier(salience: float) -> str:
+        if salience >= TIER_CORE:
+            return "core"
+        if salience >= TIER_ACTIVE:
+            return "active"
+        if salience >= TIER_DORMANT:
+            return "dormant"
+        return "ephemeral"

services/metrics.py

@@ -0,0 +1,86 @@
+"""MetricsCollector — Aggregates metrics from all hybrid tier services.
+
+Provides a single unified view of:
+- Tier 1 (Output Filter): calls, raw/filtered tokens, savings
+- Tier 2 (Router): routing decisions per class, latency, failures
+- Tier 3 (SLTM): collection sizes, backend status
+"""
+
+
+class MetricsCollector:
+    """Aggregates metrics from output_filter, router, vector_store, and activity_log."""
+
+    def __init__(self, output_filter=None, router=None, vector_store=None, activity_log=None):
+        self.output_filter = output_filter
+        self.router = router
+        self.vector_store = vector_store
+        self.activity_log = activity_log
+
+    def collect(self) -> dict:
+        """Gather metrics from all tier services."""
+        result = {
+            "tier1_filter": None,
+            "tier2_router": None,
+            "tier3_sltm": None,
+            "precision": None,
+        }
+
+        if self.output_filter:
+            try:
+                result["tier1_filter"] = self.output_filter.get_metrics()
+            except Exception:
+                result["tier1_filter"] = {"error": "failed to collect"}
+
+        if self.router:
+            try:
+                result["tier2_router"] = self.router.get_metrics()
+            except Exception:
+                result["tier2_router"] = {"error": "failed to collect"}
+
+        if self.vector_store:
+            try:
+                result["tier3_sltm"] = self.vector_store.get_stats()
+            except Exception:
+                result["tier3_sltm"] = {"error": "failed to collect"}
+
+        if self.activity_log:
+            try:
+                stats = self.activity_log.get_stats()
+                # Determine precision: % of tool calls that are c3_*
+                # We need to look at actual tool names if possible, but for now
+                # we use the 'by_type' counts if they distinguish.
+                # (Refinement: ActivityLog should ideally track tool_name in tool_call events)
+                # For now, we'll provide a placeholder or return the raw counts.
+                result["precision"] = stats.get("by_type", {})
+            except Exception:
+                pass
+
+        return result
+
+    def summary(self) -> str:
+        """One-line summary of all tiers."""
+        metrics = self.collect()
+        parts = []
+
+        t1 = metrics.get("tier1_filter")
+        if t1 and "calls" in t1:
+            parts.append(f"filter:{t1['calls']}calls,{t1.get('total_savings_pct', 0)}%saved")
+
+        t2 = metrics.get("tier2_router")
+        if t2 and "total_routes" in t2:
+            parts.append(f"router:{t2['total_routes']}routes,{t2.get('avg_latency_ms', 0)}ms")
+
+        t3 = metrics.get("tier3_sltm")
+        if t3 and "total_records" in t3:
+            vec = "on" if t3.get("vector_enabled") else "off"
+            parts.append(f"sltm:{t3['total_records']}rec,vec={vec}")
+
+        # Precision metric: ratio of precision tools
+        p = metrics.get("precision", {})
+        total_calls = p.get("tool_call", 0)
+        if total_calls > 0:
+            # This is just a count of tool_call events, not tool names yet.
+            # To be truly useful, we'd need to parse the log for 'c3_' prefixes.
+            pass
+
+        return " | ".join(parts) if parts else "no hybrid services active"

services/notifications.py

@@ -0,0 +1,209 @@
+"""NotificationStore — Thread-safe notification queue for background agents.
+
+Persists to .c3/notifications.jsonl. Supports dedup, severity filtering,
+and auto-acknowledgement when surfaced to Claude via tool responses.
+"""
+import hashlib
+import json
+import threading
+import uuid
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+# How long to suppress a repeated agent+title after it has been acknowledged.
+_COOLDOWN_MINUTES = {"critical": 5, "warning": 30, "info": 60}
+
+
+class NotificationStore:
+    """Thread-safe JSONL notification store for background agents."""
+
+    def __init__(self, project_path: str):
+        self._file = Path(project_path) / ".c3" / "notifications.jsonl"
+        self._file.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+
+    def add(self, agent: str, severity: str, title: str, message: str,
+            ai_enhanced: bool = False, replace_if_unacked: bool = False) -> dict | None:
+        """Append a notification. Dedup: skip if same agent+title+message already unacknowledged.
+
+        severity: 'info', 'warning', 'critical'
+        replace_if_unacked: if True and an unacked notification with the same agent+title
+            already exists, update its message in-place instead of appending a new entry.
+            Use for high-frequency agents (budget, index) to prevent pile-up.
+        Returns the entry if written/updated, None if deduped.
+        """
+        with self._lock:
+            message_hash = hashlib.md5((message or "").encode("utf-8")).hexdigest()[:12]
+            cooldown = timedelta(minutes=_COOLDOWN_MINUTES.get(severity, 30))
+            now = datetime.now(timezone.utc)
+            entries = self._read_all()
+            for existing in entries:
+                if existing.get("agent") != agent or existing.get("title") != title:
+                    continue
+                if not existing.get("acknowledged"):
+                    if replace_if_unacked:
+                        # Update in-place — prevents repeated pile-up for chatty agents
+                        existing["message"] = message
+                        existing["message_hash"] = message_hash
+                        existing["timestamp"] = now.isoformat()
+                        existing["ai_enhanced"] = ai_enhanced
+                        self._write_all(entries)
+                        return existing
+                    # Same notification still pending — dedup if message matches
+                    if existing.get("message_hash") == message_hash:
+                        return None
+                else:
+                    # Already acknowledged — suppress if within cooldown window
+                    try:
+                        acked_at = datetime.fromisoformat(existing["timestamp"])
+                        if acked_at.tzinfo is None:
+                            acked_at = acked_at.replace(tzinfo=timezone.utc)
+                        if now - acked_at < cooldown:
+                            return None
+                    except (KeyError, ValueError):
+                        pass
+
+            entry = {
+                "id": uuid.uuid4().hex[:12],
+                "agent": agent,
+                "severity": severity,
+                "title": title,
+                "message": message,
+                "message_hash": message_hash,
+                "timestamp": now.isoformat(),
+                "acknowledged": False,
+                "ai_enhanced": ai_enhanced,
+            }
+            with open(self._file, "a", encoding="utf-8") as f:
+                f.write(json.dumps(entry) + "\n")
+            return entry
+
+    def get_pending_count(self) -> int:
+        """Return count of unacknowledged warning/critical notifications without consuming them."""
+        with self._lock:
+            return sum(
+                1 for e in self._read_all()
+                if not e.get("acknowledged")
+                and e.get("severity") in ("warning", "critical")
+            )
+
+    # Default filter: only notifications a human should act on.
+    # Info-level entries are archival; they show up in get_history(), not here.
+    _ACTIONABLE = ("warning", "critical")
+
+    def get_unacknowledged(self, limit: int = 5, severities=None) -> list:
+        """Return unacknowledged notifications, newest first.
+
+        severities: tuple of severities to include. Defaults to actionable
+            ('warning', 'critical') so auto-chatter 'info' events don't
+            drown real signals. Pass severities=() or ('info','warning','critical')
+            to include info events (e.g. for an activity log view).
+        """
+        if severities is None:
+            severities = self._ACTIONABLE
+        with self._lock:
+            entries = [
+                e for e in self._read_all()
+                if not e.get("acknowledged")
+                and (not severities or e.get("severity") in severities)
+            ]
+            entries.sort(key=lambda e: e.get("timestamp", ""), reverse=True)
+            return entries[:limit]
+
+    def get_suppressed_info_count(self) -> int:
+        """Count of unacknowledged 'info' notifications not shown in actionable view."""
+        with self._lock:
+            return sum(
+                1 for e in self._read_all()
+                if not e.get("acknowledged") and e.get("severity") == "info"
+            )
+
+    def get_history(self, limit: int = 50) -> list:
+        """Return all notifications (including acknowledged) for the activity console, newest first."""
+        with self._lock:
+            entries = self._read_all()
+            entries.sort(key=lambda e: e.get("timestamp", ""), reverse=True)
+            return entries[:limit]
+
+    def acknowledge(self, notification_id: str) -> bool:
+        """Mark a single notification as acknowledged."""
+        with self._lock:
+            return self._set_ack(lambda e: e.get("id") == notification_id)
+
+    def acknowledge_all(self) -> int:
+        """Mark all unacknowledged notifications as acknowledged. Returns count."""
+        with self._lock:
+            entries = self._read_all()
+            count = 0
+            for e in entries:
+                if not e.get("acknowledged"):
+                    e["acknowledged"] = True
+                    count += 1
+            if count:
+                self._write_all(entries)
+            return count
+
+    def get_pending_summary(self) -> str:
+        """Format up to 3 unacked warning/critical notifications for prepending.
+
+        Auto-acknowledges those included. Returns empty string if none.
+        """
+        with self._lock:
+            entries = self._read_all()
+            pending = [
+                e for e in entries
+                if not e.get("acknowledged")
+                and e.get("severity") in ("warning", "critical")
+            ]
+            # Newest first
+            pending.sort(key=lambda e: e.get("timestamp", ""), reverse=True)
+            pending = pending[:3]
+
+            if not pending:
+                return ""
+
+            # Auto-acknowledge
+            pending_ids = {e["id"] for e in pending}
+            for e in entries:
+                if e.get("id") in pending_ids:
+                    e["acknowledged"] = True
+            self._write_all(entries)
+
+            # Format
+            lines = ["[c3:agents]"]
+            for e in pending:
+                prefix = "!!" if e["severity"] == "critical" else "!"
+                lines.append(f"{prefix} {e['agent']}: {e['title']} — {e['message']}")
+            return "\n".join(lines)
+
+    def _read_all(self) -> list:
+        """Read all entries from JSONL file. Caller must hold _lock."""
+        if not self._file.exists():
+            return []
+        entries = []
+        for line in self._file.read_text(encoding="utf-8").strip().splitlines():
+            if not line.strip():
+                continue
+            try:
+                entries.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+        return entries
+
+    def _write_all(self, entries: list):
+        """Rewrite entire file. Caller must hold _lock."""
+        with open(self._file, "w", encoding="utf-8") as f:
+            for e in entries:
+                f.write(json.dumps(e) + "\n")
+
+    def _set_ack(self, predicate) -> bool:
+        """Acknowledge entries matching predicate. Caller must hold _lock."""
+        entries = self._read_all()
+        found = False
+        for e in entries:
+            if not e.get("acknowledged") and predicate(e):
+                e["acknowledged"] = True
+                found = True
+        if found:
+            self._write_all(entries)
+        return found