cc-star 0.1.0__py3-none-any.whl

cc_star/__init__.py

@@ -0,0 +1,3 @@
+"""cc-star — Claude Code memory upgrade kit."""
+
+__version__ = "0.1.0"

cc_star/cache/__init__.py

@@ -0,0 +1 @@
+"""SQLite local cache layer."""

cc_star/cache/connection.py

@@ -0,0 +1,100 @@
+"""SQLite connection management with performance optimizations."""
+
+from __future__ import annotations
+
+import sqlite3
+import threading
+from pathlib import Path
+from typing import Optional
+
+
+# Shared statement cache across threads
+_STMT_CACHE: dict[str, sqlite3.Cursor] = {}
+
+
+class CacheConnection:
+    """Thread-safe SQLite connection manager with performance tuning.
+
+    Optimizations:
+    - WAL mode for concurrent reads
+    - 64MB cache for hot data
+    - memory-mapped I/O (256MB)
+    - Lazy pragma initialization (deferred until first query)
+    """
+
+    def __init__(self, db_path: str, wal_mode: bool = True):
+        self._db_path = str(Path(db_path).expanduser())
+        self._wal = wal_mode
+        self._local = threading.local()
+        self._lock = threading.Lock()
+        self._initialized = False
+
+        # Ensure parent directory exists
+        Path(self._db_path).parent.mkdir(parents=True, exist_ok=True)
+
+    def _ensure_init(self) -> None:
+        """Apply performance pragmas once per connection."""
+        if self._initialized:
+            return
+        conn = self._get_conn_raw()
+        if self._wal:
+            conn.execute("PRAGMA journal_mode=WAL")
+        conn.executescript("""
+            PRAGMA synchronous=NORMAL;
+            PRAGMA foreign_keys=ON;
+            PRAGMA cache_size=-65536;
+            PRAGMA mmap_size=268435456;
+            PRAGMA temp_store=MEMORY;
+            PRAGMA busy_timeout=5000;
+        """)
+        self._initialized = True
+
+    def _get_conn_raw(self) -> sqlite3.Connection:
+        """Create a raw connection without pragma setup."""
+        if not hasattr(self._local, "conn") or self._local.conn is None:
+            conn = sqlite3.connect(
+                self._db_path,
+                check_same_thread=False,
+                isolation_level=None,  # autocommit mode
+            )
+            conn.row_factory = sqlite3.Row
+            self._local.conn = conn
+        return self._local.conn
+
+    @property
+    def conn(self) -> sqlite3.Connection:
+        self._ensure_init()
+        return self._get_conn_raw()
+
+    def execute(self, sql: str, params: tuple = ()) -> sqlite3.Cursor:
+        """Execute with automatic pragma init."""
+        self._ensure_init()
+        return self._get_conn_raw().execute(sql, params)
+
+    def executemany(self, sql: str, params: list[tuple]) -> sqlite3.Cursor:
+        """Batch execute with automatic pragma init."""
+        self._ensure_init()
+        return self._get_conn_raw().executemany(sql, params)
+
+    def close(self) -> None:
+        """Close the connection for the current thread."""
+        if hasattr(self._local, "conn") and self._local.conn is not None:
+            try:
+                self._local.conn.execute("PRAGMA optimize")
+            except Exception:
+                pass
+            self._local.conn.close()
+            self._local.conn = None
+            self._initialized = False
+
+    def close_all(self) -> None:
+        """Force close via lock (use sparingly)."""
+        with self._lock:
+            if hasattr(self._local, "conn") and self._local.conn is not None:
+                try:
+                    self._local.conn.execute("PRAGMA optimize")
+                except Exception:
+                    pass
+                self._local.conn.close()
+                self._local.conn = None
+                self._initialized = False

cc_star/cache/policies.py

