ragtime-cli 0.1.0__py3-none-any.whl

src/commands/audit.md

@@ -0,0 +1,151 @@
+---
+description: Audit local memories for duplicates, conflicts, and stale data
+allowed-tools: Bash, mcp__ragtime__search, mcp__ragtime__list_memories, mcp__ragtime__forget, mcp__ragtime__update_status, AskUserQuestion
+---
+
+# Memory Audit
+
+Periodic cleanup of local memories. This is a **human-in-the-loop** review - no automatic deletions.
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     CUSTOMIZABLE: Add project-specific audit rules, adjust the report format,
+     add custom namespace checks, etc.
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+## Namespaces to Audit
+
+- `app` - Codebase knowledge (architecture, decisions)
+- `team` - Team conventions (standards, processes)
+- `user-*` - Developer preferences
+- `branch-*` - Branch-specific context and decisions
+
+## Step 1: Gather All Memories
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     RAGTIME CORE - DO NOT MODIFY
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+```
+mcp__ragtime__list_memories:
+  limit: 100
+```
+
+For each namespace:
+```
+mcp__ragtime__list_memories:
+  namespace: "{namespace}"
+  limit: 50
+```
+
+<!-- ═══════════════════════════════════════════════════════════════════════════ -->
+
+## Step 2: Identify Issues
+
+Group memories by topic and identify:
+
+| Issue | Description |
+|-------|-------------|
+| **DUPLICATES** | Memories saying essentially the same thing |
+| **CONFLICTS** | Memories that contradict each other |
+| **STALE** | References to code/features that no longer exist |
+| **ORPHANED** | Branch memories for deleted/merged branches |
+| **LOW_VALUE** | Vague memories that aren't useful |
+
+## Step 3: Check for Stale Branches
+
+```bash
+# List branch memory folders
+ls -la .claude/memory/branches/
+
+# For each, check if branch still exists
+for dir in .claude/memory/branches/*/; do
+  branch_slug=$(basename "$dir")
+  # Check if branch exists on remote
+  if ! git branch -a | grep -q "$branch_slug"; then
+    echo "⚠️  Potentially stale: $branch_slug"
+  fi
+done
+```
+
+Also run:
+```bash
+ragtime prune --dry-run
+```
+
+## Step 4: Present Report
+
+```
+## Memory Audit Report
+
+### App Namespace ({count} memories)
+- Potential duplicates: {n}
+- Potential conflicts: {n}
+- Possibly stale: {n}
+
+### Team Namespace ({count} memories)
+- Potential duplicates: {n}
+
+### Branch Namespaces
+- Active branches: {n}
+- Stale (unmerged) folders: {n}
+- Ready to prune: {n}
+
+───────────────────────────────────────────
+
+### Issues Found:
+
+**1. Possible Duplicate:**
+- "Auth uses JWT tokens" (app, abc123)
+- "JWT auth with 15-min expiry" (app, def456)
+→ Action: Merge into one?
+
+**2. Possible Conflict:**
+- "Use tabs for indentation" (team, ghi789)
+- "Use 2-space indentation" (team, jkl012)
+→ Action: Which is correct?
+
+**3. Stale Branch:**
+- branches/old-feature/ (branch deleted)
+→ Action: Prune with `ragtime prune`?
+```
+
+## Step 5: Get User Approval
+
+For each issue found, ask:
+
+- "Should I merge these duplicates?"
+- "Which of these conflicting memories is correct?"
+- "Should I mark this as abandoned?"
+- "Run `ragtime prune` to clean stale branches?"
+
+Only make changes the user explicitly approves.
+
+## Step 6: Execute Approved Actions
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     RAGTIME CORE - DO NOT MODIFY
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+**Delete a memory:**
+```
+mcp__ragtime__forget:
+  memory_id: "{id}"
+```
+
+**Mark as abandoned:**
+```
+mcp__ragtime__update_status:
+  memory_id: "{id}"
+  status: "abandoned"
+```
+
+**Prune stale branches:**
+```bash
+ragtime prune
+```
+
+<!-- ═══════════════════════════════════════════════════════════════════════════ -->
+
+## Suggested Cadence
+
+Run monthly or when memories feel cluttered.

src/commands/handoff.md

