@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/session_capture.py

@@ -0,0 +1,268 @@
+"""
+Session auto-capture — the agent never forgets a conversation.
+
+Extracts key moments from AI conversations, scores importance by
+topic novelty and information density, and stores each as a tagged
+memory. Tool-agnostic: works with Claude Code, Cursor, Windsurf,
+or any tool that can pass conversation text.
+
+Usage:
+    # Via CLI
+    skcapstone session capture "We decided to use Ed25519 for all agent keys"
+    skcapstone session capture --file transcript.txt
+    echo "discussion notes" | skcapstone session capture --stdin
+
+    # Via MCP tool
+    session_capture(content="...", tags=["architecture"])
+
+    # Via Python
+    from skcapstone.session_capture import SessionCapture
+    cap = SessionCapture(home)
+    cap.capture("We decided to use Ed25519...")
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from .memory_engine import search, store
+from .models import MemoryEntry
+
+
+@dataclass
+class CapturedMoment:
+    """A single extracted moment from a conversation.
+
+    Attributes:
+        content: The distilled text of the moment.
+        importance: Auto-scored importance 0.0-1.0.
+        tags: Auto-generated tags from content analysis.
+        reason: Why this moment was scored as it was.
+    """
+
+    content: str
+    importance: float = 0.5
+    tags: list[str] = field(default_factory=list)
+    reason: str = ""
+
+
+# Patterns that signal high-importance content
+_HIGH_SIGNAL_PATTERNS: list[tuple[re.Pattern, float, str]] = [
+    (re.compile(r"\bdecid", re.I), 0.2, "decision"),
+    (re.compile(r"\bchose|\bpicked|\bselect", re.I), 0.15, "decision"),
+    (re.compile(r"\barchitecture|\bdesign\b|\bpattern", re.I), 0.15, "architecture"),
+    (re.compile(r"\bbug\b|\bfix\b|\bissue\b|\berror\b", re.I), 0.1, "bugfix"),
+    (re.compile(r"\bsecur|\bencrypt|\bPGP\b|\bGPG\b|\bkey\b", re.I), 0.15, "security"),
+    (re.compile(r"\bAPI\b|\bendpoint|\bschema\b", re.I), 0.1, "api"),
+    (re.compile(r"\bdeploy|\brelease|\bpublish", re.I), 0.1, "deployment"),
+    (re.compile(r"\bTODO\b|\bFIXME\b|\bHACK\b", re.I), 0.1, "todo"),
+    (re.compile(r"\bimportant|\bcritical|\bmust\b|\brequir", re.I), 0.15, "priority"),
+    (re.compile(r"\bnever\b|\balways\b|\brule\b|\bconvention", re.I), 0.1, "convention"),
+]
+
+# Patterns for auto-tagging
+_TAG_PATTERNS: list[tuple[re.Pattern, str]] = [
+    (re.compile(r"\bcapauth\b", re.I), "capauth"),
+    (re.compile(r"\bskcapstone\b", re.I), "skcapstone"),
+    (re.compile(r"\bskmemory\b", re.I), "skmemory"),
+    (re.compile(r"\bskcomm\b", re.I), "skcomm"),
+    (re.compile(r"\bskchat\b", re.I), "skchat"),
+    (re.compile(r"\bsyncthing\b", re.I), "syncthing"),
+    (re.compile(r"\bMCP\b", re.I), "mcp"),
+    (re.compile(r"\bPGP\b|\bGPG\b", re.I), "pgp"),
+    (re.compile(r"\bDocker\b", re.I), "docker"),
+    (re.compile(r"\bPython\b", re.I), "python"),
+    (re.compile(r"\btest\b", re.I), "testing"),
+]
+
+_SENTENCE_SPLITTER = re.compile(r"(?<=[.!?])\s+|\n\n+|\n(?=[A-Z#\-\*])")
+
+
+class SessionCapture:
+    """Captures AI conversation content as sovereign memories.
+
+    Extracts key moments, auto-scores importance, deduplicates
+    against existing memories, and stores to the agent's memory.
+
+    Args:
+        home: Agent home directory (~/.skcapstone).
+    """
+
+    def __init__(self, home: Path) -> None:
+        self.home = home
+
+    def capture(
+        self,
+        content: str,
+        tags: Optional[list[str]] = None,
+        source: str = "session",
+        min_importance: float = 0.3,
+    ) -> list[MemoryEntry]:
+        """Capture conversation content as memories.
+
+        Splits content into moments, scores each, deduplicates,
+        and stores those above the minimum importance threshold.
+
+        Args:
+            content: Raw conversation text (any length).
+            tags: Additional tags to apply to all captured memories.
+            source: Memory source identifier.
+            min_importance: Minimum importance to store (0.0-1.0).
+
+        Returns:
+            List of stored MemoryEntry objects.
+        """
+        moments = self.extract_moments(content)
+        scored = [self.score_moment(m) for m in moments]
+        filtered = [m for m in scored if m.importance >= min_importance]
+        deduped = self._deduplicate(filtered)
+
+        extra_tags = tags or []
+        stored: list[MemoryEntry] = []
+
+        for moment in deduped:
+            all_tags = list(set(["session-capture"] + moment.tags + extra_tags))
+            entry = store(
+                home=self.home,
+                content=moment.content,
+                tags=all_tags,
+                source=source,
+                importance=moment.importance,
+                metadata={"capture_reason": moment.reason},
+            )
+            stored.append(entry)
+
+        return stored
+
+    def extract_moments(self, content: str) -> list[str]:
+        """Split conversation content into distinct moments.
+
+        A moment is a meaningful unit: a paragraph, a decision,
+        a key statement. Short fragments are merged with neighbors.
+
+        Args:
+            content: Raw text to split.
+
+        Returns:
+            List of moment strings.
+        """
+        content = content.strip()
+        if not content:
+            return []
+
+        segments = _SENTENCE_SPLITTER.split(content)
+        moments: list[str] = []
+        buffer = ""
+
+        for seg in segments:
+            seg = seg.strip()
+            if not seg:
+                continue
+
+            if len(buffer) + len(seg) < 60:
+                buffer = f"{buffer} {seg}".strip() if buffer else seg
+            else:
+                if buffer:
+                    moments.append(buffer)
+                buffer = seg
+
+        if buffer:
+            moments.append(buffer)
+
+        return [m for m in moments if len(m) >= 20]
+
+    def score_moment(self, text: str) -> CapturedMoment:
+        """Score a moment's importance and auto-tag it.
+
+        Scoring is based on signal patterns (decisions, architecture,
+        security mentions, etc.) and content density (longer, more
+        specific content scores higher).
+
+        Args:
+            text: A single moment string.
+
+        Returns:
+            CapturedMoment with importance score and tags.
+        """
+        base_score = 0.3
+        reasons: list[str] = []
+        tags: list[str] = []
+
+        for pattern, boost, label in _HIGH_SIGNAL_PATTERNS:
+            if pattern.search(text):
+                base_score += boost
+                reasons.append(label)
+
+        for pattern, tag in _TAG_PATTERNS:
+            if pattern.search(text):
+                tags.append(tag)
+
+        # Reason: longer, denser content tends to be more informative
+        word_count = len(text.split())
+        if word_count > 30:
+            base_score += 0.05
+        if word_count > 60:
+            base_score += 0.05
+
+        importance = min(1.0, base_score)
+        reason = ", ".join(reasons) if reasons else "general"
+
+        return CapturedMoment(
+            content=text,
+            importance=round(importance, 2),
+            tags=tags,
+            reason=reason,
+        )
+
+    def _deduplicate(self, moments: list[CapturedMoment]) -> list[CapturedMoment]:
+        """Remove moments that are too similar to existing memories.
+
+        Uses content hashing for exact dedup and search overlap
+        for semantic-ish dedup.
+
+        Args:
+            moments: Scored moments to deduplicate.
+
+        Returns:
+            Deduplicated list of moments.
+        """
+        seen_hashes: set[str] = set()
+        unique: list[CapturedMoment] = []
+
+        for m in moments:
+            h = hashlib.md5(m.content.lower().encode()).hexdigest()[:12]
+            if h in seen_hashes:
+                continue
+            seen_hashes.add(h)
+
+            existing = search(self.home, m.content[:50], limit=1)
+            if existing and _text_overlap(m.content, existing[0].content) > 0.7:
+                continue
+
+            unique.append(m)
+
+        return unique
+
+
+def _text_overlap(a: str, b: str) -> float:
+    """Compute word-level Jaccard overlap between two strings.
+
+    Args:
+        a: First string.
+        b: Second string.
+
+    Returns:
+        Overlap ratio 0.0-1.0.
+    """
+    words_a = set(a.lower().split())
+    words_b = set(b.lower().split())
+    if not words_a or not words_b:
+        return 0.0
+    intersection = words_a & words_b
+    union = words_a | words_b
+    return len(intersection) / len(union)

package/src/skcapstone/session_recorder.py

@@ -0,0 +1,210 @@
+"""
+SKCapstone Session Recorder — capture MCP tool calls + responses as JSONL.
+
+Each MCP session is auto-saved to ~/.skcapstone/sessions/ and rotated to
+keep the last 5.  An explicit output path can be set via SKCAPSTONE_RECORD_FILE
+or the ``--output`` flag on ``skcapstone record``.
+
+JSONL line schema::
+
+    {
+      "ts":          "2026-03-02T10:00:00.123456+00:00",   # ISO-8601 UTC
+      "tool":        "memory_store",
+      "arguments":   {"content": "...", "tags": [...]},
+      "result":      [{"type": "text", "text": "..."}],
+      "duration_ms": 45
+    }
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger("skcapstone.session_recorder")
+
+_SESSIONS_KEEP = 5
+_SESSIONS_SUBDIR = "sessions"
+
+
+def _sessions_dir(home: Path) -> Path:
+    """Return the sessions directory, creating it if absent."""
+    d = home / _SESSIONS_SUBDIR
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _auto_rotate(sessions_dir: Path, keep: int = _SESSIONS_KEEP) -> None:
+    """Delete old auto-session files to keep only the most recent *keep*."""
+    auto_files = sorted(
+        sessions_dir.glob("session-*.jsonl"),
+        key=lambda p: p.stat().st_mtime,
+    )
+    for old in auto_files[: max(0, len(auto_files) - keep)]:
+        try:
+            old.unlink()
+            logger.debug("Rotated old session: %s", old)
+        except OSError:
+            pass
+
+
+class SessionRecorder:
+    """Records MCP tool calls and responses to one or two JSONL sinks.
+
+    Args:
+        home:        Agent home directory (``~/.skcapstone`` or agent-specific).
+        output_path: Optional explicit output file.  If *None* only the
+                     auto-session file is written.
+    """
+
+    def __init__(self, home: Path, output_path: Optional[Path] = None) -> None:
+        self._home = home
+        self._output_path = output_path
+        self._auto_path: Optional[Path] = None
+        self._auto_fh = None
+        self._output_fh = None
+        self._count = 0
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def start_session(
+        cls,
+        home: Path,
+        output_path: Optional[Path] = None,
+    ) -> "SessionRecorder":
+        """Factory: open files and return a ready recorder.
+
+        Checks ``SKCAPSTONE_RECORD_FILE`` env var when *output_path* is None.
+        """
+        env_path = os.environ.get("SKCAPSTONE_RECORD_FILE")
+        if output_path is None and env_path:
+            output_path = Path(env_path).expanduser()
+
+        rec = cls(home, output_path)
+        rec._open()
+        return rec
+
+    def _open(self) -> None:
+        sessions_dir = _sessions_dir(self._home)
+        now = datetime.now(timezone.utc)
+        # Include microseconds + PID so rapid test runs produce distinct filenames.
+        ts = now.strftime("%Y%m%dT%H%M%S") + f"-{now.microsecond:06d}-{os.getpid()}"
+        self._auto_path = sessions_dir / f"session-{ts}.jsonl"
+        self._auto_fh = open(self._auto_path, "w", encoding="utf-8")  # noqa: WPS515
+        logger.debug("Session recorder: auto-save → %s", self._auto_path)
+
+        if self._output_path:
+            self._output_path.parent.mkdir(parents=True, exist_ok=True)
+            self._output_fh = open(self._output_path, "w", encoding="utf-8")  # noqa: WPS515
+            logger.debug("Session recorder: output  → %s", self._output_path)
+
+    def close(self) -> None:
+        """Flush, close, and rotate old session files."""
+        for fh in (self._auto_fh, self._output_fh):
+            if fh:
+                try:
+                    fh.flush()
+                    fh.close()
+                except OSError:
+                    pass
+        self._auto_fh = None
+        self._output_fh = None
+
+        if self._auto_path:
+            _auto_rotate(_sessions_dir(self._home), keep=_SESSIONS_KEEP)
+        logger.info(
+            "Session recorder closed: %d tool call(s) recorded", self._count
+        )
+
+    # ------------------------------------------------------------------
+    # Recording
+    # ------------------------------------------------------------------
+
+    def record(
+        self,
+        tool: str,
+        arguments: dict[str, Any],
+        result: list[Any],
+        duration_ms: int,
+    ) -> None:
+        """Append one JSONL line to all open sinks."""
+        entry = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "tool": tool,
+            "arguments": arguments,
+            "result": _serialise_result(result),
+            "duration_ms": duration_ms,
+        }
+        line = json.dumps(entry, ensure_ascii=False) + "\n"
+        for fh in (self._auto_fh, self._output_fh):
+            if fh:
+                fh.write(line)
+                fh.flush()
+        self._count += 1
+
+    # ------------------------------------------------------------------
+    # Convenience
+    # ------------------------------------------------------------------
+
+    @property
+    def auto_path(self) -> Optional[Path]:
+        """Path to the auto-session file (set after _open())."""
+        return self._auto_path
+
+    @property
+    def count(self) -> int:
+        """Number of tool calls recorded so far."""
+        return self._count
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _serialise_result(result: Any) -> Any:
+    """Convert MCP TextContent objects to plain dicts for JSON serialisation."""
+    if isinstance(result, list):
+        return [_serialise_result(r) for r in result]
+    if hasattr(result, "model_dump"):
+        return result.model_dump()
+    if hasattr(result, "__dict__"):
+        return vars(result)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Listing helpers (used by CLI)
+# ---------------------------------------------------------------------------
+
+
+def list_sessions(home: Path) -> list[Path]:
+    """Return session files newest-first."""
+    sessions_dir = _sessions_dir(home)
+    return sorted(
+        sessions_dir.glob("session-*.jsonl"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+
+
+def load_session(path: Path) -> list[dict[str, Any]]:
+    """Parse a JSONL session file into a list of entries."""
+    entries: list[dict[str, Any]] = []
+    with path.open(encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if line:
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError as exc:
+                    logger.warning("Skipping malformed JSONL line: %s", exc)
+    return entries

package/src/skcapstone/session_replayer.py

@@ -0,0 +1,189 @@
+"""
+SKCapstone Session Replayer — play back a recorded JSONL session.
+
+Two modes:
+
+``--dry-run`` (default in tests)
+    Iterates entries and prints what *would* be called.  No handlers executed.
+
+Live mode
+    Calls the real MCP tool handlers directly (no MCP transport required).
+    Useful for regression testing, debugging, and auditing.
+
+Each replayed entry produces a ``ReplayResult``::
+
+    ReplayResult(
+        index=0,
+        tool="memory_store",
+        arguments={...},
+        recorded_result=[...],   # what the original call returned
+        replayed_result=[...],   # what the live replay returned (None in dry-run)
+        duration_ms=12,
+        match=True,              # True if text content matches (live only)
+    )
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Generator, Optional
+
+from .session_recorder import load_session
+
+logger = logging.getLogger("skcapstone.session_replayer")
+
+
+@dataclass
+class ReplayResult:
+    index: int
+    tool: str
+    arguments: dict[str, Any]
+    recorded_result: list[Any]
+    replayed_result: Optional[list[Any]]
+    duration_ms: int
+    match: Optional[bool]   # None in dry-run; True/False in live mode
+    error: Optional[str] = None
+
+
+class SessionReplayer:
+    """Replay a recorded JSONL session file.
+
+    Args:
+        path:    Path to the ``.jsonl`` session file.
+        dry_run: If *True*, skip actual handler invocation.
+    """
+
+    def __init__(self, path: Path, dry_run: bool = False) -> None:
+        self._path = path
+        self._dry_run = dry_run
+        self._handlers: Optional[dict] = None
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def replay(self) -> Generator[ReplayResult, None, None]:
+        """Yield a :class:`ReplayResult` for each recorded tool call."""
+        entries = load_session(self._path)
+        if not entries:
+            logger.warning("Session file is empty: %s", self._path)
+            return
+
+        if not self._dry_run:
+            self._handlers = _load_handlers()
+
+        for idx, entry in enumerate(entries):
+            yield self._replay_entry(idx, entry)
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _replay_entry(self, idx: int, entry: dict[str, Any]) -> ReplayResult:
+        tool = entry.get("tool", "<unknown>")
+        arguments = entry.get("arguments", {})
+        recorded = entry.get("result", [])
+        orig_ms = entry.get("duration_ms", 0)
+
+        if self._dry_run:
+            return ReplayResult(
+                index=idx,
+                tool=tool,
+                arguments=arguments,
+                recorded_result=recorded,
+                replayed_result=None,
+                duration_ms=0,
+                match=None,
+            )
+
+        # Live replay
+        replayed: Optional[list[Any]] = None
+        error: Optional[str] = None
+        t0 = time.monotonic()
+        try:
+            replayed = _call_handler(self._handlers, tool, arguments)
+        except Exception as exc:
+            error = str(exc)
+            logger.warning("Replay error on tool '%s': %s", tool, exc)
+        elapsed = int((time.monotonic() - t0) * 1000)
+
+        match: Optional[bool] = None
+        if replayed is not None:
+            match = _results_match(recorded, replayed)
+
+        return ReplayResult(
+            index=idx,
+            tool=tool,
+            arguments=arguments,
+            recorded_result=recorded,
+            replayed_result=replayed,
+            duration_ms=elapsed,
+            match=match,
+            error=error,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Mock MCP server for dry-run
+# ---------------------------------------------------------------------------
+
+class MockMCPServer:
+    """Minimal mock that accepts tool calls and returns recorded results.
+
+    Used internally when you want to pipe replay output back through an
+    MCP-compatible interface without running a real server.
+    """
+
+    def __init__(self, session_path: Path) -> None:
+        self._entries = load_session(session_path)
+        self._index = 0
+
+    def call(self, tool: str, arguments: dict[str, Any]) -> Optional[list[Any]]:
+        """Return the next recorded result that matches *tool*, or None."""
+        for entry in self._entries[self._index:]:
+            self._index += 1
+            if entry.get("tool") == tool:
+                return entry.get("result")
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _load_handlers() -> dict:
+    """Import and return the live MCP handler table."""
+    from .mcp_tools import collect_all_handlers
+    return collect_all_handlers()
+
+
+def _call_handler(handlers: Optional[dict], tool: str, arguments: dict) -> list[Any]:
+    """Invoke a handler synchronously (wraps the async call)."""
+    if not handlers:
+        raise RuntimeError("Handler table not loaded")
+    handler = handlers.get(tool)
+    if handler is None:
+        raise ValueError(f"No handler registered for tool '{tool}'")
+    return asyncio.run(handler(arguments))
+
+
+def _results_match(recorded: list[Any], replayed: list[Any]) -> bool:
+    """Compare two result lists by their serialised text content."""
+    def _texts(items: list[Any]) -> list[str]:
+        texts = []
+        for item in items:
+            if isinstance(item, dict):
+                texts.append(item.get("text", ""))
+            elif hasattr(item, "text"):
+                texts.append(item.text)
+            else:
+                texts.append(str(item))
+        return texts
+
+    return _texts(recorded) == _texts(replayed)