ccrecall 0.10.0__py3-none-any.whl

ccrecall/__init__.py

@@ -0,0 +1,18 @@
+"""
+ccrecall — conversation memory package for Claude Code.
+
+Submodules:
+  db                — Database connection, config/settings, vec operations, logging
+  schema            — Conversation DB schema constants (SCHEMA_*) and FTS detection
+  content           — Message content extraction and tool detection
+  parsing           — JSONL parsing, branch detection, metadata extraction
+  formatting        — Session formatting, time/path utilities
+  project_ops       — Shared project upsert logic (cwd strategy + JSONL-probe strategy)
+  session_ops       — Shared session import logic (used by sync and import pipelines)
+  token_schema      — Token ingest schema definitions, ensure_schema(), version management
+  token_parser      — Token JSONL parsing, data classes, session parsing, file discovery
+  token_analytics   — Session import and token_snapshots backfill
+  token_output      — Dashboard JSON output assembly (chart queries)
+  token_insights    — Trend analysis, insight generation, findings/recommendations
+  token_dashboard   — Token dashboard deployment and main() entry point
+"""

ccrecall/cli/__init__.py

@@ -0,0 +1,98 @@
+"""ccrecall CLI — single entry point consolidating the former cm-* binaries.
+
+Root ``App`` plus a ``backfill`` sub-``App``. Command functions live in
+``commands.py`` and register themselves on import (the import at the bottom of
+this module triggers that registration).
+"""
+
+import inspect
+from importlib.metadata import PackageNotFoundError, version
+from typing import Annotated
+
+from cyclopts import App, Group, Parameter
+from cyclopts.exceptions import CycloptsError
+
+from ccrecall.cli.context import CLIContext
+
+try:
+    _version = version("ccrecall")
+except PackageNotFoundError:
+    _version = "unknown"
+
+app = App(
+    name="ccrecall",
+    version=_version,
+    version_flags=["--version", "-V"],
+    help="Conversation history and semantic search for Claude Code.",
+    # Plaintext so the examples block keeps its line breaks and literal <…>
+    # placeholders (markdown/rst reflow them and strip the angle brackets).
+    help_format="plaintext",
+    help_epilogue=(
+        "Examples:\n"
+        "  ccrecall recent --n 5\n"
+        "  ccrecall --json search -q 'auth bug'\n"
+        "  ccrecall tail <session-id>\n"
+        "  ccrecall backfill embeddings --status"
+    ),
+)
+
+# Global options live on the meta launcher; group them so they render under one
+# heading in `ccrecall --help` rather than scattered among the subcommands.
+app.meta.group_parameters = Group("Global Options", sort_key=0)
+
+
+backfill_app = App(name="backfill", help="Seed historical summaries and embeddings.")
+app.command(backfill_app)
+
+
+@app.meta.default
+def launcher(
+    *tokens: Annotated[str, Parameter(show=False, allow_leading_hyphen=True)],
+    json_mode: Annotated[
+        bool,
+        Parameter(name=["--json"], help="Emit machine-readable JSON instead of markdown.", negative=[]),
+    ] = False,
+) -> None:
+    """Parse global options into a CLIContext, then dispatch to the chosen command.
+
+    The single global ``--json`` is the only output-format surface — commands no
+    longer carry their own ``--json``/``--format`` flag, which is what keeps the
+    contract from drifting. ``parse_args`` here mirrors the app-level error
+    contract (boxed message, raise instead of exit) so ``main`` can force exit 2.
+    """
+    ctx = CLIContext(json_mode=json_mode)
+    # print_error=True is load-bearing: a CycloptsError escaping a meta.default
+    # body is NOT re-rendered by the outer app.meta(), so this inner call is the
+    # only thing that prints the boxed message. exit_on_error=False makes it
+    # raise instead, so main()'s handler can force exit 2.
+    command, bound, _ = app.parse_args(tokens, print_error=True, exit_on_error=False)
+    # Inject ctx only where the command declares it (recent/search/backfill
+    # embeddings) — output-less commands (hooks, tail, import) omit the param and
+    # ignore a global --json. The third parse_args return value carries the ctx
+    # *type*, not an instance, so it can't do the injection; we set it by hand.
+    # ctx must stay keyword-only in every command for **bound.kwargs to carry it.
+    if "ctx" in inspect.signature(command).parameters:
+        bound.arguments["ctx"] = ctx
+    command(*bound.args, **bound.kwargs)
+
+
+def main() -> None:
+    """Console-script entry point.
+
+    Wraps the cyclopts meta app so every argument-parsing error exits 2 — the
+    usual usage-error code — carrying cyclopts' boxed message, so parser errors
+    agree with the app-level validators. A command that raises its own SystemExit
+    bypasses this handler (SystemExit is not a CycloptsError), keeping its code.
+    """
+    try:
+        app.meta(exit_on_error=False, print_error=True)
+    except CycloptsError as exc:
+        raise SystemExit(2) from exc
+
+
+# Importing the commands module registers every subcommand on ``app`` /
+# ``backfill_app`` via the @app.command decorators it defines. Kept at the
+# bottom so ``app`` and ``backfill_app`` exist before the decorators run. The
+# redundant ``as commands`` alias marks it as an intentional side-effect import,
+# so ruff and pyright don't flag it unused without needing a separate sentinel.
+from ccrecall.cli import commands as commands  # noqa: E402

