superlocalmemory 3.4.10 → 3.4.12

package/src/superlocalmemory/evolution/__init__.py

@@ -0,0 +1,29 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Skill Evolution Engine — track, analyze, and evolve AI agent skills.
+
+3-trigger system (post-session + degradation + health check) with
+LLM confirmation gate and blind verification.
+
+Inspired by: HKUDS/OpenSpace (arXiv:2604.01687), ECC continuous learning.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from superlocalmemory.evolution.types import (
+    EvolutionCandidate,
+    EvolutionRecord,
+    EvolutionType,
+    TriggerType,
+    EvolutionStatus,
+)
+
+__all__ = [
+    "EvolutionCandidate",
+    "EvolutionRecord",
+    "EvolutionType",
+    "TriggerType",
+    "EvolutionStatus",
+]

package/src/superlocalmemory/evolution/blind_verifier.py

@@ -0,0 +1,115 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Blind Verifier — information-isolated skill verification.
+
+The key insight from EvoSkills (arXiv:2604.01687): when a generator
+creates a skill and the same model verifies it, confirmation bias is
+nearly guaranteed. The verifier must be BLIND to the generator's reasoning.
+
+This verifier:
+- Uses a DIFFERENT model from the generator (Haiku vs Sonnet)
+- CANNOT see: original skill, mutation rationale, generator's reasoning
+- CAN see: task description (what the skill should do), evolved SKILL.md
+- Evaluates independently: "Does this skill correctly address the task?"
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class VerificationResult:
+    """Result of blind verification."""
+    passed: bool
+    confidence: float  # 0.0-1.0
+    issues: tuple[str, ...] = ()
+    reasoning: str = ""
+
+
+def build_verification_prompt(
+    skill_name: str,
+    skill_description: str,
+    evolved_content: str,
+) -> str:
+    """Build blind verification prompt.
+
+    The verifier sees ONLY:
+    - What the skill is supposed to do (name + description)
+    - The evolved skill content
+
+    The verifier does NOT see:
+    - The original skill
+    - Why it was evolved
+    - What evidence triggered evolution
+    - The generator's reasoning
+    """
+    return f"""You are an independent skill quality reviewer. You have NOT seen the original
+version of this skill or why it was modified. Evaluate it purely on its merits.
+
+SKILL PURPOSE: {skill_name}
+EXPECTED BEHAVIOR: {skill_description}
+
+SKILL CONTENT TO REVIEW:
+{evolved_content[:8000]}
+
+EVALUATE:
+1. Does the skill clearly explain what to do? (clarity)
+2. Are the instructions specific and actionable? (specificity)
+3. Are there any obvious errors, contradictions, or missing steps? (correctness)
+4. Would an AI agent be able to follow these instructions? (executability)
+
+RESPOND IN JSON FORMAT:
+{{
+  "passed": true/false,
+  "confidence": 0.0-1.0,
+  "issues": ["issue1", "issue2"],
+  "reasoning": "brief explanation"
+}}
+
+Be strict. Only pass skills that are genuinely clear, correct, and actionable.
+A mediocre skill that might work sometimes should FAIL — evolution should produce
+clear improvements, not marginal changes."""
+
+
+def parse_verification_response(response: str) -> VerificationResult:
+    """Parse the verifier's JSON response."""
+    # Try parsing JSON from response
+    json_match = re.search(r"\{[^{}]*\"passed\"[^{}]*\}", response, re.DOTALL)
+    if json_match:
+        try:
+            data = json.loads(json_match.group(0))
+            return VerificationResult(
+                passed=bool(data.get("passed", False)),
+                confidence=float(data.get("confidence", 0.5)),
+                issues=tuple(data.get("issues", [])),
+                reasoning=str(data.get("reasoning", "")),
+            )
+        except (json.JSONDecodeError, TypeError, ValueError):
+            pass
+
+    # Fallback: keyword detection
+    lower = response.lower()
+    if any(kw in lower for kw in ("\"passed\": true", "passed: true", "approve", "looks good")):
+        return VerificationResult(passed=True, confidence=0.6, reasoning="keyword match")
+
+    if any(kw in lower for kw in ("\"passed\": false", "passed: false", "reject", "fail")):
+        return VerificationResult(passed=False, confidence=0.6, reasoning="keyword match")
+
+    # Default: reject if can't parse (conservative)
+    return VerificationResult(
+        passed=False,
+        confidence=0.3,
+        reasoning="Could not parse verification response",
+        issues=("Unparseable response",),
+    )

