claudetools/.claude/CONTEXT_RECALL_QUICK_START.md

# Context Recall - Quick Start

One-page reference for the Claude Code Context Recall System.

## Setup (First Time)

```bash
# 1. Start API
uvicorn api.main:app --reload

# 2. Setup (in new terminal)
bash scripts/setup-context-recall.sh

# 3. Test
bash scripts/test-context-recall.sh
```

## Files

```
.claude/
├── hooks/
│   ├── user-prompt-submit      # Recalls context before messages
│   ├── task-complete           # Saves context after tasks
│   └── README.md               # Hook documentation
├── context-recall-config.env   # Configuration (gitignored)
└── CONTEXT_RECALL_QUICK_START.md

scripts/
├── setup-context-recall.sh     # One-command setup
└── test-context-recall.sh      # System testing
```

## Configuration

Edit `.claude/context-recall-config.env`:

```bash
CLAUDE_API_URL=http://localhost:8000    # API URL
CLAUDE_PROJECT_ID=                      # Auto-detected
JWT_TOKEN=                              # From setup script
CONTEXT_RECALL_ENABLED=true             # Enable/disable
MIN_RELEVANCE_SCORE=5.0                 # Filter threshold (0-10)
MAX_CONTEXTS=10                         # Max contexts per query
```

## How It Works

```
User Message → [Recall Context] → Claude (with context) → Response
                                         ↓
                                   [Save Context]
```

### user-prompt-submit Hook
- Runs **before** each user message
- Calls `GET /api/conversation-contexts/recall`
- Injects relevant context from previous sessions
- Falls back gracefully if API unavailable

### task-complete Hook
- Runs **after** task completion
- Calls `POST /api/conversation-contexts`
- Saves conversation summary
- Updates project state

## Common Commands

```bash
# Re-run setup (get new JWT token)
bash scripts/setup-context-recall.sh

# Test system
bash scripts/test-context-recall.sh

# Test hooks manually
source .claude/context-recall-config.env
bash .claude/hooks/user-prompt-submit

# Enable debug mode
echo "DEBUG_CONTEXT_RECALL=true" >> .claude/context-recall-config.env

# Disable context recall
echo "CONTEXT_RECALL_ENABLED=false" >> .claude/context-recall-config.env

# Check API health
curl http://localhost:8000/health

# View your project
source .claude/context-recall-config.env
curl -H "Authorization: Bearer $JWT_TOKEN" \
  http://localhost:8000/api/projects/$CLAUDE_PROJECT_ID

# Query contexts manually
curl "http://localhost:8000/api/conversation-contexts/recall?project_id=$CLAUDE_PROJECT_ID&limit=5" \
  -H "Authorization: Bearer $JWT_TOKEN"
```

## Troubleshooting

| Problem | Solution |
|---------|----------|
| Context not appearing | Check API is running: `curl http://localhost:8000/health` |
| Hooks not executing | Make executable: `chmod +x .claude/hooks/*` |
| JWT token expired | Re-run setup: `bash scripts/setup-context-recall.sh` |
| Context not saving | Check project ID: `echo $CLAUDE_PROJECT_ID` |
| Debug hook output | Enable debug: `DEBUG_CONTEXT_RECALL=true` in config |

## API Endpoints

- `GET /api/conversation-contexts/recall` - Get relevant contexts
- `POST /api/conversation-contexts` - Save new context
- `POST /api/project-states` - Update project state
- `POST /api/auth/login` - Get JWT token
- `GET /api/projects` - List projects

## Configuration Parameters

### MIN_RELEVANCE_SCORE (0.0 - 10.0)
- **5.0** - Balanced (recommended)
- **7.0** - Only high-quality contexts
- **3.0** - Include more historical context

### MAX_CONTEXTS (1 - 50)
- **10** - Balanced (recommended)
- **5** - Focused, minimal context
- **20** - Comprehensive history

## Security

- JWT tokens stored in `.claude/context-recall-config.env`
- File is gitignored (never commit!)
- Tokens expire after 24 hours
- Re-run setup to refresh

## Example Output

When context is available:

```markdown
## 📚 Previous Context

The following context has been automatically recalled from previous sessions:

### 1. Database Schema Updates (Score: 8.5/10)
*Type: technical_decision*

Updated the Project model to include new fields for MSP integration...

---

### 2. API Endpoint Changes (Score: 7.2/10)
*Type: session_summary*

Implemented new REST endpoints for context recall...

---
```

## Performance

- Hook overhead: <500ms per message
- API query time: <100ms
- Timeouts: 3-5 seconds
- Silent failures (don't break Claude)

## Full Documentation

- **Setup Guide:** `CONTEXT_RECALL_SETUP.md`
- **Hook Details:** `.claude/hooks/README.md`
- **API Spec:** `.claude/API_SPEC.md`

---

**Quick Start:** `bash scripts/setup-context-recall.sh` and you're done!