ccrecall/cli/commands.py

@@ -0,0 +1,245 @@
+"""ccrecall subcommand definitions.
+
+Each command is a thin cyclopts wrapper that parses typed parameters and calls
+the ``run(...)`` logic function in the owning module. Output, exit codes, and
+PID-file lifecycle are preserved from the former cm-* entry points; only the
+argument-parsing layer changed (argparse -> cyclopts).
+"""
+
+from pathlib import Path
+from typing import Annotated, Literal
+
+from cyclopts import ArgumentCollection, Group, Parameter
+from cyclopts.validators import Number
+
+from ccrecall import recent_chats as recent_chats_mod
+from ccrecall import search_conversations as search_mod
+from ccrecall import session_tail as session_tail_mod
+from ccrecall import token_dashboard as token_dashboard_mod
+from ccrecall.cli import app, backfill_app
+from ccrecall.cli.context import DEFAULT_CLI_CONTEXT, CLIContextParam
+from ccrecall.db import DEFAULT_DB_PATH, DEFAULT_PROJECTS_DIR
+from ccrecall.embeddings import DEFAULT_EMBED_THREADS
+from ccrecall.hooks import backfill_embeddings as backfill_embeddings_mod
+from ccrecall.hooks import backfill_summaries as backfill_summaries_mod
+from ccrecall.hooks import import_conversations as import_mod
+from ccrecall.hooks import sync_current as sync_current_mod
+from ccrecall.hooks import write_config as write_config_mod
+
+# store_true flags carry no --no-<flag> negation, matching the former argparse.
+_FLAG = Parameter(negative=[])
+
+
+def _exactly_one_query_or_status(arguments: ArgumentCollection) -> None:
+    """Group validator: search needs exactly one of --query / --status.
+
+    Runs at parse time so the message renders in cyclopts' boxed error style
+    (and exits 2 via the entry-point wrapper), matching every other usage error.
+    search_conversations.run() keeps the same guard for direct (non-CLI) callers.
+    """
+    # arg.tokens is non-empty only when that argument was supplied on the CLI.
+    provided = [arg for arg in arguments if arg.tokens]
+    if not provided:
+        raise ValueError("one of --query/-q or --status is required")
+    if len(provided) > 1:
+        raise ValueError("--query and --status are mutually exclusive")
+
+
+# Membership in this group (query + status below) is what triggers the
+# exactly-one validator at parse time — the flags carry no logic themselves.
+_SEARCH_MODE = Group("Search mode", validator=_exactly_one_query_or_status)
+
+# Output format is global: the meta launcher's --json fills ctx.json_mode, which
+# read commands map to their run()'s output_format kwd. list_sessions -> --list
+# is renamed to avoid shadowing the list builtin; Parameter(name=...) keeps the
+# user-facing flag intact.
+
+# Shared flag types mirroring the former cm-* read tools.
+_VERBOSE = Annotated[bool, _FLAG, Parameter(name=["--verbose", "-v"], help="Include files_modified and commits.")]
+_NOTIFS = Annotated[
+    bool, _FLAG, Parameter(name=["--include-notifications"], help="Include task notification messages.")
+]
+_DB = Annotated[Path, Parameter(name=["--db"], help="Database path.")]
+# Default for `tail -n`, sourced from session_tail so the two never drift.
+_TAIL_DEFAULT_N = session_tail_mod.DEFAULT_TAIL_EVENTS
+
+
+@app.command(name="sync-current")
+def cmd_sync_current(
+    *,
+    input_file: Annotated[
+        Path | None,
+        Parameter(name="--input-file", help="Read hook input from this file instead of stdin."),
+    ] = None,
+) -> None:
+    """Sync the current session into the memory DB (Stop-hook helper)."""
+    sync_current_mod.run(input_file)
+
+
+@app.command(name="import")
+def cmd_import(
+    *,
+    db: Annotated[Path, Parameter(help="Database path.")] = DEFAULT_DB_PATH,
+    projects_dir: Annotated[Path, Parameter(help="Projects directory.")] = DEFAULT_PROJECTS_DIR,
+    project: Annotated[str | None, Parameter(help="Import only this project (by directory name).")] = None,
+) -> None:
+    """Import Claude Code conversations into the memory DB."""
+    import_mod.run(db=db, projects_dir=projects_dir, project=project)
+
+
+@app.command(name="stats")
+def cmd_stats(
+    *,
+    db: Annotated[Path, Parameter(help="Database path.")] = DEFAULT_DB_PATH,
+) -> None:
+    """Show memory database statistics."""
+    # Read-only DB-global counts: print_stats() shares no PID lifecycle with
+    # import.run(), so it can't disturb a concurrent background import.
+    import_mod.print_stats(db=db)
+
+
+@backfill_app.command(name="summaries")
+def cmd_backfill_summaries() -> None:
+    """Backfill context summaries for branches that lack a current one."""
+    backfill_summaries_mod.run()
+
+
+@backfill_app.command(name="embeddings")
+def cmd_backfill_embeddings(
+    *,
+    status: Annotated[bool, _FLAG, Parameter(help="Report progress and exit without embedding (read-only).")] = False,
+    days: Annotated[
+        int | None,
+        Parameter(validator=Number(gte=1), help="Only embed branches ended within the last N days (>= 1)."),
+    ] = None,
+    limit: Annotated[
+        int | None,
+        Parameter(validator=Number(gte=1), help="Stop after embedding at most N branches this run (>= 1)."),
+    ] = None,
+    progress_every: Annotated[
+        int, Parameter(help="Print a progress line every N newly embedded branches.")
+    ] = backfill_embeddings_mod.DEFAULT_PROGRESS_EVERY,
+    threads: Annotated[int, Parameter(help="Inference threads.")] = DEFAULT_EMBED_THREADS,
+    ctx: CLIContextParam = DEFAULT_CLI_CONTEXT,
+) -> None:
+    """Seed historical embeddings for active-leaf branch summaries (opt-in)."""
+    try:
+        code = backfill_embeddings_mod.run(
+            status=status,
+            json_mode=ctx.json_mode,
+            days=days,
+            limit=limit,
+            progress_every=progress_every,
+            threads=threads,
+        )
+    finally:
+        # Status is read-only: never disturb a concurrent backfill's PID marker.
+        if not status:
+            backfill_embeddings_mod.cleanup_pid()
+    raise SystemExit(code)
+
+
+@app.command(name="recent")
+def cmd_recent(
+    *,
+    n: Annotated[
+        int,
+        Parameter(
+            name=["--n", "-n"],
+            validator=Number(gte=1, lte=recent_chats_mod.MAX_RECENT_SESSIONS),
+            help=f"Number of sessions (1-{recent_chats_mod.MAX_RECENT_SESSIONS}).",
+        ),
+    ] = 3,
+    sort_order: Annotated[Literal["desc", "asc"], Parameter(name=["--sort-order"], help="Sort order.")] = "desc",
+    before: Annotated[str | None, Parameter(help="Sessions before this datetime (ISO).")] = None,
+    after: Annotated[str | None, Parameter(help="Sessions after this datetime (ISO).")] = None,
+    session: Annotated[str | None, Parameter(help="Filter by session UUID (prefix match).")] = None,
+    project: Annotated[str | None, Parameter(help="Filter by project name(s), comma-separated.")] = None,
+    path: Annotated[str | None, Parameter(help="Filter by cwd substring (e.g. worktree name).")] = None,
+    verbose: _VERBOSE = False,
+    include_notifications: _NOTIFS = False,
+    db: _DB = DEFAULT_DB_PATH,
+    ctx: CLIContextParam = DEFAULT_CLI_CONTEXT,
+) -> None:
+    """List recent conversation sessions."""
+    recent_chats_mod.run(
+        n=n,
+        sort_order=sort_order,
+        before=before,
+        after=after,
+        session=session,
+        project=project,
+        path=path,
+        output_format=ctx.output_format,
+        verbose=verbose,
+        include_notifications=include_notifications,
+        db=db,
+    )
+
+
+@app.command(name="search")
+def cmd_search(
+    *,
+    query: Annotated[str | None, Parameter(name=["--query", "-q"], group=_SEARCH_MODE, help="Search keywords.")] = None,
+    status: Annotated[bool, _FLAG, Parameter(group=_SEARCH_MODE, help="Print diagnostic status and exit.")] = False,
+    keyword_only: Annotated[bool, _FLAG, Parameter(help="Skip embedding; keyword search only.")] = False,
+    max_results: Annotated[
+        int,
+        Parameter(
+            name=["--max-results"],
+            validator=Number(gte=1, lte=search_mod.MAX_SEARCH_RESULTS),
+            help=f"Max sessions (1-{search_mod.MAX_SEARCH_RESULTS}).",
+        ),
+    ] = 5,
+    session: Annotated[str | None, Parameter(help="Filter by session UUID (prefix match).")] = None,
+    project: Annotated[str | None, Parameter(help="Filter by project name(s), comma-separated.")] = None,
+    path: Annotated[str | None, Parameter(help="Filter by cwd substring (e.g. worktree name).")] = None,
+    verbose: _VERBOSE = False,
+    include_notifications: _NOTIFS = False,
+    db: _DB = DEFAULT_DB_PATH,
+    ctx: CLIContextParam = DEFAULT_CLI_CONTEXT,
+) -> None:
+    """Search conversation sessions (keyword + vector fusion)."""
+    search_mod.run(
+        query=query,
+        status=status,
+        keyword_only=keyword_only,
+        max_results=max_results,
+        session=session,
+        project=project,
+        path=path,
+        output_format=ctx.output_format,
+        verbose=verbose,
+        include_notifications=include_notifications,
+        db=db,
+    )
+
+
+@app.command(name="tail")
+def cmd_tail(
+    selector: Annotated[str | None, Parameter(help="Session id or substring to target.")] = None,
+    *,
+    list_sessions: Annotated[bool, _FLAG, Parameter(name=["--list"], help="List sessions and exit.")] = False,
+    cwd: Annotated[str | None, Parameter(name=["--cwd"], help="Derive project dir from this path.")] = None,
+    n: Annotated[int, Parameter(name=["-n"], help="Number of tail events to show.")] = _TAIL_DEFAULT_N,
+) -> None:
+    """Print the tail of a prior session's transcript for fast resume."""
+    raise SystemExit(session_tail_mod.run(selector, list_sessions=list_sessions, cwd=cwd, n=n))
+
+
+@app.command(name="tokens")
+def cmd_tokens() -> None:
+    """Ingest token data, refresh the dashboard, and print a slim summary."""
+    token_dashboard_mod.run()
+
+
+@app.command(name="write-config")
+def cmd_write_config(
+    *,
+    defaults: Annotated[bool, _FLAG, Parameter(help="Write recommended defaults without explicit flags.")] = False,
+    auto_inject_context: Annotated[
+        bool | None, Parameter(name=["--auto-inject-context"], help="Enable session context injection on startup.")
+    ] = None,
+) -> None:
+    """Write or update the ccrecall config from onboarding choices."""
+    write_config_mod.run(defaults=defaults, auto_inject_context=auto_inject_context)

