claudetools/.claude/hooks/EXAMPLES.md

# Context Recall Examples

Real-world examples of how the Context Recall System works.

## Example 1: Continuing Previous Work

### Session 1 (Monday)

**User:** "Add authentication endpoints to the API"

**Claude:** Creates `/api/auth/login` and `/api/auth/register` endpoints

**System:** Saves context:
```json
{
  "title": "Session: 2025-01-13T14:30:00Z",
  "context_type": "session_summary",
  "dense_summary": "Created authentication endpoints including login and register. Implemented JWT token generation with 24-hour expiry. Added password hashing with bcrypt.",
  "relevance_score": 8.5,
  "metadata": {
    "files_modified": "api/auth.py,api/models.py",
    "git_branch": "feature/auth"
  }
}
```

### Session 2 (Tuesday)

**User:** "Add password reset functionality"

**System:** Automatically recalls context:
```markdown
## [DOCS] Previous Context

### 1. Session: 2025-01-13T14:30:00Z (Score: 8.5/10)
*Type: session_summary*

Created authentication endpoints including login and register.
Implemented JWT token generation with 24-hour expiry.
Added password hashing with bcrypt.

Modified files: api/auth.py,api/models.py
Branch: feature/auth
```

**Claude:** (with context) "I'll add password reset to the existing authentication system. Based on the previous session, I can see we're using JWT tokens and bcrypt..."

## Example 2: Technical Decision Recall

### Session 1

**User:** "Why did we choose PostgreSQL over MongoDB?"

**Claude:** "We chose PostgreSQL because: 1) Strong ACID guarantees, 2) Complex relationships in data model, 3) Team familiarity..."

**System:** Saves context:
```json
{
  "title": "Database Technology Decision",
  "context_type": "technical_decision",
  "dense_summary": "Chose PostgreSQL over MongoDB for: ACID guarantees, complex relationships, team familiarity, excellent tooling ecosystem. Decision made after evaluating both options.",
  "relevance_score": 9.0
}
```

### Session 2 (Weeks Later)

**User:** "Should we use MongoDB for the logging service?"

**System:** Recalls context:
```markdown
## [DOCS] Previous Context

### 1. Database Technology Decision (Score: 9.0/10)
*Type: technical_decision*

Chose PostgreSQL over MongoDB for: ACID guarantees, complex relationships,
team familiarity, excellent tooling ecosystem. Decision made after
evaluating both options.
```

**Claude:** "Given our previous decision to use PostgreSQL for its ACID guarantees and relational features, let's consider if logging has different requirements..."

## Example 3: Bug Fix History

### Session 1

**User:** "Fix the authentication timeout issue"

**Claude:** Fixes bug in JWT token validation

**System:** Saves:
```json
{
  "title": "Bug Fix: Authentication Timeouts",
  "context_type": "bug_fix",
  "dense_summary": "Fixed authentication timeout issue caused by incorrect JWT expiry validation. Changed from server time to UTC. Added timezone handling.",
  "relevance_score": 8.0,
  "metadata": {
    "bug_type": "authentication",
    "fix_type": "timezone_handling"
  }
}
```

### Session 2

**User:** "Users are getting logged out randomly"

**System:** Recalls:
```markdown
## [DOCS] Previous Context

### 1. Bug Fix: Authentication Timeouts (Score: 8.0/10)
*Type: bug_fix*

Fixed authentication timeout issue caused by incorrect JWT expiry
validation. Changed from server time to UTC. Added timezone handling.
```

**Claude:** "This might be related to the previous timeout issue. Let me check the JWT timezone handling..."

## Example 4: Multi-Session Feature Development

### Session 1: Planning

**User:** "Plan a user dashboard feature"

**Claude:** Creates architecture plan

**System:** Saves:
```json
{
  "title": "User Dashboard Architecture",
  "context_type": "architecture_decision",
  "dense_summary": "Planned user dashboard with: Real-time metrics, customizable widgets, role-based access. Tech stack: React frontend, WebSocket for real-time, Redis for caching.",
  "relevance_score": 9.5
}
```

### Session 2: Frontend Implementation

**User:** "Implement the dashboard frontend"

**System:** Recalls planning context, Claude implements according to plan

**System:** Saves:
```json
{
  "title": "Dashboard Frontend Implementation",
  "context_type": "session_summary",
  "dense_summary": "Implemented React dashboard with widget system. Created: DashboardContainer, WidgetGrid, individual widget components. Used WebSocket hook for real-time updates.",
  "relevance_score": 8.0
}
```

### Session 3: Backend Implementation

**User:** "Add the backend API for the dashboard"

**System:** Recalls both previous contexts

**Claude:** "Based on the architecture plan and frontend implementation, I'll create the WebSocket endpoints and Redis caching layer..."

### Session 4: Testing

**User:** "Write tests for the dashboard"

**System:** Recalls all three previous contexts

**Claude:** "I'll write tests covering the complete dashboard flow: frontend widgets, WebSocket connections, Redis caching, and API endpoints..."

## Example 5: Context Filtering

### Query with High Threshold

```bash
MIN_RELEVANCE_SCORE=7.5
```

Result: Only highly relevant contexts (major decisions, current feature work)

```markdown
### 1. User Authentication Refactor (Score: 9.0/10)
### 2. Database Schema Changes (Score: 8.5/10)
### 3. API Rate Limiting Implementation (Score: 7.8/10)
```

