synaptic-state 0.1.0__py3-none-any.whl

synaptic_state/__init__.py

@@ -0,0 +1,28 @@
+"""
+SynapticAI: Verifiable State Plane for Autonomous Agents
+
+Remember less. Stay correct longer.
+Neuro-Symbolic Memory That Learns What to Forget.
+"""
+
+__version__ = "0.1.0"
+__author__ = "SynapticAI Team"
+__license__ = "MIT"
+
+from synaptic_state.core.stateplane import StatePlane
+from synaptic_state.core.agm import AGMEngine, BeliefState
+from synaptic_state.core.verification import VerificationGate, VerificationResult
+from synaptic_state.adaptive.forgetting import LearnableForgetting
+from synaptic_state.retrieval.hybrid import HybridRetriever
+from synaptic_state.adaptive.budget import ContextBudgetRL
+
+__all__ = [
+    "StatePlane",
+    "AGMEngine",
+    "BeliefState", 
+    "VerificationGate",
+    "VerificationResult",
+    "LearnableForgetting",
+    "HybridRetriever",
+    "ContextBudgetRL",
+]

synaptic_state/adaptive/__init__.py

@@ -0,0 +1,4 @@
+"""Adaptive layer: Budget Optimization and Learnable Forgetting."""
+from synaptic_state.adaptive.budget import ContextBudgetRL
+from synaptic_state.adaptive.forgetting import LearnableForgetting
+__all__ = ["ContextBudgetRL", "LearnableForgetting"]

synaptic_state/adaptive/budget.py

