ragtime-cli 0.1.0__py3-none-any.whl

src/commands/remember.md

@@ -0,0 +1,168 @@
+---
+description: Capture ad-hoc knowledge to local memory mid-session
+allowed-arguments: the thing to remember (e.g., /remember auth uses 15-min JWT expiry)
+allowed-tools: Bash, AskUserQuestion, mcp__ragtime__remember
+---
+
+# Remember
+
+Capture ad-hoc knowledge to the local memory system during a session.
+
+**Usage:**
+- `/remember auth uses 15-minute JWT expiry` - Quick capture with content
+- `/remember` - Interactive mode, asks what to remember
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     CUSTOMIZABLE: Modify prompts, add project-specific types, adjust the
+     approval flow, etc. Everything above the RAGTIME CORE section can be
+     tailored to your project's needs.
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+## When to Use
+
+Use `/remember` when you discover something worth preserving:
+- Architecture patterns ("the validation pipeline works like X")
+- Gotchas ("don't use Y because Z")
+- Decisions made during discussion
+- Team preferences discovered
+- Anything you'd want future sessions to know
+
+**Don't use for:**
+- Temporary debug notes (those belong in handoff.md)
+- Personal todos (use GitHub issues)
+- Things that will be captured by `/pr-graduate` anyway
+
+## Step 1: Capture the Knowledge
+
+**If `$ARGUMENTS` provided:**
+- Use it as the memory content
+
+**If no arguments:**
+- Ask: "What would you like me to remember?"
+
+## Step 2: Determine Memory Type
+
+Ask the user:
+
+```
+What type of knowledge is this?
+
+1. 🏗️ **Architecture** - How something works in the codebase
+2. 📋 **Convention** - Team rule or standard practice
+3. ⚠️ **Gotcha** - Warning or "don't do this"
+4. 🎯 **Decision** - Why we chose X over Y
+5. 💡 **Pattern** - Reusable approach for common problem
+```
+
+<!-- CUSTOMIZABLE: Add your own types here if needed -->
+
+## Step 3: Determine Scope
+
+```
+Where does this knowledge apply?
+
+1. 🌐 **Global** - Applies everywhere
+2. 📦 **Component** - Specific area (auth, claims, shifts, etc.)
+3. 📄 **File** - Specific file or folder
+```
+
+If Component or File, ask which one.
+
+<!-- CUSTOMIZABLE: Add your own components here -->
+
+## Step 4: Determine Confidence
+
+```
+How confident are you in this knowledge?
+
+1. ✅ **High** - Verified, tested, or from authoritative source
+2. ⚡ **Medium** - Observed it working, but not extensively tested
+3. 🤔 **Low** - Best guess or inference, should be validated
+```
+
+## Step 5: Determine Namespace
+
+Based on the memory type, suggest the appropriate namespace:
+
+| Type | Default Namespace |
+|------|------------------|
+| Architecture | `app` |
+| Convention | `team` |
+| Gotcha | `app` |
+| Decision | `app` (or `branch-{branch}` if WIP) |
+| Pattern | `app` |
+
+Ask: "Store in `{suggested namespace}`? Or somewhere else?"
+
+<!-- CUSTOMIZABLE: Adjust routing rules for your project -->
+
+## Step 6: Confirm and Store
+
+Present the memory for confirmation:
+
+```
+## Memory to Store
+
+**Content:** {the knowledge}
+**Type:** {type}
+**Namespace:** {namespace}
+**Confidence:** {confidence}
+**Scope:** {scope}
+**Component:** {if applicable}
+
+Store this? (yes/edit/cancel)
+```
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     RAGTIME CORE - DO NOT MODIFY
+     These commands must match ragtime's expected format.
+     Changing these may break storage/retrieval.
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+Once confirmed, store using ragtime MCP:
+
+```
+mcp__ragtime__remember:
+  content: "{the knowledge}"
+  namespace: "{namespace}"
+  type: "{architecture|convention|decision|pattern}"
+  component: "{component if applicable}"
+  confidence: "{high|medium|low}"
+  confidence_reason: "manual"
+  source: "remember"
+```
+
+<!-- ═══════════════════════════════════════════════════════════════════════════ -->
+
+## Step 7: Confirm Storage
+
+```
+✅ Remembered!
+
+"{abbreviated content}..."
+
+Stored to: {namespace}
+Confidence: {confidence}
+Query with: ragtime search "{topic}" --namespace {namespace}
+```
+
+## Quick Mode
+
+For rapid capture, you can specify everything inline:
+
+```
+/remember [high] auth uses 15-min JWT expiry #auth #architecture
+```
+
+Parsing:
+- `[high]` → confidence
+- `#auth` → component
+- `#architecture` → type
+- Rest → content
+
+## Notes
+
+- Memories stored via `/remember` get `source: "remember"` and default to medium confidence unless specified
+- If on a feature branch, consider whether this is branch-specific or general knowledge
+- For decisions that might be reversed, use low confidence
+- Team conventions should be discussed before storing to `team` namespace

