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:

{
  "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:

## [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:

{
  "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:

## [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:

{
  "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:

## [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:

{
  "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:

{
  "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

MIN_RELEVANCE_SCORE=7.5

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

### 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

MIN_RELEVANCE_SCORE=3.0

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

### 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:

{
  "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:

### 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:

<!-- 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):

MIN_RELEVANCE_SCORE=7.0
MAX_CONTEXTS=5

For comprehensive context (complex projects):

MIN_RELEVANCE_SCORE=5.0
MAX_CONTEXTS=15

For debugging (need full history):

MIN_RELEVANCE_SCORE=3.0
MAX_CONTEXTS=20

Next Steps

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