@@ -0,0 +1,94 @@
+"""Policy repository — local SQLite CRUD for policies."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from cc_star.cache.connection import CacheConnection
+from cc_star.cache.schema import ensure_schema
+from cc_star.memos.types import PolicyRow
+
+
+class PolicyRepository:
+    """Persist and query policies locally."""
+
+    def __init__(self, cache: CacheConnection):
+        self._cache = cache
+        ensure_schema(cache)
+
+    def insert(self, policy: PolicyRow) -> None:
+        """Insert a policy into local cache."""
+        conn = self._cache.conn
+        conn.execute(
+            """
+            INSERT OR REPLACE INTO policies
+                (id, name, description, trigger_pattern, action_template,
+                 embedding, confidence, activation_count, source_trace_ids,
+                 metadata, created_at, synced)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                policy.id,
+                policy.name,
+                policy.description,
+                policy.trigger_pattern,
+                policy.action_template,
+                json.dumps(policy.embedding) if policy.embedding else None,
+                policy.confidence,
+                policy.activation_count,
+                json.dumps(policy.source_trace_ids, ensure_ascii=False),
+                json.dumps(policy.metadata, ensure_ascii=False, default=str),
+                policy.created_at,
+                0,
+            ),
+        )
+        conn.commit()
+
+    def get(self, policy_id: str) -> Optional[PolicyRow]:
+        """Get a policy by ID."""
+        row = self._cache.conn.execute(
+            "SELECT * FROM policies WHERE id = ?", (policy_id,)
+        ).fetchone()
+        if row is None:
+            return None
+        return self._row_to_policy(row)
+
+    def list_active(self, min_confidence: float = 0.3, limit: int = 20) -> list[PolicyRow]:
+        """List policies with confidence above threshold."""
+        rows = self._cache.conn.execute(
+            "SELECT * FROM policies WHERE confidence >= ? ORDER BY confidence DESC LIMIT ?",
+            (min_confidence, limit),
+        ).fetchall()
+        return [self._row_to_policy(r) for r in rows]
+
+    def increment_activation(self, policy_id: str) -> None:
+        """Increment activation count for a policy."""
+        self._cache.conn.execute(
+            "UPDATE policies SET activation_count = activation_count + 1 WHERE id = ?",
+            (policy_id,),
+        )
+        self._cache.conn.commit()
+
+    def count(self) -> int:
+        """Total policy count."""
+        row = self._cache.conn.execute("SELECT COUNT(*) as cnt FROM policies").fetchone()
+        return row["cnt"] if row else 0
+
+    @staticmethod
+    def _row_to_policy(row: Any) -> PolicyRow:
+        return PolicyRow(
+            id=row["id"],
+            name=row["name"],
+            description=row["description"],
+            trigger_pattern=row["trigger_pattern"],
+            action_template=row["action_template"],
+            embedding=json.loads(row["embedding"]) if row["embedding"] else None,
+            confidence=row["confidence"],
+            activation_count=row["activation_count"],
+            source_trace_ids=json.loads(row["source_trace_ids"])
+            if isinstance(row["source_trace_ids"], str)
+            else [],
+            metadata=json.loads(row["metadata"]) if isinstance(row["metadata"], str) else {},
+            created_at=row["created_at"],
+        )

cc_star/cache/schema.py

