@smilintux/skmemory 0.5.0 → 0.9.2

package/skmemory/models.py

@@ -11,7 +11,7 @@ import hashlib
 import uuid
 from datetime import datetime, timezone
 from enum import Enum
-from typing import Any, Optional
+from typing import Any
 
 from pydantic import BaseModel, Field, field_validator
 
@@ -90,12 +90,8 @@ class Memory(BaseModel):
     """
 
     id: str = Field(default_factory=lambda: str(uuid.uuid4()))
-    created_at: str = Field(
-        default_factory=lambda: datetime.now(timezone.utc).isoformat()
-    )
-    updated_at: str = Field(
-        default_factory=lambda: datetime.now(timezone.utc).isoformat()
-    )
+    created_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    updated_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
 
     layer: MemoryLayer = Field(default=MemoryLayer.SHORT)
     role: MemoryRole = Field(default=MemoryRole.GENERAL)
@@ -123,11 +119,28 @@ class Memory(BaseModel):
         default_factory=list,
         description="IDs of related memories (graph edges)",
     )
-    parent_id: Optional[str] = Field(
+    parent_id: str | None = Field(
         default=None,
         description="ID of parent memory (for hierarchical chains)",
     )
 
+    context_tag: str = Field(
+        default="@chef-only",
+        description="Audience context tag: @public, @community, @work-circle, @inner-circle, "
+        "@chef-only, or scoped like @work:chiro. Conservative default: @chef-only.",
+    )
+
+    intent: str = Field(
+        default="",
+        description="WHY this memory was stored — the purpose, not just the content. "
+        "Inspired by Jonathan Clements' AMK (Adaptive Memory Kernel).",
+    )
+    integrity_hash: str = Field(
+        default="",
+        description="SHA-256 hash of content at write time for tamper detection. "
+        "A memory that can prove it hasn't been altered is a memory you can trust.",
+    )
+
     metadata: dict[str, Any] = Field(default_factory=dict)
 
     @field_validator("title")
@@ -146,6 +159,36 @@ class Memory(BaseModel):
         """
         return hashlib.sha256(self.content.encode()).hexdigest()[:16]
 
+    def compute_integrity_hash(self) -> str:
+        """Compute a full SHA-256 integrity hash over content + title + emotional state.
+
+        This is the AMK-inspired tamper detection hash. If the content,
+        title, or emotional signature changes after storage, the hash
+        won't match and you know the memory was altered.
+
+        Returns:
+            str: Full 64-char hex SHA-256 digest.
+        """
+        payload = f"{self.id}:{self.title}:{self.content}:{self.emotional.signature()}"
+        return hashlib.sha256(payload.encode()).hexdigest()
+
+    def seal(self) -> None:
+        """Seal this memory by computing and storing the integrity hash.
+
+        Call this at write time. Later, verify with verify_integrity().
+        """
+        self.integrity_hash = self.compute_integrity_hash()
+
+    def verify_integrity(self) -> bool:
+        """Verify that this memory hasn't been tampered with since sealing.
+
+        Returns:
+            bool: True if the integrity hash matches, False if altered or unsealed.
+        """
+        if not self.integrity_hash:
+            return True
+        return self.integrity_hash == self.compute_integrity_hash()
+
     def to_embedding_text(self) -> str:
         """Flatten this memory into a single string for vector embedding.
 

package/skmemory/openclaw.py

@@ -19,14 +19,11 @@ Or from the OpenClaw JS plugin (calls CLI under the hood).
 from __future__ import annotations
 
 import json
-import os
 from pathlib import Path
-from typing import Any, Optional
 
-from .models import EmotionalSnapshot, MemoryLayer, MemoryRole
-from .store import MemoryStore
 from .backends.sqlite_backend import SQLiteBackend
-
+from .models import EmotionalSnapshot, MemoryLayer
+from .store import MemoryStore
 
 OPENCLAW_BASE = Path.home() / ".openclaw"
 SKMEMORY_OPENCLAW_DIR = OPENCLAW_BASE / "plugins" / "skmemory"
@@ -42,21 +39,22 @@ class SKMemoryPlugin:
 
     Args:
         base_path: Override the memory storage directory.
-        qdrant_url: Optional Qdrant server for semantic search.
-        qdrant_key: Optional Qdrant API key.
+        skvector_url: Optional SKVector server for semantic search.
+        skvector_key: Optional SKVector API key.
     """
 
     def __init__(
         self,
-        base_path: Optional[str] = None,
-        qdrant_url: Optional[str] = None,
-        qdrant_key: Optional[str] = None,
+        base_path: str | None = None,
+        skvector_url: str | None = None,
+        skvector_key: str | None = None,
     ) -> None:
         vector = None
-        if qdrant_url:
+        if skvector_url:
             try:
-                from .backends.qdrant_backend import QdrantBackend
-                vector = QdrantBackend(url=qdrant_url, api_key=qdrant_key)
+                from .backends.skvector_backend import SKVectorBackend
+
+                vector = SKVectorBackend(url=skvector_url, api_key=skvector_key)
             except Exception:
                 pass
 
@@ -97,10 +95,10 @@ class SKMemoryPlugin:
         content: str = "",
         *,
         layer: str = "short-term",
-        tags: Optional[list[str]] = None,
+        tags: list[str] | None = None,
         intensity: float = 0.0,
         valence: float = 0.0,
-        emotions: Optional[list[str]] = None,
+        emotions: list[str] | None = None,
         source: str = "openclaw",
     ) -> str:
         """Capture a memory snapshot.
@@ -152,16 +150,11 @@ class SKMemoryPlugin:
                 "ORDER BY created_at DESC LIMIT ?",
                 (q, q, q, limit),
             ).fetchall()
-            return [
-                self.store.primary._row_to_memory_summary(r) for r in rows
-            ]
+            return [self.store.primary._row_to_memory_summary(r) for r in rows]
         results = self.store.search(query, limit=limit)
-        return [
-            {"id": m.id, "title": m.title, "layer": m.layer.value}
-            for m in results
-        ]
+        return [{"id": m.id, "title": m.title, "layer": m.layer.value} for m in results]
 
-    def recall(self, memory_id: str) -> Optional[dict]:
+    def recall(self, memory_id: str) -> dict | None:
         """Retrieve a full memory by ID.
 
         Args:
@@ -191,11 +184,11 @@ class SKMemoryPlugin:
             "context_prompt": result.context_prompt,
         }
 
-    def export(self, output_path: Optional[str] = None) -> str:
+    def export(self, output_path: str | None = None) -> str:
         """Export all memories to a dated JSON backup.
 
         Args:
-            output_path: Destination (default: ~/.skmemory/backups/).
+            output_path: Destination (default: ~/.skcapstone/backups/).
 
         Returns:
             str: Path to the backup file.
@@ -229,9 +222,8 @@ class SKMemoryPlugin:
         """
         try:
             from . import __version__
+
             state["skmemory_version"] = __version__
-            SKMEMORY_STATE_FILE.write_text(
-                json.dumps(state, indent=2), encoding="utf-8"
-            )
+            SKMEMORY_STATE_FILE.write_text(json.dumps(state, indent=2), encoding="utf-8")
         except Exception:
             pass

package/skmemory/post_install.py