### Query with Low Threshold

```bash
MIN_RELEVANCE_SCORE=3.0
```

Result: More historical context (includes older sessions, minor changes)

```markdown
### 1. User Authentication Refactor (Score: 9.0/10)
### 2. Database Schema Changes (Score: 8.5/10)
### 3. API Rate Limiting Implementation (Score: 7.8/10)
### 4. Update README documentation (Score: 6.5/10)
### 5. Fix typo in comment (Score: 4.2/10)
### 6. Add gitignore entry (Score: 3.5/10)
```

## Example 6: Project State Tracking

### After Each Session

**task-complete hook** saves project state:

```json
{
  "project_id": "abc123...",
  "state_data": {
    "last_task_completion": "2025-01-15T10:30:00Z",
    "last_git_commit": "a1b2c3d",
    "last_git_branch": "feature/dashboard",
    "recent_files": "src/Dashboard.tsx,api/dashboard.py"
  },
  "state_type": "task_completion"
}
```

This enables Claude to answer questions like:
- "What was I working on last?"
- "What files did I modify recently?"
- "What branch am I on?"

## Example 7: Cross-Feature Context

### Session 1: Feature A

**User:** "Add user roles system"

**System:** Saves context about role implementation (Admin, User, Guest)

### Session 2: Feature B

**User:** "Add permissions to the API endpoints"

**System:** Recalls role system context

**Claude:** "I'll add permissions using the existing role system (Admin, User, Guest) that we implemented..."

This shows how context from one feature automatically informs work on related features.

## Example 8: Onboarding New Team Members

### New Developer's First Session

**New Dev:** "How does authentication work in this project?"

**System:** Recalls all authentication-related contexts:
```markdown
### 1. User Authentication Refactor (Score: 9.0/10)
Implemented JWT-based authentication with bcrypt password hashing...

### 2. Session Management Design (Score: 8.5/10)
Added Redis-backed session storage with 24-hour expiry...

### 3. OAuth Integration (Score: 8.0/10)
Integrated Google and GitHub OAuth providers...
```

**Claude:** (with full context) "Our authentication system uses JWT tokens with bcrypt hashing. We also have OAuth integration with Google and GitHub..."

## Example 9: Debugging with Context

### Session 1: Implementation

**User:** "Add email notification system"

**System:** Saves implementation details (SMTP config, template system, queuing)

### Session 2: Bug Report

**User:** "Emails aren't being sent"

**System:** Recalls implementation context

**Claude:** "Let me check the email system we implemented. Based on the previous session, we're using SMTP with a queue system. Common issues could be..."

## Example 10: Evolving Requirements

### Month 1

**User:** "Build simple user profile page"

**System:** Saves initial implementation

### Month 2

**User:** "Add social features to profiles"

**System:** Recalls original implementation

**Claude:** "I'll extend the existing profile system to include social features..."

### Month 3

**User:** "Make profiles customizable"

**System:** Recalls both previous implementations

**Claude:** "Building on the profile and social features, I'll add customization options..."

Each session builds on previous work with full context.

## Real Output Example

Here's what you actually see in Claude Code when context is recalled:

```markdown
<!-- Context Recall: Retrieved 3 relevant context(s) -->

## [DOCS] Previous Context

The following context has been automatically recalled from previous sessions:

### 1. API Authentication Implementation (Score: 8.5/10)
*Type: session_summary*

Task completed on branch 'feature/auth' (commit: a1b2c3d).

Summary: Implemented JWT-based authentication system with login/register
endpoints. Added password hashing using bcrypt. Created middleware for
protected routes. Token expiry set to 24 hours.

Modified files: api/auth.py,api/middleware.py,api/models.py

Timestamp: 2025-01-15T14:30:00Z

---

### 2. Database Schema for Users (Score: 7.8/10)
*Type: technical_decision*

Added User model with fields: id, username, email, password_hash,
created_at, last_login. Decided to use UUID for user IDs instead of
auto-increment integers for better security and scalability.

---

### 3. Security Best Practices Discussion (Score: 7.2/10)
*Type: session_summary*

Discussed security considerations: password hashing (bcrypt), token
storage (httpOnly cookies), CORS configuration, rate limiting. Decided
to implement rate limiting in next session.

---

*This context was automatically injected to help maintain continuity across sessions.*
```

This gives Claude complete awareness of your previous work without you having to explain it!

## Benefits Demonstrated

1. **Continuity** - Work picks up exactly where you left off
2. **Consistency** - Decisions made previously are remembered
3. **Efficiency** - No need to re-explain project details
4. **Learning** - New team members get instant project knowledge
5. **Debugging** - Past implementations inform current troubleshooting
6. **Evolution** - Features build naturally on previous work

## Configuration Tips

**For focused work (single feature):**
```bash
MIN_RELEVANCE_SCORE=7.0
MAX_CONTEXTS=5
```

**For comprehensive context (complex projects):**
```bash
MIN_RELEVANCE_SCORE=5.0
MAX_CONTEXTS=15
```

**For debugging (need full history):**
```bash
MIN_RELEVANCE_SCORE=3.0
MAX_CONTEXTS=20
```

## Next Steps

See `CONTEXT_RECALL_SETUP.md` for setup instructions and `README.md` for technical details.