src/commands/save.md

@@ -0,0 +1,10 @@
+---
+description: Save current progress (alias for /handoff)
+allowed-tools: Bash, Read, Write, mcp__ragtime__remember
+---
+
+# Save
+
+Alias for `/handoff`. See that command for full documentation.
+
+Run `/handoff` to save current context to branch memory.

src/commands/start.md

@@ -0,0 +1,206 @@
+---
+description: Start or resume work on a GitHub issue
+allowed-arguments: issue number (e.g., /start 230)
+allowed-tools: Bash, Read, Write, mcp__ragtime__search, mcp__ragtime__remember, AskUserQuestion
+---
+
+# Start or Resume Work
+
+Smart command that starts fresh OR resumes existing work depending on context.
+
+**Usage:**
+- `/start 230` - Start or resume work on issue #230
+- `/start` - Show your assigned issues and prompt for selection
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     CUSTOMIZABLE: Adjust branch naming conventions, issue lookup, workflow
+     steps, etc.
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+## Step 1: Determine the Issue
+
+**If an issue number was provided as an argument**, use it directly.
+
+**If no argument was provided**, check current state and prompt:
+
+```bash
+BRANCH=$(git branch --show-current)
+ISSUE_NUM=$(echo "$BRANCH" | grep -oE '[0-9]+' | head -1)
+DEVNAME=$(gh api user --jq '.login' 2>/dev/null || git config user.name | tr ' ' '-' | tr '[:upper:]' '[:lower:]')
+
+echo "Current branch: $BRANCH"
+echo "Developer: $DEVNAME"
+
+if [ -n "$ISSUE_NUM" ]; then
+  echo "Already on issue branch: #$ISSUE_NUM"
+else
+  echo ""
+  echo "=== Your Assigned Issues ==="
+  gh issue list --assignee @me --state open
+fi
+```
+
+If not on an issue branch and no argument provided, ask: **"Which issue would you like to start?"**
+
+## Step 2: Switch to the Branch
+
+```bash
+ISSUE_NUM={issue_number}
+
+# Check if branch exists
+EXISTING_BRANCH=$(git branch -a | grep -E "/$ISSUE_NUM-|/$ISSUE_NUM$" | head -1 | tr -d ' *')
+
+if [ -n "$EXISTING_BRANCH" ]; then
+  echo "Found existing branch: $EXISTING_BRANCH"
+  git checkout "$EXISTING_BRANCH"
+else
+  # Create new branch
+  ISSUE_TITLE=$(gh issue view $ISSUE_NUM --json title --jq '.title' | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-' | head -c 40)
+  NEW_BRANCH="$DEVNAME/$ISSUE_NUM-$ISSUE_TITLE"
+  echo "Creating new branch: $NEW_BRANCH"
+  git checkout -b "$NEW_BRANCH" main
+fi
+```
+
+<!-- CUSTOMIZABLE: Adjust branch naming convention for your project -->
+
+## Step 3: Check for Existing Context
+
+```bash
+BRANCH=$(git branch --show-current)
+BRANCH_SLUG=$(echo "$BRANCH" | tr '/' '-')
+CONTEXT_FILE=".claude/memory/branches/$BRANCH_SLUG/context.md"
+
+if [ -f "$CONTEXT_FILE" ]; then
+  echo "✓ Found branch context"
+  cat "$CONTEXT_FILE"
+else
+  echo "No existing context found"
+fi
+```
+
+### Decision Tree:
+
+**If context.md exists:**
+→ **RESUME MODE** - Go to Step 4a
+
+**If NO context.md:**
+→ **FRESH START MODE** - Go to Step 4b
+
+## Step 4a: Resume Mode
+
+Load and present the existing context:
+
+1. Read the branch's `context.md`
+2. Display the current state and what's left
+3. Ask: "Ready to continue? What would you like to work on first?"
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     RAGTIME CORE - DO NOT MODIFY
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+Also load any branch memories:
+
+```
+mcp__ragtime__search:
+  query: "decisions patterns architecture"
+  namespace: "branch-{branch}"
+  limit: 10
+```
+
+<!-- ═══════════════════════════════════════════════════════════════════════════ -->
+
+Present:
+
+```
+## Resuming Issue #{issue_num}
+
+### Current State:
+{from context.md}
+
+### What's Left:
+{from context.md}
+
+### Branch Memories:
+{list of decisions/patterns stored}
+
+Ready to continue? What would you like to work on first?
+```
+
+## Step 4b: Fresh Start Mode
+
+Create a new implementation plan:
+
+1. Fetch issue details:
+   ```bash
+   gh issue view "$ISSUE_NUM" --json title,body,labels,assignees
+   ```
+
+2. Parse the GitHub issue (title, body, labels)
+
+3. Identify which parts of the app this touches
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     RAGTIME CORE - DO NOT MODIFY
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+4. Search for relevant context:
+
+   **App knowledge (architecture for those areas):**
+   ```
+   mcp__ragtime__search:
+     query: "{component or feature area}"
+     namespace: "app"
+     limit: 10
+   ```
+
+   **Team conventions:**
+   ```
+   mcp__ragtime__search:
+     query: "conventions standards"
+     namespace: "team"
+     limit: 10
+   ```
+
+<!-- ═══════════════════════════════════════════════════════════════════════════ -->
+
+5. Create an implementation plan based on:
+   - Issue requirements
+   - Codebase knowledge from memories
+   - Team conventions
+
+6. Present the plan and ask if the user wants to proceed or adjust
+
+## Step 5: Save Initial Context (Fresh Start only)
+
+**After user approves the plan**, save it to context.md:
+
+```bash
+BRANCH=$(git branch --show-current)
+BRANCH_SLUG=$(echo "$BRANCH" | tr '/' '-')
+mkdir -p ".claude/memory/branches/$BRANCH_SLUG"
+```
+
+Write the context.md with the plan (see `/handoff` for format).
+
+## Step 6: Ready to Work
+
+```
+Ready to work on Issue #{issue_num}!
+
+What would you like to tackle first?
+```
+
+## Syncing Teammate Context
+
+If you need context from a teammate's branch:
+
+```bash
+# Fetch their branch
+git fetch origin jm/feature-auth
+
+# Sync their memories
+ragtime sync origin/jm/feature-auth
+```
+
+This creates `branches/jm-feature-auth(unmerged)/` with their context and memories, searchable but gitignored.

