Operations

Operations & Health

SmartAssist CLI

The smartassist command is available globally after pip install -e. It provides 9 subcommands:

smartassist init          # Create .claude/smartassist/ in current project
smartassist serve         # Start MCP server (stdio transport)
smartassist health        # Run 6-check system health dashboard
smartassist migrate       # Copy data from old rag-setup location
smartassist vectorize     # Re-vectorize all lessons
smartassist maintenance   # Staleness check + LanceDB compaction
smartassist analyze       # Usage analytics (hit rate, latency, trends)
smartassist dashboard     # Generate HTML dashboard
smartassist seed          # Seed lessons from CLAUDE.md

Health Check

Run smartassist health from any project with SmartAssist initialized:

Check	What it verifies	Status
Vector Database	LanceDB has documents, categories are specific, text has proper format	PASS
Feedback Data	feedback_log.jsonl exists, events counted, distribution analyzed	PASS
Reliability Scores	Thompson Sampling scores exist for all categories	PASS
Usage Evidence	usage_log.jsonl exists, tool calls logged, hit rate, latency	PASS
Vectorization Sync	DB in sync with feedback log	PASS
MCP Registration	smartassist server registered in ~/.claude/mcp.json	PASS

Auto-Vectorization

smartassist.hooks.vectorize_learnings automatically vectorizes new lessons whenever feedback is added:

1. Read vectorization_log.json (last processed count)
2. Get new events since last run
3. Filter: must be >30 chars, not a skip pattern
4. Sanitize to imperative lesson form
5. Embed with BAAI/bge-m3 (1024-dim)
6. Add to LanceDB with category metadata
7. Update vectorization_log.json

What Gets Vectorized

• Corrections ≥ 30 characters
• Not matching 20+ skip/filter patterns
• Sanitized to imperative lesson form
• Proper category in metadata

What Gets Filtered

• Short responses: "ok", "fix", "yes"
• Status updates: "Done - fixed in PR #123"
• Acknowledgements: "LGTM", "good catch", "thanks"
• Conversational noise, why-questions, narratives, defensive explanations

Quick Start for New Projects

cd ~/your-new-project
smartassist init

# Optional: migrate data from old rag-setup
smartassist migrate ~/old-project/rag-setup

The init command:

• Creates .claude/smartassist/{data,lancedb}/
• Creates empty data files
• Updates .gitignore to exclude .claude/smartassist/