claudetools/CONTEXT_RECALL_SETUP.md

Context Recall System - Setup Guide

Complete guide for setting up the Claude Code Context Recall System in ClaudeTools.

Quick Start

# 1. Start the API server
uvicorn api.main:app --reload

# 2. Run the automated setup (in a new terminal)
bash scripts/setup-context-recall.sh

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

# 4. Start using Claude Code - context recall is now automatic!

Overview

The Context Recall System provides seamless context continuity across Claude Code sessions by:

• Automatic Recall - Injects relevant context from previous sessions before each message
• Automatic Saving - Saves conversation summaries after task completion
• Project Awareness - Tracks project state across sessions
• Graceful Degradation - Works offline without breaking Claude

System Architecture

Claude Code Conversation
    ↓
[user-prompt-submit hook]
    ↓
Query: GET /api/conversation-contexts/recall
    ↓
Inject context into conversation
    ↓
User message processed with context
    ↓
Task completion
    ↓
[task-complete hook]
    ↓
Save: POST /api/conversation-contexts
Update: POST /api/project-states

Files Created

Hooks

• .claude/hooks/user-prompt-submit - Recalls context before each message
• .claude/hooks/task-complete - Saves context after task completion
• .claude/hooks/README.md - Hook documentation

Configuration

• .claude/context-recall-config.env - Main configuration file (gitignored)

Scripts

• scripts/setup-context-recall.sh - One-command setup
• scripts/test-context-recall.sh - System testing

Documentation

• CONTEXT_RECALL_SETUP.md - This file

Setup Instructions

Automated Setup (Recommended)

1. Start the API server:

   cd D:\ClaudeTools
   uvicorn api.main:app --reload
   

2. Run setup script:

   bash scripts/setup-context-recall.sh
   

   The script will:

   • Check API availability
   • Request your credentials
   • Obtain JWT token
   • Detect or create your project
   • Configure environment variables
   • Make hooks executable
   • Test the system

3. Follow the prompts:

   Enter API credentials:
   Username [admin]: admin
   Password: ********
   

4. Verify setup:

   bash scripts/test-context-recall.sh
   

Manual Setup

If you prefer manual setup or need to troubleshoot:

1. Get JWT Token:

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

   Save the access_token from the response.

2. Create or Get Project:

   # Create new project
   curl -X POST http://localhost:8000/api/projects \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "ClaudeTools",
       "description": "ClaudeTools development project",
       "project_type": "development"
     }'
   

   Save the id from the response.

3. Configure .claude/context-recall-config.env:

   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:

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

5. Save project ID to git config:

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

Configuration Options

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

# API Configuration
CLAUDE_API_URL=http://localhost:8000        # API base URL

# Project Identification
CLAUDE_PROJECT_ID=                          # Auto-detected if not set

# Authentication
JWT_TOKEN=                                  # Required - from login endpoint

# Context Recall Settings
CONTEXT_RECALL_ENABLED=true                 # Enable/disable system
MIN_RELEVANCE_SCORE=5.0                     # Minimum score (0.0-10.0)
MAX_CONTEXTS=10                             # Max contexts per query

# Context Storage Settings
AUTO_SAVE_CONTEXT=true                      # Save after completion
DEFAULT_RELEVANCE_SCORE=7.0                 # Score for saved contexts

# Debug Settings
DEBUG_CONTEXT_RECALL=false                  # Enable debug output

Configuration Details

MIN_RELEVANCE_SCORE (0.0 - 10.0)

• Only contexts with score >= this value are recalled
• Lower = more contexts (may include less relevant)
• Higher = fewer contexts (only highly relevant)
• Recommended: 5.0 for general use, 7.0 for focused work

MAX_CONTEXTS (1 - 50)

• Maximum number of contexts to inject per message
• More contexts = more background but longer prompts
• Recommended: 10 for general use, 5 for focused work

DEBUG_CONTEXT_RECALL

• Set to true to see detailed hook output
• Useful for troubleshooting
• Disable in production for cleaner output

Usage