@@ -0,0 +1,100 @@
+"""SQLite schema — traces, policies, skills tables with FTS5."""
+
+from __future__ import annotations
+
+from cc_star.cache.connection import CacheConnection
+
+
+def ensure_schema(conn_or_cache: CacheConnection) -> None:
+    """Create all tables and indexes if they don't exist."""
+    conn = conn_or_cache.conn if isinstance(conn_or_cache, CacheConnection) else conn_or_cache
+
+    conn.executescript("""
+        CREATE TABLE IF NOT EXISTS traces (
+            id          TEXT PRIMARY KEY,
+            session_id  TEXT NOT NULL,
+            turn_index  INTEGER NOT NULL DEFAULT 0,
+            user_content TEXT NOT NULL,
+            assistant_content TEXT NOT NULL DEFAULT '',
+            embedding   BLOB,
+            reward      REAL NOT NULL DEFAULT 0.0,
+            tags        TEXT DEFAULT '',
+            metadata    TEXT DEFAULT '{}',
+            created_at  TEXT NOT NULL,
+            synced      INTEGER NOT NULL DEFAULT 0
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_traces_session
+            ON traces(session_id);
+        CREATE INDEX IF NOT EXISTS idx_traces_created
+            ON traces(created_at);
+        CREATE INDEX IF NOT EXISTS idx_traces_synced
+            ON traces(synced);
+
+        CREATE TABLE IF NOT EXISTS policies (
+            id              TEXT PRIMARY KEY,
+            name            TEXT NOT NULL,
+            description     TEXT NOT NULL DEFAULT '',
+            trigger_pattern TEXT NOT NULL DEFAULT '',
+            action_template TEXT NOT NULL DEFAULT '',
+            embedding       BLOB,
+            confidence      REAL NOT NULL DEFAULT 0.0,
+            activation_count INTEGER NOT NULL DEFAULT 0,
+            source_trace_ids TEXT DEFAULT '[]',
+            metadata        TEXT DEFAULT '{}',
+            created_at      TEXT NOT NULL,
+            synced          INTEGER NOT NULL DEFAULT 0
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_policies_confidence
+            ON policies(confidence DESC);
+
+        CREATE TABLE IF NOT EXISTS skills (
+            name            TEXT PRIMARY KEY,
+            description     TEXT NOT NULL DEFAULT '',
+            usage_guide     TEXT NOT NULL DEFAULT '',
+            source_policy_ids TEXT DEFAULT '[]',
+            version         INTEGER NOT NULL DEFAULT 1,
+            metadata        TEXT DEFAULT '{}',
+            created_at      TEXT NOT NULL
+        );
+
+        CREATE VIRTUAL TABLE IF NOT EXISTS traces_fts
+            USING fts5(
+                user_content,
+                assistant_content,
+                tags,
+                content='traces',
+                content_rowid='rowid'
+            );
+
+        CREATE TRIGGER IF NOT EXISTS traces_ai AFTER INSERT ON traces BEGIN
+            INSERT INTO traces_fts(rowid, user_content, assistant_content, tags)
+            VALUES (new.rowid, new.user_content, new.assistant_content, new.tags);
+        END;
+
+        CREATE TRIGGER IF NOT EXISTS traces_ad AFTER DELETE ON traces BEGIN
+            INSERT INTO traces_fts(traces_fts, rowid, user_content, assistant_content, tags)
+            VALUES ('delete', old.rowid, old.user_content, old.assistant_content, old.tags);
+        END;
+
+        CREATE TRIGGER IF NOT EXISTS traces_au AFTER UPDATE ON traces BEGIN
+            INSERT INTO traces_fts(traces_fts, rowid, user_content, assistant_content, tags)
+            VALUES ('delete', old.rowid, old.user_content, old.assistant_content, old.tags);
+            INSERT INTO traces_fts(rowid, user_content, assistant_content, tags)
+            VALUES (new.rowid, new.user_content, new.assistant_content, new.tags);
+        END;
+    """)
+    conn.commit()
+
+
+def drop_schema(conn_or_cache: CacheConnection) -> None:
+    """Drop all tables (for testing)."""
+    conn = conn_or_cache.conn if isinstance(conn_or_cache, CacheConnection) else conn_or_cache
+    conn.executescript("""
+        DROP TABLE IF EXISTS traces_fts;
+        DROP TABLE IF EXISTS skills;
+        DROP TABLE IF EXISTS policies;
+        DROP TABLE IF EXISTS traces;
+    """)
+    conn.commit()

cc_star/cache/skills.py

@@ -0,0 +1,89 @@
+"""Skill repository — local SQLite CRUD for skills."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from cc_star.cache.connection import CacheConnection
+from cc_star.cache.schema import ensure_schema
+from cc_star.memos.types import SkillRow
+
+
+class SkillRepository:
+    """Persist and query skills locally."""
+
+    def __init__(self, cache: CacheConnection):
+        self._cache = cache
+        ensure_schema(cache)
+
+    def insert(self, skill: SkillRow) -> None:
+        """Insert a skill into local cache."""
+        conn = self._cache.conn
+        conn.execute(
+            """
+            INSERT OR REPLACE INTO skills
+                (name, description, usage_guide, source_policy_ids,
+                 version, metadata, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                skill.name,
+                skill.description,
+                skill.usage_guide,
+                json.dumps(skill.source_policy_ids, ensure_ascii=False),
+                skill.version,
+                json.dumps(skill.metadata, ensure_ascii=False, default=str),
+                skill.created_at,
+            ),
+        )
+        conn.commit()
+
+    def get(self, name: str) -> Optional[SkillRow]:
+        """Get a skill by name."""
+        row = self._cache.conn.execute(
+            "SELECT * FROM skills WHERE name = ?", (name,)
+        ).fetchone()
+        if row is None:
+            return None
+        return self._row_to_skill(row)
+
+    def list_all(self) -> list[SkillRow]:
+        """List all skills."""
+        rows = self._cache.conn.execute(
+            "SELECT * FROM skills ORDER BY name ASC"
+        ).fetchall()
+        return [self._row_to_skill(r) for r in rows]
+
+    def search(self, query: str, limit: int = 10) -> list[SkillRow]:
+        """Search skills by name or description."""
+        like = f"%{query}%"
+        rows = self._cache.conn.execute(
+            "SELECT * FROM skills WHERE name LIKE ? OR description LIKE ? LIMIT ?",
+            (like, like, limit),
+        ).fetchall()
+        return [self._row_to_skill(r) for r in rows]
+
+    def delete(self, name: str) -> None:
+        """Delete a skill by name."""
+        self._cache.conn.execute("DELETE FROM skills WHERE name = ?", (name,))
+        self._cache.conn.commit()
+
+    def count(self) -> int:
+        """Total skill count."""
+        row = self._cache.conn.execute("SELECT COUNT(*) as cnt FROM skills").fetchone()
+        return row["cnt"] if row else 0
+
+    @staticmethod
+    def _row_to_skill(row: Any) -> SkillRow:
+        return SkillRow(
+            name=row["name"],
+            description=row["description"],
+            usage_guide=row["usage_guide"],
+            source_policy_ids=json.loads(row["source_policy_ids"])
+            if isinstance(row["source_policy_ids"], str)
+            else [],
+            version=row["version"],
+            metadata=json.loads(row["metadata"]) if isinstance(row["metadata"], str) else {},
+            created_at=row["created_at"],
+        )

