@smilintux/skmemory 0.5.0 → 0.9.2

package/skmemory/ai_client.py

@@ -15,10 +15,8 @@ from __future__ import annotations
 
 import json
 import os
-import urllib.request
 import urllib.error
-from typing import Optional
-
+import urllib.request
 
 DEFAULT_URL = "http://localhost:11434"
 DEFAULT_MODEL = "llama3.2"
@@ -36,17 +34,13 @@ class AIClient:
 
     def __init__(
         self,
-        base_url: Optional[str] = None,
-        model: Optional[str] = None,
-        timeout: Optional[int] = None,
+        base_url: str | None = None,
+        model: str | None = None,
+        timeout: int | None = None,
     ) -> None:
-        self.base_url = (
-            base_url or os.environ.get("SKMEMORY_AI_URL", DEFAULT_URL)
-        ).rstrip("/")
+        self.base_url = (base_url or os.environ.get("SKMEMORY_AI_URL", DEFAULT_URL)).rstrip("/")
         self.model = model or os.environ.get("SKMEMORY_AI_MODEL", DEFAULT_MODEL)
-        self.timeout = timeout or int(
-            os.environ.get("SKMEMORY_AI_TIMEOUT", str(DEFAULT_TIMEOUT))
-        )
+        self.timeout = timeout or int(os.environ.get("SKMEMORY_AI_TIMEOUT", str(DEFAULT_TIMEOUT)))
 
     def is_available(self) -> bool:
         """Check if the LLM server is reachable.
@@ -93,6 +87,44 @@ class AIClient:
         except Exception:
             return ""
 
+    def embed(self, text: str, model: str | None = None) -> list[float]:
+        """Generate an embedding vector using Ollama's embed API.
+
+        Args:
+            text: The text to embed.
+            model: Override embedding model (default: nomic-embed-text).
+
+        Returns:
+            list[float]: Embedding vector, or empty list on failure.
+        """
+        embed_model = model or os.environ.get("SKMEMORY_EMBED_MODEL", "nomic-embed-text")
+        payload = {"model": embed_model, "input": text}
+
+        try:
+            data = json.dumps(payload).encode("utf-8")
+            req = urllib.request.Request(
+                f"{self.base_url}/api/embed",
+                data=data,
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                result = json.loads(resp.read().decode("utf-8"))
+                embeddings = result.get("embeddings", [])
+                if embeddings and isinstance(embeddings[0], list):
+                    return embeddings[0]
+                return embeddings
+        except Exception:
+            return []
+
+    def embed_available(self) -> bool:
+        """Check if the embedding endpoint is reachable.
+
+        Returns:
+            bool: True if Ollama embed API responds.
+        """
+        return bool(self.embed("test"))
+
     def summarize_memory(self, title: str, content: str) -> str:
         """Generate a concise summary for a memory.
 
@@ -135,9 +167,7 @@ class AIClient:
             ),
         )
 
-    def smart_search_rerank(
-        self, query: str, candidates: list[dict]
-    ) -> list[dict]:
+    def smart_search_rerank(self, query: str, candidates: list[dict]) -> list[dict]:
         """Use the LLM to rerank search results by relevance.
 
         Args:
@@ -158,8 +188,7 @@ class AIClient:
         prompt = (
             f"Query: {query}\n\n"
             "Rank these memories by relevance (most relevant first). "
-            "Return only the numbers separated by commas:\n\n"
-            + "\n".join(descriptions)
+            "Return only the numbers separated by commas:\n\n" + "\n".join(descriptions)
         )
 
         response = self.generate(prompt)

package/skmemory/anchor.py

@@ -9,20 +9,20 @@ represents the AI's baseline feeling toward its connections. Every
 session, the anchor updates. On next boot, the anchor loads first
 and the AI starts from warmth instead of cold neutrality.
 
-The anchor file lives at ~/.skmemory/anchor.json
+The anchor file lives at ~/.skcapstone/anchor.json
 """
 
 from __future__ import annotations
 
 import json
