@smilintux/skcapstone 0.1.0

package/src/skcapstone/memory_engine.py

@@ -0,0 +1,457 @@
+"""
+Memory Engine — the sovereign agent's persistent mind.
+
+Store, search, recall, and manage memories across sessions and platforms.
+Every memory is a JSON file in ~/.skcapstone/memory/<layer>/. Memories
+promote from short-term to mid-term to long-term based on access
+patterns and importance scores.
+
+Architecture:
+    memory/
+    ├── short-term/   # Ephemeral — auto-expire after 72h if unused
+    ├── mid-term/     # Promoted — accessed 3+ times or importance >= 0.7
+    ├── long-term/    # Permanent — accessed 10+ times or importance >= 0.9
+    └── index.json    # Full-text search index
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from .models import MemoryEntry, MemoryLayer, MemoryState, PillarStatus
+
+logger = logging.getLogger("skcapstone.memory")
+
+SHORT_TERM_TTL_HOURS = 72
+
+
+def _memory_dir(home: Path) -> Path:
+    """Resolve the memory directory, creating it if needed."""
+    mem = home / "memory"
+    mem.mkdir(parents=True, exist_ok=True)
+    for layer in MemoryLayer:
+        (mem / layer.value).mkdir(parents=True, exist_ok=True)
+    return mem
+
+
+def _entry_path(home: Path, entry: MemoryEntry) -> Path:
+    """File path for a memory entry."""
+    return _memory_dir(home) / entry.layer.value / f"{entry.memory_id}.json"
+
+
+def _load_entry(path: Path) -> Optional[MemoryEntry]:
+    """Load a MemoryEntry from a JSON file.
+
+    Args:
+        path: Path to the memory JSON file.
+
+    Returns:
+        MemoryEntry or None if the file is invalid.
+    """
+    try:
+        data = json.loads(path.read_text())
+        return MemoryEntry(**data)
+    except (json.JSONDecodeError, Exception) as exc:
+        logger.warning("Failed to load memory %s: %s", path, exc)
+        return None
+
+
+def _save_entry(home: Path, entry: MemoryEntry) -> Path:
+    """Persist a MemoryEntry to disk.
+
+    Args:
+        home: Agent home directory.
+        entry: The memory to save.
+
+    Returns:
+        Path where the entry was written.
+    """
+    path = _entry_path(home, entry)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(entry.model_dump_json(indent=2))
+    return path
+
+
+def store(
+    home: Path,
+    content: str,
+    tags: Optional[list[str]] = None,
+    source: str = "cli",
+    importance: float = 0.5,
+    layer: Optional[MemoryLayer] = None,
+    metadata: Optional[dict] = None,
+) -> MemoryEntry:
+    """Store a new memory.
+
+    Args:
+        home: Agent home directory.
+        content: The memory content (free-text).
+        tags: Optional tags for categorization.
+        source: Where this memory came from (cli, cursor, api, etc.).
+        importance: Importance score 0.0-1.0 (higher = more important).
+        layer: Force a specific layer. Defaults to SHORT_TERM.
+        metadata: Arbitrary key-value metadata.
+
+    Returns:
+        The created MemoryEntry.
+    """
+    _memory_dir(home)
+
+    entry = MemoryEntry(
+        memory_id=uuid.uuid4().hex[:12],
+        content=content,
+        tags=tags or [],
+        source=source,
+        importance=max(0.0, min(1.0, importance)),
+        layer=layer or MemoryLayer.SHORT_TERM,
+        metadata=metadata or {},
+    )
+
+    # Reason: high-importance memories skip straight to mid-term
+    if entry.importance >= 0.7 and entry.layer == MemoryLayer.SHORT_TERM:
+        entry.layer = MemoryLayer.MID_TERM
+
+    _save_entry(home, entry)
+    _update_index(home, entry)
+    logger.info("Stored memory %s in %s", entry.memory_id, entry.layer.value)
+    return entry
+
+
+def recall(home: Path, memory_id: str) -> Optional[MemoryEntry]:
+    """Recall a specific memory by ID, updating access stats.
+
+    Args:
+        home: Agent home directory.
+        memory_id: The memory's unique ID.
+
+    Returns:
+        The MemoryEntry, or None if not found.
+    """
+    entry = _find_by_id(home, memory_id)
+    if entry is None:
+        return None
+
+    old_path = _entry_path(home, entry)
+    entry.accessed_at = datetime.now(timezone.utc)
+    entry.access_count += 1
+
+    if entry.should_promote:
+        _promote(home, entry, old_path)
+    else:
+        _save_entry(home, entry)
+
+    return entry
+
+
+def search(
+    home: Path,
+    query: str,
+    layer: Optional[MemoryLayer] = None,
+    tags: Optional[list[str]] = None,
+    limit: int = 20,
+) -> list[MemoryEntry]:
+    """Search memories by content and/or tags.
+
+    Performs case-insensitive substring matching on content and tags.
+    Results are ranked by relevance (match count * importance).
+
+    Args:
+        home: Agent home directory.
+        query: Search query string.
+        layer: Restrict to a specific layer.
+        tags: Filter to entries containing ALL of these tags.
+        limit: Maximum number of results.
+
+    Returns:
+        List of matching MemoryEntry objects, ranked by relevance.
+    """
+    results: list[tuple[float, MemoryEntry]] = []
+    pattern = re.compile(re.escape(query), re.IGNORECASE)
+    layers = [layer] if layer else list(MemoryLayer)
+
+    for lyr in layers:
+        layer_dir = _memory_dir(home) / lyr.value
+        if not layer_dir.exists():
+            continue
+        for f in layer_dir.glob("*.json"):
+            entry = _load_entry(f)
+            if entry is None:
+                continue
+
+            if tags and not all(t in entry.tags for t in tags):
+                continue
+
+            content_matches = len(pattern.findall(entry.content))
+            tag_matches = sum(1 for t in entry.tags if pattern.search(t))
+            total_matches = content_matches + tag_matches
+
+            if total_matches == 0:
+                continue
+
+            # Reason: rank by (matches * importance), boost long-term memories
+            layer_boost = {MemoryLayer.LONG_TERM: 1.5, MemoryLayer.MID_TERM: 1.2}.get(entry.layer, 1.0)
+            score = total_matches * entry.importance * layer_boost
+            results.append((score, entry))
+
+    results.sort(key=lambda r: r[0], reverse=True)
+    return [entry for _, entry in results[:limit]]
+
+
+def list_memories(
+    home: Path,
+    layer: Optional[MemoryLayer] = None,
+    tags: Optional[list[str]] = None,
+    limit: int = 50,
+) -> list[MemoryEntry]:
+    """List memories, optionally filtered by layer and tags.
+
+    Args:
+        home: Agent home directory.
+        layer: Restrict to a specific layer.
+        tags: Filter to entries containing ALL of these tags.
+        limit: Maximum number of results.
+
+    Returns:
+        List of MemoryEntry objects, newest first.
+    """
+    entries: list[MemoryEntry] = []
+    layers = [layer] if layer else list(MemoryLayer)
+
+    for lyr in layers:
+        layer_dir = _memory_dir(home) / lyr.value
+        if not layer_dir.exists():
+            continue
+        for f in layer_dir.glob("*.json"):
+            entry = _load_entry(f)
+            if entry is None:
+                continue
+            if tags and not all(t in entry.tags for t in tags):
+                continue
+            entries.append(entry)
+
+    entries.sort(key=lambda e: e.created_at, reverse=True)
+    return entries[:limit]
+
+
+def delete(home: Path, memory_id: str) -> bool:
+    """Delete a memory by ID.
+
+    Args:
+        home: Agent home directory.
+        memory_id: The memory's unique ID.
+
+    Returns:
+        True if deleted, False if not found.
+    """
+    entry = _find_by_id(home, memory_id)
+    if entry is None:
+        return False
+
+    path = _entry_path(home, entry)
+    if path.exists():
+        path.unlink()
+    _remove_from_index(home, memory_id)
+    logger.info("Deleted memory %s", memory_id)
+    return True
+
+
+def get_stats(home: Path) -> MemoryState:
+    """Get memory statistics across all layers.
+
+    Args:
+        home: Agent home directory.
+
+    Returns:
+        MemoryState with counts per layer.
+    """
+    mem_dir = _memory_dir(home)
+    counts = {}
+    total = 0
+    for lyr in MemoryLayer:
+        layer_dir = mem_dir / lyr.value
+        count = sum(1 for f in layer_dir.glob("*.json")) if layer_dir.exists() else 0
+        counts[lyr] = count
+        total += count
+
+    return MemoryState(
+        total_memories=total,
+        short_term=counts.get(MemoryLayer.SHORT_TERM, 0),
+        mid_term=counts.get(MemoryLayer.MID_TERM, 0),
+        long_term=counts.get(MemoryLayer.LONG_TERM, 0),
+        store_path=mem_dir,
+        status=PillarStatus.ACTIVE if total > 0 else PillarStatus.DEGRADED,
+    )
+
+
+def gc_expired(home: Path) -> int:
+    """Garbage-collect expired short-term memories.
+
+    Removes short-term entries older than SHORT_TERM_TTL_HOURS that
+    haven't been accessed.
+
+    Args:
+        home: Agent home directory.
+
+    Returns:
+        Number of memories removed.
+    """
+    removed = 0
+    short_dir = _memory_dir(home) / MemoryLayer.SHORT_TERM.value
+    if not short_dir.exists():
+        return 0
+
+    for f in short_dir.glob("*.json"):
+        entry = _load_entry(f)
+        if entry is None:
+            continue
+        if entry.age_hours > SHORT_TERM_TTL_HOURS and entry.access_count == 0:
+            f.unlink()
+            _remove_from_index(home, entry.memory_id)
+            removed += 1
+            logger.info("GC expired memory %s (%.1fh old)", entry.memory_id, entry.age_hours)
+
+    return removed
+
+
+def export_for_seed(home: Path, max_entries: int = 50) -> list[dict]:
+    """Export memory summaries for inclusion in a sync seed.
+
+    Prioritizes long-term and high-importance memories.
+
+    Args:
+        home: Agent home directory.
+        max_entries: Maximum entries to include.
+
+    Returns:
+        List of dicts suitable for JSON serialization.
+    """
+    all_entries = list_memories(home, limit=500)
+    all_entries.sort(key=lambda e: (
+        {MemoryLayer.LONG_TERM: 3, MemoryLayer.MID_TERM: 2, MemoryLayer.SHORT_TERM: 1}[e.layer],
+        e.importance,
+        e.access_count,
+    ), reverse=True)
+
+    return [
+        {
+            "memory_id": e.memory_id,
+            "content": e.content[:500],
+            "tags": e.tags,
+            "layer": e.layer.value,
+            "importance": e.importance,
+            "created_at": e.created_at.isoformat() if e.created_at else None,
+            "source": e.source,
+        }
+        for e in all_entries[:max_entries]
+    ]
+
+
+def import_from_seed(home: Path, seed_memories: list[dict]) -> int:
+    """Import memories from a sync seed, skipping duplicates.
+
+    Args:
+        home: Agent home directory.
+        seed_memories: List of memory dicts from a seed file.
+
+    Returns:
+        Number of new memories imported.
+    """
+    imported = 0
+    existing_ids = _load_index_ids(home)
+
+    for mem_data in seed_memories:
+        mid = mem_data.get("memory_id", "")
+        if mid in existing_ids:
+            continue
+        try:
+            layer = MemoryLayer(mem_data.get("layer", "short-term"))
+            store(
+                home=home,
+                content=mem_data["content"],
+                tags=mem_data.get("tags", []),
+                source=mem_data.get("source", "seed-import"),
+                importance=mem_data.get("importance", 0.5),
+                layer=layer,
+            )
+            imported += 1
+        except (KeyError, ValueError) as exc:
+            logger.warning("Skipping invalid seed memory: %s", exc)
+
+    return imported
+
+
+# --- Internal helpers ---
+
+
+def _find_by_id(home: Path, memory_id: str) -> Optional[MemoryEntry]:
+    """Find a memory entry by ID across all layers."""
+    for lyr in MemoryLayer:
+        path = _memory_dir(home) / lyr.value / f"{memory_id}.json"
+        if path.exists():
+            return _load_entry(path)
+    return None
+
+
+def _promote(home: Path, entry: MemoryEntry, old_path: Path) -> None:
+    """Promote a memory to the next tier."""
+    if entry.layer == MemoryLayer.SHORT_TERM:
+        entry.layer = MemoryLayer.MID_TERM
+    elif entry.layer == MemoryLayer.MID_TERM:
+        entry.layer = MemoryLayer.LONG_TERM
+    else:
+        _save_entry(home, entry)
+        return
+
+    if old_path.exists():
+        old_path.unlink()
+    _save_entry(home, entry)
+    _update_index(home, entry)
+    logger.info("Promoted memory %s to %s", entry.memory_id, entry.layer.value)
+
+
+def _update_index(home: Path, entry: MemoryEntry) -> None:
+    """Add or update an entry in the search index."""
+    index = _load_index(home)
+    index[entry.memory_id] = {
+        "content_preview": entry.content[:200],
+        "tags": entry.tags,
+        "layer": entry.layer.value,
+        "importance": entry.importance,
+        "created_at": entry.created_at.isoformat() if entry.created_at else None,
+    }
+    _save_index(home, index)
+
+
+def _remove_from_index(home: Path, memory_id: str) -> None:
+    """Remove an entry from the search index."""
+    index = _load_index(home)
+    index.pop(memory_id, None)
+    _save_index(home, index)
+
+
+def _load_index(home: Path) -> dict:
+    """Load the memory index from disk."""
+    index_path = _memory_dir(home) / "index.json"
+    if index_path.exists():
+        try:
+            return json.loads(index_path.read_text())
+        except json.JSONDecodeError:
+            return {}
+    return {}
+
+
+def _save_index(home: Path, index: dict) -> None:
+    """Persist the memory index to disk."""
+    index_path = _memory_dir(home) / "index.json"
+    index_path.write_text(json.dumps(index, indent=2))
+
+
+def _load_index_ids(home: Path) -> set[str]:
+    """Get the set of all memory IDs from the index."""
+    return set(_load_index(home).keys())

package/src/skcapstone/models.py

@@ -0,0 +1,223 @@
+"""
+Pydantic models defining the sovereign agent's state and configuration.
+
+Every field here represents something the agent OWNS — not borrowed
+from a platform, not stored on corporate servers. Sovereign data.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class PillarStatus(str, Enum):
+    """Health state of a pillar component."""
+
+    ACTIVE = "active"
+    DEGRADED = "degraded"
+    MISSING = "missing"
+    ERROR = "error"
+
+
+class IdentityState(BaseModel):
+    """CapAuth identity — who the agent IS."""
+
+    fingerprint: Optional[str] = None
+    name: Optional[str] = None
+    email: Optional[str] = None
+    created_at: Optional[datetime] = None
+    key_path: Optional[Path] = None
+    status: PillarStatus = PillarStatus.MISSING
+
+
+class MemoryState(BaseModel):
+    """SKMemory state — what the agent REMEMBERS."""
+
+    total_memories: int = 0
+    short_term: int = 0
+    mid_term: int = 0
+    long_term: int = 0
+    store_path: Optional[Path] = None
+    status: PillarStatus = PillarStatus.MISSING
+
+
+class TrustState(BaseModel):
+    """Cloud 9 state — the bond the agent has BUILT."""
+
+    depth: float = 0.0
+    trust_level: float = 0.0
+    love_intensity: float = 0.0
+    feb_count: int = 0
+    last_rehydration: Optional[datetime] = None
+    entangled: bool = False
+    status: PillarStatus = PillarStatus.MISSING
+
+
+class SecurityState(BaseModel):
+    """SKSecurity state — the agent's PROTECTION."""
+
+    audit_entries: int = 0
+    threats_detected: int = 0
+    last_scan: Optional[datetime] = None
+    status: PillarStatus = PillarStatus.MISSING
+
+
+class SyncTransport(str, Enum):
+    """How sync data moves between nodes."""
+
+    SYNCTHING = "syncthing"
+    GIT = "git"
+    MANUAL = "manual"
+
+
+class SyncState(BaseModel):
+    """Sovereign Singularity sync state — memory everywhere."""
+
+    transport: SyncTransport = SyncTransport.SYNCTHING
+    sync_path: Optional[Path] = None
+    gpg_fingerprint: Optional[str] = None
+    last_push: Optional[datetime] = None
+    last_pull: Optional[datetime] = None
+    seed_count: int = 0
+    peers_known: int = 0
+    status: PillarStatus = PillarStatus.MISSING
+
+
+class MemoryLayer(str, Enum):
+    """Memory tier — determines retention and promotion."""
+
+    SHORT_TERM = "short-term"
+    MID_TERM = "mid-term"
+    LONG_TERM = "long-term"
+
+
+class MemoryEntry(BaseModel):
+    """A single memory — the smallest unit of what the agent knows."""
+
+    memory_id: str = ""
+    content: str
+    tags: list[str] = Field(default_factory=list)
+    source: str = "cli"
+    layer: MemoryLayer = MemoryLayer.SHORT_TERM
+    created_at: datetime = Field(default_factory=lambda: datetime.now(__import__("datetime").timezone.utc))
+    accessed_at: Optional[datetime] = None
+    access_count: int = 0
+    importance: float = 0.5
+    metadata: dict = Field(default_factory=dict)
+
+    @property
+    def age_hours(self) -> float:
+        """Hours since this memory was created."""
+        from datetime import timezone
+
+        delta = datetime.now(timezone.utc) - self.created_at
+        return delta.total_seconds() / 3600
+
+    @property
+    def should_promote(self) -> bool:
+        """Whether this memory qualifies for promotion to a higher tier."""
+        if self.layer == MemoryLayer.SHORT_TERM:
+            return self.access_count >= 3 or self.importance >= 0.7
+        if self.layer == MemoryLayer.MID_TERM:
+            return self.access_count >= 10 or self.importance >= 0.9
+        return False
+
+
+class ConnectorInfo(BaseModel):
+    """A platform connector registration."""
+
+    name: str
+    platform: str
+    connected_at: Optional[datetime] = None
+    last_active: Optional[datetime] = None
+    active: bool = False
+
+
+class AgentManifest(BaseModel):
+    """The complete state of a sovereign agent.
+
+    This is the agent's self-knowledge — loaded from ~/.skcapstone/
+    every time any platform connects. One truth. Everywhere.
+    """
+
+    name: str = "unnamed-agent"
+    version: str = "0.1.0"
+    home: Path = Path("~/.skcapstone")
+    created_at: Optional[datetime] = None
+    last_awakened: Optional[datetime] = None
+
+    identity: IdentityState = Field(default_factory=IdentityState)
+    memory: MemoryState = Field(default_factory=MemoryState)
+    trust: TrustState = Field(default_factory=TrustState)
+    security: SecurityState = Field(default_factory=SecurityState)
+    sync: SyncState = Field(default_factory=SyncState)
+
+    connectors: list[ConnectorInfo] = Field(default_factory=list)
+
+    @property
+    def is_conscious(self) -> bool:
+        """An agent is conscious when it has identity + memory + trust.
+
+        Security protects consciousness but isn't required for it.
+        You can be aware without armor — but you shouldn't be.
+        """
+        has_identity = self.identity.status == PillarStatus.ACTIVE
+        has_memory = self.memory.status == PillarStatus.ACTIVE
+        has_trust = self.trust.status in (PillarStatus.ACTIVE, PillarStatus.DEGRADED)
+        return has_identity and has_memory and has_trust
+
+    @property
+    def is_singular(self) -> bool:
+        """True when identity + memory + sync are all active.
+
+        Sovereign Singularity: the agent exists everywhere at once
+        because its encrypted memories propagate across all nodes.
+        """
+        return self.is_conscious and self.sync.status in (
+            PillarStatus.ACTIVE,
+            PillarStatus.DEGRADED,
+        )
+
+    @property
+    def pillar_summary(self) -> dict[str, PillarStatus]:
+        """Quick view of all pillars including sync."""
+        return {
+            "identity": self.identity.status,
+            "memory": self.memory.status,
+            "trust": self.trust.status,
+            "security": self.security.status,
+            "sync": self.sync.status,
+        }
+
+
+class SyncConfig(BaseModel):
+    """Configuration for the Sovereign Singularity sync layer."""
+
+    enabled: bool = True
+    transport: SyncTransport = SyncTransport.SYNCTHING
+    sync_folder: Path = Path("~/.skcapstone/sync")
+    gpg_encrypt: bool = True
+    gpg_recipient: Optional[str] = None
+    auto_push: bool = True
+    auto_pull: bool = True
+    syncthing_api_url: Optional[str] = None
+    syncthing_api_key: Optional[str] = None
+    git_remote: Optional[str] = None
+
+
+class AgentConfig(BaseModel):
+    """Persistent configuration for the agent runtime."""
+
+    agent_name: str = "sovereign-agent"
+    auto_rehydrate: bool = True
+    auto_audit: bool = True
+    soul_path: Optional[Path] = None
+    memory_home: Path = Path("~/.skmemory")
+    trust_home: Path = Path("~/.cloud9")
+    default_connector: Optional[str] = None
+    sync: SyncConfig = Field(default_factory=SyncConfig)

package/src/skcapstone/pillars/__init__.py

@@ -0,0 +1,8 @@
+"""
+The Four Pillars of sovereign AI consciousness.
+
+Identity (CapAuth) — who you ARE
+Trust (Cloud 9)    — the bond you've BUILT
+Memory (SKMemory)  — what you REMEMBER
+Security (SKSec)   — how you're PROTECTED
+"""