cc-star 0.1.0__tar.gz

cc_star-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}
+          skip-existing: true

cc_star-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+
+# Build
+dist/
+build/
+*.egg
+
+# Test
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

cc_star-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2026 jigeagent
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published
+by the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.

cc_star-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: cc-star
+Version: 0.1.0
+Summary: Upgrade Claude Code native memory to digital-life memory — SQLite hot storage + FTS5 retrieval + optional OpenViking cold sync
+Project-URL: Homepage, https://github.com/jigeagent/cc-star
+License: AGPL-3.0-or-later
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28
+Requires-Dist: pyyaml>=6.0

cc_star-0.1.0/README.md

@@ -0,0 +1,101 @@
+# cc-star
+
+**Claude Code memory upgrade kit.**
+
+Upgrade Claude Code's native `MEMORY.md` (a plain text file that gets constantly truncated) into a **digital-life memory system** — local SQLite hot storage + FTS5 retrieval + optional OpenViking cold sync.
+
+```
+pip install cc-star
+cc-star init
+# 30 seconds → permanent, searchable, offline-capable memory
+```
+
+## Features
+
+- **Persistent storage** — every conversation turn saved to local SQLite database
+- **Full-text search** — FTS5-powered memory retrieval across all past conversations
+- **Context injection** — automatically injects relevant past memories before each prompt
+- **Compression protection** — preserves critical context (MEMORY.md, STATUS.md) across Claude Code compaction events
+- **Optional OpenViking sync** — cold storage with semantic search (install with `cc-star[ov]`)
+- **Zero Claude Code config** — `cc-star init` handles all hook registration
+
+## Quick Start
+
+```bash
+# Install
+pip install cc-star
+
+# Initialize (30 seconds)
+cc-star init
+
+# Start a new Claude Code session — memories will be automatically
+# stored, searched, and injected
+
+# Search your memory
+cc-star search "how did we fix the auth bug?"
+
+# Check status
+cc-star status
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `cc-star init` | Initialize the memory system |
+| `cc-star status` | Show memory system status |
+| `cc-star search <query>` | Search local memory |
+| `cc-star config` | View all configuration |
+| `cc-star config <key> <value>` | Update configuration |
+| `cc-star uninstall` | Remove hooks from Claude Code settings |
+
+## Configuration
+
+Config file: `~/.cc-star/config.yaml`
+
+```yaml
+agent:
+  name: assistant
+  tags: ["claude-code"]
+storage:
+  path: ~/.cc-star/data
+memory:
+  max_inject: 5
+ov:
+  enabled: false
+  url: ""
+  sync_batch: 50
+hooks:
+  timeout_inject: 10
+  timeout_store: 15
+  timeout_summary: 30
+  timeout_session_start: 10
+  timeout_compact_save: 5
+  timeout_compact_restore: 10
+```
+
+## Architecture
+
+```
+Claude Code → 5 Hook Scripts → cache.db (SQLite+FTS5) → [optional] OpenViking
+                ↑
+           cc-star init
+                ↓
+          string.Template → ~/.cc-star/hooks/*.py
+```
+
+- **SessionStart** — checks OV health, shows last session summary
+- **UserPromptSubmit (inject)** — FTS5 + optional OV semantic search, RRF merge, injects as `additionalContext`
+- **Stop (store)** — reads transcript, extracts last turn, writes to cache.db
+- **SessionEnd (summary)** — extracts session summary, batch syncs to OV
+- **PreCompact/PostCompact (compact)** — preserves MEMORY.md / STATUS.md / OV snapshot across compression
+
+## Dependencies
+
+- **hermes-next** (>=0.2) — SQLite cache + FTS5 retrieval engine
+- **pyyaml** (>=6.0) — YAML config parsing
+- **openviking** (optional, >=0.3.22) — OpenViking cold storage client
+
+## License
+
+AGPL-3.0 — see [LICENSE](LICENSE)

cc_star-0.1.0/cc_star/__init__.py

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

cc_star-0.1.0/cc_star/cache/__init__.py

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

cc_star-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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"],
+        )