superlocalmemory 2.7.6 → 2.8.0

package/src/mcp_tools_v28.py

@@ -0,0 +1,280 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""v2.8 MCP tool handlers — lifecycle, behavioral, compliance tools.
+
+These functions implement the 6 new MCP tools added in v2.8.
+They are registered with the MCP server in mcp_server.py.
+Each function is a thin wrapper around the appropriate engine.
+
+Tool list:
+    1. report_outcome        — Record action outcomes for behavioral learning
+    2. get_lifecycle_status   — View memory lifecycle states
+    3. set_retention_policy   — Configure compliance retention policies
+    4. compact_memories       — Trigger lifecycle transitions
+    5. get_behavioral_patterns — View learned behavioral patterns
+    6. audit_trail            — Query compliance audit trail
+"""
+import json
+import sys
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+# Default database paths — overridable for testing
+DEFAULT_MEMORY_DB = str(Path.home() / ".claude-memory" / "memory.db")
+DEFAULT_LEARNING_DB = str(Path.home() / ".claude-memory" / "learning.db")
+DEFAULT_AUDIT_DB = str(Path.home() / ".claude-memory" / "audit.db")
+
+# Ensure src/ is on the path so subpackage imports work
+_SRC_DIR = str(Path(__file__).resolve().parent)
+if _SRC_DIR not in sys.path:
+    sys.path.insert(0, _SRC_DIR)
+
+
+async def report_outcome(
+    memory_ids: list,
+    outcome: str,
+    action_type: str = "other",
+    context: Optional[str] = None,
+    agent_id: str = "user",
+    project: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Record an action outcome for behavioral learning.
+
+    Args:
+        memory_ids: List of memory IDs involved in the action.
+        outcome: One of 'success', 'failure', or 'partial'.
+        action_type: Category (code_written, decision_made, debug_resolved, etc.).
+        context: Optional JSON string with additional context metadata.
+        agent_id: Identifier for the reporting agent.
+        project: Project name for scoping.
+
+    Returns:
+        Dict with success status and outcome_id on success.
+    """
+    try:
+        from behavioral.outcome_tracker import OutcomeTracker
+
+        tracker = OutcomeTracker(DEFAULT_LEARNING_DB)
+        ctx = json.loads(context) if context else {}
+        outcome_id = tracker.record_outcome(
+            memory_ids=memory_ids,
+            outcome=outcome,
+            action_type=action_type,
+            context=ctx,
+            agent_id=agent_id,
+            project=project,
+        )
+        if outcome_id is None:
+            return {
+                "success": False,
+                "error": f"Invalid outcome: {outcome}. Use success/failure/partial.",
+            }
+        return {
+            "success": True,
+            "outcome_id": outcome_id,
+            "outcome": outcome,
+            "memory_ids": memory_ids,
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def get_lifecycle_status(
+    memory_id: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Get lifecycle status — distribution across states or single memory state.
+
+    Args:
+        memory_id: Optional specific memory ID. If None, returns full distribution.
+
+    Returns:
+        Dict with state distribution or single memory lifecycle state.
+    """
+    try:
+        from lifecycle.lifecycle_engine import LifecycleEngine
+
+        engine = LifecycleEngine(DEFAULT_MEMORY_DB)
+        if memory_id is not None:
+            state = engine.get_memory_state(memory_id)
+            if state is None:
+                return {"success": False, "error": f"Memory {memory_id} not found"}
+            return {
+                "success": True,
+                "memory_id": memory_id,
+                "lifecycle_state": state,
+            }
+        else:
+            dist = engine.get_state_distribution()
+            total = sum(dist.values())
+            return {
+                "success": True,
+                "distribution": dist,
+                "total_memories": total,
+            }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def set_retention_policy(
+    name: str,
+    framework: str,
+    retention_days: int,
+    action: str = "retain",
+    applies_to_tags: Optional[list] = None,
+    applies_to_project: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Create a retention policy for compliance.
+
+    Args:
+        name: Policy name (e.g., 'GDPR Erasure', 'HIPAA Retention').
+        framework: Regulatory framework (gdpr, hipaa, eu_ai_act, internal).
+        retention_days: Days to retain (0 = immediate action).
+        action: Policy action (retain, tombstone, archive).
+        applies_to_tags: Tags that trigger this policy.
+        applies_to_project: Project name that triggers this policy.
+
+    Returns:
+        Dict with policy_id on success.
+    """
+    try:
+        from lifecycle.retention_policy import RetentionPolicyManager
+
+        mgr = RetentionPolicyManager(DEFAULT_MEMORY_DB)
+        applies_to: Dict[str, Any] = {}
+        if applies_to_tags:
+            applies_to["tags"] = applies_to_tags
+        if applies_to_project:
+            applies_to["project_name"] = applies_to_project
+        policy_id = mgr.create_policy(
+            name=name,
+            retention_days=retention_days,
+            framework=framework,
+            action=action,
+            applies_to=applies_to,
+        )
+        return {
+            "success": True,
+            "policy_id": policy_id,
+            "name": name,
+            "framework": framework,
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def compact_memories(
+    dry_run: bool = True,
+    profile: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Evaluate and compact memories — transition stale ones through lifecycle.
+
+    Args:
+        dry_run: If True (default), show what would happen without changes.
+        profile: Optional profile filter.
+
+    Returns:
+        Dict with recommendations (dry_run=True) or transition counts (dry_run=False).
+    """
+    try:
+        from lifecycle.lifecycle_evaluator import LifecycleEvaluator
+        from lifecycle.lifecycle_engine import LifecycleEngine
+
+        evaluator = LifecycleEvaluator(DEFAULT_MEMORY_DB)
+        recommendations = evaluator.evaluate_memories(profile=profile)
+
+        if dry_run:
+            return {
+                "success": True,
+                "dry_run": True,
+                "recommendations": len(recommendations),
+                "details": [
+                    {
+                        "memory_id": r["memory_id"],
+                        "from": r["from_state"],
+                        "to": r["to_state"],
+                        "reason": r["reason"],
+                    }
+                    for r in recommendations[:20]
+                ],
+            }
+
+        engine = LifecycleEngine(DEFAULT_MEMORY_DB)
+        transitioned = 0
+        for rec in recommendations:
+            result = engine.transition_memory(
+                rec["memory_id"], rec["to_state"], reason=rec["reason"]
+            )
+            if result.get("success"):
+                transitioned += 1
+
+        return {
+            "success": True,
+            "dry_run": False,
+            "evaluated": len(recommendations),
+            "transitioned": transitioned,
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def get_behavioral_patterns(
+    min_confidence: float = 0.0,
+    project: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Get learned behavioral patterns from outcome analysis.
+
+    Args:
+        min_confidence: Minimum confidence threshold (0.0-1.0).
+        project: Optional project filter.
+
+    Returns:
+        Dict with patterns list and count.
+    """
+    try:
+        from behavioral.behavioral_patterns import BehavioralPatternExtractor
+
+        extractor = BehavioralPatternExtractor(DEFAULT_LEARNING_DB)
+        patterns = extractor.get_patterns(
+            min_confidence=min_confidence, project=project
+        )
+        return {"success": True, "patterns": patterns, "count": len(patterns)}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+async def audit_trail(
+    event_type: Optional[str] = None,
+    actor: Optional[str] = None,
+    limit: int = 50,
+    verify_chain: bool = False,
+) -> Dict[str, Any]:
+    """Query the compliance audit trail.
+
+    Args:
+        event_type: Filter by event type (memory.created, memory.recalled, etc.).
+        actor: Filter by actor (user, agent_id, etc.).
+        limit: Max events to return.
+        verify_chain: If True, verify hash chain integrity.
+
+    Returns:
+        Dict with events list, count, and optional chain verification result.
+    """
+    try:
+        from compliance.audit_db import AuditDB
+
+        db = AuditDB(DEFAULT_AUDIT_DB)
+        result: Dict[str, Any] = {"success": True}
+
+        if verify_chain:
+            chain_result = db.verify_chain()
+            result["chain_valid"] = chain_result["valid"]
+            result["chain_entries"] = chain_result["entries_checked"]
+
+        events = db.query_events(
+            event_type=event_type, actor=actor, limit=limit
+        )
+        result["events"] = events
+        result["count"] = len(events)
+        return result
+    except Exception as e:
+        return {"success": False, "error": str(e)}

package/src/memory-profiles.py

@@ -1,16 +1,6 @@
 #!/usr/bin/env python3
-"""
-SuperLocalMemory V2 - Intelligent Local Memory System
-Copyright (c) 2026 Varun Pratap Bhardwaj
-Licensed under MIT License
-
-Repository: https://github.com/varun369/SuperLocalMemoryV2
-Author: Varun Pratap Bhardwaj (Solution Architect)
-
-NOTICE: This software is protected by MIT License.
-Attribution must be preserved in all copies or derivatives.
-"""
-
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
 """
 SuperLocalMemory V2 - Profile Management System (Column-Based)
 

package/src/memory-reset.py

@@ -1,16 +1,6 @@
 #!/usr/bin/env python3
-"""
-SuperLocalMemory V2 - Intelligent Local Memory System
-Copyright (c) 2026 Varun Pratap Bhardwaj
-Licensed under MIT License
-
-Repository: https://github.com/varun369/SuperLocalMemoryV2
-Author: Varun Pratap Bhardwaj (Solution Architect)
-
-NOTICE: This software is protected by MIT License.
-Attribution must be preserved in all copies or derivatives.
-"""
-
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
 """
 SuperLocalMemory V2 - Reset & Reinitialize Utility
 

package/src/memory_compression.py

@@ -1,16 +1,6 @@
 #!/usr/bin/env python3
-"""
-SuperLocalMemory V2 - Intelligent Local Memory System
-Copyright (c) 2026 Varun Pratap Bhardwaj
-Licensed under MIT License
-
-Repository: https://github.com/varun369/SuperLocalMemoryV2
-Author: Varun Pratap Bhardwaj (Solution Architect)
-
-NOTICE: This software is protected by MIT License.
-Attribution must be preserved in all copies or derivatives.
-"""
-
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
 """
 Progressive Summarization Compression for SuperLocalMemory
 Tier-based compression system to maintain 100+ memories efficiently.

package/src/memory_store_v2.py

@@ -1,16 +1,6 @@
 #!/usr/bin/env python3
-"""
-SuperLocalMemory V2 - Intelligent Local Memory System
-Copyright (c) 2026 Varun Pratap Bhardwaj
-Licensed under MIT License
-
-Repository: https://github.com/varun369/SuperLocalMemoryV2
-Author: Varun Pratap Bhardwaj (Solution Architect)
-
-NOTICE: This software is protected by MIT License.
-Attribution must be preserved in all copies or derivatives.
-"""
-
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
 """
 MemoryStore V2 - Extended Memory System with Tree and Graph Support
 Maintains backward compatibility with V1 API while adding:
@@ -320,6 +310,19 @@ class MemoryStoreV2:
                         # Column might already exist from concurrent migration
                         pass
 
+            # v2.8.0 schema migration — lifecycle + access control columns
+            _v28_migrations = [
+                ("lifecycle_state", "TEXT DEFAULT 'active'"),
+                ("lifecycle_updated_at", "TIMESTAMP"),
+                ("lifecycle_history", "TEXT DEFAULT '[]'"),
+                ("access_level", "TEXT DEFAULT 'public'"),
+            ]
+            for col_name, col_type in _v28_migrations:
+                try:
+                    cursor.execute(f"ALTER TABLE memories ADD COLUMN {col_name} {col_type}")
+                except sqlite3.OperationalError:
+                    pass  # Column already exists
+
             # Sessions table (V1 compatible)
             cursor.execute('''
                 CREATE TABLE IF NOT EXISTS sessions (
@@ -382,6 +385,13 @@ class MemoryStoreV2:
                     # Index will be created automatically on next schema upgrade
                     pass
 
+            # v2.8.0 indexes for lifecycle + access control
+            try:
+                cursor.execute("CREATE INDEX IF NOT EXISTS idx_lifecycle_state ON memories(lifecycle_state)")
+                cursor.execute("CREATE INDEX IF NOT EXISTS idx_access_level ON memories(access_level)")
+            except sqlite3.OperationalError:
+                pass
+
             # Creator Attribution Metadata Table (REQUIRED by MIT License)
             # This table embeds creator information directly in the database
             cursor.execute('''
@@ -604,7 +614,9 @@ class MemoryStoreV2:
         memory_type: Optional[str] = None,
         category: Optional[str] = None,
         cluster_id: Optional[int] = None,
-        min_importance: Optional[int] = None
+        min_importance: Optional[int] = None,
+        lifecycle_states: Optional[tuple] = None,
+        agent_context: Optional[Dict[str, Any]] = None,
     ) -> List[Dict[str, Any]]:
         """
         Search memories with enhanced V2 filtering.
@@ -617,10 +629,14 @@ class MemoryStoreV2:
             category: Filter by category
             cluster_id: Filter by graph cluster
             min_importance: Minimum importance score
+            lifecycle_states: Tuple of lifecycle states to include (default: active, warm)
 
         Returns:
             List of memory dictionaries with scores
         """
+        if lifecycle_states is None:
+            lifecycle_states = ("active", "warm")
+
         results = []
         active_profile = self._get_active_profile()
 
@@ -640,12 +656,12 @@ class MemoryStoreV2:
                                     SELECT id, content, summary, project_path, project_name, tags,
                                            category, parent_id, tree_path, depth,
                                            memory_type, importance, created_at, cluster_id,
-                                           last_accessed, access_count
+                                           last_accessed, access_count, lifecycle_state
                                     FROM memories WHERE id = ? AND profile = ?
                                 ''', (memory_id, active_profile))
                                 row = cursor.fetchone()
                                 if row and self._apply_filters(row, project_path, memory_type,
-                                                              category, cluster_id, min_importance):
+                                                              category, cluster_id, min_importance, lifecycle_states):
                                     results.append(self._row_to_dict(row, score, 'hnsw'))
                         _hnsw_used = len(results) > 0
                 except (ImportError, Exception):
@@ -670,13 +686,13 @@ class MemoryStoreV2:
                                     SELECT id, content, summary, project_path, project_name, tags,
                                            category, parent_id, tree_path, depth,
                                            memory_type, importance, created_at, cluster_id,
-                                           last_accessed, access_count
+                                           last_accessed, access_count, lifecycle_state
                                     FROM memories WHERE id = ? AND profile = ?
                                 ''', (memory_id, active_profile))
                                 row = cursor.fetchone()
 
                                 if row and self._apply_filters(row, project_path, memory_type,
-                                                              category, cluster_id, min_importance):
+                                                              category, cluster_id, min_importance, lifecycle_states):
                                     results.append(self._row_to_dict(row, score, 'semantic'))
 
                 except Exception as e:
@@ -694,7 +710,7 @@ class MemoryStoreV2:
                     SELECT m.id, m.content, m.summary, m.project_path, m.project_name,
                            m.tags, m.category, m.parent_id, m.tree_path, m.depth,
                            m.memory_type, m.importance, m.created_at, m.cluster_id,
-                           m.last_accessed, m.access_count
+                           m.last_accessed, m.access_count, m.lifecycle_state
                     FROM memories m
                     JOIN memories_fts fts ON m.id = fts.rowid
                     WHERE memories_fts MATCH ? AND m.profile = ?
@@ -707,12 +723,23 @@ class MemoryStoreV2:
                 for row in cursor.fetchall():
                     if row[0] not in existing_ids:
                         if self._apply_filters(row, project_path, memory_type,
-                                              category, cluster_id, min_importance):
+                                              category, cluster_id, min_importance, lifecycle_states):
                             results.append(self._row_to_dict(row, 0.5, 'keyword'))
 
         # Update access tracking for returned results
         self._update_access_tracking([r['id'] for r in results])
 
+        # Reactivate warm memories that were recalled (lifecycle v2.8)
+        warm_ids = [r['id'] for r in results if r.get('lifecycle_state') == 'warm']
+        if warm_ids:
+            try:
+                from lifecycle.lifecycle_engine import LifecycleEngine
+                engine = LifecycleEngine(self.db_path)
+                for mem_id in warm_ids:
+                    engine.reactivate_memory(mem_id, trigger="recall")
+            except (ImportError, Exception):
+                pass  # Lifecycle engine not available
+
         # Sort by score and limit
         results.sort(key=lambda x: x['score'], reverse=True)
         return results[:limit]
@@ -724,7 +751,8 @@ class MemoryStoreV2:
         memory_type: Optional[str],
         category: Optional[str],
         cluster_id: Optional[int],
-        min_importance: Optional[int]
+        min_importance: Optional[int],
+        lifecycle_states: Optional[tuple] = None,
     ) -> bool:
         """Apply filter criteria to a database row."""
         # Row indices: project_path=3, category=6, memory_type=10, importance=11, cluster_id=13