ccrecall/cli/context.py

@@ -0,0 +1,31 @@
+"""CLI context object — frozen dataclass carrying per-invocation global options."""
+
+from dataclasses import dataclass
+from typing import Annotated
+
+from cyclopts import Parameter
+
+
+@dataclass(frozen=True)
+class CLIContext:
+    """Immutable global options for a single CLI invocation.
+
+    Built by the meta launcher from parsed global flags and injected into every
+    command that declares a ``ctx`` parameter via ``bound.arguments["ctx"]``.
+    Commands map it onto their owning ``run(...)`` kwargs, so ``run`` stays the
+    stable callable API while the CLI keeps one global ``--json`` surface.
+    """
+
+    json_mode: bool = False
+
+    @property
+    def output_format(self) -> str:
+        """The ``output_format`` string the markdown/JSON-aware ``run()`` funcs expect."""
+        return "json" if self.json_mode else "markdown"
+
+
+# parse=False: the launcher injects this, cyclopts never fills it from tokens,
+# and it stays out of every command's --help.
+CLIContextParam = Annotated[CLIContext, Parameter(parse=False)]
+
+DEFAULT_CLI_CONTEXT = CLIContext()

ccrecall/content.py

@@ -0,0 +1,152 @@
+"""Message content extraction and tool detection utilities."""
+
+import json
+import re
+
+# Commit messages are stored truncated — they're for at-a-glance session context,
+# not full reconstruction.
+MAX_COMMIT_MESSAGE_LEN = 100
+
+
+def sanitize_fts_term(term: str) -> str:
+    """Remove FTS special characters from search term.
+
+    Strips characters that are FTS operators or special syntax:
+    quotes, parentheses, asterisks, and FTS keywords.
+    Hyphens are replaced with spaces so hyphenated identifiers
+    (e.g. 'pytest-mock') match their FTS tokens correctly — the
+    unicode61 tokenizer splits on hyphens, so 'pytest-mock' indexes
+    as two tokens ('pytest', 'mock'). Stripping hyphens entirely
+    would produce 'pytestmock', which matches nothing.
+    Leading hyphens (FTS NOT shorthand) become harmless whitespace.
+    """
+    # Replace hyphens with spaces (handles both identifier separators
+    # and leading NOT-operator hyphens)
+    sanitized = term.replace("-", " ")
+    # Remove remaining FTS operators: quotes, parens, asterisk, caret
+    sanitized = re.sub(r'["\(\)*^]', "", sanitized)
+    # Remove FTS keywords: NEAR, AND, OR, NOT (case-insensitive)
+    sanitized = re.sub(r"\b(NEAR|AND|OR|NOT)\b", "", sanitized, flags=re.IGNORECASE)
+    # Collapse whitespace and strip
+    sanitized = re.sub(r"\s+", " ", sanitized).strip()
+    return sanitized
+
+
+def extract_text_content(content) -> tuple[str, bool, bool, str | None]:
+    """
+    Extract text from message content.
+    Returns: (text, has_tool_use, has_thinking, tool_summary_json)
+
+    tool_summary_json is a JSON string like '{"Bash":3,"Read":2}' or None.
+    Tool use markers are NOT materialized into text.
+    """
+    has_tool_use = False
+    has_thinking = False
+    tool_counts: dict[str, int] = {}
+
+    if isinstance(content, str):
+        # Clean up command artifacts
+        text = re.sub(r"<command-name>.*?</command-name>", "", content, flags=re.DOTALL)
+        text = re.sub(r"<command-message>.*?</command-message>", "", text, flags=re.DOTALL)
+        text = re.sub(r"<command-args>.*?</command-args>", "", text, flags=re.DOTALL)
+        text = re.sub(
+            r"<local-command-stdout>.*?</local-command-stdout>",
+            "",
+            text,
+            flags=re.DOTALL,
+        )
+        text = re.sub(r"<channel\b[^>]*>\n?([\s\S]*?)\n?</channel>", r"\1", text, flags=re.DOTALL)
+        return text.strip(), False, False, None
+
+    if isinstance(content, list):
+        texts = []
+        for item in content:
+            if isinstance(item, dict):
+                item_type = item.get("type", "")
+                if item_type == "text":
+                    texts.append(item.get("text", ""))
+                elif item_type == "tool_use":
+                    has_tool_use = True
+                    tool_name = item.get("name", "")
+                    if tool_name:
+                        tool_counts[tool_name] = tool_counts.get(tool_name, 0) + 1
+                elif item_type == "thinking":
+                    has_thinking = True
+        tool_summary = json.dumps(tool_counts) if tool_counts else None
+        return "\n".join(texts).strip(), has_tool_use, has_thinking, tool_summary
+
+    return "", False, False, None
+
+
+def parse_origin(entry: dict) -> str | None:
+    """Extract clean platform name from origin.server (e.g. 'telegram' from 'plugin:telegram:telegram')."""
+    origin = entry.get("origin")
+    if not origin or not isinstance(origin, dict):
+        return None
+    server = origin.get("server") or ""
+    if not server:
+        return None
+    # Pattern: "plugin:telegram:telegram" -> "telegram"
+    parts = server.split(":")
+    if len(parts) >= 2 and parts[1]:
+        return parts[1]
+    return None
+
+
+def extract_plain_text(content) -> str | None:
+    """Join text blocks (or a bare string) into stripped plain text; None if neither shape."""
+    if isinstance(content, list):
+        texts = [item.get("text", "") for item in content if isinstance(item, dict) and item.get("type") == "text"]
+        return "\n".join(texts).strip()
+    if isinstance(content, str):
+        return content.strip()
+    return None
+
+
+def is_task_notification(content) -> bool:
+    """Check if content is a task-notification message (subagent result)."""
+    text = extract_plain_text(content)
+    return text is not None and text.startswith("<task-notification>")
+
+
+def is_teammate_message(content) -> bool:
+    """Detect teammate coordination messages (team reports, idle notifications, shutdown)."""
+    text = extract_plain_text(content)
+    return text is not None and text.startswith("<teammate-message")
+
+
+def is_tool_result(content) -> bool:
+    """Check if content is a tool result (not a real user message)."""
+    if isinstance(content, list) and content:
+        first = content[0]
+        if isinstance(first, dict) and first.get("type") == "tool_result":
+            return True
+    return False
+
+
+def extract_files_modified(content) -> list[str]:
+    """Extract file paths from Edit/Write/MultiEdit tool uses."""
+    files = []
+    if isinstance(content, list):
+        for item in content:
+            if isinstance(item, dict) and item.get("type") == "tool_use":
+                name = item.get("name", "")
+                inp = item.get("input", {})
+                if name in ("Edit", "Write", "MultiEdit") and "file_path" in inp:
+                    files.append(inp["file_path"])
+    return files
+
+
+def extract_commits(content) -> list[str]:
+    """Extract git commit messages from Bash tool uses."""
+    commits = []
+    if isinstance(content, list):
+        for item in content:
+            if isinstance(item, dict) and item.get("type") == "tool_use":
+                if item.get("name") == "Bash":
+                    cmd = item.get("input", {}).get("command", "")
+                    if "git commit" in cmd:
+                        match = re.search(r'-m\s+["\']([^"\']+)["\']', cmd)
+                        if match:
+                            commits.append(match.group(1)[:MAX_COMMIT_MESSAGE_LEN])
+    return commits