@@ -0,0 +1,186 @@
+"""
+ContextBudget RL: Adaptive Context Budget Allocation
+
+Based on ContextBudget paper (arXiv:2604.01664):
+- Formulates context management as a sequential decision problem
+- Learns optimal compression strategies under varying budgets
+
+For MVP: Heuristic-based allocation (Phase 2: actual RL)
+"""
+
+from __future__ import annotations
+
+import time
+import logging
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class ContextBudgetRL:
+    """
+    Adaptive context budget optimizer.
+    
+    Allocates token budget across memory types based on:
+    1. Task type (coding, analysis, conversation, etc.)
+    2. History of what was most useful
+    3. Current context constraints
+    
+    MVP: Rule-based allocation with learning hooks.
+    Phase 2: Actual RL-trained policy network.
+    """
+    
+    # Default allocation percentages by strategy
+    ALLOCATION_PROFILES = {
+        "greedy": {
+            "episodic": 0.4,
+            "procedural": 0.2,
+            "semantic": 0.25,
+            "symbolic": 0.15,
+        },
+        "rl_optimized": {
+            "episodic": 0.3,
+            "procedural": 0.3,
+            "semantic": 0.25,
+            "symbolic": 0.15,
+        },
+        "symbolic_heavy": {
+            "episodic": 0.15,
+            "procedural": 0.2,
+            "semantic": 0.3,
+            "symbolic": 0.35,
+        },
+        "conversation": {
+            "episodic": 0.5,
+            "procedural": 0.1,
+            "semantic": 0.3,
+            "symbolic": 0.1,
+        },
+    }
+    
+    def __init__(
+        self,
+        default_budget: int = 2048,
+        max_budget: int = 8192,
+        learning_rate: float = 0.01,
+    ):
+        self.default_budget = default_budget
+        self.max_budget = max_budget
+        self.learning_rate = learning_rate
+        
+        # Learning state (for Phase 2 RL)
+        self._task_history: list = []
+        self._allocation_history: list = []
+        self._feedback_scores: list = []  # 0-1 scores post-task
+    
+    def allocate_budget(
+        self,
+        requested_budget: Optional[int] = None,
+        strategy: str = "rl_optimized",
+        task_type: str = "generic",
+        available_types: Optional[Dict[str, int]] = None,
+    ) -> Dict[str, int]:
+        """
+        Allocate token budget across memory types.
+        
+        Returns: {"episodic": N, "procedural": N, "semantic": N, "symbolic": N}
+        """
+        budget = min(
+            requested_budget or self.default_budget,
+            self.max_budget,
+        )
+        
+        profile = self.ALLOCATION_PROFILES.get(strategy, self.ALLOCATION_PROFILES["rl_optimized"])
+        
+        # Apply task-type adjustments
+        adjusted = self._adjust_for_task_type(profile, task_type)
+        
+        # Normalize
+        total = sum(adjusted.values())
+        if total > 0:
+            allocation = {
+                k: int(budget * v / total)
+                for k, v in adjusted.items()
+            }
+        else:
+            allocation = {k: budget // len(adjusted) for k in adjusted}
+        
+        # Log for learning
+        self._allocation_history.append({
+            "timestamp": time.time(),
+            "budget": budget,
+            "strategy": strategy,
+            "task_type": task_type,
+            "allocation": allocation,
+        })
+        
+        # Apply available constraints
+        if available_types:
+            for mem_type, available_count in available_types.items():
+                if mem_type in allocation and available_count == 0:
+                    allocation[mem_type] = 0
+        
+        return allocation
+    
+    def record_feedback(self, task_type: str, score: float, allocation: Dict[str, int]) -> None:
+        """
+        Record task feedback for future learning.
+        
+        score: 0.0 (bad allocation) to 1.0 (perfect allocation)
+        """
+        self._feedback_scores.append({
+            "timestamp": time.time(),
+            "task_type": task_type,
+            "score": score,
+            "allocation": allocation,
+        })
+    
+    def _adjust_for_task_type(self, profile: Dict[str, float], task_type: str) -> Dict[str, float]:
+        """Adjust allocation ratios based on task type."""
+        adjusted = dict(profile)
+        
+        adjustments = {
+            "coding": {"procedural": 0.15, "symbolic": 0.1, "episodic": -0.1, "semantic": -0.05},
+            "debug": {"episodic": 0.15, "procedural": 0.1, "symbolic": 0.0, "semantic": 0.0},
+            "analysis": {"semantic": 0.15, "episodic": 0.05, "procedural": -0.05, "symbolic": -0.05},
+            "conversation": {"episodic": 0.2, "semantic": 0.1, "procedural": -0.15, "symbolic": -0.05},
+        }
+        
+        task_adjust = adjustments.get(task_type, {})
+        for mem_type, delta in task_adjust.items():
+            if mem_type in adjusted:
+                adjusted[mem_type] = max(0.05, adjusted[mem_type] + delta)
+        
+        return adjusted
+    
+    def get_optimal_strategy(self, task_type: str = "generic") -> str:
+        """
+        Suggest optimal strategy based on historical feedback.
+        
+        For Phase 2: this will use learned RL policy.
+        For MVP: simple heuristic.
+        """
+        if not self._feedback_scores:
+            return "rl_optimized"
+        
+        # Find highest-scoring strategy for this task type
+        task_feedback = [f for f in self._feedback_scores if f["task_type"] == task_type]
+        if not task_feedback:
+            return "rl_optimized"
+        
+        # Simple averaging
+        avg_scores: Dict[str, float] = {}
+        for fb in task_feedback:
+            strategy = fb.get("allocation", {}).get("_strategy", "rl_optimized")
+            if strategy not in avg_scores:
+                avg_scores[strategy] = []
+            avg_scores[strategy].append(fb["score"])
+        
+        if not avg_scores:
+            return "rl_optimized"
+        
+        best_strategy = max(
+            avg_scores.items(),
+            key=lambda x: sum(x[1]) / len(x[1])
+        )
+        return best_strategy[0]

synaptic_state/adaptive/forgetting.py

@@ -0,0 +1,225 @@
+"""
+Learnable Forgetting Engine
+
+Based on Oblivion (arXiv:2604.00131):
+- Models biological forgetting curves
+- Importance-based retention vs static TTL
+- Explainable: "Why was this forgotten?"
+
+Instead of expiring memories by time, this engine:
+1. Adjusts decay rates based on importance and access patterns
+2. Can strengthen frequently accessed memories
+3. Provides explanations for forgetting decisions
+"""
+
+from __future__ import annotations
+
+import time
+import math
+import logging
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass
+
+from synaptic_state.core.models import MemoryEntry
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DecayConfig:
+    """Configuration for decay behavior."""
+    # Base decay rates per memory type
+    episodic_decay: float = 0.02      # Experiences fade faster
+    procedural_decay: float = 0.005   # Skills persist
+    semantic_decay: float = 0.01      # Facts fade slowly
+    symbolic_decay: float = 0.003     # Rules persist longest
+    
+    # Access-based reinforcement
+    access_boost_per_use: float = 0.05
+    max_access_boost: float = 0.3
+    
+    # Verification-based retention
+    verified_retention_bonus: float = 0.1
+    
+    # Ebbinghaus forgetting curve parameters
+    ebbinghaus_S: float = 100  # Initial memory strength (%)
+    ebbinghaus_k: float = 1.25  # Forgetting constant
+
+
+class LearnableForgetting:
+    """
+    Learnable decay and forgetting engine.
+    
+    Models how memories fade over time, with:
+    - Type-specific decay rates
+    - Access-based reinforcement (use it or lose it)
+    - Verification-based retention
+    - Ebbinghaus forgetting curve
+    - Explainable decisions
+    """
+    
+    def __init__(
+        self,
+        default_decay_rate: float = 0.01,
+        config: Optional[DecayConfig] = None,
+        enabled: bool = True,
+    ):
+        self.default_decay_rate = default_decay_rate
+        self.config = config or DecayConfig()
+        self.enabled = enabled
+        self.decay_history: Dict[str, List[Dict[str, Any]]] = {}
+        self._forget_count = 0
+    
+    def on_commit(self, entry: MemoryEntry) -> None:
+        """Record when a memory is committed."""
+        self.decay_history[entry.key] = [{
+            "event": "commit",
+            "timestamp": time.time(),
+            "strength": entry.current_strength,
+            "importance": entry.importance,
+            "decay_rate": entry.decay_rate,
+        }]
+    
+    def on_forget(self, entry: MemoryEntry, reason: str = "expired") -> None:
+        """Record when a memory is forgotten."""
+        if entry.key not in self.decay_history:
+            self.decay_history[entry.key] = []
+        
+        self.decay_history[entry.key].append({
+            "event": "forget",
+            "timestamp": time.time(),
+            "reason": reason,
+            "final_strength": entry.current_strength,
+        })
+        self._forget_count += 1
+    
+    def on_access(self, entry: MemoryEntry) -> float:
+        """
+        Record memory access and apply reinforcement.
+        
+        Returns the new strength after access boost.
+        """
+        access_count = entry.access_count
+        entry.access_count += 1
+        entry.last_accessed = time.time()
+        
+        # Apply access boost (diminishing returns)
+        boost = self.config.access_boost_per_use / (1 + access_count * 0.1)
+        boost = min(boost, self.config.max_access_boost - 
+                   sum(h["event"] == "boost" for h in self.decay_history.get(entry.key, [])) * 0.05)
+        
+        new_strength = min(1.0, entry.current_strength + boost)
+        entry.current_strength = new_strength
+        
+        if entry.key not in self.decay_history:
+            self.decay_history[entry.key] = []
+        self.decay_history[entry.key].append({
+            "event": "access_boost",
+            "timestamp": time.time(),
+            "strength_before": new_strength - boost,
+            "strength_after": new_strength,
+            "boost": boost,
+            "access_count": entry.access_count,
+        })
+        
+        return new_strength
+    
+    def apply_decay_to_entry(self, entry: MemoryEntry) -> None:
+        """Apply time-based decay to a single entry."""
+        if not self.enabled:
+            return
+        
+        now = time.time()
+        last_update = entry.updated_at
+        elapsed_hours = max(0, (now - last_update) / 3600.0)
+        
+        if elapsed_hours < 0.01:  # Less than 36 seconds
+            return
+        
+        # Get type-specific decay rate
+        type_decay = {
+            "episodic": self.config.episodic_decay,
+            "procedural": self.config.procedural_decay,
+            "semantic": self.config.semantic_decay,
+            "symbolic": self.config.symbolic_decay,
+        }.get(entry.memory_type.value if hasattr(entry.memory_type, 'value') else str(entry.memory_type), 
+              self.default_decay_rate)
+        
+        # Apply Ebbinghaus curve
+        ebbinghaus_strength = (
+            self.config.ebbinghaus_S * 
+            math.exp(-self.config.ebbinghaus_k * elapsed_hours)
+        )
+        
+        # Exponential decay
+        base_decay = type_decay * elapsed_hours
+        
+        # Verification bonus
+        if entry.is_verified:
+            base_decay *= (1 - self.config.verified_retention_bonus)
+        
+        entry.decay_rate = type_decay
+        entry.apply_decay(elapsed_hours)
+    
+    def apply_global_decay(self) -> None:
+        """
+        Apply decay to all tracked entries.
+        
+        This should be called periodically (e.g., at the start of each recall).
+        """
+        if not self.enabled:
+            return
+        
+        # Decay is applied per-entry during commit/recall in StatePlane
+        pass
+    
+    def generate_explanation(self, key: str) -> str:
+        """
+        Explain why a memory was forgotten or has low strength.
+        
+        Returns a human-readable explanation.
+        """
+        history = self.decay_history.get(key, [])
+        
+        if not history:
+            return f"No history found for '{key}'."
+        
+        explanations = []
+        
+        for event in history:
+            if event["event"] == "commit":
+                explanations.append(
+                    f"Committed with importance {event['importance']:.2f} "
+                    f"and initial strength {event['strength']:.2f}."
+                )
+            elif event["event"] == "forget":
+                explanations.append(
+                    f"Forgotten because: {event['reason']}. "
+                    f"Final strength: {event.get('final_strength', 'N/A')}."
+                )
+            elif event["event"] == "access_boost":
+                explanations.append(
+                    f"Accessed {event['access_count']} times, "
+                    f"strength boosted to {event['strength_after']:.2f}."
+                )
+        
+        return " ".join(explanations)
+    
+    def get_decay_stats(self) -> Dict[str, Any]:
+        """Get overall forgetting statistics."""
+        total_committed = sum(
+            1 for history in self.decay_history.values()
+            if any(e["event"] == "commit" for e in history)
+        )
+        total_forgotten = sum(
+            1 for history in self.decay_history.values()
+            if any(e["event"] == "forget" for e in history)
+        )
+        
+        return {
+            "enabled": self.enabled,
+            "tracked_keys": len(self.decay_history),
+            "total_committed": total_committed,
+            "total_forgotten": total_forgotten,
+            "forget_rate": total_forgotten / max(total_committed, 1),
+        }

synaptic_state/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI for SynapticAI."""

synaptic_state/cli/main.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""
+SynapticAI CLI
+
+Usage:
+  synaptic commit --key USER_PREF --value '{"tabs": 2}'
+  synaptic recall --intent "editor settings"
+  synaptic forget --key USER_PREF
+  synaptic explain --key USER_PREF
+  synaptic status
+"""
+
+import argparse
+import json
+import sys
+
+from synaptic_state.core.stateplane import StatePlane
+import logging
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s: %(message)s")
+
+def main():
+    parser = argparse.ArgumentParser(description="SynapticAI CLI")
+    sub = parser.add_subparsers(dest="command", help="Available commands")
+    
+    # Commit
+    p_commit = sub.add_parser("commit", help="Commit a memory entry")
+    p_commit.add_argument("--key", required=True, help="Memory key")
+    p_commit.add_argument("--value", required=True, help="Memory value (JSON or string)")
+    p_commit.add_argument("--type", default="episodic", choices=["episodic", "procedural", "semantic", "symbolic"])
+    p_commit.add_argument("--verify", action="store_true", default=True)
+    p_commit.add_argument("--ttl", type=float, default=None)
+    p_commit.add_argument("--source", default="cli")
+    p_commit.add_argument("--session", default="")
+    
+    # Recall
+    p_recall = sub.add_parser("recall", help="Recall memories")
+    p_recall.add_argument("--intent", default="", help="What you're looking for")
+    p_recall.add_argument("--budget", type=int, default=2048)
+    p_recall.add_argument("--strategy", default="rl_optimized")
+    p_recall.add_argument("--min-confidence", type=float, default=0.3)
+    
+    # Forget
+    p_forget = sub.add_parser("forget", help="Remove a memory entry")
+    p_forget.add_argument("--key", required=True)
+    
+    # Explain
+    p_explain = sub.add_parser("explain", help="Explain why a memory was forgotten")
+    p_explain.add_argument("--key", required=True)
+    
+    # Status
+    sub.add_parser("status", help="Show operational statistics")
+    
+    args = parser.parse_args()
+    plane = StatePlane()
+    
+    if args.command == "commit":
+        result = plane.commit(
+            key=args.key,
+            value=json.loads(args.value) if args.value.startswith(('{', '[')) else args.value,
+            memory_type=args.type,
+            verify=args.verify,
+            ttl=args.ttl,
+            source=args.source,
+            session_id=args.session,
+        )
+        print(json.dumps(result, indent=2))
+    
+    elif args.command == "recall":
+        result = plane.recall(
+            intent=args.intent,
+            budget_tokens=args.budget,
+            strategy=args.strategy,
+            min_confidence=args.min_confidence,
+        )
+        output = {
+            "memories": [{"key": m.key, "type": m.memory_type.value, "strength": m.current_strength} for m in result.memories],
+            "total_tokens": result.total_tokens_estimated,
+            "budget_used": f"{result.total_tokens_estimated}/{result.budget_requested}",
+            "stale_count": result.stale_count,
+            "conflict_count": result.conflict_count,
+        }
+        print(json.dumps(output, indent=2))
+    
+    elif args.command == "forget":
+        entry = plane.forget(args.key)
+        if entry:
+            print(f"Forgotten: {args.key}")
+        else:
+            print(f"Key not found: {args.key}")
+    
+    elif args.command == "explain":
+        explanation = plane.explain_forgetting(args.key)
+        print(json.dumps(explanation, indent=2))
+    
+    elif args.command == "status":
+        stats = plane.get_stats()
+        drift = plane.get_drift_report()
+        print(json.dumps({"stats": stats, "drift": drift}, indent=2))
+    
+    else:
+        parser.print_help()
+
+if __name__ == "__main__":
+    main()

synaptic_state/core/__init__.py

@@ -0,0 +1,6 @@
+"""Core components: StatePlane, AGM Belief Revision, Verification Gate."""
+from synaptic_state.core.stateplane import StatePlane
+from synaptic_state.core.agm import AGMEngine, BeliefState
+from synaptic_state.core.verification import VerificationGate, VerificationResult
+
+__all__ = ["StatePlane", "AGMEngine", "BeliefState", "VerificationGate", "VerificationResult"]