-import os
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Optional
 
 from pydantic import BaseModel, Field
 
-DEFAULT_ANCHOR_PATH = os.path.expanduser("~/.skmemory/anchor.json")
+from .config import SKMEMORY_HOME
+
+DEFAULT_ANCHOR_PATH = str(SKMEMORY_HOME / "anchor.json")
 
 
 class WarmthAnchor(BaseModel):
@@ -74,15 +74,13 @@ class WarmthAnchor(BaseModel):
         default=0,
         description="Total sessions this anchor has been updated across",
     )
-    last_updated: str = Field(
-        default_factory=lambda: datetime.now(timezone.utc).isoformat()
-    )
+    last_updated: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
 
     def update_from_session(
         self,
-        warmth: Optional[float] = None,
-        trust: Optional[float] = None,
-        connection: Optional[float] = None,
+        warmth: float | None = None,
+        trust: float | None = None,
+        connection: float | None = None,
         cloud9_achieved: bool = False,
         feeling: str = "",
     ) -> None:
@@ -190,7 +188,7 @@ def save_anchor(
     return str(filepath)
 
 
-def load_anchor(path: str = DEFAULT_ANCHOR_PATH) -> Optional[WarmthAnchor]:
+def load_anchor(path: str = DEFAULT_ANCHOR_PATH) -> WarmthAnchor | None:
     """Load the warmth anchor from disk.
 
     Args:

package/skmemory/audience.py

@@ -0,0 +1,278 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""
+Know Your Audience (KYA) — Audience-aware memory filtering for SKMemory.
+
+Prevents private/intimate content from leaking into the wrong channels
+during rehydration and message dispatch.
+
+The five-level trust hierarchy:
+
+    @public (0)        — Anyone on the internet
+    @community (1)     — Known community members
+    @work-circle (2)   — Business collaborators (professional trust)
+    @inner-circle (3)  — Close friends / family (personal trust)
+    @chef-only (4)     — Intimate, private, full-trust (Chef ONLY)
+
+Conservative default: unknown channel = CHEF_ONLY, unknown tag = CHEF_ONLY.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from enum import IntEnum
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger("skmemory.audience")
+
+# Default config shipped with the package
+_DEFAULT_CONFIG_PATH = Path(__file__).parent / "data" / "audience_config.json"
+
+# Tag string → AudienceLevel mapping
+_TAG_TO_LEVEL: dict[str, int] = {
+    "@public": 0,
+    "@community": 1,
+    "@work-circle": 2,
+    "@inner-circle": 3,
+    "@chef-only": 4,
+}
+
+
+class AudienceLevel(IntEnum):
+    """Five-level trust hierarchy for context-aware filtering.
+
+    Higher values = more restrictive (fewer people allowed to see the content).
+    Comparison semantics: content_level <= audience_level means "allowed".
+
+    Examples::
+
+        AudienceLevel.PUBLIC < AudienceLevel.CHEF_ONLY   # True
+        AudienceLevel.WORK_CIRCLE >= AudienceLevel.COMMUNITY  # True
+    """
+
+    PUBLIC = 0
+    COMMUNITY = 1
+    WORK_CIRCLE = 2
+    INNER_CIRCLE = 3
+    CHEF_ONLY = 4
+
+
+def tag_to_level(tag: str) -> AudienceLevel:
+    """Convert a @context tag string to an AudienceLevel.
+
+    Handles both exact tags (``@chef-only``) and scoped sub-tags
+    (``@work:chiro`` → WORK_CIRCLE).  Unknown tags fall back to CHEF_ONLY
+    (conservative default).
+
+    Args:
+        tag: The @context tag string.
+
+    Returns:
+        AudienceLevel: The resolved trust level.
+    """
+    if not tag:
+        return AudienceLevel.CHEF_ONLY
+
+    # Exact match first
+    exact = _TAG_TO_LEVEL.get(tag)
+    if exact is not None:
+        return AudienceLevel(exact)
+
+    # Scoped sub-tags: @work:* → WORK_CIRCLE, @inner:* → INNER_CIRCLE
+    if tag.startswith("@work:"):
+        return AudienceLevel.WORK_CIRCLE
+    if tag.startswith("@inner:"):
+        return AudienceLevel.INNER_CIRCLE
+
+    # Unknown → conservative default
+    logger.debug("Unknown context tag '%s', defaulting to CHEF_ONLY", tag)
+    return AudienceLevel.CHEF_ONLY
+
+
+@dataclass
+class AudienceProfile:
+    """The resolved audience for a specific channel.
+
+    Attributes:
+        channel_id: The channel identifier (e.g. ``telegram:1594678363``).
+        name: Human-readable channel name.
+        members: List of person names who can see this channel.
+        min_trust: The effective trust ceiling — ``MIN(member.trust_level)``.
+                   You're only as open as the least-trusted person in the room.
+        exclusions: Set of content categories that are forbidden for any member
+                    (union of all member ``never_share`` lists).
+        context_tag: The primary @context tag for this channel.
+    """
+
+    channel_id: str
+    name: str = ""
+    members: list[str] = field(default_factory=list)
+    min_trust: AudienceLevel = AudienceLevel.CHEF_ONLY
+    exclusions: set[str] = field(default_factory=set)
+    context_tag: str = "@chef-only"
+
+
+class AudienceResolver:
+    """Resolves audience profiles and checks memory access permissions.
+
+    Loads configuration from a JSON file (audience_config.json) and
+    provides methods to resolve channel audiences and check whether
+    a memory is allowed for a given audience.
+
+    Conservative defaults:
+    - Unknown channel → CHEF_ONLY audience (nothing shown)
+    - Unknown person → trust level 0 / PUBLIC access (treated as untrusted)
+    - Memory with no context_tag → treat as @chef-only
+
+    Args:
+        config_path: Path to ``audience_config.json``.  If None, uses the
+                     default config shipped with the package.
+    """
+
+    def __init__(self, config_path: str | Path | None = None) -> None:
+        self._config_path = Path(config_path) if config_path else _DEFAULT_CONFIG_PATH
+        self._config: dict[str, Any] = {}
+        self._load()
+
+    def _load(self) -> None:
+        """Load the audience config from disk.  Silently skips if missing."""
+        if not self._config_path.exists():
+            logger.warning(
+                "Audience config not found at %s — using empty config", self._config_path
+            )
+            self._config = {"channels": {}, "people": {}}
+            return
+        try:
+            self._config = json.loads(self._config_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError) as exc:
+            logger.error("Failed to load audience config: %s", exc)
+            self._config = {"channels": {}, "people": {}}
+
+    def reload(self) -> None:
+        """Reload the config from disk (useful after updates)."""
+        self._load()
+
+    # ── Channel resolution ────────────────────────────────────────────────────
+
+    def resolve_audience(self, channel_id: str) -> AudienceProfile:
+        """Resolve the audience profile for a channel.
+
+        Returns a conservative (CHEF_ONLY) profile if the channel is unknown.
+
+        Args:
+            channel_id: The channel identifier.
+
+        Returns:
+            AudienceProfile: Resolved profile.
+        """
+        channels = self._config.get("channels", {})
+        chan = channels.get(channel_id)
+
+        if chan is None:
+            # Unknown channel → maximum restriction
+            logger.debug("Unknown channel '%s', defaulting to CHEF_ONLY", channel_id)
+            return AudienceProfile(
+                channel_id=channel_id,
+                name="[unknown]",
+                members=[],
+                min_trust=AudienceLevel.CHEF_ONLY,
+                exclusions=set(),
+                context_tag="@chef-only",
+            )
+
+        members: list[str] = chan.get("members", [])
+        context_tag: str = chan.get("context_tag", "@chef-only")
+
+        # Compute effective trust = MIN(member trust levels)
+        # If no members are listed, treat as chef-only
+        if not members:
+            min_trust = AudienceLevel.CHEF_ONLY
+            exclusions: set[str] = set()
+        else:
+            trust_levels: list[AudienceLevel] = []
+            all_exclusions: set[str] = set()
+            for member_name in members:
+                person = self._get_person(member_name)
+                trust_levels.append(AudienceLevel(person.get("trust_level", 4)))
+                all_exclusions.update(person.get("never_share", []))
+            min_trust = min(trust_levels)
+            exclusions = all_exclusions
+
+        return AudienceProfile(
+            channel_id=channel_id,
+            name=chan.get("name", channel_id),
+            members=members,
+            min_trust=min_trust,
+            exclusions=exclusions,
+            context_tag=context_tag,
+        )
+
+    # ── Person lookup ─────────────────────────────────────────────────────────
+
+    def _get_person(self, name: str) -> dict[str, Any]:
+        """Return a person's config dict, or an empty dict if unknown."""
+        return self._config.get("people", {}).get(name, {})
+
+    def get_person_trust(self, name: str) -> AudienceLevel:
+        """Get the trust level for a named person.
+
+        Unknown persons default to PUBLIC (lowest trust — most conservative
+        in terms of what they are *allowed* to receive).
+
+        Args:
+            name: Person's name as it appears in audience_config.json.
+
+        Returns:
+            AudienceLevel: The trust level for this person.
+        """
+        person = self._get_person(name)
+        if not person:
+            logger.debug("Unknown person '%s', defaulting to PUBLIC trust", name)
+            return AudienceLevel.PUBLIC
+        return AudienceLevel(person.get("trust_level", 4))
+
+    # ── Memory access check ───────────────────────────────────────────────────
+
+    def is_memory_allowed(
+        self,
+        memory_context_tag: str,
+        audience: AudienceProfile,
+        memory_tags: list[str] | None = None,
+    ) -> bool:
+        """Check whether content with the given context tag is allowed for an audience.
+
+        A memory is allowed when **both** conditions are true:
+        1. Its trust level ≤ the audience's minimum trust level.
+        2. None of the memory's tags intersect the audience's exclusion list.
+
+        Conservative defaults:
+        - Empty/missing context_tag → treat as @chef-only (level 4).
+        - If audience has no members → block unless it's explicitly @chef-only.
+
+        Args:
+            memory_context_tag: The ``@context`` tag of the memory/seed.
+            audience: The resolved audience profile for the channel.
+            memory_tags: Optional list of free-form memory tags to check
+                         against audience exclusions.
+
+        Returns:
+            bool: True if the content may be shown to this audience.
+        """
+        # Determine the content's required trust level
+        content_level = tag_to_level(memory_context_tag)
+
+        # Gate 1: trust level check
+        # content_level must be ≤ audience.min_trust
+        # e.g. @work-circle(2) content in a @public(0) audience → blocked
+        if content_level > audience.min_trust:
+            return False
+
+        # Gate 2: exclusion check — any overlap with audience exclusions?
+        if audience.exclusions and memory_tags:
+            for tag in memory_tags:
+                if tag in audience.exclusions:
+                    return False
+
+        return True

package/skmemory/backends/__init__.py

@@ -1,12 +1,19 @@
 """
 Storage backends for SKMemory.
 
-Level 1 (file)   - JSON files on disk, zero infrastructure.
-Level 2 (qdrant) - Vector search via Qdrant for semantic recall.
-Level 3 (graph)  - FalkorDB graph relationships between memories.
+Level 0 (sqlite)   - SQLite index, zero infrastructure.
+Level 0.5 (vault)  - SQLite + transparent AES-256-GCM at-rest encryption.
+Level 1 (skvector) - Semantic vector search (powered by Qdrant).
+Level 2 (skgraph)  - Graph relationship traversal (powered by FalkorDB).
 """
 
 from .base import BaseBackend
 from .file_backend import FileBackend
+from .skgraph_backend import SKGraphBackend
 
-__all__ = ["BaseBackend", "FileBackend"]
+__all__ = ["BaseBackend", "SKGraphBackend", "FileBackend", "VaultedSQLiteBackend"]
+
+try:
+    from .vaulted_backend import VaultedSQLiteBackend
+except ImportError:
+    VaultedSQLiteBackend = None  # type: ignore[assignment,misc]

package/skmemory/backends/base.py

@@ -8,7 +8,6 @@ delegates to whichever backend(s) are configured.
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Optional
 
 from ..models import Memory, MemoryLayer
 
@@ -28,7 +27,7 @@ class BaseBackend(ABC):
         """
 
     @abstractmethod
-    def load(self, memory_id: str) -> Optional[Memory]:
+    def load(self, memory_id: str) -> Memory | None:
         """Retrieve a single memory by ID.
 
         Args:
@@ -52,8 +51,8 @@ class BaseBackend(ABC):
     @abstractmethod
     def list_memories(
         self,
-        layer: Optional[MemoryLayer] = None,
-        tags: Optional[list[str]] = None,
+        layer: MemoryLayer | None = None,
+        tags: list[str] | None = None,
         limit: int = 50,
     ) -> list[Memory]:
         """List memories with optional filtering.

package/skmemory/backends/file_backend.py

@@ -19,14 +19,13 @@ Directory layout:
 from __future__ import annotations
 
 import json
-import os
 from pathlib import Path
-from typing import Optional
 
+from ..config import SKMEMORY_HOME
 from ..models import Memory, MemoryLayer
 from .base import BaseBackend
 
-DEFAULT_BASE_PATH = os.path.expanduser("~/.skmemory/memories")
+DEFAULT_BASE_PATH = str(SKMEMORY_HOME / "memory")
 
 
 class FileBackend(BaseBackend):
@@ -56,7 +55,7 @@ class FileBackend(BaseBackend):
         """
         return self.base_path / memory.layer.value / f"{memory.id}.json"
 
-    def _find_file(self, memory_id: str) -> Optional[Path]:
+    def _find_file(self, memory_id: str) -> Path | None:
         """Locate a memory file across all layers.
 
         Args:
@@ -88,7 +87,7 @@ class FileBackend(BaseBackend):
         )
         return memory.id
 
-    def load(self, memory_id: str) -> Optional[Memory]:
+    def load(self, memory_id: str) -> Memory | None:
         """Load a memory by ID from disk.
 
         Args:
@@ -123,8 +122,8 @@ class FileBackend(BaseBackend):
 
     def list_memories(
         self,
-        layer: Optional[MemoryLayer] = None,
-        tags: Optional[list[str]] = None,
+        layer: MemoryLayer | None = None,
+        tags: list[str] | None = None,
         limit: int = 50,
     ) -> list[Memory]:
         """List memories from disk with optional filtering.
@@ -167,8 +166,11 @@ class FileBackend(BaseBackend):
         Returns:
             list[Memory]: Matching memories.
         """
-        query_lower = query.lower()
+        words = [w.lower() for w in query.split()]
+        if not words:
+            return []
         results: list[Memory] = []
+        scored: list[tuple[int, Memory]] = []
 
         for layer in MemoryLayer:
             layer_dir = self.base_path / layer.value
@@ -176,15 +178,19 @@ class FileBackend(BaseBackend):
                 continue
             for json_file in layer_dir.glob("*.json"):
                 try:
-                    raw = json_file.read_text(encoding="utf-8")
-                    if query_lower not in raw.lower():
+                    data = json.loads(json_file.read_text(encoding="utf-8"))
+                    mem = Memory(**data)
+                    searchable = mem.to_embedding_text().lower()
+                    hits = sum(1 for w in words if w in searchable)
+                    if hits == 0:
                         continue
-                    data = json.loads(raw)
-                    results.append(Memory(**data))
+                    scored.append((hits, mem))
                 except (json.JSONDecodeError, Exception):
                     continue
 
-        results.sort(key=lambda m: m.created_at, reverse=True)
+        # Sort by match count desc, then recency
+        scored.sort(key=lambda t: (t[0], t[1].created_at), reverse=True)
+        results = [m for _, m in scored]
         return results[:limit]
 
     def health_check(self) -> dict: