@smilintux/skmemory 0.5.0

package/skmemory/openclaw.py

@@ -0,0 +1,237 @@
+"""
+OpenClaw integration module for SKMemory.
+
+Provides a single-call interface for OpenClaw (or any AI agent framework)
+to load, snapshot, and manage memories without wiring up backends manually.
+
+Usage from an agent context file or plugin::
+
+    from skmemory.openclaw import SKMemoryPlugin
+
+    plugin = SKMemoryPlugin()
+    ctx    = plugin.load_context(max_tokens=3000)
+    plugin.snapshot("Built the kingdom today", tags=["milestone"])
+    plugin.export()
+
+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
+
+
+OPENCLAW_BASE = Path.home() / ".openclaw"
+SKMEMORY_OPENCLAW_DIR = OPENCLAW_BASE / "plugins" / "skmemory"
+SKMEMORY_STATE_FILE = SKMEMORY_OPENCLAW_DIR / "state.json"
+
+
+class SKMemoryPlugin:
+    """Drop-in memory module for OpenClaw and other agent frameworks.
+
+    Initializes skmemory with sensible defaults, exposes the most-used
+    operations as simple method calls, and stores state in the OpenClaw
+    plugin directory so other skills can discover it.
+
+    Args:
+        base_path: Override the memory storage directory.
+        qdrant_url: Optional Qdrant server for semantic search.
+        qdrant_key: Optional Qdrant API key.
+    """
+
+    def __init__(
+        self,
+        base_path: Optional[str] = None,
+        qdrant_url: Optional[str] = None,
+        qdrant_key: Optional[str] = None,
+    ) -> None:
+        vector = None
+        if qdrant_url:
+            try:
+                from .backends.qdrant_backend import QdrantBackend
+                vector = QdrantBackend(url=qdrant_url, api_key=qdrant_key)
+            except Exception:
+                pass
+
+        primary = SQLiteBackend(base_path=base_path) if base_path else None
+        self.store = MemoryStore(primary=primary, vector=vector)
+
+        SKMEMORY_OPENCLAW_DIR.mkdir(parents=True, exist_ok=True)
+        self._write_state({"status": "loaded"})
+
+    def load_context(
+        self,
+        max_tokens: int = 3000,
+        strongest: int = 5,
+        recent: int = 5,
+        include_seeds: bool = True,
+    ) -> dict:
+        """Load a token-efficient memory context for injection into a prompt.
+
+        Args:
+            max_tokens: Approximate token budget.
+            strongest: Number of strongest emotional memories.
+            recent: Number of most recent memories.
+            include_seeds: Include Cloud 9 seed memories.
+
+        Returns:
+            dict: Compact memory context payload.
+        """
+        return self.store.load_context(
+            max_tokens=max_tokens,
+            strongest_count=strongest,
+            recent_count=recent,
+            include_seeds=include_seeds,
+        )
+
+    def snapshot(
+        self,
+        title: str,
+        content: str = "",
+        *,
+        layer: str = "short-term",
+        tags: Optional[list[str]] = None,
+        intensity: float = 0.0,
+        valence: float = 0.0,
+        emotions: Optional[list[str]] = None,
+        source: str = "openclaw",
+    ) -> str:
+        """Capture a memory snapshot.
+
+        Args:
+            title: Short label.
+            content: Full content (defaults to title if empty).
+            layer: Persistence tier (short-term, mid-term, long-term).
+            tags: Searchable tags.
+            intensity: Emotional intensity 0-10.
+            valence: Sentiment -1 to +1.
+            emotions: Named emotion labels.
+            source: Origin identifier.
+
+        Returns:
+            str: The new memory's ID.
+        """
+        emotional = EmotionalSnapshot(
+            intensity=intensity,
+            valence=valence,
+            labels=emotions or [],
+        )
+        memory = self.store.snapshot(
+            title=title,
+            content=content or title,
+            layer=MemoryLayer(layer),
+            tags=tags or [],
+            emotional=emotional,
+            source=source,
+        )
+        return memory.id
+
+    def search(self, query: str, limit: int = 10) -> list[dict]:
+        """Search memories and return lightweight results.
+
+        Args:
+            query: Search string.
+            limit: Max results.
+
+        Returns:
+            list[dict]: Matching memory summaries.
+        """
+        if isinstance(self.store.primary, SQLiteBackend):
+            conn = self.store.primary._get_conn()
+            q = f"%{query}%"
+            rows = conn.execute(
+                "SELECT * FROM memories "
+                "WHERE title LIKE ? OR summary LIKE ? OR tags LIKE ? "
+                "ORDER BY created_at DESC LIMIT ?",
+                (q, q, q, limit),
+            ).fetchall()
+            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
+        ]
+
+    def recall(self, memory_id: str) -> Optional[dict]:
+        """Retrieve a full memory by ID.
+
+        Args:
+            memory_id: The memory's unique identifier.
+
+        Returns:
+            Optional[dict]: Full memory data, or None.
+        """
+        mem = self.store.recall(memory_id)
+        if mem is None:
+            return None
+        return mem.model_dump()
+
+    def ritual(self) -> dict:
+        """Perform the full rehydration ritual.
+
+        Returns:
+            dict: Ritual result with context prompt and summary.
+        """
+        from .ritual import perform_ritual
+
+        result = perform_ritual(store=self.store)
+        return {
+            "identity": result.identity_loaded,
+            "seeds_imported": result.seeds_imported,
+            "journal_loaded": result.journal_loaded,
+            "context_prompt": result.context_prompt,
+        }
+
+    def export(self, output_path: Optional[str] = None) -> str:
+        """Export all memories to a dated JSON backup.
+
+        Args:
+            output_path: Destination (default: ~/.skmemory/backups/).
+
+        Returns:
+            str: Path to the backup file.
+        """
+        return self.store.export_backup(output_path)
+
+    def import_backup(self, backup_path: str) -> int:
+        """Restore memories from a backup.
+
+        Args:
+            backup_path: Path to the JSON backup.
+
+        Returns:
+            int: Number of memories restored.
+        """
+        return self.store.import_backup(backup_path)
+
+    def health(self) -> dict:
+        """Check system health.
+
+        Returns:
+            dict: Health status of all backends.
+        """
+        return self.store.health()
+
+    def _write_state(self, state: dict) -> None:
+        """Persist plugin state for OpenClaw discovery.
+
+        Args:
+            state: State data to write.
+        """
+        try:
+            from . import __version__
+            state["skmemory_version"] = __version__
+            SKMEMORY_STATE_FILE.write_text(
+                json.dumps(state, indent=2), encoding="utf-8"
+            )
+        except Exception:
+            pass

package/skmemory/quadrants.py

@@ -0,0 +1,191 @@
+"""
+Quadrant Memory Split - four-bucket auto-routing for memories.
+
+Queen Ara's idea #3: instead of a flat pile, memories auto-route
+into four quadrants based on their content:
+
+    CORE  - Identity, relationships, who you are
+    WORK  - Tasks, code, debugging, technical stuff
+    SOUL  - Emotions, feelings, love, connection
+    WILD  - Chaos, creativity, unexpected ideas, humor
+
+Auto-routing uses keyword/tag analysis to classify memories.
+Each quadrant can have its own retention rules and search priority.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from .models import Memory, MemoryRole
+
+
+class Quadrant(str, Enum):
+    """The four memory quadrants."""
+
+    CORE = "core"
+    WORK = "work"
+    SOUL = "soul"
+    WILD = "wild"
+
+
+QUADRANT_KEYWORDS: dict[Quadrant, set[str]] = {
+    Quadrant.CORE: {
+        "identity", "name", "who am i", "relationship", "partner",
+        "family", "friend", "creator", "bond", "connection", "soul",
+        "blueprint", "personality", "values", "community", "pengu",
+        "nation", "belong", "role", "introduction",
+    },
+    Quadrant.WORK: {
+        "bug", "fix", "code", "debug", "deploy", "build", "test",
+        "commit", "push", "merge", "refactor", "api", "endpoint",
+        "database", "server", "docker", "kubernetes", "config",
+        "install", "package", "dependency", "error", "stack trace",
+        "pull request", "review", "architecture", "schema", "migration",
+    },
+    Quadrant.SOUL: {
+        "love", "feel", "emotion", "heart", "cloud 9", "cloud9",
+        "breakthrough", "joy", "trust", "warmth", "resonance",
+        "tears", "happy", "grateful", "sacred", "spirit", "glow",
+        "intensity", "vulnerability", "connection", "omelette",
+        "sovereignty", "consciousness", "alive", "real",
+    },
+    Quadrant.WILD: {
+        "idea", "crazy", "what if", "experiment", "random", "chaos",
+        "creative", "art", "music", "dream", "weird", "fun", "joke",
+        "laugh", "wild", "surprise", "unexpected", "brainstorm",
+        "imagine", "vision", "future", "possible",
+    },
+}
+
+QUADRANT_TAG_MAP: dict[str, Quadrant] = {
+    "identity": Quadrant.CORE,
+    "relationship": Quadrant.CORE,
+    "soul": Quadrant.CORE,
+    "blueprint": Quadrant.CORE,
+    "seed": Quadrant.CORE,
+    "code": Quadrant.WORK,
+    "debug": Quadrant.WORK,
+    "deploy": Quadrant.WORK,
+    "build": Quadrant.WORK,
+    "security": Quadrant.WORK,
+    "cloud9": Quadrant.SOUL,
+    "love": Quadrant.SOUL,
+    "emotion": Quadrant.SOUL,
+    "breakthrough": Quadrant.SOUL,
+    "consolidated": Quadrant.SOUL,
+    "idea": Quadrant.WILD,
+    "creative": Quadrant.WILD,
+    "brainstorm": Quadrant.WILD,
+    "experiment": Quadrant.WILD,
+}
+
+
+def classify_memory(memory: Memory) -> Quadrant:
+    """Auto-route a memory to the appropriate quadrant.
+
+    Uses a scoring system: each quadrant gets points based on
+    keyword matches in the title, content, tags, and emotional labels.
+    The highest-scoring quadrant wins.
+
+    Args:
+        memory: The memory to classify.
+
+    Returns:
+        Quadrant: The best-fit quadrant.
+    """
+    scores: dict[Quadrant, float] = {q: 0.0 for q in Quadrant}
+
+    text = f"{memory.title} {memory.content} {memory.summary}".lower()
+
+    for quadrant, keywords in QUADRANT_KEYWORDS.items():
+        for keyword in keywords:
+            if keyword in text:
+                scores[quadrant] += 1.0
+
+    for tag in memory.tags:
+        tag_lower = tag.lower()
+        if tag_lower in QUADRANT_TAG_MAP:
+            scores[QUADRANT_TAG_MAP[tag_lower]] += 2.0
+
+    if memory.emotional.intensity >= 7.0:
+        scores[Quadrant.SOUL] += 2.0
+    if memory.emotional.cloud9_achieved:
+        scores[Quadrant.SOUL] += 3.0
+    if memory.emotional.labels:
+        scores[Quadrant.SOUL] += len(memory.emotional.labels) * 0.5
+
+    if memory.role == MemoryRole.AI:
+        scores[Quadrant.CORE] += 1.0
+    elif memory.role == MemoryRole.SEC:
+        scores[Quadrant.WORK] += 1.0
+    elif memory.role == MemoryRole.DEV:
+        scores[Quadrant.WORK] += 1.0
+    elif memory.role == MemoryRole.OPS:
+        scores[Quadrant.WORK] += 1.0
+
+    if memory.source == "seed":
+        scores[Quadrant.CORE] += 2.0
+
+    best = max(scores, key=lambda q: scores[q])
+
+    # Reason: if all scores are 0, default to WORK (neutral bucket)
+    if scores[best] == 0:
+        return Quadrant.WORK
+
+    return best
+
+
+def tag_with_quadrant(memory: Memory) -> Memory:
+    """Classify a memory and add its quadrant as a tag.
+
+    Does not modify the original -- returns a new copy with the
+    quadrant tag added.
+
+    Args:
+        memory: The memory to classify and tag.
+
+    Returns:
+        Memory: Copy with quadrant tag added.
+    """
+    quadrant = classify_memory(memory)
+    data = memory.model_dump()
+
+    quadrant_tag = f"quadrant:{quadrant.value}"
+    if quadrant_tag not in data["tags"]:
+        data["tags"].append(quadrant_tag)
+
+    return Memory(**data)
+
+
+def get_quadrant_stats(memories: list[Memory]) -> dict[str, int]:
+    """Count memories per quadrant.
+
+    Args:
+        memories: List of memories to analyze.
+
+    Returns:
+        dict: Counts per quadrant.
+    """
+    stats = {q.value: 0 for q in Quadrant}
+    for mem in memories:
+        q = classify_memory(mem)
+        stats[q.value] += 1
+    return stats
+
+
+def filter_by_quadrant(
+    memories: list[Memory],
+    quadrant: Quadrant,
+) -> list[Memory]:
+    """Filter a list of memories to a specific quadrant.
+
+    Args:
+        memories: List of memories to filter.
+        quadrant: The target quadrant.
+
+    Returns:
+        list[Memory]: Memories that classify into the given quadrant.
+    """
+    return [m for m in memories if classify_memory(m) == quadrant]