@@ -0,0 +1,176 @@
+---
+description: Save current context to branch memory for session continuity
+allowed-tools: Bash, Read, Write, mcp__ragtime__remember
+---
+
+# Save Context for Handoff
+
+Capture the current session's context into the branch's `context.md` so the next session (or another developer) can pick up seamlessly.
+
+The context lives permanently in `.claude/memory/branches/{branch}/context.md` - no cleanup needed.
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     CUSTOMIZABLE: Adjust the context template, add project-specific sections,
+     modify the commit message format, etc.
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+## Step 1: Gather Current State
+
+```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:]')
+TIMESTAMP=$(date +%Y-%m-%d)
+
+echo "Branch: $BRANCH"
+echo "Issue: #$ISSUE_NUM"
+echo "Developer: $DEVNAME"
+
+# Get recent commits on this branch
+echo ""
+echo "=== Recent Commits ==="
+git log main..HEAD --oneline 2>/dev/null || git log -10 --oneline
+
+# Get current changes
+echo ""
+echo "=== Uncommitted Changes ==="
+git status --short
+```
+
+## Step 2: Summarize Session Context
+
+Based on the conversation, create a summary that includes:
+
+1. **What This Branch Does** - High-level purpose
+2. **Current State** - What's been done, recent commits
+3. **What's Left To Do** - Remaining tasks, in priority order
+4. **Testing Status** - What's been tested, what hasn't
+5. **Known Issues / Lessons Learned** - Gotchas for the next session
+6. **Architecture Decisions** - Why things were done a certain way
+7. **Next Steps** - Specific instructions for resuming
+
+## Step 3: Write to Branch Context
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     RAGTIME CORE - DO NOT MODIFY
+     The file path and frontmatter format must match ragtime's expectations.
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+Write to `.claude/memory/branches/{branch-slug}/context.md`:
+
+```markdown
+---
+id: context
+namespace: branch-{branch}
+type: context
+status: active
+added: '{date}'
+author: {devname}
+issue: '#{issue_num}'
+---
+
+## Branch: {branch}
+
+### What This Branch Does
+
+{summary}
+
+---
+
+## CURRENT STATE (as of {date})
+
+{current state details}
+
+---
+
+## WHAT'S LEFT TO DO
+
+{prioritized task list}
+
+---
+
+## TESTING STATUS
+
+### Tested and Working:
+{list}
+
+### Not Yet Tested:
+{list}
+
+---
+
+## KNOWN ISSUES / LESSONS LEARNED
+
+{numbered list}
+
+---
+
+## ARCHITECTURE DECISIONS
+
+{bullet points}
+
+---
+
+## NEXT STEPS FOR NEW SESSION
+
+{specific instructions}
+```
+
+<!-- ═══════════════════════════════════════════════════════════════════════════ -->
+
+<!-- CUSTOMIZABLE: Add project-specific sections to the context template -->
+
+## Step 4: Index the Context
+
+After writing the file, ensure it's indexed:
+
+```
+mcp__ragtime__remember:
+  content: "{summary of context for search}"
+  namespace: "branch-{branch}"
+  type: "context"
+  issue: "#{issue_num}"
+  source: "handoff"
+```
+
+## Step 5: Commit and Push
+
+```bash
+BRANCH=$(git branch --show-current)
+BRANCH_SLUG=$(echo "$BRANCH" | tr '/' '-')
+ISSUE_NUM=$(echo "$BRANCH" | grep -oE '[0-9]+' | head -1)
+
+# Block pushes to main/master
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  echo "❌ ERROR: Cannot push directly to $BRANCH"
+  exit 1
+fi
+
+git add ".claude/memory/branches/$BRANCH_SLUG/context.md"
+git commit -m "docs(context): update branch context for session continuity
+
+Relates to #$ISSUE_NUM
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+
+git push -u origin "$BRANCH"
+```
+
+## Step 6: Confirm Handoff Complete
+
+```
+✅ Handoff Complete
+
+- Context saved to: .claude/memory/branches/{branch}/context.md
+- Committed and pushed to remote
+- Ready for next session or another developer
+
+To resume: Start a new session and say "continue on this branch"
+```
+
+## Notes
+
+- The context.md file lives permanently with the branch - no cleanup needed
+- Each `/handoff` overwrites the previous context.md (it's always current state)
+- On `/start`, Claude reads the branch's context.md to resume
+- When syncing from teammate branches, their context.md comes along too

src/commands/pr-graduate.md

@@ -0,0 +1,187 @@
+---
+description: Graduate branch knowledge to app after PR merge
+allowed-tools: Bash, mcp__ragtime__search, mcp__ragtime__graduate, mcp__ragtime__update_status, mcp__ragtime__remember, AskUserQuestion
+---
+
+# PR Graduate: Curate Branch Knowledge
+
+After a PR is merged, review branch memories and decide what becomes permanent app knowledge.
+
+**This is a human-in-the-loop process** - you curate which memories graduate.
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     CUSTOMIZABLE: Adjust the curation workflow, add project-specific
+     graduation criteria, modify the summary format, etc.
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+## Process Overview
+
+```
+For EACH branch memory:
+
+✅ Graduate → Copy to app namespace with high confidence
+📚 Keep     → Leave in branch (reference/history)
+❌ Abandon  → Mark as abandoned (noise, superseded)
+
+Branch memories are preserved - nothing is deleted.
+```
+
+## Step 1: Get the Branch
+
+```bash
+BRANCH=$(git branch --show-current)
+BRANCH_SLUG=$(echo "$BRANCH" | tr '/' '-')
+ISSUE_NUM=$(echo "$BRANCH" | grep -oE '[0-9]+' | head -1)
+
+echo "Branch: $BRANCH"
+echo "Issue: #$ISSUE_NUM"
+
+# Check if PR was merged
+gh pr list --head "$BRANCH" --state merged --json number,title
+```
+
+## Step 2: Gather Branch Memories
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     RAGTIME CORE - DO NOT MODIFY
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+```
+mcp__ragtime__search:
+  query: "decisions patterns architecture"
+  namespace: "branch-{branch}"
+  limit: 50
+```
+
+<!-- ═══════════════════════════════════════════════════════════════════════════ -->
+
+## Step 3: Present Memories for Curation
+
+Display each memory with options:
+
+```
+───────────────────────────────────────────
+📋 BRANCH MEMORY CURATION
+───────────────────────────────────────────
+
+Branch: {branch}
+Total memories found: {count}
+
+For each memory, choose:
+  ✅ Graduate - Promote to app knowledge (high confidence)
+  📚 Keep - Leave in branch for reference
+  ❌ Abandon - Mark as noise/superseded
+
+───────────────────────────────────────────
+
+**Memory 1 of {count}:**
+
+"{memory content preview - first 200 chars}..."
+
+Type: {type} | Added: {date}
+
+What should happen to this memory?
+1. ✅ Graduate to app
+2. 📚 Keep in branch
+3. ❌ Mark as abandoned
+4. 👀 Show full content
+```
+
+## Step 4: Process Each Memory
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     RAGTIME CORE - DO NOT MODIFY
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+### If ✅ Graduate:
+
+```
+mcp__ragtime__graduate:
+  memory_id: "{id}"
+  confidence: "high"
+```
+
+This creates a copy in `app/` namespace and marks the original as graduated.
+
+### If 📚 Keep:
+
+No action needed - memory stays in branch namespace for reference.
+
+### If ❌ Abandon:
+
+```
+mcp__ragtime__update_status:
+  memory_id: "{id}"
+  status: "abandoned"
+```
+
+<!-- ═══════════════════════════════════════════════════════════════════════════ -->
+
+## Step 5: Handle Context Document
+
+The branch's `context.md` is a full document, not individual memories:
+
+```
+The context.md contains the full development context.
+
+Options:
+1. **Extract key insights** - I'll identify valuable patterns to graduate
+2. **Keep as reference** - Leave it in branch history
+3. **Skip** - Context was just for session continuity
+```
+
+If extracting: Identify the most valuable insights and present for approval before graduating.
+
+## Step 6: Summary
+
+```
+───────────────────────────────────────────
+✅ PR GRADUATION COMPLETE
+───────────────────────────────────────────
+
+Branch: {branch}
+
+Memories processed: {total}
+  ✅ Graduated to app: {count}
+  📚 Kept in branch: {count}
+  ❌ Marked abandoned: {count}
+
+Graduated knowledge now searchable via:
+  /recall {topic} --namespace app
+```
+
+## Quick Mode
+
+For simpler PRs, offer quick mode:
+
+```
+Found {count} branch memories.
+
+Options:
+1. **Review each** - Curate one by one (recommended)
+2. **Quick mode** - I'll propose which to graduate
+3. **Graduate all** - Promote everything
+4. **Keep all** - Leave everything in branch
+```
+
+Quick mode generates a proposal:
+
+```
+## Quick Mode Proposal
+
+**Recommend Graduate:**
+- "Auth uses JWT with 15-min expiry" ← architecture insight
+- "Redis chosen for session storage" ← key decision
+
+**Recommend Keep:**
+- "Debugging: token refresh issue" ← development context
+
+Approve? (yes/edit/review-each)
+```
+
+## Notes
+
+- Branch memories stay forever (history) - only status changes
+- Graduated memories get `source: "pr-graduate"` and high confidence
+- Abandoned memories are excluded from default searches
+- Use `/recall --namespace branch-{name}` to see branch history

src/commands/recall.md

@@ -0,0 +1,175 @@
+---
+description: Search the local memory system for knowledge
+allowed-arguments: search query and optional filters (e.g., /recall auth patterns, /recall --namespace app)
+allowed-tools: mcp__ragtime__search, mcp__ragtime__list_memories, AskUserQuestion
+---
+
+# Recall
+
+Search the local memory system for stored knowledge.
+
+**Usage:**
+- `/recall auth patterns` - Search for auth-related patterns
+- `/recall #301 decisions` - Decisions related to issue #301
+- `/recall --namespace team` - All team conventions
+- `/recall` - Interactive search mode
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     CUSTOMIZABLE: Modify query parsing, add project-specific filters,
+     adjust result formatting, etc.
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+## Query Syntax
+
+```
+/recall [modifiers] <search terms> [filters]
+```
+
+**Modifiers:**
+- `all:` - Include all confidence levels (default: high + medium only)
+- `pre-merge:` - Include unmerged branch memories from teammates
+
+**Filters:**
+- `#301` or `--issue 301` - Filter by issue number
+- `@auth` or `--component auth` - Filter by component
+- `--type decision` - Filter by memory type
+- `--namespace app` - Filter by namespace
+- `--status active` - Filter by status
+
+<!-- CUSTOMIZABLE: Add your own filter shortcuts -->
+
+## Step 1: Parse the Query
+
+**If `$ARGUMENTS` provided:**
+- Parse modifiers, search terms, and filters
+
+**If no arguments:**
+- Ask: "What are you looking for?"
+- Optionally ask for filters
+
+## Step 2: Build the Search
+
+Construct filters based on parsed query:
+
+- Default: exclude `status: "abandoned"` and `confidence: "low"`
+- If `all:` modifier: include everything
+- If `pre-merge:` modifier: include `status: "pre-merge"`
+
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     RAGTIME CORE - DO NOT MODIFY
+     These commands must match ragtime's expected format.
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
+Execute the search:
+
+```
+mcp__ragtime__search:
+  query: "{search terms}"
+  namespace: "{namespace if specified}"
+  type: "{type if specified}"
+  component: "{component if specified}"
+  limit: 20
+```
+
+For listing without semantic search:
+
+```
+mcp__ragtime__list_memories:
+  namespace: "{namespace}"
+  type: "{type}"
+  status: "{status}"
+  component: "{component}"
+  limit: 20
+```
+
+<!-- ═══════════════════════════════════════════════════════════════════════════ -->
+
+## Step 3: Present Results
+
+Format results clearly:
+
+```
+## 🧠 Recall: "{search terms}"
+
+Found {count} memories:
+
+### High Confidence
+───────────────────────────────────────────
+
+**Auth uses JWT with 15-min expiry**
+- Type: architecture | Component: auth
+- Added: 2026-01-15 | Source: pr-graduate
+
+**Sessions stored in Redis, not cookies**
+- Type: decision | Component: auth
+- Added: 2026-01-10 | Source: meeting
+
+### Medium Confidence
+───────────────────────────────────────────
+
+**Consider rate limiting on auth endpoints**
+- Type: pattern | Component: auth
+- Added: 2026-01-20 | Source: remember
+
+───────────────────────────────────────────
+
+Showing {count} of {total} results.
+Refine with: /recall auth --type decision
+Include low confidence: /recall all: auth
+```
+
+### Pre-Merge Results
+
+If pre-merge memories are found, show them separately with a warning:
+
+```
+### ⚠️ Pre-Merge (from teammate branches)
+───────────────────────────────────────────
+
+**New auth middleware pattern** (pre-merge)
+- From: origin/jm/feature-auth
+- Type: architecture | Component: auth
+- ⚠️ Not yet merged - may change
+
+```
+
+## Step 4: Offer Actions
+
+```
+What would you like to do?
+
+1. **Use this context** - I'll incorporate these into our work
+2. **Refine search** - Try different filters
+3. **View details** - See full content of a specific memory
+4. **Done** - Just wanted to see what we know
+```
+
+## Example Queries
+
+| Query | What it finds |
+|-------|---------------|
+| `/recall auth` | All auth-related memories (high/medium confidence) |
+| `/recall #301 decisions` | Decisions made during issue #301 |
+| `/recall --namespace team` | All team conventions |
+| `/recall --component shifts --type architecture` | Shifts architecture |
+| `/recall pre-merge: auth` | Include teammate WIP auth knowledge |
+| `/recall all: validation` | Include low-confidence validation memories |
+
+## No Results Handling
+
+```
+No memories found for "{query}" with current filters.
+
+Suggestions:
+- Try broader terms: /recall {simpler query}
+- Include all confidence: /recall all: {query}
+- Check different namespace: /recall --namespace team {query}
+- Include pre-merge: /recall pre-merge: {query}
+```
+
+## Notes
+
+- Results are sorted by relevance (semantic similarity)
+- Default excludes low confidence and abandoned memories
+- Use `all:` modifier to see everything
+- Pre-merge memories are from `(unmerged)` folders synced from teammate branches