# 🚀 ClaudeTools - Start Here

**Welcome!** This is your MSP Work Tracking System with AI Context Recall.

---

## ⚡ Quick Start (First Time)

### 1. Start the API

```bash
# Open terminal in D:\ClaudeTools
api\venv\Scripts\activate
python -m api.main
```

✅ **API running at:** http://localhost:8000
📚 **Docs available at:** http://localhost:8000/api/docs

---

### 2. Enable Context Recall (One-Time Setup)

**Open a NEW terminal** (keep API running):

```bash
cd D:\ClaudeTools
bash scripts/setup-context-recall.sh
```

This will:
- ✅ Generate JWT token
- ✅ Detect/create project
- ✅ Configure environment
- ✅ Test the system
- ✅ Enable automatic context injection

**Takes ~2 minutes** - then you're done forever!

---

### 3. Verify Everything Works

```bash
bash scripts/test-context-recall.sh
```

Should show:
```
✅ API connectivity
✅ Authentication
✅ Context recall working
✅ Context saving working
✅ Hooks executing
```

---

## 🎯 What You Get

### Cross-Machine Context Continuity

```
Machine A: "Build user authentication"
  → Context saves automatically

Machine B (tomorrow): "Continue with that project"
  → Context recalls automatically
  → Claude knows: "You were implementing JWT auth..."
```

**Zero effort required** - hooks handle everything!

---

## 📖 How To Use

### Normal Claude Code Usage

Just use Claude Code as normal - context recall happens automatically:

1. **Before each message** → Hook recalls relevant context from database
2. **After each task** → Hook saves new context to database
3. **Cross-machine** → Same context on any machine

### Manual Context Operations

**Recall context for current project:**
```bash
curl "http://localhost:8000/api/conversation-contexts/recall?project_id=$PROJECT_ID&limit=10" \
  -H "Authorization: Bearer $JWT_TOKEN"
```

**Save important context:**
```python
POST /api/conversation-contexts
{
  "project_id": "uuid",
  "title": "Implemented feature X",
  "dense_summary": "Added JWT auth with Argon2 hashing...",
  "tags": ["auth", "security", "jwt"]
}
```

**Check project state:**
```python
GET /api/project-states/by-project/{project_id}
```

---

## 📂 Key Files You Should Know

| File | Purpose |
|------|---------|
| `.claude/claude.md` | Auto-loaded context (read on Claude startup) |
| `SESSION_STATE.md` | Complete project history |
| `.claude/context-recall-config.env` | Your JWT token & settings |
| `.claude/hooks/user-prompt-submit` | Auto-recalls context |
| `.claude/hooks/task-complete` | Auto-saves context |

---

## 🔧 Common Tasks

### View All Projects
```bash
curl http://localhost:8000/api/projects \
  -H "Authorization: Bearer $JWT_TOKEN"
```

### Create New Project
```python
POST /api/projects
{
  "name": "New Website",
  "client_id": "client-uuid",
  "status": "planning"
}
```

### Log Decision
```python
POST /api/decision-logs
{
  "project_id": "uuid",
  "decision_type": "technical",
  "decision_text": "Using PostgreSQL for main database",
  "rationale": "ACID compliance, JSON support, mature",
  "impact": "high"
}
```

### Track Work Session
```python
POST /api/sessions
{
  "project_id": "uuid",
  "machine_id": "uuid",
  "started_at": "2026-01-16T10:00:00Z"
}
```

---

## 🎛️ Configuration

**Database:**
- Host: `172.16.3.20:3306`
- Database: `claudetools`
- User: `claudetools`
- Password: In `C:\Users\MikeSwanson\claude-projects\shared-data\credentials.md`

**API:**
- URL: `http://localhost:8000`
- Docs: `http://localhost:8000/api/docs`
- Auth: JWT Bearer tokens

**Context Recall:**
- Config: `.claude/context-recall-config.env`
- Min Score: `5.0` (adjustable)
- Max Contexts: `10` (adjustable)

---

## 🐛 Troubleshooting

### API Won't Start
```bash
# Check if already running
netstat -ano | findstr :8000

# Test database connection
python test_db_connection.py
```

### Context Recall Not Working
```bash
# Run diagnostics
bash scripts/test-context-recall.sh

# Check hook permissions
ls -l .claude/hooks/
# Should show: -rwxr-xr-x (executable)

# View configuration
cat .claude/context-recall-config.env
```

### Need to Reset
```bash
# Re-run setup
bash scripts/setup-context-recall.sh
```

---

## 📊 System Status

**Current State:**
- ✅ 130 API endpoints operational
- ✅ 43 database tables migrated
- ✅ 99.1% test pass rate
- ✅ Context recall system ready
- ✅ Encryption & auth working
- ✅ Claude Code hooks installed

**What's Built:**
- Core APIs (Machines, Clients, Projects, Sessions, Tags)
- MSP Work Tracking (Work Items, Tasks, Billable Time)
- Infrastructure Management (Sites, Infrastructure, Services, Networks, Firewalls, M365)
- Credentials Management (Encrypted storage, Audit logs, Incidents)
- **Context Recall (Conversations, Snippets, Project States, Decisions)**

---

## 📚 Documentation

**Quick References:**
- `.claude/CONTEXT_RECALL_QUICK_START.md` - One-page context recall guide
- `.claude/claude.md` - Auto-loaded project context
- `SESSION_STATE.md` - Complete implementation history

**Full Guides:**
- `CONTEXT_RECALL_SETUP.md` - Detailed setup instructions
- `.claude/CONTEXT_RECALL_ARCHITECTURE.md` - System architecture
- `.claude/hooks/README.md` - Hook documentation
- `.claude/hooks/EXAMPLES.md` - Real-world examples

**Test Reports:**
- `TEST_PHASE5_RESULTS.md` - Phase 5 API tests
- `TEST_CONTEXT_RECALL_RESULTS.md` - Context recall tests

---

## 🎯 Next Steps

1. ✅ **You are here** - Reading this guide
2. ⏭️ **Start API** - `python -m api.main`
3. ⏭️ **Run setup** - `bash scripts/setup-context-recall.sh`
4. ⏭️ **Test system** - `bash scripts/test-context-recall.sh`
5. ✨ **Start using Claude Code** - Context recall is automatic!

---

## 💡 Pro Tips

**Token Efficiency:**
- Context compression achieves 90-95% reduction
- Only relevant context injected (filtered by tags, relevance)
- Automatic deduplication

**Cross-Machine Workflow:**
1. Work on any machine
2. Context saves to database automatically
3. Switch machines anytime
4. Context recalls automatically
5. Zero manual syncing needed

**Building Institutional Memory:**
- Every decision auto-tagged
- Patterns emerge over time
- Knowledge grows with usage
- Most-used snippets ranked higher

---

**Need Help?** Check `.claude/claude.md` for comprehensive context or `SESSION_STATE.md` for project history.

**Ready to go?** Run: `bash scripts/setup-context-recall.sh`