Once configured, the system works completely automatically:

During a Claude Code Session

1. Start Claude Code - Context is recalled automatically
2. Work normally - Your conversation happens as usual
3. Complete tasks - Context is saved automatically
4. Next session - Previous context is available

What You'll See

When context is available, you'll see it injected at the start:

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

---

This context is invisible to you but helps Claude maintain continuity.

Testing

Full System Test

bash scripts/test-context-recall.sh

Tests:

1. API connectivity
2. JWT token validity
3. Project access
4. Context recall endpoint
5. Context saving endpoint
6. Hook files exist and are executable
7. Hook execution
8. Project state updates

Expected output:

==========================================
Context Recall System Test
==========================================

Configuration loaded:
  API URL: http://localhost:8000
  Project ID: abc123...
  Enabled: true

[Test 1] API Connectivity
Testing: API health endpoint... ✓ PASS

[Test 2] Authentication
Testing: JWT token validity... ✓ PASS

...

==========================================
Test Summary
==========================================

Tests Passed: 15
Tests Failed: 0

✓ All tests passed! Context recall system is working correctly.

Manual Testing

Test context recall:

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

Test context saving:

source .claude/context-recall-config.env
export TASK_SUMMARY="Test task"
bash .claude/hooks/task-complete

Test API endpoints:

source .claude/context-recall-config.env

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

# List projects
curl http://localhost:8000/api/projects \
  -H "Authorization: Bearer $JWT_TOKEN"

Troubleshooting

Context Not Appearing

Symptoms: No context injected before messages

Solutions:

1. Enable debug mode:

   echo "DEBUG_CONTEXT_RECALL=true" >> .claude/context-recall-config.env
   

2. Check API is running:

   curl http://localhost:8000/health
   

3. Verify JWT token:

   source .claude/context-recall-config.env
   curl -H "Authorization: Bearer $JWT_TOKEN" http://localhost:8000/api/projects
   

4. Check hook is executable:

   ls -la .claude/hooks/user-prompt-submit
   

5. Test hook manually:

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

Context Not Saving

Symptoms: Context not persisted after tasks

Solutions:

1. Verify project ID:

   source .claude/context-recall-config.env
   echo "Project ID: $CLAUDE_PROJECT_ID"
   

2. Check task-complete hook:

   export TASK_SUMMARY="Test"
   bash -x .claude/hooks/task-complete
   

3. Check API logs:

   tail -f api/logs/app.log
   

Hooks Not Running

Symptoms: Hooks don't execute at all

Solutions:

1. Verify Claude Code hooks are enabled:

   • Check Claude Code documentation
   • Verify .claude/hooks/ directory is recognized