package/src/superlocalmemory/evolution/evolution_store.py

@@ -0,0 +1,302 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Evolution Store — SQLite persistence for skill evolution history.
+
+Stores evolution records, lineage DAG, and anti-loop state.
+Uses the same memory.db as the rest of SLM — no separate database.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from superlocalmemory.evolution.types import (
+    EvolutionCandidate,
+    EvolutionRecord,
+    EvolutionStatus,
+    EvolutionType,
+    TriggerType,
+)
+
+logger = logging.getLogger(__name__)
+
+_SCHEMA_DDL = """
+CREATE TABLE IF NOT EXISTS skill_evolution_log (
+    id TEXT PRIMARY KEY,
+    skill_name TEXT NOT NULL,
+    parent_skill_id TEXT,
+    evolution_type TEXT NOT NULL,
+    trigger_type TEXT NOT NULL,
+    generation INTEGER DEFAULT 0,
+    status TEXT DEFAULT 'candidate',
+    mutation_summary TEXT DEFAULT '',
+    evidence TEXT DEFAULT '[]',
+    original_content TEXT DEFAULT '',
+    evolved_content TEXT DEFAULT '',
+    content_diff TEXT DEFAULT '',
+    blind_verified INTEGER DEFAULT 0,
+    rejection_reason TEXT DEFAULT '',
+    created_at TEXT NOT NULL,
+    completed_at TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_evo_skill ON skill_evolution_log(skill_name);
+CREATE INDEX IF NOT EXISTS idx_evo_status ON skill_evolution_log(status);
+CREATE INDEX IF NOT EXISTS idx_evo_created ON skill_evolution_log(created_at);
+
+CREATE TABLE IF NOT EXISTS evolution_cycle_state (
+    key TEXT PRIMARY KEY,
+    value INTEGER DEFAULT 0,
+    updated_at TEXT
+);
+"""
+
+# Anti-loop budget
+MAX_EVOLUTIONS_PER_CYCLE = 3
+MAX_ATTEMPTS_PER_SKILL = 3
+MIN_FRESH_INVOCATIONS = 5
+
+
+class EvolutionStore:
+    """SQLite persistence for evolution history and anti-loop state."""
+
+    def __init__(self, db_path: str | Path):
+        self._db_path = str(db_path)
+        self._ensure_schema()
+        self._addressed_degradations: dict[str, set[str]] = {}
+
+    def _ensure_schema(self) -> None:
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        try:
+            conn.executescript(_SCHEMA_DDL)
+            conn.commit()
+        except sqlite3.OperationalError as exc:
+            logger.warning("Evolution schema creation failed: %s", exc)
+        finally:
+            conn.close()
+
+    def reset_cycle(self) -> None:
+        """Reset per-cycle counters. Call at start of each consolidation."""
+        now = datetime.now(timezone.utc).isoformat()
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        try:
+            conn.execute(
+                "INSERT OR REPLACE INTO evolution_cycle_state (key, value, updated_at) "
+                "VALUES ('cycle_count', 0, ?)",
+                (now,),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def can_evolve(self) -> bool:
+        """Check if budget allows another evolution this cycle."""
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        try:
+            row = conn.execute(
+                "SELECT value FROM evolution_cycle_state WHERE key = 'cycle_count'",
+            ).fetchone()
+            count = row[0] if row else 0
+            return count < MAX_EVOLUTIONS_PER_CYCLE
+        finally:
+            conn.close()
+
+    def record_evolution_attempt(self) -> None:
+        """Increment cycle counter in DB."""
+        now = datetime.now(timezone.utc).isoformat()
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        try:
+            row = conn.execute(
+                "SELECT value FROM evolution_cycle_state WHERE key = 'cycle_count'",
+            ).fetchone()
+            current = row[0] if row else 0
+            conn.execute(
+                "INSERT OR REPLACE INTO evolution_cycle_state (key, value, updated_at) "
+                "VALUES ('cycle_count', ?, ?)",
+                (current + 1, now),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def _get_cycle_count(self) -> int:
+        """Read current cycle count from DB."""
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        try:
+            row = conn.execute(
+                "SELECT value FROM evolution_cycle_state WHERE key = 'cycle_count'",
+            ).fetchone()
+            return row[0] if row else 0
+        finally:
+            conn.close()
+
+    # ------------------------------------------------------------------
+    # Anti-loop: addressed degradations (adopted from OpenSpace)
+    # ------------------------------------------------------------------
+
+    def is_addressed(self, skill_name: str, context_hash: str) -> bool:
+        return context_hash in self._addressed_degradations.get(skill_name, set())
+
+    def mark_addressed(self, skill_name: str, context_hash: str) -> None:
+        self._addressed_degradations.setdefault(skill_name, set()).add(context_hash)
+
+    def prune_recovered(self, active_degraded_skills: set[str]) -> None:
+        """Remove tracking for skills that recovered."""
+        recovered = [
+            k for k in self._addressed_degradations
+            if k not in active_degraded_skills
+        ]
+        for k in recovered:
+            del self._addressed_degradations[k]
+
+    # ------------------------------------------------------------------
+    # CRUD
+    # ------------------------------------------------------------------
+
+    def save_record(self, record: EvolutionRecord) -> None:
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        try:
+            conn.execute(
+                "INSERT OR REPLACE INTO skill_evolution_log "
+                "(id, skill_name, parent_skill_id, evolution_type, trigger_type, "
+                " generation, status, mutation_summary, evidence, "
+                " original_content, evolved_content, content_diff, "
+                " blind_verified, rejection_reason, created_at, completed_at) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    record.id,
+                    record.skill_name,
+                    record.parent_skill_id,
+                    record.evolution_type.value,
+                    record.trigger.value,
+                    record.generation,
+                    record.status.value,
+                    record.mutation_summary,
+                    json.dumps(list(record.evidence)),
+                    record.original_content,
+                    record.evolved_content,
+                    record.content_diff,
+                    1 if record.blind_verified else 0,
+                    record.rejection_reason,
+                    record.created_at,
+                    record.completed_at,
+                ),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def get_record(self, record_id: str) -> Optional[EvolutionRecord]:
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        conn.row_factory = sqlite3.Row
+        try:
+            row = conn.execute(
+                "SELECT * FROM skill_evolution_log WHERE id = ?",
+                (record_id,),
+            ).fetchone()
+            if not row:
+                return None
+            return self._row_to_record(dict(row))
+        finally:
+            conn.close()
+
+    def get_skill_history(self, skill_name: str, limit: int = 20) -> list[EvolutionRecord]:
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        conn.row_factory = sqlite3.Row
+        try:
+            rows = conn.execute(
+                "SELECT * FROM skill_evolution_log "
+                "WHERE skill_name = ? ORDER BY created_at DESC LIMIT ?",
+                (skill_name, limit),
+            ).fetchall()
+            return [self._row_to_record(dict(r)) for r in rows]
+        finally:
+            conn.close()
+
+    def get_recent(self, limit: int = 10) -> list[EvolutionRecord]:
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        conn.row_factory = sqlite3.Row
+        try:
+            rows = conn.execute(
+                "SELECT * FROM skill_evolution_log "
+                "ORDER BY created_at DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+            return [self._row_to_record(dict(r)) for r in rows]
+        finally:
+            conn.close()
+
+    def count_attempts(self, skill_name: str) -> int:
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        try:
+            row = conn.execute(
+                "SELECT COUNT(*) FROM skill_evolution_log "
+                "WHERE skill_name = ? AND status NOT IN ('promoted')",
+                (skill_name,),
+            ).fetchone()
+            return row[0] if row else 0
+        finally:
+            conn.close()
+
+    def has_exceeded_attempts(self, skill_name: str) -> bool:
+        return self.count_attempts(skill_name) >= MAX_ATTEMPTS_PER_SKILL
+
+    def get_stats(self) -> dict:
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        try:
+            total = conn.execute(
+                "SELECT COUNT(*) FROM skill_evolution_log",
+            ).fetchone()[0]
+            by_status = {}
+            for row in conn.execute(
+                "SELECT status, COUNT(*) FROM skill_evolution_log GROUP BY status",
+            ).fetchall():
+                by_status[row[0]] = row[1]
+            by_type = {}
+            for row in conn.execute(
+                "SELECT evolution_type, COUNT(*) FROM skill_evolution_log GROUP BY evolution_type",
+            ).fetchall():
+                by_type[row[0]] = row[1]
+            return {
+                "total": total,
+                "by_status": by_status,
+                "by_type": by_type,
+                "cycle_budget_remaining": MAX_EVOLUTIONS_PER_CYCLE - self._get_cycle_count(),
+            }
+        finally:
+            conn.close()
+
+    def _row_to_record(self, row: dict) -> EvolutionRecord:
+        evidence_raw = row.get("evidence", "[]")
+        try:
+            evidence = tuple(json.loads(evidence_raw))
+        except (json.JSONDecodeError, TypeError):
+            evidence = ()
+
+        return EvolutionRecord(
+            id=row["id"],
+            skill_name=row["skill_name"],
+            parent_skill_id=row.get("parent_skill_id"),
+            evolution_type=EvolutionType(row["evolution_type"]),
+            trigger=TriggerType(row["trigger_type"]),
+            generation=row.get("generation", 0),
+            status=EvolutionStatus(row.get("status", "candidate")),
+            mutation_summary=row.get("mutation_summary", ""),
+            evidence=evidence,
+            original_content=row.get("original_content", ""),
+            evolved_content=row.get("evolved_content", ""),
+            content_diff=row.get("content_diff", ""),
+            blind_verified=bool(row.get("blind_verified", 0)),
+            rejection_reason=row.get("rejection_reason", ""),
+            created_at=row.get("created_at", ""),
+            completed_at=row.get("completed_at"),
+        )

package/src/superlocalmemory/evolution/mutation_generator.py

@@ -0,0 +1,181 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Mutation Generator — LLM-driven skill improvement.
+
+Reads the original SKILL.md + failure evidence + performance data,
+generates an improved version. Apply-retry cycle (3 attempts) for
+malformed output.
+
+Token-driven termination: <EVOLUTION_COMPLETE> or <EVOLUTION_FAILED>.
+Adopted from OpenSpace evolver.py patterns.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Optional
+
+from superlocalmemory.evolution.types import (
+    EvolutionCandidate,
+    EvolutionType,
+)
+
+logger = logging.getLogger(__name__)
+
+MAX_APPLY_RETRIES = 3
+MAX_CONTENT_CHARS = 12_000  # Truncate skill content in prompt
+
+
+def build_mutation_prompt(
+    candidate: EvolutionCandidate,
+    original_content: str,
+) -> str:
+    """Build the LLM prompt for skill mutation."""
+    truncated = original_content[:MAX_CONTENT_CHARS]
+    evidence_text = "\n".join(f"- {e}" for e in candidate.evidence)
+
+    if candidate.evolution_type == EvolutionType.FIX:
+        return _fix_prompt(candidate.skill_name, truncated, evidence_text, candidate.effective_score)
+    elif candidate.evolution_type == EvolutionType.DERIVED:
+        return _derived_prompt(candidate.skill_name, truncated, evidence_text, candidate.effective_score)
+    else:
+        return _captured_prompt(candidate.skill_name, evidence_text)
+
+
+def parse_mutation_output(output: str) -> Optional[str]:
+    """Extract evolved SKILL.md content from LLM output.
+
+    Looks for content between markdown code fences or after
+    <EVOLUTION_COMPLETE> token. Returns None if <EVOLUTION_FAILED>
+    or no valid content found.
+    """
+    if "<EVOLUTION_FAILED>" in output:
+        return None
+
+    # Try extracting from code fence
+    fence_match = re.search(
+        r"```(?:markdown|md)?\s*\n(---\s*\n.*?)```",
+        output,
+        re.DOTALL,
+    )
+    if fence_match:
+        return fence_match.group(1).strip()
+
+    # Try extracting after EVOLUTION_COMPLETE token
+    complete_match = re.search(
+        r"<EVOLUTION_COMPLETE>\s*(---\s*\n.*)",
+        output,
+        re.DOTALL,
+    )
+    if complete_match:
+        return complete_match.group(1).strip()
+
+    # Try finding YAML frontmatter directly
+    frontmatter_match = re.search(
+        r"(---\s*\nname:.*?)(?:\n---|\Z)",
+        output,
+        re.DOTALL,
+    )
+    if frontmatter_match:
+        # Return everything from the frontmatter start
+        idx = output.index(frontmatter_match.group(0))
+        return output[idx:].strip()
+
+    return None
+
+
+def validate_skill_content(content: str) -> Optional[str]:
+    """Validate evolved skill content. Returns error message or None if valid."""
+    if not content or len(content) < 50:
+        return "Content too short (< 50 chars)"
+    if "---" not in content:
+        return "Missing YAML frontmatter (no --- found)"
+    if content.count("---") >= 2 and "name:" not in content.split("---")[1]:
+        return "Missing 'name:' in frontmatter"
+    return None
+
+
+def build_retry_prompt(original_prompt: str, error: str, attempt: int) -> str:
+    """Build retry prompt after failed mutation attempt."""
+    return (
+        f"{original_prompt}\n\n"
+        f"--- RETRY (attempt {attempt}/{MAX_APPLY_RETRIES}) ---\n"
+        f"Previous output was invalid: {error}\n"
+        f"Please generate a valid SKILL.md with proper YAML frontmatter "
+        f"(--- / name: / description: / ---) followed by markdown instructions.\n"
+        f"End with <EVOLUTION_COMPLETE> or <EVOLUTION_FAILED>."
+    )
+
+
+# ------------------------------------------------------------------
+# Prompt templates
+# ------------------------------------------------------------------
+
+def _fix_prompt(skill_name: str, content: str, evidence: str, score: float) -> str:
+    return f"""You are a skill evolution engine. A skill is underperforming and needs repair.
+
+SKILL NAME: {skill_name}
+EFFECTIVE SCORE: {score:.0%} (approximate)
+
+CURRENT SKILL CONTENT:
+{content}
+
+EVIDENCE OF PROBLEMS:
+{evidence}
+
+YOUR TASK:
+Generate an improved version of this SKILL.md that addresses the identified problems.
+Keep the same overall structure and purpose. Fix what's broken, don't rewrite from scratch.
+
+OUTPUT FORMAT:
+Return the complete improved SKILL.md content inside a markdown code fence.
+The file must start with YAML frontmatter (--- / name: / description: / ---).
+End your response with <EVOLUTION_COMPLETE> if you generated a valid improvement,
+or <EVOLUTION_FAILED> if you cannot improve this skill."""
+
+
+def _derived_prompt(skill_name: str, content: str, evidence: str, score: float) -> str:
+    return f"""You are a skill evolution engine. A skill works for some tasks but not others.
+Create a specialized variant for the failing task type.
+
+PARENT SKILL: {skill_name}
+EFFECTIVE SCORE: {score:.0%} (moderate — works sometimes, fails sometimes)
+
+PARENT SKILL CONTENT:
+{content}
+
+EVIDENCE:
+{evidence}
+
+YOUR TASK:
+Create a specialized DERIVED variant that handles the failing cases better.
+Give it a new name (e.g., "{skill_name}-specialized" or a descriptive name).
+Keep the parent's strengths. Add specific handling for the failure patterns.
+
+OUTPUT FORMAT:
+Return the complete new SKILL.md inside a markdown code fence.
+Must start with YAML frontmatter (--- / name: / description: / ---).
+End with <EVOLUTION_COMPLETE> or <EVOLUTION_FAILED>."""
+
+
+def _captured_prompt(skill_name: str, evidence: str) -> str:
+    return f"""You are a skill evolution engine. A repeated workflow pattern was detected
+that no existing skill covers. Create a new skill to codify this pattern.
+
+PATTERN NAME: {skill_name}
+EVIDENCE:
+{evidence}
+
+YOUR TASK:
+Create a new SKILL.md that codifies this workflow pattern into a reusable skill.
+Make it specific and actionable — not generic advice.
+
+OUTPUT FORMAT:
+Return the complete SKILL.md inside a markdown code fence.
+Must start with YAML frontmatter (--- / name: / description: / ---).
+End with <EVOLUTION_COMPLETE> or <EVOLUTION_FAILED>."""