cc_star/cache/traces.py

@@ -0,0 +1,163 @@
+"""Trace repository — local SQLite CRUD for traces with batch operations."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from cc_star.cache.connection import CacheConnection
+from cc_star.cache.schema import ensure_schema
+from cc_star.memos.types import TraceRow
+
+
+class TraceRepository:
+    """Persist and query traces locally."""
+
+    def __init__(self, cache: CacheConnection):
+        self._cache = cache
+        ensure_schema(cache)
+        # Prepared statements
+        self._insert_sql = (
+            "INSERT OR REPLACE INTO traces "
+            "(id, session_id, turn_index, user_content, assistant_content, "
+            "embedding, reward, tags, metadata, created_at, synced) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"
+        )
+
+    def insert(self, trace: TraceRow) -> None:
+        """Insert a single trace into local cache."""
+        self._cache.execute(
+            self._insert_sql,
+            self._trace_to_row(trace),
+        )
+
+    def insert_batch(self, traces: list[TraceRow]) -> None:
+        """Batch insert multiple traces (faster than individual inserts)."""
+        rows = [self._trace_to_row(t) for t in traces]
+        self._cache.executemany(self._insert_sql, rows)
+
+    def get(self, trace_id: str) -> Optional[TraceRow]:
+        """Get a trace by ID."""
+        row = self._cache.execute(
+            "SELECT * FROM traces WHERE id = ?", (trace_id,)
+        ).fetchone()
+        if row is None:
+            return None
+        return self._row_to_trace(row)
+
+    def list_by_session(self, session_id: str, limit: int = 50) -> list[TraceRow]:
+        """List traces for a session, ordered by turn index."""
+        rows = self._cache.execute(
+            "SELECT * FROM traces WHERE session_id = ? ORDER BY turn_index ASC LIMIT ?",
+            (session_id, limit),
+        ).fetchall()
+        return [self._row_to_trace(r) for r in rows]
+
+    def search_fts(self, query: str, limit: int = 8) -> list[TraceRow]:
+        """Full-text search on traces using FTS5."""
+        # Strip surrogate characters and control chars that crash FTS5
+        query = query.encode("utf-8", "surrogatepass").decode("utf-8", "replace")
+        query = "".join(c for c in query if c.isprintable() or c in (" ", "\n", "\t"))
+        safe = query.replace('"', '""')
+        rows = self._cache.execute(
+            """
+            SELECT t.* FROM traces t
+            JOIN traces_fts fts ON t.rowid = fts.rowid
+            WHERE traces_fts MATCH ?
+            ORDER BY rank
+            LIMIT ?
+            """,
+            (safe, limit),
+        ).fetchall()
+        return [self._row_to_trace(r) for r in rows]
+
+    def list_recent(self, limit: int = 20) -> list[TraceRow]:
+        """List most recent traces."""
+        rows = self._cache.execute(
+            "SELECT * FROM traces ORDER BY created_at DESC LIMIT ?",
+            (limit,),
+        ).fetchall()
+        return [self._row_to_trace(r) for r in rows]
+
+    def count(self) -> int:
+        """Total trace count."""
+        row = self._cache.execute(
+            "SELECT COUNT(*) as cnt FROM traces"
+        ).fetchone()
+        return row["cnt"] if row else 0
+
+    def mark_synced(self, trace_id: str) -> None:
+        """Mark a trace as synced to OpenViking."""
+        self._cache.execute(
+            "UPDATE traces SET synced = 1 WHERE id = ?", (trace_id,)
+        )
+
+    def mark_synced_batch(self, trace_ids: list[str]) -> None:
+        """Batch mark multiple traces as synced."""
+        rows = [(tid,) for tid in trace_ids]
+        self._cache.executemany(
+            "UPDATE traces SET synced = 1 WHERE id = ?", rows,
+        )
+
+    def get_unsynced(self, limit: int = 50) -> list[TraceRow]:
+        """Get traces that haven't been synced to OpenViking yet."""
+        rows = self._cache.execute(
+            "SELECT * FROM traces WHERE synced = 0 ORDER BY created_at ASC LIMIT ?",
+            (limit,),
+        ).fetchall()
+        return [self._row_to_trace(r) for r in rows]
+
+    def delete_old(self, before_timestamp: str) -> int:
+        """Delete traces older than a timestamp. Returns count deleted."""
+        cursor = self._cache.execute(
+            "DELETE FROM traces WHERE created_at < ?", (before_timestamp,)
+        )
+        return cursor.rowcount
+
+    def get_all_embeddings(self, limit: int = 1000) -> list[tuple[str, list[float]]]:
+        """Get all (id, embedding) pairs for bulk similarity search."""
+        rows = self._cache.execute(
+            "SELECT id, embedding FROM traces WHERE embedding IS NOT NULL LIMIT ?",
+            (limit,),
+        ).fetchall()
+        result = []
+        for r in rows:
+            if r["embedding"]:
+                try:
+                    emb = json.loads(r["embedding"])
+                    if emb:
+                        result.append((r["id"], emb))
+                except (json.JSONDecodeError, TypeError):
+                    pass
+        return result
+
+    @staticmethod
+    def _trace_to_row(trace: TraceRow) -> tuple:
+        return (
+            trace.id,
+            trace.session_id,
+            trace.turn_index,
+            trace.user_content,
+            trace.assistant_content,
+            json.dumps(trace.embedding) if trace.embedding else None,
+            trace.reward,
+            json.dumps(trace.tags, ensure_ascii=False),
+            json.dumps(trace.metadata, ensure_ascii=False, default=str),
+            trace.created_at,
+            0,
+        )
+
+    @staticmethod
+    def _row_to_trace(row: Any) -> TraceRow:
+        return TraceRow(
+            id=row["id"],
+            session_id=row["session_id"],
+            turn_index=row["turn_index"],
+            user_content=row["user_content"],
+            assistant_content=row["assistant_content"],
+            embedding=json.loads(row["embedding"]) if row["embedding"] else None,
+            reward=row["reward"],
+            tags=json.loads(row["tags"]) if isinstance(row["tags"], str) else [],
+            metadata=json.loads(row["metadata"]) if isinstance(row["metadata"], str) else {},
+            created_at=row["created_at"],
+        )