2. Check hook permissions:

   chmod +x .claude/hooks/*
   ls -la .claude/hooks/
   

3. Test hooks in isolation:

   source .claude/context-recall-config.env
   ./.claude/hooks/user-prompt-submit
   

API Connection Errors

Symptoms: "Connection refused" or timeout errors

Solutions:

1. Verify API is running:

   curl http://localhost:8000/health
   

2. Check API URL in config:

   grep CLAUDE_API_URL .claude/context-recall-config.env
   

3. Check firewall/antivirus:

   • Allow connections to localhost:8000
   • Disable firewall temporarily to test

4. Check API logs:

   uvicorn api.main:app --reload --log-level debug
   

JWT Token Expired

Symptoms: 401 Unauthorized errors

Solutions:

1. Re-run setup to get new token:

   bash scripts/setup-context-recall.sh
   

2. Or manually get new token:

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

3. Update config with new token:

   # Edit .claude/context-recall-config.env
   JWT_TOKEN=new-token-here
   

Advanced Usage

Custom Context Types

Edit task-complete hook to create custom context types:

# In .claude/hooks/task-complete, modify:
CONTEXT_TYPE="bug_fix"       # or "feature", "refactor", etc.
RELEVANCE_SCORE=9.0          # Higher for important contexts

Filtering by Context Type

Query specific context types via API:

curl "http://localhost:8000/api/conversation-contexts/recall?project_id=$PROJECT_ID&context_type=technical_decision" \
  -H "Authorization: Bearer $JWT_TOKEN"

Adjusting Recall Behavior

Fine-tune what context is recalled:

# In .claude/context-recall-config.env

# Only recall high-value contexts
MIN_RELEVANCE_SCORE=7.5

# Limit to most recent contexts
MAX_CONTEXTS=5

# Or get more historical context
MAX_CONTEXTS=20
MIN_RELEVANCE_SCORE=3.0

Manual Context Injection

Manually trigger context recall in any conversation:

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

Copy the output and paste into Claude Code.

Disabling for Specific Sessions

Temporarily disable context recall:

export CONTEXT_RECALL_ENABLED=false
# Use Claude Code
export CONTEXT_RECALL_ENABLED=true  # Re-enable

Security

JWT Token Storage

• JWT tokens are stored in .claude/context-recall-config.env
• This file is in .gitignore (NEVER commit it!)
• Tokens expire after 24 hours (configurable in API)
• Re-run setup to get fresh token

Best Practices

1. Never commit tokens:

   • .claude/context-recall-config.env is gitignored
   • Verify: git status should not show it

2. Rotate tokens regularly:

   • Re-run setup script weekly
   • Or implement token refresh in hooks

3. Use strong passwords:

   • For API authentication
   • Store securely (password manager)

4. Limit token scope:

   • Tokens are project-specific
   • Create separate projects for sensitive work

API Endpoints Used

The hooks interact with these API endpoints:

• 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
• GET /api/projects/{id} - Get specific project
• POST /api/auth/login - Authenticate and get JWT token

Integration with ClaudeTools

The Context Recall System integrates seamlessly with ClaudeTools:

• Database: Uses existing PostgreSQL database
• Models: Uses ConversationContext and ProjectState models
• API: Uses FastAPI REST endpoints
• Authentication: Uses JWT token system
• Projects: Links contexts to projects automatically

Performance Considerations

Hook Performance

• Hooks run synchronously before/after messages
• API calls have 3-5 second timeouts
• Failures are silent (don't break Claude)
• Average overhead: <500ms per message

Database Performance

• Context recall uses indexed queries
• Relevance scoring is pre-computed
• Typical query time: <100ms
• Scales to thousands of contexts per project

Optimization Tips

1. Adjust MIN_RELEVANCE_SCORE:

   • Higher = faster queries, fewer contexts
   • Lower = more contexts, slightly slower

2. Limit MAX_CONTEXTS:

   • Fewer contexts = faster injection
   • Recommended: 5-10 for best performance

3. Clean old contexts:

   • Archive contexts older than 6 months
   • Keep database lean

Future Enhancements

Potential improvements:

• Semantic search for context recall
• Token refresh automation
• Context compression for long summaries
• Multi-project context linking
• Context importance learning
• Web UI for context management
• Export/import context archives
• Context analytics dashboard

References

• Claude Code Hooks Documentation
• ClaudeTools API Documentation
• Database Schema
• Hook Implementation

Support

For issues or questions:

1. Check logs:

   tail -f api/logs/app.log
   

2. Run tests:

   bash scripts/test-context-recall.sh
   

3. Enable debug mode:

   echo "DEBUG_CONTEXT_RECALL=true" >> .claude/context-recall-config.env
   

4. Review documentation:

   • .claude/hooks/README.md - Hook-specific help
   • CONTEXT_RECALL_SETUP.md - This guide

Summary

The Context Recall System provides:

• Seamless context continuity across Claude Code sessions
• Automatic recall of relevant previous work
• Automatic saving of completed tasks
• Project-aware context management
• Graceful degradation if API unavailable

Once configured, it works completely automatically, making every Claude Code session aware of your project's history and context.

Setup time: ~2 minutes with automated script Maintenance: Token refresh every 24 hours (automated via setup script) Performance impact: <500ms per message User action required: None (fully automatic)

Enjoy enhanced Claude Code sessions with full context awareness!