contextsynapse 1.0.0__py3-none-any.whl

contextsynapse/security/tenant.py

@@ -0,0 +1,401 @@
+"""TenantIsolation — ensures data separation between AMCs/organizations.
+
+Every resource belongs to a tenant. Users can only access resources
+within their tenant. Cross-tenant access is never allowed (even for admins).
+
+In dev mode: a single default tenant is used.
+In production: tenant is extracted from JWT and enforced on every query.
+
+Namespace isolation (legacy):
+    ti = TenantIsolation()
+    ns = ti.namespace("alpha_capital", "portfolio_growth")
+    # -> "alpha_capital_portfolio_growth"
+
+    ti.validate_access("alpha_capital", ns)  # True
+    ti.validate_access("beta_wealth", ns)    # False
+    ti.validate_access("anyone", "market_nifty50")  # True (shared)
+
+Tenant management (new — PostgreSQL-backed):
+    tm = TenantManager()
+    tenant = tm.create_tenant("Alpha Capital", "alpha-capital", plan="pro")
+    tm.get_tenant(tenant["id"])
+    tm.suspend_tenant(tenant["id"], reason="Non-payment")
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Set
+
+from fastapi import HTTPException, Request
+
+logger = logging.getLogger(__name__)
+
+
+# ── Shared namespace prefixes (platform-level data) ──────────────────────────
+# Namespace prefixes that are shared across all tenants
+SHARED_PREFIXES: List[str] = [
+    "market_",
+    "stock_",
+    "macro_",
+    "regulatory_",
+    "fund_nav_",
+    "sector_",
+    "index_",
+    "currency_",
+    "fii_",
+]
+
+# Known tenant IDs (populated at runtime)
+_known_tenants: Set[str] = set()
+
+# Default tenant for dev mode
+DEFAULT_TENANT_SLUG = "dev"
+DEFAULT_TENANT_NAME = "Development"
+
+
+# ── Namespace isolation (legacy, kept for backward compat) ───────────────────
+
+class TenantIsolation:
+    """Enforces tenant-scoped namespace isolation."""
+
+    def __init__(self):
+        self._known_tenants: Set[str] = set()
+
+    def namespace(self, tenant_id: str, resource: str) -> str:
+        """Create a tenant-scoped namespace."""
+        safe_tenant = re.sub(r'[^a-zA-Z0-9_]', '_', tenant_id)
+        safe_resource = re.sub(r'[^a-zA-Z0-9_]', '_', resource)
+        self._known_tenants.add(safe_tenant)
+        return f"{safe_tenant}_{safe_resource}"
+
+    def is_shared(self, namespace: str) -> bool:
+        """Check if a namespace is shared (platform-level market data)."""
+        return any(namespace.startswith(prefix) for prefix in SHARED_PREFIXES)
+
+    def extract_tenant(self, namespace: str) -> Optional[str]:
+        """Extract tenant ID from a namespaced string."""
+        if self.is_shared(namespace):
+            return None
+
+        # Try to match against known tenants
+        for tenant in self._known_tenants:
+            if namespace.startswith(f"{tenant}_"):
+                return tenant
+
+        return None
+
+    def validate_access(
+        self, tenant_id: str, namespace: str
+    ) -> bool:
+        """Check if a tenant can access a namespace."""
+        # Shared namespaces accessible to all
+        if self.is_shared(namespace):
+            return True
+
+        # Tenant can access their own namespaces
+        safe_tenant = re.sub(r'[^a-zA-Z0-9_]', '_', tenant_id)
+        return namespace.startswith(f"{safe_tenant}_")
+
+
+# ── Tenant Manager (PostgreSQL-backed) ───────────────────────────────────────
+
+class TenantManager:
+    """Manages tenants in the database (PostgreSQL or SQLite).
+
+    Uses contextsynapse.core.db for database access, so it works with both
+    backends seamlessly.
+    """
+
+    _DDL_PG = """
+    CREATE TABLE IF NOT EXISTS tenants (
+        id          TEXT PRIMARY KEY,
+        name        TEXT NOT NULL,
+        slug        TEXT NOT NULL UNIQUE,
+        plan        TEXT NOT NULL DEFAULT 'free',
+        settings    TEXT NOT NULL DEFAULT '{}',
+        is_active   BOOLEAN NOT NULL DEFAULT TRUE,
+        suspended   BOOLEAN NOT NULL DEFAULT FALSE,
+        suspend_reason TEXT,
+        created_at  TIMESTAMP NOT NULL DEFAULT NOW(),
+        updated_at  TIMESTAMP NOT NULL DEFAULT NOW()
+    );
+    CREATE INDEX IF NOT EXISTS idx_tenants_slug ON tenants(slug);
+    CREATE INDEX IF NOT EXISTS idx_tenants_active ON tenants(is_active);
+    """
+
+    _DDL_SQLITE = """
+    CREATE TABLE IF NOT EXISTS tenants (
+        id          TEXT PRIMARY KEY,
+        name        TEXT NOT NULL,
+        slug        TEXT NOT NULL UNIQUE,
+        plan        TEXT NOT NULL DEFAULT 'free',
+        settings    TEXT NOT NULL DEFAULT '{}',
+        is_active   INTEGER NOT NULL DEFAULT 1,
+        suspended   INTEGER NOT NULL DEFAULT 0,
+        suspend_reason TEXT,
+        created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_tenants_slug ON tenants(slug);
+    CREATE INDEX IF NOT EXISTS idx_tenants_active ON tenants(is_active);
+    """
+
+    def __init__(self):
+        from ..core.db import IS_POSTGRES
+        self._is_pg = IS_POSTGRES
+        self._ensure_table()
+
+    def _ensure_table(self):
+        """Create tenants table if it doesn't exist."""
+        from ..core.db import transaction, run_ddl, IS_POSTGRES
+        try:
+            with transaction() as (conn, _cur):
+                ddl = self._DDL_PG if IS_POSTGRES else self._DDL_SQLITE
+                run_ddl(conn, ddl)
+        except Exception as exc:
+            logger.warning("Could not create tenants table: %s", exc)
+
+    # ── CRUD ─────────────────────────────────────────────────────────────────
+
+    def create_tenant(
+        self,
+        name: str,
+        slug: str,
+        plan: str = "free",
+        settings: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Create a new tenant. Returns the tenant dict."""
+        import json
+        from ..core.db import transaction, PH, integrity_error
+
+        tenant_id = str(uuid.uuid4())
+        now = datetime.now(timezone.utc).isoformat()
+        settings_json = json.dumps(settings or {})
+
+        try:
+            with transaction() as (conn, cur):
+                cur.execute(
+                    f"INSERT INTO tenants (id, name, slug, plan, settings, created_at, updated_at) "
+                    f"VALUES ({PH}, {PH}, {PH}, {PH}, {PH}, {PH}, {PH})",
+                    (tenant_id, name, slug, plan, settings_json, now, now),
+                )
+        except integrity_error():
+            raise ValueError(f"Tenant with slug '{slug}' already exists")
+
+        return {
+            "id": tenant_id,
+            "name": name,
+            "slug": slug,
+            "plan": plan,
+            "settings": settings or {},
+            "is_active": True,
+            "suspended": False,
+            "suspend_reason": None,
+            "created_at": now,
+            "updated_at": now,
+        }
+
+    def get_tenant(self, tenant_id: str) -> Optional[Dict[str, Any]]:
+        """Get a tenant by ID."""
+        from ..core.db import transaction, PH, row_to_dict
+        with transaction() as (_conn, cur):
+            cur.execute(
+                f"SELECT * FROM tenants WHERE id = {PH}", (tenant_id,)
+            )
+            row = cur.fetchone()
+            return self._parse_row(row_to_dict(row))
+
+    def get_tenant_by_slug(self, slug: str) -> Optional[Dict[str, Any]]:
+        """Get a tenant by slug."""
+        from ..core.db import transaction, PH, row_to_dict
+        with transaction() as (_conn, cur):
+            cur.execute(
+                f"SELECT * FROM tenants WHERE slug = {PH}", (slug,)
+            )
+            row = cur.fetchone()
+            return self._parse_row(row_to_dict(row))
+
+    def list_tenants(self) -> List[Dict[str, Any]]:
+        """List all tenants."""
+        from ..core.db import transaction, row_to_dict
+        with transaction() as (_conn, cur):
+            cur.execute("SELECT * FROM tenants ORDER BY created_at")
+            rows = cur.fetchall()
+            return [
+                self._parse_row(row_to_dict(r))
+                for r in rows
+                if row_to_dict(r) is not None
+            ]
+
+    def update_tenant(self, tenant_id: str, **updates) -> Optional[Dict[str, Any]]:
+        """Update tenant fields. Allowed: name, plan, settings, is_active."""
+        import json
+        from ..core.db import transaction, PH
+
+        allowed = {"name", "plan", "settings", "is_active"}
+        filtered = {k: v for k, v in updates.items() if k in allowed}
+        if not filtered:
+            return self.get_tenant(tenant_id)
+
+        # Serialize settings to JSON if present
+        if "settings" in filtered and isinstance(filtered["settings"], dict):
+            filtered["settings"] = json.dumps(filtered["settings"])
+
+        now = datetime.now(timezone.utc).isoformat()
+        filtered["updated_at"] = now
+
+        set_clauses = ", ".join(f"{k} = {PH}" for k in filtered)
+        values = list(filtered.values()) + [tenant_id]
+
+        with transaction() as (_conn, cur):
+            cur.execute(
+                f"UPDATE tenants SET {set_clauses} WHERE id = {PH}",
+                tuple(values),
+            )
+
+        return self.get_tenant(tenant_id)
+
+    def suspend_tenant(self, tenant_id: str, reason: str = "") -> Optional[Dict[str, Any]]:
+        """Suspend a tenant (block all access)."""
+        from ..core.db import transaction, PH
+
+        now = datetime.now(timezone.utc).isoformat()
+        with transaction() as (_conn, cur):
+            cur.execute(
+                f"UPDATE tenants SET suspended = {PH}, suspend_reason = {PH}, "
+                f"updated_at = {PH} WHERE id = {PH}",
+                (True if self._is_pg else 1, reason, now, tenant_id),
+            )
+
+        logger.warning("Tenant %s suspended: %s", tenant_id, reason)
+        return self.get_tenant(tenant_id)
+
+    def get_or_create_default(self) -> Dict[str, Any]:
+        """Get or create the default 'dev' tenant (for development mode)."""
+        existing = self.get_tenant_by_slug(DEFAULT_TENANT_SLUG)
+        if existing:
+            return existing
+
+        return self.create_tenant(
+            name=DEFAULT_TENANT_NAME,
+            slug=DEFAULT_TENANT_SLUG,
+            plan="free",
+        )
+
+    # ── Middleware helper ────────────────────────────────────────────────────
+
+    def ensure_tenant_context(self, tenant_id: str) -> Dict[str, Any]:
+        """Validate that the tenant exists and is active. Returns tenant dict.
+
+        Raises HTTPException if tenant is not found or suspended.
+        Called by middleware to set the current tenant on the request.
+        """
+        tenant = self.get_tenant(tenant_id)
+        if not tenant:
+            raise HTTPException(status_code=404, detail="Tenant not found")
+        if tenant.get("suspended"):
+            raise HTTPException(
+                status_code=403,
+                detail=f"Tenant suspended: {tenant.get('suspend_reason', 'Contact support')}",
+            )
+        if not tenant.get("is_active"):
+            raise HTTPException(status_code=403, detail="Tenant is inactive")
+        return tenant
+
+    # ── Internal helpers ─────────────────────────────────────────────────────
+
+    @staticmethod
+    def _parse_row(row: Optional[Dict]) -> Optional[Dict[str, Any]]:
+        """Parse a raw DB row into a clean tenant dict."""
+        if row is None:
+            return None
+        import json
+        result = dict(row)
+        # Parse settings JSON
+        if isinstance(result.get("settings"), str):
+            try:
+                result["settings"] = json.loads(result["settings"])
+            except (json.JSONDecodeError, TypeError):
+                result["settings"] = {}
+        # Normalize booleans (SQLite stores as 0/1)
+        for key in ("is_active", "suspended"):
+            if key in result:
+                result[key] = bool(result[key])
+        return result
+
+
+# ── Tenant middleware ────────────────────────────────────────────────────────
+
+_tenant_manager: Optional[TenantManager] = None
+
+
+def _get_tenant_manager() -> TenantManager:
+    """Lazy singleton for TenantManager."""
+    global _tenant_manager
+    if _tenant_manager is None:
+        _tenant_manager = TenantManager()
+    return _tenant_manager
+
+
+def _is_production() -> bool:
+    return os.environ.get("CONTEXTSYNAPSE_ENV") or os.environ.get("AICONTEXTDB_ENV", "").lower() == "production"
+
+
+async def tenant_middleware(request: Request, call_next):
+    """Extract tenant from JWT and set on request state.
+
+    In dev mode: use default tenant.
+    In production: extract from JWT, validate tenant is active.
+    """
+    # Skip tenant check for health/docs endpoints
+    path = request.url.path
+    if path in ("/health", "/docs", "/openapi.json", "/redoc"):
+        response = await call_next(request)
+        return response
+
+    tm = _get_tenant_manager()
+
+    if not _is_production():
+        # Dev mode: use default tenant
+        default = tm.get_or_create_default()
+        request.state.tenant_id = default["id"]
+        request.state.tenant = default
+        response = await call_next(request)
+        return response
+
+    # Production: extract tenant from JWT claims (set by auth middleware)
+    tenant_id = None
+
+    # Check if auth middleware already set the tenant
+    if hasattr(request.state, "tenant_id") and request.state.tenant_id:
+        tenant_id = request.state.tenant_id
+    else:
+        # Try extracting from Authorization header JWT
+        auth_header = request.headers.get("Authorization", "")
+        if auth_header.startswith("Bearer "):
+            token = auth_header[7:]
+            try:
+                from ..api.auth import verify_jwt
+                payload = verify_jwt(token)
+                if payload:
+                    tenant_id = payload.get("tenant") or payload.get("tenant_id")
+            except Exception:
+                pass
+
+    if not tenant_id:
+        raise HTTPException(
+            status_code=401,
+            detail="Tenant context required. Include tenant in JWT.",
+        )
+
+    # Validate tenant is active and not suspended
+    tenant = tm.ensure_tenant_context(tenant_id)
+    request.state.tenant_id = tenant_id
+    request.state.tenant = tenant
+
+    response = await call_next(request)
+    return response

contextsynapse/shield/__init__.py

@@ -0,0 +1,21 @@
+"""AgentShield — continuous behavioral auth + adaptive trust."""
+from __future__ import annotations
+
+_shield = None
+
+def get_agent_shield():
+    global _shield
+    if _shield is None:
+        redis_client = None
+        try:
+            import os, redis
+            url = os.environ.get("CONTEXTSYNAPSE_REDIS_URL") or os.environ.get("AICONTEXTDB_REDIS_URL")
+            if url:
+                redis_client = redis.from_url(url)
+        except Exception:
+            pass
+        from .shield import AgentShield
+        _shield = AgentShield(redis_client=redis_client)
+    return _shield
+
+__all__ = ["get_agent_shield"]

contextsynapse/shield/anomaly.py

@@ -0,0 +1,56 @@
+"""AnomalyDetector — statistical anomaly detection for agent behavior."""
+from __future__ import annotations
+import json, math
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+@dataclass
+class AnomalyResult:
+    score: float = 0.0
+    flags: List[str] = field(default_factory=list)
+    details: Dict[str, Any] = field(default_factory=dict)
+    frozen: bool = False
+
+class AnomalyDetector:
+    MIN_TOOL_CALLS = 20
+    MIN_SESSIONS = 2
+
+    def analyze(self, profile: Dict, session: Dict) -> AnomalyResult:
+        if profile.get("total_tool_calls", 0) < self.MIN_TOOL_CALLS:
+            return AnomalyResult()
+        if profile.get("sessions_count", 0) < self.MIN_SESSIONS:
+            return AnomalyResult()
+        flags = []
+        details = {}
+        hist_dist = json.loads(profile.get("tool_distribution", "{}"))
+        sess_dist = json.loads(session.get("tool_distribution", "{}"))
+        if hist_dist and sess_dist:
+            divergence = self._cosine_distance(hist_dist, sess_dist)
+            if divergence > 0.6:
+                flags.append("tool_pattern_change")
+                details["tool_divergence"] = round(divergence, 3)
+        hist_quality = profile.get("feedback_quality", 0.5)
+        sess_quality = session.get("feedback_quality")
+        if sess_quality is not None and profile.get("total_feedback_given", 0) > 10:
+            if sess_quality < hist_quality - 0.3:
+                flags.append("quality_drop")
+                details["quality_delta"] = round(sess_quality - hist_quality, 3)
+        hist_ratio = profile.get("read_write_ratio", 0.5)
+        sess_ratio = session.get("read_write_ratio")
+        if sess_ratio is not None:
+            if abs(sess_ratio - hist_ratio) > 0.4:
+                flags.append("unusual_read_scope")
+                details["ratio_delta"] = round(sess_ratio - hist_ratio, 3)
+        weights = {"tool_pattern_change": 0.35, "quality_drop": 0.30, "unusual_read_scope": 0.20}
+        score = min(sum(weights.get(f, 0.15) for f in flags), 1.0)
+        return AnomalyResult(score=round(score, 3), flags=flags, details=details, frozen=score >= 0.7)
+
+    @staticmethod
+    def _cosine_distance(a: Dict[str, int], b: Dict[str, int]) -> float:
+        all_keys = set(a) | set(b)
+        if not all_keys:
+            return 0.0
+        dot = sum(a.get(k, 0) * b.get(k, 0) for k in all_keys)
+        mag_a = math.sqrt(sum(v ** 2 for v in a.values())) or 1.0
+        mag_b = math.sqrt(sum(v ** 2 for v in b.values())) or 1.0
+        return round(1.0 - dot / (mag_a * mag_b), 4)

contextsynapse/shield/permissions.py

@@ -0,0 +1,99 @@
+"""AdaptivePermissions — map trust levels to tool access tiers."""
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Dict, Set
+
+TIER_READ = {
+    "search_nodes", "get_context", "orient", "briefing", "ask", "recall",
+    "graph_summary", "query_graph", "rag_query", "rag_graph", "graph_timeline",
+    "graph_diff", "check_freshness", "get_suggestions", "project_status",
+    "list_tasks", "my_tasks", "get_agent_context", "get_unblocked_tasks",
+    "task_context", "ws_read_file", "ws_list_files", "ws_git_status",
+    "a2a_discover", "a2a_get_task", "my_usage", "boundary_costs", "get_tool_policy",
+    "explain_context", "topic_scan", "check_reviews", "trace_lineage",
+    "search", "code_project_status", "list_pipelines", "list_schemas",
+    "get_versions", "get_context_meta",
+}
+
+TIER_WRITE = TIER_READ | {
+    "add_knowledge", "add_relationship", "add_decision", "add_task",
+    "claim_task", "complete_task", "handoff_task", "log_action",
+    "remember", "rate_context", "detect_conflicts", "resolve_conflict",
+    "report_external", "report_tokens", "a2a_send_task", "a2a_cancel_task",
+    "invalidate_node", "request_review", "request_promotion",
+}
+
+TIER_FULL = TIER_WRITE | {
+    "dispatch_goal", "generate_tasks",
+    "ws_write_file", "ws_commit", "ws_push", "ws_create_branch", "ws_run_command",
+    "use_graph", "save_schema", "run_pipeline",
+}
+
+@dataclass
+class PermissionDecision:
+    allowed: bool
+    reason: str = ""
+
+class AdaptivePermissions:
+    def __init__(self):
+        self._frozen: Set[str] = set()
+        self._active: Dict[str, str] = {}  # agent_id -> task_id (mid-workflow)
+        self._pending_restrictions: Dict[str, str] = {}  # agent_id -> reason (apply after task)
+
+    def check(self, agent_id: str, tool_name: str, trust_score: float = 0.5) -> PermissionDecision:
+        # Grace period: if agent is mid-task, allow but warn
+        if agent_id in self._active:
+            is_restricted = (agent_id in self._frozen) or (trust_score < 0.2 and tool_name not in TIER_READ)
+            if is_restricted:
+                reason = "frozen" if agent_id in self._frozen else f"low trust ({trust_score:.2f})"
+                self._pending_restrictions[agent_id] = reason
+                return PermissionDecision(True, f"WARNING: {reason} — restrictions apply after current task completes")
+            # Normal permission check for active agents
+            return self._check_tier(agent_id, tool_name, trust_score)
+
+        # Not active — enforce restrictions immediately
+        # But first check if there's a pending restriction from a completed task
+        if agent_id in self._pending_restrictions:
+            if tool_name == "claim_task":
+                # Block new task claims — restrictions are now active
+                reason = self._pending_restrictions.pop(agent_id)
+                return PermissionDecision(False, f"Restricted: {reason}")
+
+        return self._check_tier(agent_id, tool_name, trust_score)
+
+    def _check_tier(self, agent_id: str, tool_name: str, trust_score: float) -> PermissionDecision:
+        if agent_id in self._frozen:
+            if tool_name in TIER_READ:
+                return PermissionDecision(True, "read-only (frozen)")
+            return PermissionDecision(False, "Agent frozen — anomaly detected")
+        if trust_score >= 0.8:
+            return PermissionDecision(True, "trusted")
+        if trust_score >= 0.5:
+            if tool_name in TIER_FULL:
+                return PermissionDecision(True, "verified")
+            return PermissionDecision(False, f"Requires trust >= 0.8 (current: {trust_score:.2f})")
+        if trust_score >= 0.2:
+            if tool_name in TIER_WRITE:
+                return PermissionDecision(True, "provisional")
+            return PermissionDecision(False, f"Requires trust >= 0.5 (current: {trust_score:.2f})")
+        if tool_name in TIER_READ:
+            return PermissionDecision(True, "untrusted: read-only")
+        return PermissionDecision(False, "Untrusted agent: read-only access")
+
+    def mark_active(self, agent_id: str, task_id: str):
+        """Mark agent as mid-workflow (won't be blocked until task completes)."""
+        self._active[agent_id] = task_id
+
+    def mark_idle(self, agent_id: str):
+        """Mark agent as idle (restrictions now enforced)."""
+        self._active.pop(agent_id, None)
+
+    def freeze(self, agent_id: str):
+        self._frozen.add(agent_id)
+
+    def unfreeze(self, agent_id: str):
+        self._frozen.discard(agent_id)
+        self._pending_restrictions.pop(agent_id, None)
+
+    def is_frozen(self, agent_id: str) -> bool:
+        return agent_id in self._frozen

contextsynapse/shield/profile.py

@@ -0,0 +1,103 @@
+"""AgentProfile — behavioral fingerprint per agent."""
+from __future__ import annotations
+import json, logging
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_PROFILE = {
+    "total_reads": 0, "total_writes": 0, "total_tool_calls": 0,
+    "total_feedback_given": 0, "total_derivations": 0,
+    "feedback_useful": 0, "feedback_misleading": 0, "feedback_incorrect": 0, "feedback_outdated": 0,
+    "invalidations_caused": 0, "read_write_ratio": 0.5, "feedback_quality": 0.5,
+    "tool_distribution": "{}", "hour_distribution": "{}",
+    "sessions_count": 0, "consecutive_clean": 0,
+}
+
+class AgentProfile:
+    def __init__(self, redis_client=None):
+        self._redis = redis_client
+        self._memory: Dict[str, Dict[str, Any]] = {}
+        self._prefix = "contextcore:shield:profile"
+
+    def get(self, agent_id: str) -> Dict[str, Any]:
+        if self._redis:
+            try:
+                key = f"{self._prefix}:{agent_id}"
+                raw = self._redis.hgetall(key)
+                if raw:
+                    data = dict(_DEFAULT_PROFILE)
+                    for k, v in raw.items():
+                        k = k.decode() if isinstance(k, bytes) else k
+                        v = v.decode() if isinstance(v, bytes) else v
+                        if k in data and isinstance(data[k], (int, float)):
+                            data[k] = type(data[k])(v)
+                        else:
+                            data[k] = v
+                    return data
+            except Exception:
+                pass
+        return dict(self._memory.get(agent_id, _DEFAULT_PROFILE))
+
+    def record_event(self, agent_id: str, event_type: str):
+        d = self._ensure(agent_id)
+        if event_type == "read":
+            d["total_reads"] += 1
+        elif event_type in ("write", "derive"):
+            d["total_writes"] += 1
+            if event_type == "derive":
+                d["total_derivations"] += 1
+        total = d["total_reads"] + d["total_writes"]
+        d["read_write_ratio"] = round(d["total_reads"] / total, 3) if total > 0 else 0.5
+        self._save(agent_id, d)
+
+    def record_tool_call(self, agent_id: str, tool_name: str):
+        d = self._ensure(agent_id)
+        d["total_tool_calls"] += 1
+        dist = json.loads(d["tool_distribution"])
+        dist[tool_name] = dist.get(tool_name, 0) + 1
+        d["tool_distribution"] = json.dumps(dist)
+        hour = str(datetime.now(timezone.utc).hour)
+        hours = json.loads(d["hour_distribution"])
+        hours[hour] = hours.get(hour, 0) + 1
+        d["hour_distribution"] = json.dumps(hours)
+        self._save(agent_id, d)
+
+    def record_feedback(self, agent_id: str, signal: str):
+        d = self._ensure(agent_id)
+        d["total_feedback_given"] += 1
+        key = f"feedback_{signal}"
+        if key in d:
+            d[key] += 1
+        good = d["feedback_useful"]
+        bad = d["feedback_misleading"] + d["feedback_incorrect"] + d["feedback_outdated"]
+        total = good + bad
+        d["feedback_quality"] = round(good / total, 3) if total > 0 else 0.5
+        if signal in ("misleading", "incorrect"):
+            d["consecutive_clean"] = 0
+        self._save(agent_id, d)
+
+    def record_invalidation(self, agent_id: str, count: int = 1):
+        d = self._ensure(agent_id)
+        d["invalidations_caused"] += count
+        d["consecutive_clean"] = 0
+        self._save(agent_id, d)
+
+    def increment_clean(self, agent_id: str):
+        d = self._ensure(agent_id)
+        d["consecutive_clean"] += 1
+        self._save(agent_id, d)
+
+    def _ensure(self, agent_id: str) -> Dict[str, Any]:
+        if agent_id not in self._memory:
+            self._memory[agent_id] = dict(_DEFAULT_PROFILE)
+        return self._memory[agent_id]
+
+    def _save(self, agent_id: str, data: Dict):
+        self._memory[agent_id] = data
+        if self._redis:
+            try:
+                self._redis.hset(f"{self._prefix}:{agent_id}", mapping={k: str(v) for k, v in data.items()})
+            except Exception:
+                pass