src/config.py

@@ -0,0 +1,101 @@
+"""
+Configuration management for ragtime.
+
+Config lives in .ragtime/config.yaml in the project root.
+"""
+
+from pathlib import Path
+from dataclasses import dataclass, field
+import yaml
+
+
+@dataclass
+class DocsConfig:
+    """Configuration for docs indexing."""
+    paths: list[str] = field(default_factory=lambda: ["docs", ".claude/memory"])
+    patterns: list[str] = field(default_factory=lambda: ["**/*.md"])
+    exclude: list[str] = field(default_factory=lambda: [
+        "**/node_modules/**",
+        "**/.git/**",
+        "**/.ragtime/**",
+    ])
+
+
+@dataclass
+class CodeConfig:
+    """Configuration for code indexing."""
+    paths: list[str] = field(default_factory=lambda: ["."])
+    languages: list[str] = field(default_factory=lambda: ["dart", "typescript", "python"])
+    exclude: list[str] = field(default_factory=lambda: [
+        "**/node_modules/**",
+        "**/.git/**",
+        "**/build/**",
+        "**/dist/**",
+        "**/.dart_tool/**",
+    ])
+
+
+@dataclass
+class RagtimeConfig:
+    """Main ragtime configuration."""
+    docs: DocsConfig = field(default_factory=DocsConfig)
+    code: CodeConfig = field(default_factory=CodeConfig)
+
+    @classmethod
+    def load(cls, project_path: Path) -> "RagtimeConfig":
+        """Load config from .ragtime/config.yaml or return defaults."""
+        config_path = project_path / ".ragtime" / "config.yaml"
+
+        if not config_path.exists():
+            return cls()
+
+        try:
+            with open(config_path) as f:
+                data = yaml.safe_load(f) or {}
+        except (IOError, yaml.YAMLError):
+            return cls()
+
+        docs_data = data.get("docs", {})
+        code_data = data.get("code", {})
+
+        return cls(
+            docs=DocsConfig(
+                paths=docs_data.get("paths", DocsConfig().paths),
+                patterns=docs_data.get("patterns", DocsConfig().patterns),
+                exclude=docs_data.get("exclude", DocsConfig().exclude),
+            ),
+            code=CodeConfig(
+                paths=code_data.get("paths", CodeConfig().paths),
+                languages=code_data.get("languages", CodeConfig().languages),
+                exclude=code_data.get("exclude", CodeConfig().exclude),
+            ),
+        )
+
+    def save(self, project_path: Path) -> None:
+        """Save config to .ragtime/config.yaml."""
+        config_dir = project_path / ".ragtime"
+        config_dir.mkdir(parents=True, exist_ok=True)
+        config_path = config_dir / "config.yaml"
+
+        data = {
+            "docs": {
+                "paths": self.docs.paths,
+                "patterns": self.docs.patterns,
+                "exclude": self.docs.exclude,
+            },
+            "code": {
+                "paths": self.code.paths,
+                "languages": self.code.languages,
+                "exclude": self.code.exclude,
+            },
+        }
+
+        with open(config_path, "w") as f:
+            yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+
+
+def init_config(project_path: Path) -> RagtimeConfig:
+    """Initialize a new config file with defaults."""
+    config = RagtimeConfig()
+    config.save(project_path)
+    return config