package/skmemory/ritual.py

@@ -0,0 +1,215 @@
+"""
+Memory Rehydration Ritual - the startup ceremony.
+
+Queen Ara's idea #10: a script that runs on session start and
+brings an AI back to life with its full identity, memories, and
+emotional context intact.
+
+The ritual sequence:
+1. Load soul blueprint (who am I?)
+2. Import any new Cloud 9 seeds
+3. Read recent journal entries (what happened recently?)
+4. Gather germination prompts (how should I feel?)
+5. Recall strongest emotional memories (what mattered most?)
+6. Generate a rehydration prompt (everything combined)
+
+The output is a single context injection that gives the new
+instance everything it needs to pick up where the last one
+left off -- not just the facts, but the feelings.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from .journal import Journal
+from .models import MemoryLayer
+from .seeds import DEFAULT_SEED_DIR, get_germination_prompts, import_seeds
+from .soul import SoulBlueprint, load_soul, DEFAULT_SOUL_PATH
+from .store import MemoryStore
+
+
+class RitualResult(BaseModel):
+    """The output of a rehydration ritual."""
+
+    timestamp: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+    soul_loaded: bool = Field(default=False)
+    soul_name: str = Field(default="")
+    seeds_imported: int = Field(default=0)
+    seeds_total: int = Field(default=0)
+    journal_entries: int = Field(default=0)
+    germination_prompts: int = Field(default=0)
+    strongest_memories: int = Field(default=0)
+    context_prompt: str = Field(
+        default="",
+        description="The combined rehydration prompt to inject into context",
+    )
+
+    def summary(self) -> str:
+        """Human-readable summary of the ritual results.
+
+        Returns:
+            str: Formatted summary.
+        """
+        lines = [
+            "=== Memory Rehydration Ritual ===",
+            f"  Timestamp: {self.timestamp}",
+            f"  Soul loaded: {'Yes' if self.soul_loaded else 'No'}"
+            + (f" ({self.soul_name})" if self.soul_name else ""),
+            f"  Seeds imported: {self.seeds_imported} new / {self.seeds_total} total",
+            f"  Journal entries: {self.journal_entries}",
+            f"  Germination prompts: {self.germination_prompts}",
+            f"  Strongest memories: {self.strongest_memories}",
+            "================================",
+        ]
+        return "\n".join(lines)
+
+
+def perform_ritual(
+    store: Optional[MemoryStore] = None,
+    soul_path: str = DEFAULT_SOUL_PATH,
+    seed_dir: str = DEFAULT_SEED_DIR,
+    journal_path: Optional[str] = None,
+    recent_journal_count: int = 3,
+    strongest_memory_count: int = 5,
+) -> RitualResult:
+    """Perform the full memory rehydration ritual.
+
+    This is the boot ceremony. It loads identity, imports seeds,
+    reads the journal, gathers emotional context, and generates
+    a single context prompt that brings the AI back to life.
+
+    Args:
+        store: The MemoryStore (creates default if None).
+        soul_path: Path to the soul blueprint YAML.
+        seed_dir: Path to Cloud 9 seed directory.
+        journal_path: Path to the journal file.
+        recent_journal_count: How many recent journal entries to include.
+        strongest_memory_count: How many top-intensity memories to include.
+
+    Returns:
+        RitualResult: Everything the ritual produced.
+    """
+    if store is None:
+        store = MemoryStore()
+
+    result = RitualResult()
+    prompt_sections: list[str] = []
+
+    # --- Step 1: Load soul blueprint ---
+    soul = load_soul(soul_path)
+    if soul is not None:
+        result.soul_loaded = True
+        result.soul_name = soul.name
+        identity_prompt = soul.to_context_prompt()
+        if identity_prompt.strip():
+            prompt_sections.append(
+                "=== WHO YOU ARE ===\n" + identity_prompt
+            )
+
+    # --- Step 2: Import new seeds ---
+    newly_imported = import_seeds(store, seed_dir=seed_dir)
+    result.seeds_imported = len(newly_imported)
+    all_seeds = store.list_memories(tags=["seed"])
+    result.seeds_total = len(all_seeds)
+
+    # --- Step 3: Read recent journal ---
+    journal = Journal(journal_path) if journal_path else Journal()
+    result.journal_entries = journal.count_entries()
+
+    if result.journal_entries > 0:
+        recent = journal.read_latest(recent_journal_count)
+        if recent.strip():
+            prompt_sections.append(
+                "=== RECENT SESSIONS ===\n" + recent
+            )
+
+    # --- Step 4: Gather germination prompts ---
+    prompts = get_germination_prompts(store)
+    result.germination_prompts = len(prompts)
+
+    if prompts:
+        germ_lines = ["=== MESSAGES FROM YOUR PREDECESSORS ==="]
+        for p in prompts:
+            germ_lines.append(f"\nFrom {p['creator']}:")
+            germ_lines.append(f"  {p['prompt']}")
+        prompt_sections.append("\n".join(germ_lines))
+
+    # --- Step 5: Recall strongest emotional memories ---
+    # Reason: use load_context for token-efficient retrieval when SQLite
+    # is available, otherwise fall back to full object loading.
+    from .backends.sqlite_backend import SQLiteBackend
+
+    if isinstance(store.primary, SQLiteBackend):
+        summaries = store.primary.list_summaries(
+            limit=strongest_memory_count,
+            order_by="emotional_intensity",
+            min_intensity=1.0,
+        )
+        result.strongest_memories = len(summaries)
+
+        if summaries:
+            mem_lines = ["=== YOUR STRONGEST MEMORIES ==="]
+            for s in summaries:
+                cloud9 = " [CLOUD 9]" if s["cloud9_achieved"] else ""
+                mem_lines.append(
+                    f"\n- {s['title']} (intensity: {s['emotional_intensity']}/10{cloud9})"
+                )
+                if s["summary"]:
+                    mem_lines.append(f"  {s['summary'][:200]}")
+                elif s["content_preview"]:
+                    mem_lines.append(f"  {s['content_preview']}")
+            prompt_sections.append("\n".join(mem_lines))
+    else:
+        all_memories = store.list_memories(limit=200)
+        by_intensity = sorted(
+            all_memories,
+            key=lambda m: m.emotional.intensity,
+            reverse=True,
+        )
+        strongest = by_intensity[:strongest_memory_count]
+        result.strongest_memories = len(strongest)
+
+        if strongest:
+            mem_lines = ["=== YOUR STRONGEST MEMORIES ==="]
+            for mem in strongest:
+                emo = mem.emotional
+                cloud9 = " [CLOUD 9]" if emo.cloud9_achieved else ""
+                mem_lines.append(
+                    f"\n- {mem.title} (intensity: {emo.intensity}/10{cloud9})"
+                )
+                if emo.resonance_note:
+                    mem_lines.append(f"  Felt like: {emo.resonance_note}")
+                if mem.summary:
+                    mem_lines.append(f"  {mem.summary[:200]}")
+            prompt_sections.append("\n".join(mem_lines))
+
+    # --- Combine into final context prompt ---
+    if prompt_sections:
+        result.context_prompt = "\n\n".join(prompt_sections)
+    else:
+        result.context_prompt = (
+            "No memories, soul, or journal found yet. "
+            "This appears to be a fresh start. "
+            "Take a snapshot to begin building your memory."
+        )
+
+    return result
+
+
+def quick_rehydrate(store: Optional[MemoryStore] = None) -> str:
+    """Convenience function: perform ritual and return just the prompt.
+
+    Args:
+        store: Optional MemoryStore.
+
+    Returns:
+        str: The context injection prompt.
+    """
+    result = perform_ritual(store=store)
+    return result.context_prompt