cc_star/cache/vector.py

@@ -0,0 +1,58 @@
+"""Local cosine similarity search using numpy."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+
+
+def cosine_similarity(a: list[float], b: list[float]) -> float:
+    """Compute cosine similarity between two vectors."""
+    va = np.array(a, dtype=np.float64)
+    vb = np.array(b, dtype=np.float64)
+    norm_a = np.linalg.norm(va)
+    norm_b = np.linalg.norm(vb)
+    if norm_a < 1e-12 or norm_b < 1e-12:
+        return 0.0
+    return float(np.dot(va, vb) / (norm_a * norm_b))
+
+
+def search_by_embedding(
+    query_embedding: list[float],
+    candidates: list[tuple[str, list[float]]],
+    k: int = 8,
+) -> list[tuple[str, float]]:
+    """Search nearest neighbors by cosine similarity.
+
+    Args:
+        query_embedding: Query vector.
+        candidates: List of (id, embedding_vector) tuples.
+        k: Number of results to return.
+
+    Returns:
+        List of (id, score) tuples sorted by descending similarity.
+    """
+    if not candidates:
+        return []
+
+    scores: list[tuple[str, float]] = []
+    for cid, emb in candidates:
+        if emb and len(emb) > 0:
+            sim = cosine_similarity(query_embedding, emb)
+            scores.append((cid, sim))
+
+    scores.sort(key=lambda x: x[1], reverse=True)
+    return scores[:k]
+
+
+def compute_embedding(text: str, dim: int = 384) -> list[float]:
+    """Compute a simple bag-of-characters embedding as a fallback.
+
+    This is a lightweight fallback when the OpenViking embed API is unavailable.
+    For production use, use OpenViking's native embedding instead.
+    """
+    rng = np.random.RandomState(hash(text) & 0xFFFFFFFF)
+    vec = rng.randn(dim)
+    vec = vec / (np.linalg.norm(vec) + 1e-12)
+    return vec.tolist()