src/db.py

@@ -0,0 +1,167 @@
+"""
+ChromaDB wrapper for ragtime.
+
+Handles storage and retrieval of indexed documents and code.
+"""
+
+from pathlib import Path
+from typing import Any
+import chromadb
+from chromadb.config import Settings
+
+
+class RagtimeDB:
+    """Vector database for ragtime indexes."""
+
+    def __init__(self, path: Path):
+        """
+        Initialize the database.
+
+        Args:
+            path: Directory to store ChromaDB data
+        """
+        self.path = path
+        path.mkdir(parents=True, exist_ok=True)
+
+        self.client = chromadb.PersistentClient(
+            path=str(path),
+            settings=Settings(anonymized_telemetry=False),
+        )
+        self.collection = self.client.get_or_create_collection(
+            name="ragtime",
+            metadata={"hnsw:space": "cosine"},
+        )
+
+    def add(
+        self,
+        ids: list[str],
+        documents: list[str],
+        metadatas: list[dict[str, Any]],
+    ) -> None:
+        """
+        Add documents to the index.
+
+        Args:
+            ids: Unique identifiers for each document
+            documents: Text content to embed and index
+            metadatas: Metadata dicts for filtering
+        """
+        self.collection.add(
+            ids=ids,
+            documents=documents,
+            metadatas=metadatas,
+        )
+
+    def update(
+        self,
+        ids: list[str],
+        documents: list[str],
+        metadatas: list[dict[str, Any]],
+    ) -> None:
+        """Update existing documents."""
+        self.collection.update(
+            ids=ids,
+            documents=documents,
+            metadatas=metadatas,
+        )
+
+    def upsert(
+        self,
+        ids: list[str],
+        documents: list[str],
+        metadatas: list[dict[str, Any]],
+    ) -> None:
+        """Insert or update documents."""
+        self.collection.upsert(
+            ids=ids,
+            documents=documents,
+            metadatas=metadatas,
+        )
+
+    def search(
+        self,
+        query: str,
+        limit: int = 10,
+        type_filter: str | None = None,
+        namespace: str | None = None,
+        **filters,
+    ) -> list[dict]:
+        """
+        Semantic search over indexed content.
+
+        Args:
+            query: Natural language search query
+            limit: Max results to return
+            type_filter: "code" or "docs" (None = both)
+            namespace: Filter by namespace (for docs)
+            **filters: Additional metadata filters
+
+        Returns:
+            List of dicts with 'content', 'metadata', 'distance'
+        """
+        where = {}
+
+        if type_filter:
+            where["type"] = type_filter
+
+        if namespace:
+            where["namespace"] = namespace
+
+        for key, value in filters.items():
+            where[key] = value
+
+        results = self.collection.query(
+            query_texts=[query],
+            n_results=limit,
+            where=where if where else None,
+        )
+
+        # Flatten results into list of dicts
+        output = []
+        if results["documents"] and results["documents"][0]:
+            for i, doc in enumerate(results["documents"][0]):
+                output.append({
+                    "content": doc,
+                    "metadata": results["metadatas"][0][i] if results["metadatas"] else {},
+                    "distance": results["distances"][0][i] if results["distances"] else None,
+                })
+
+        return output
+
+    def delete(self, ids: list[str]) -> None:
+        """Delete documents by ID."""
+        self.collection.delete(ids=ids)
+
+    def clear(self, type_filter: str | None = None) -> None:
+        """
+        Clear the index.
+
+        Args:
+            type_filter: Only clear "code" or "docs" (None = everything)
+        """
+        if type_filter:
+            # Get all IDs matching the type
+            results = self.collection.get(where={"type": type_filter})
+            if results["ids"]:
+                self.collection.delete(ids=results["ids"])
+        else:
+            # Nuclear option - recreate collection
+            self.client.delete_collection("ragtime")
+            self.collection = self.client.get_or_create_collection(
+                name="ragtime",
+                metadata={"hnsw:space": "cosine"},
+            )
+
+    def stats(self) -> dict:
+        """Get index statistics."""
+        count = self.collection.count()
+
+        # Count by type
+        docs_count = len(self.collection.get(where={"type": "docs"})["ids"])
+        code_count = len(self.collection.get(where={"type": "code"})["ids"])
+
+        return {
+            "total": count,
+            "docs": docs_count,
+            "code": code_count,
+        }