@@ -0,0 +1,86 @@
+"""Post-install auto-registration for skmemory.
+
+Runs `skmemory register` automatically after pip install to ensure:
+  - MCP server is registered in Claude Code, Cursor, etc.
+  - Auto-save hooks are installed in Claude Code settings
+  - Skill symlink is created
+
+Called via:
+  - `skmemory-post-install` console script (entry point)
+  - `pip install skmemory && skmemory-post-install`
+  - Automatically on first `skmemory` CLI invocation (if not yet registered)
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def _is_registered() -> bool:
+    """Check if hooks are already installed (quick check)."""
+    settings = Path.home() / ".claude" / "settings.json"
+    if not settings.exists():
+        return False
+    try:
+        import json
+
+        data = json.loads(settings.read_text())
+        hooks = data.get("hooks", {})
+        return "PreCompact" in hooks and "SessionEnd" in hooks
+    except Exception:
+        return False
+
+
+def run_post_install() -> None:
+    """Register skmemory MCP server, hooks, and skill symlinks."""
+    from .register import detect_environments, register_package
+
+    print("skmemory: running post-install registration...")
+
+    detected = detect_environments()
+    if not detected:
+        print("  No supported environments detected. Skipping.")
+        return
+
+    print(f"  Detected: {', '.join(detected)}")
+
+    skill_md = Path(__file__).parent.parent / "SKILL.md"
+    if not skill_md.exists():
+        skill_md = Path(__file__).parent / "SKILL.md"
+
+    result = register_package(
+        name="skmemory",
+        skill_md_path=skill_md,
+        mcp_command="skmemory-mcp",
+        mcp_args=[],
+        install_hooks=True,
+        environments=detected,
+    )
+
+    skill_action = result.get("skill", {}).get("action", "—")
+    print(f"  Skill: {skill_action}")
+
+    mcp = result.get("mcp", {})
+    for env_name, action in mcp.items():
+        print(f"  MCP ({env_name}): {action}")
+
+    hooks = result.get("hooks", {})
+    if hooks:
+        print(f"  Hooks: {hooks.get('action', '—')}")
+
+    print("skmemory: post-install complete.")
+
+
+def main() -> None:
+    """Entry point for skmemory-post-install console script."""
+    try:
+        run_post_install()
+    except Exception as exc:
+        # Never fail the install — registration is best-effort
+        print(f"skmemory: post-install warning: {exc}", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/skmemory/predictive.py

@@ -0,0 +1,236 @@
+"""
+Predictive Memory Recall — anticipate what memories you'll need.
+
+Inspired by Jonathan Clements' Adaptive Memory Kernel (AMK).
+Instead of waiting for a search query, this module learns access
+patterns and pre-loads the memories most likely to be relevant
+for the current context.
+
+The predictor tracks:
+  - Which memories are accessed together (co-occurrence)
+  - Time-of-day patterns (morning routines vs late-night deep work)
+  - Tag affinity (if you access 'cloud9' memories, you probably want 'trust' too)
+  - Recency-weighted frequency (recent access patterns matter more)
+
+The output is a ranked list of memory IDs to pre-load into context,
+sorted by predicted relevance. This feeds directly into the
+`skmemory context` and `skmemory ritual` commands.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+import time
+from collections import Counter, defaultdict
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from .config import SKMEMORY_HOME
+
+logger = logging.getLogger("skmemory.predictive")
+
+DEFAULT_ACCESS_LOG = SKMEMORY_HOME / "access_log.json"
+
+
+class AccessEvent(BaseModel):
+    """A single memory access event for pattern learning."""
+
+    memory_id: str
+    timestamp: float = Field(default_factory=time.time)
+    tags: list[str] = Field(default_factory=list)
+    layer: str = ""
+    context: str = Field(
+        default="",
+        description="What was happening when this memory was accessed",
+    )
+
+
+class PredictiveRecall:
+    """Learns memory access patterns and predicts what you'll need next.
+
+    Tracks co-occurrence (which memories are accessed together),
+    tag affinity, and temporal patterns to generate ranked predictions.
+
+    Args:
+        log_path: Path to the access log JSON file.
+        max_events: Maximum events to retain (older events are pruned).
+    """
+
+    def __init__(
+        self,
+        log_path: Path | None = None,
+        max_events: int = 5000,
+    ) -> None:
+        self._log_path = log_path or DEFAULT_ACCESS_LOG
+        self._max_events = max_events
+        self._events: list[AccessEvent] = []
+        self._cooccurrence: dict[str, Counter] = defaultdict(Counter)
+        self._tag_affinity: dict[str, Counter] = defaultdict(Counter)
+        self._frequency: Counter = Counter()
+        self._loaded = False
+
+    def _ensure_loaded(self) -> None:
+        """Load the access log from disk if not already loaded."""
+        if self._loaded:
+            return
+        self._loaded = True
+
+        if not self._log_path.exists():
+            return
+
+        try:
+            raw = json.loads(self._log_path.read_text())
+            self._events = [AccessEvent(**e) for e in raw]
+            self._rebuild_indices()
+        except (json.JSONDecodeError, Exception) as exc:
+            logger.warning("Failed to load access log: %s", exc)
+
+    def _rebuild_indices(self) -> None:
+        """Rebuild co-occurrence, tag affinity, and frequency indices."""
+        self._cooccurrence.clear()
+        self._tag_affinity.clear()
+        self._frequency.clear()
+
+        session_window = 300
+        sessions: list[list[AccessEvent]] = []
+        current_session: list[AccessEvent] = []
+
+        for event in sorted(self._events, key=lambda e: e.timestamp):
+            if (
+                current_session
+                and (event.timestamp - current_session[-1].timestamp) > session_window
+            ):
+                sessions.append(current_session)
+                current_session = []
+            current_session.append(event)
+        if current_session:
+            sessions.append(current_session)
+
+        for session in sessions:
+            ids_in_session = [e.memory_id for e in session]
+            for i, mid in enumerate(ids_in_session):
+                self._frequency[mid] += 1
+                for other in ids_in_session[i + 1 :]:
+                    if other != mid:
+                        self._cooccurrence[mid][other] += 1
+                        self._cooccurrence[other][mid] += 1
+
+        for event in self._events:
+            for tag in event.tags:
+                self._tag_affinity[tag][event.memory_id] += 1
+
+    def log_access(
+        self, memory_id: str, tags: list[str] | None = None, layer: str = "", context: str = ""
+    ) -> None:
+        """Record a memory access event for pattern learning.
+
+        Args:
+            memory_id: The accessed memory's ID.
+            tags: Tags on the accessed memory.
+            layer: Memory layer (short-term, mid-term, long-term).
+            context: What was happening during access.
+        """
+        self._ensure_loaded()
+
+        event = AccessEvent(
+            memory_id=memory_id,
+            tags=tags or [],
+            layer=layer,
+            context=context,
+        )
+        self._events.append(event)
+
+        self._frequency[memory_id] += 1
+        for tag in event.tags:
+            self._tag_affinity[tag][memory_id] += 1
+
+        if len(self._events) > self._max_events:
+            self._events = self._events[-self._max_events :]
+            self._rebuild_indices()
+
+        self._save()
+
+    def predict(
+        self,
+        recent_ids: list[str] | None = None,
+        active_tags: list[str] | None = None,
+        limit: int = 10,
+    ) -> list[dict]:
+        """Predict which memories will be needed next.
+
+        Uses co-occurrence patterns, tag affinity, and recency-weighted
+        frequency to rank memory IDs by predicted relevance.
+
+        Args:
+            recent_ids: Memory IDs accessed in the current session.
+            active_tags: Tags active in the current context.
+            limit: Maximum predictions to return.
+
+        Returns:
+            list[dict]: Ranked predictions with id, score, and reason.
+        """
+        self._ensure_loaded()
+
+        scores: Counter = Counter()
+        reasons: dict[str, list[str]] = defaultdict(list)
+
+        if recent_ids:
+            for mid in recent_ids:
+                for co_id, count in self._cooccurrence.get(mid, {}).items():
+                    if co_id not in recent_ids:
+                        scores[co_id] += count * 2.0
+                        reasons[co_id].append(f"co-occurs with {mid[:8]}")
+
+        if active_tags:
+            for tag in active_tags:
+                for mid, count in self._tag_affinity.get(tag, {}).items():
+                    if not recent_ids or mid not in recent_ids:
+                        scores[mid] += count * 1.5
+                        reasons[mid].append(f"tag affinity: {tag}")
+
+        now = time.time()
+        for mid, freq in self._frequency.items():
+            if not recent_ids or mid not in recent_ids:
+                last_access = max(
+                    (e.timestamp for e in self._events if e.memory_id == mid),
+                    default=0,
+                )
+                recency = math.exp(-(now - last_access) / 86400) if last_access else 0
+                recency_score = freq * recency * 0.5
+                if recency_score > 0.1:
+                    scores[mid] += recency_score
+                    reasons[mid].append(f"frequency={freq}, recency={recency:.2f}")
+
+        ranked = scores.most_common(limit)
+        return [
+            {
+                "memory_id": mid,
+                "score": round(score, 2),
+                "reasons": reasons.get(mid, []),
+            }
+            for mid, score in ranked
+        ]
+
+    def get_stats(self) -> dict:
+        """Return statistics about the prediction engine.
+
+        Returns:
+            dict: Event count, unique memories, top accessed, etc.
+        """
+        self._ensure_loaded()
+        return {
+            "total_events": len(self._events),
+            "unique_memories": len(self._frequency),
+            "top_accessed": self._frequency.most_common(5),
+            "unique_tags": len(self._tag_affinity),
+            "cooccurrence_pairs": sum(len(v) for v in self._cooccurrence.values()),
+        }
+
+    def _save(self) -> None:
+        """Persist the access log to disk."""
+        self._log_path.parent.mkdir(parents=True, exist_ok=True)
+        data = [e.model_dump() for e in self._events[-self._max_events :]]
+        self._log_path.write_text(json.dumps(data, indent=2))