claudetools/.claude/hooks/README.md

# Claude Code Context Recall Hooks

Automatically inject and save relevant context from the ClaudeTools database into Claude Code conversations.

## Overview

This system provides seamless context continuity across Claude Code sessions by:

1. **Recalling context** - Automatically inject relevant context from previous sessions before each message
2. **Saving context** - Automatically save conversation summaries after task completion
3. **Project awareness** - Track project state and maintain context across sessions

## Hooks

### `user-prompt-submit`

**Runs:** Before each user message is processed

**Purpose:** Injects relevant context from the database into the conversation

**What it does:**
- Detects the current project ID (from git config or remote URL)
- Calls `/api/conversation-contexts/recall` to fetch relevant contexts
- Injects context as a formatted markdown section
- Falls back gracefully if API is unavailable

**Example output:**
```markdown
## [DOCS] 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...

---
```

### `task-complete`

**Runs:** After a task is completed

**Purpose:** Saves conversation context to the database for future recall

**What it does:**
- Gathers task information (git branch, commit, modified files)
- Creates a compressed summary of the task
- POST to `/api/conversation-contexts` to save context
- Updates project state via `/api/project-states`

**Saved information:**
- Task summary
- Git branch and commit hash
- Modified files
- Timestamp
- Metadata for future retrieval

## Configuration

### Quick Setup

Run the automated setup script:

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

This will:
1. Create a JWT token
2. Detect or create your project
3. Configure environment variables
4. Make hooks executable
5. Test the system

### Manual Setup

1. **Get JWT Token**

```bash
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}'
```

2. **Get/Create Project**

```bash
curl -X POST http://localhost:8000/api/projects \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ClaudeTools",
    "description": "Your project description"
  }'
```

3. **Configure `.claude/context-recall-config.env`**

```bash
CLAUDE_API_URL=http://localhost:8000
CLAUDE_PROJECT_ID=your-project-uuid-here
JWT_TOKEN=your-jwt-token-here
CONTEXT_RECALL_ENABLED=true
MIN_RELEVANCE_SCORE=5.0
MAX_CONTEXTS=10
```

4. **Make hooks executable**

```bash
chmod +x .claude/hooks/user-prompt-submit
chmod +x .claude/hooks/task-complete
```

### Configuration Options

| Variable | Default | Description |
|----------|---------|-------------|
| `CLAUDE_API_URL` | `http://localhost:8000` | API base URL |
| `CLAUDE_PROJECT_ID` | Auto-detect | Project UUID |
| `JWT_TOKEN` | Required | Authentication token |
| `CONTEXT_RECALL_ENABLED` | `true` | Enable/disable system |
| `MIN_RELEVANCE_SCORE` | `5.0` | Minimum score (0-10) |
| `MAX_CONTEXTS` | `10` | Max contexts per query |
| `AUTO_SAVE_CONTEXT` | `true` | Save after completion |
| `DEBUG_CONTEXT_RECALL` | `false` | Enable debug logs |

## Project ID Detection

The system automatically detects your project ID using:

1. **Git config** - `git config --local claude.projectid`
2. **Git remote URL hash** - Consistent ID from remote URL
3. **Environment variable** - `CLAUDE_PROJECT_ID`

To manually set project ID in git config:

```bash
git config --local claude.projectid "your-project-uuid"
```

## Testing

Run the test script:

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

This will:
- Test API connectivity
- Test context recall endpoint
- Test context saving
- Verify hooks are working

## Usage

Once configured, the system works automatically:

1. **Start Claude Code** - Context is automatically recalled
2. **Work normally** - All your conversations happen as usual
3. **Complete tasks** - Context is automatically saved
4. **Next session** - Previous context is automatically available

## Troubleshooting

### Context not appearing?

1. Enable debug mode:
   ```bash
   echo "DEBUG_CONTEXT_RECALL=true" >> .claude/context-recall-config.env
   ```

2. Check API is running:
   ```bash
   curl http://localhost:8000/health
   ```

3. Verify JWT token:
   ```bash
   curl -H "Authorization: Bearer $JWT_TOKEN" http://localhost:8000/api/projects
   ```

4. Check hooks are executable:
   ```bash
   ls -la .claude/hooks/
   ```

### Context not saving?

1. Check task-complete hook output:
   ```bash
   bash -x .claude/hooks/task-complete
   ```

2. Verify project ID:
   ```bash
   source .claude/context-recall-config.env
   echo $CLAUDE_PROJECT_ID
   ```

3. Check API logs for errors

### Hooks not running?

1. Verify hook permissions:
   ```bash
   chmod +x .claude/hooks/*
   ```

2. Test hook manually:
   ```bash
   bash .claude/hooks/user-prompt-submit
   ```

3. Check Claude Code hook documentation:
   https://docs.claude.com/claude-code/hooks

### API connection errors?

1. Verify API is running:
   ```bash
   curl http://localhost:8000/health
   ```

2. Check firewall/port blocking

3. Verify API URL in config

## How It Works

### Context Recall Flow

```
User sends message
    ↓
[user-prompt-submit hook runs]
    ↓
Detect project ID
    ↓
Call /api/conversation-contexts/recall
    ↓
Format and inject context
    ↓
Claude processes message with context
```

### Context Save Flow

```
Task completes
    ↓
[task-complete hook runs]
    ↓
Gather task information
    ↓
Create context summary
    ↓
POST to /api/conversation-contexts
    ↓
Update /api/project-states
    ↓
Context saved for future recall
```

## API Endpoints Used

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

## Security Notes

- JWT tokens are stored in `.claude/context-recall-config.env`
- This file should be in `.gitignore` (DO NOT commit tokens!)
- Tokens expire after 24 hours (configurable)
- Hooks fail gracefully if authentication fails

## Advanced Usage

### Custom Context Types

Modify `task-complete` hook to create custom context types:

```bash
CONTEXT_TYPE="bug_fix"  # or "feature", "refactor", etc.
RELEVANCE_SCORE=9.0     # Higher for important contexts
```

### Filtering Contexts

Adjust recall parameters in config:

```bash
MIN_RELEVANCE_SCORE=7.0  # Only high-quality contexts
MAX_CONTEXTS=5           # Fewer contexts per query
```

### Manual Context Injection

You can manually trigger context recall:

```bash
bash .claude/hooks/user-prompt-submit
```

## References

- [Claude Code Hooks Documentation](https://docs.claude.com/claude-code/hooks)
- [ClaudeTools API Documentation](.claude/API_SPEC.md)
- [Database Schema](.claude/SCHEMA_CORE.md)

## Support

For issues or questions:
1. Check troubleshooting section above
2. Review API logs: `tail -f api/logs/app.log`
3. Test with `scripts/test-context-recall.sh`
4. Check hook output with `bash -x .claude/hooks/[hook-name]`