@@ -738,8 +766,35 @@ class MemoryStoreV2:
             return False
         if min_importance is not None and (row[11] or 0) < min_importance:
             return False
+        # Lifecycle state filter (v2.8) — index 16 if present
+        if lifecycle_states and len(row) > 16:
+            state = row[16] or "active"
+            if state not in lifecycle_states:
+                return False
         return True
 
+    def _check_abac(
+        self,
+        subject: Dict[str, Any],
+        resource: Dict[str, Any],
+        action: str,
+        policy_path: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Check ABAC policy for an access request.
+
+        Returns {"allowed": True/False, "reason": str}.
+        When ABAC engine is unavailable (import error, missing file),
+        defaults to allow for backward compatibility with v2.7.
+        """
+        try:
+            from compliance.abac_engine import ABACEngine
+            if policy_path is None:
+                policy_path = str(Path(self.db_path).parent / "abac_policies.json")
+            engine = ABACEngine(config_path=policy_path)
+            return engine.evaluate(subject=subject, resource=resource, action=action)
+        except (ImportError, Exception):
+            return {"allowed": True, "reason": "ABAC unavailable — default allow"}
+
     def _row_to_dict(self, row: tuple, score: float, match_type: str) -> Dict[str, Any]:
         """Convert database row to memory dictionary."""
         # Backward compatibility: Handle both JSON array and comma-separated string tags
@@ -771,6 +826,7 @@ class MemoryStoreV2:
             'cluster_id': row[13],
             'last_accessed': row[14],
             'access_count': row[15],
+            'lifecycle_state': row[16] if len(row) > 16 else 'active',
             'score': score,
             'match_type': match_type
         }

package/src/migrate_v1_to_v2.py

@@ -1,16 +1,6 @@
 #!/usr/bin/env python3
-"""
-SuperLocalMemory V2 - Intelligent Local Memory System
-Copyright (c) 2026 Varun Pratap Bhardwaj
-Licensed under MIT License
-
-Repository: https://github.com/varun369/SuperLocalMemoryV2
-Author: Varun Pratap Bhardwaj (Solution Architect)
-
-NOTICE: This software is protected by MIT License.
-Attribution must be preserved in all copies or derivatives.
-"""
-
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
 """
 SuperLocalMemory V1 to V2 Migration Script