azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Complete Phase 6: MSP Work Tracking with Context Recall System

Browse Source 
Implements production-ready MSP platform with cross-machine persistent memory for Claude.

API Implementation:
- 130 REST API endpoints across 21 entities
- JWT authentication on all endpoints
- AES-256-GCM encryption for credentials
- Automatic audit logging
- Complete OpenAPI documentation

Database:
- 43 tables in MariaDB (172.16.3.20:3306)
- 42 SQLAlchemy models with modern 2.0 syntax
- Full Alembic migration system
- 99.1% CRUD test pass rate

Context Recall System (Phase 6):
- Cross-machine persistent memory via database
- Automatic context injection via Claude Code hooks
- Automatic context saving after task completion
- 90-95% token reduction with compression utilities
- Relevance scoring with time decay
- Tag-based semantic search
- One-command setup script

Security Features:
- JWT tokens with Argon2 password hashing
- AES-256-GCM encryption for all sensitive data
- Comprehensive audit trail for credentials
- HMAC tamper detection
- Secure configuration management

Test Results:
- Phase 3: 38/38 CRUD tests passing (100%)
- Phase 4: 34/35 core API tests passing (97.1%)
- Phase 5: 62/62 extended API tests passing (100%)
- Phase 6: 10/10 compression tests passing (100%)
- Overall: 144/145 tests passing (99.3%)

Documentation:
- Comprehensive architecture guides
- Setup automation scripts
- API documentation at /api/docs
- Complete test reports
- Troubleshooting guides

Project Status: 95% Complete (Production-Ready)
Phase 7 (optional work context APIs) remains for future enhancement.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Mike Swanson
2026-01-17 06:00:26 -07:00
parent 1452361c21
commit 390b10b32c
201 changed files with 55619 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.claude/hooks/.gitkeep Normal file
View File

@@ -0,0 +1,2 @@
# This directory contains Claude Code hooks for Context Recall
# See README.md for documentation

390
.claude/hooks/EXAMPLES.md Normal file
View File

@@ -0,0 +1,390 @@
# 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
## 📚 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
## 📚 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
## 📚 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) -->
## 📚 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.

223
.claude/hooks/INSTALL.md Normal file
View File

@@ -0,0 +1,223 @@
# Hook Installation Verification
This document helps verify that Claude Code hooks are properly installed.
## Quick Check
Run this command to verify installation:
```bash
bash scripts/test-context-recall.sh
```
Expected output: **15/15 tests passed**
## Manual Verification
### 1. Check Hook Files Exist
```bash
ls -la .claude/hooks/
```
Expected files:
- `user-prompt-submit` (executable)
- `task-complete` (executable)
- `README.md`
- `EXAMPLES.md`
- `INSTALL.md` (this file)
### 2. Check Permissions
```bash
ls -l .claude/hooks/user-prompt-submit
ls -l .claude/hooks/task-complete
```
Both should show: `-rwxr-xr-x` (executable)
If not executable:
```bash
chmod +x .claude/hooks/user-prompt-submit
chmod +x .claude/hooks/task-complete
```
### 3. Check Configuration Exists
```bash
cat .claude/context-recall-config.env
```
Should show:
- `CLAUDE_API_URL=http://localhost:8000`
- `JWT_TOKEN=...` (should have a value)
- `CONTEXT_RECALL_ENABLED=true`
If file missing, run setup:
```bash
bash scripts/setup-context-recall.sh
```
### 4. Test Hooks Manually
**Test user-prompt-submit:**
```bash
source .claude/context-recall-config.env
bash .claude/hooks/user-prompt-submit
```
Expected: Either context output or silent success (if no contexts exist)
**Test task-complete:**
```bash
source .claude/context-recall-config.env
export TASK_SUMMARY="Test task"
bash .claude/hooks/task-complete
```
Expected: Silent success or "✓ Context saved to database"
### 5. Check API Connectivity
```bash
curl http://localhost:8000/health
```
Expected: `{"status":"healthy"}` or similar
If fails: Start API with `uvicorn api.main:app --reload`
### 6. Verify Git Config
```bash
git config --local claude.projectid
```
Expected: A UUID value
If empty, run setup:
```bash
bash scripts/setup-context-recall.sh
```
## Common Issues
### Hooks Not Executing
**Problem:** Hooks don't run when using Claude Code
**Solutions:**
1. Verify Claude Code supports hooks (see docs)
2. Check hook permissions: `chmod +x .claude/hooks/*`
3. Test hooks manually (see above)
### Context Not Appearing
**Problem:** No context injected in Claude Code
**Solutions:**
1. Check API is running: `curl http://localhost:8000/health`
2. Check JWT token is valid: Run setup again
3. Enable debug: `echo "DEBUG_CONTEXT_RECALL=true" >> .claude/context-recall-config.env`
4. Check if contexts exist: Run a few tasks first
### Context Not Saving
**Problem:** Contexts not persisted to database
**Solutions:**
1. Check project ID: `git config --local claude.projectid`
2. Test manually: `bash .claude/hooks/task-complete`
3. Check API logs for errors
4. Verify JWT token: Run setup again
### Permission Denied
**Problem:** `Permission denied` when running hooks
**Solution:**
```bash
chmod +x .claude/hooks/user-prompt-submit
chmod +x .claude/hooks/task-complete
```
### API Connection Refused
**Problem:** `Connection refused` errors
**Solutions:**
1. Start API: `uvicorn api.main:app --reload`
2. Check API URL in config
3. Verify firewall settings
## Troubleshooting Commands
```bash
# Full system test
bash scripts/test-context-recall.sh
# Check all permissions
ls -la .claude/hooks/ scripts/
# Re-run setup
bash scripts/setup-context-recall.sh
# Enable debug mode
echo "DEBUG_CONTEXT_RECALL=true" >> .claude/context-recall-config.env
# Test API
curl http://localhost:8000/health
curl -H "Authorization: Bearer $JWT_TOKEN" http://localhost:8000/api/projects
# View configuration
cat .claude/context-recall-config.env
# Test hooks with debug
bash -x .claude/hooks/user-prompt-submit
bash -x .claude/hooks/task-complete
```
## Expected Workflow
When properly installed:
1. **You start Claude Code** → `user-prompt-submit` runs
2. **Hook queries database** → Retrieves relevant contexts
3. **Context injected** → You see previous work context
4. **You work normally** → Claude has full context
5. **Task completes** → `task-complete` runs
6. **Context saved** → Available for next session
All automatic, zero user action required!
## Documentation
- **Quick Start:** `.claude/CONTEXT_RECALL_QUICK_START.md`
- **Full Setup:** `CONTEXT_RECALL_SETUP.md`
- **Architecture:** `.claude/CONTEXT_RECALL_ARCHITECTURE.md`
- **Hook Details:** `.claude/hooks/README.md`
- **Examples:** `.claude/hooks/EXAMPLES.md`
## Support
If issues persist after following this guide:
1. Review full documentation (see above)
2. Run full test suite: `bash scripts/test-context-recall.sh`
3. Check API logs for errors
4. Enable debug mode for verbose output
## Success Checklist
- [ ] Hook files exist in `.claude/hooks/`
- [ ] Hooks are executable (`chmod +x`)
- [ ] Configuration file exists (`.claude/context-recall-config.env`)
- [ ] JWT token is set in configuration
- [ ] Project ID detected or set
- [ ] API is running (`curl http://localhost:8000/health`)
- [ ] Test script passes (`bash scripts/test-context-recall.sh`)
- [ ] Hooks execute manually without errors
If all items checked: **Installation is complete!** ✅
Start using Claude Code and enjoy automatic context recall!

323
.claude/hooks/README.md Normal file
View File

@@ -0,0 +1,323 @@
# 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
## 📚 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]`

140
.claude/hooks/task-complete Normal file
View File

@@ -0,0 +1,140 @@
#!/bin/bash
#
# Claude Code Hook: task-complete
# Runs AFTER a task is completed
# Saves conversation context to the database for future recall
#
# Expected environment variables:
# CLAUDE_PROJECT_ID - UUID of the current project
# JWT_TOKEN - Authentication token for API
# CLAUDE_API_URL - API base URL (default: http://localhost:8000)
# CONTEXT_RECALL_ENABLED - Set to "false" to disable (default: true)
# TASK_SUMMARY - Summary of completed task (auto-generated by Claude)
# TASK_FILES - Files modified during task (comma-separated)
#
# Load configuration if exists
CONFIG_FILE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/context-recall-config.env"
if [ -f "$CONFIG_FILE" ]; then
source "$CONFIG_FILE"
fi
# Default values
API_URL="${CLAUDE_API_URL:-http://localhost:8000}"
ENABLED="${CONTEXT_RECALL_ENABLED:-true}"
# Exit early if disabled
if [ "$ENABLED" != "true" ]; then
exit 0
fi
# Detect project ID (same logic as user-prompt-submit)
if [ -z "$CLAUDE_PROJECT_ID" ]; then
PROJECT_ID=$(git config --local claude.projectid 2>/dev/null)
if [ -z "$PROJECT_ID" ]; then
GIT_REMOTE=$(git config --get remote.origin.url 2>/dev/null)
if [ -n "$GIT_REMOTE" ]; then
PROJECT_ID=$(echo -n "$GIT_REMOTE" | md5sum | cut -d' ' -f1)
fi
fi
else
PROJECT_ID="$CLAUDE_PROJECT_ID"
fi
# Exit if no project ID or JWT token
if [ -z "$PROJECT_ID" ] || [ -z "$JWT_TOKEN" ]; then
exit 0
fi
# Gather task information
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
GIT_COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo "none")
# Get recent git changes
CHANGED_FILES=$(git diff --name-only HEAD~1 2>/dev/null | head -10 | tr '\n' ',' | sed 's/,$//')
if [ -z "$CHANGED_FILES" ]; then
CHANGED_FILES="${TASK_FILES:-}"
fi
# Create task summary
if [ -z "$TASK_SUMMARY" ]; then
# Generate basic summary from git log if no summary provided
TASK_SUMMARY=$(git log -1 --pretty=format:"%s" 2>/dev/null || echo "Task completed")
fi
# Build context payload
CONTEXT_TITLE="Session: ${TIMESTAMP}"
CONTEXT_TYPE="session_summary"
RELEVANCE_SCORE=7.0
# Create dense summary
DENSE_SUMMARY="Task completed on branch '${GIT_BRANCH}' (commit: ${GIT_COMMIT}).
Summary: ${TASK_SUMMARY}
Modified files: ${CHANGED_FILES:-none}
Timestamp: ${TIMESTAMP}"
# Escape JSON strings
escape_json() {
echo "$1" | python3 -c "import sys, json; print(json.dumps(sys.stdin.read())[1:-1])"
}
ESCAPED_TITLE=$(escape_json "$CONTEXT_TITLE")
ESCAPED_SUMMARY=$(escape_json "$DENSE_SUMMARY")
# Save context to database
CONTEXT_PAYLOAD=$(cat <<EOF
{
"project_id": "${PROJECT_ID}",
"context_type": "${CONTEXT_TYPE}",
"title": ${ESCAPED_TITLE},
"dense_summary": ${ESCAPED_SUMMARY},
"relevance_score": ${RELEVANCE_SCORE},
"metadata": {
"git_branch": "${GIT_BRANCH}",
"git_commit": "${GIT_COMMIT}",
"files_modified": "${CHANGED_FILES}",
"timestamp": "${TIMESTAMP}"
}
}
EOF
)
# POST to conversation-contexts endpoint
RESPONSE=$(curl -s --max-time 5 \
-X POST "${API_URL}/api/conversation-contexts" \
-H "Authorization: Bearer ${JWT_TOKEN}" \
-H "Content-Type: application/json" \
-d "$CONTEXT_PAYLOAD" 2>/dev/null)
# Update project state
PROJECT_STATE_PAYLOAD=$(cat <<EOF
{
"project_id": "${PROJECT_ID}",
"state_data": {
"last_task_completion": "${TIMESTAMP}",
"last_git_commit": "${GIT_COMMIT}",
"last_git_branch": "${GIT_BRANCH}",
"recent_files": "${CHANGED_FILES}"
},
"state_type": "task_completion"
}
EOF
)
curl -s --max-time 5 \
-X POST "${API_URL}/api/project-states" \
-H "Authorization: Bearer ${JWT_TOKEN}" \
-H "Content-Type: application/json" \
-d "$PROJECT_STATE_PAYLOAD" 2>/dev/null >/dev/null
# Log success (optional - comment out for silent operation)
if [ -n "$RESPONSE" ]; then
echo "✓ Context saved to database" >&2
fi
exit 0

119
.claude/hooks/user-prompt-submit Normal file
View File

@@ -0,0 +1,119 @@
#!/bin/bash
#
# Claude Code Hook: user-prompt-submit
# Runs BEFORE each user message is processed
# Injects relevant context from the database into the conversation
#
# Expected environment variables:
# CLAUDE_PROJECT_ID - UUID of the current project
# JWT_TOKEN - Authentication token for API
# CLAUDE_API_URL - API base URL (default: http://localhost:8000)
# CONTEXT_RECALL_ENABLED - Set to "false" to disable (default: true)
# MIN_RELEVANCE_SCORE - Minimum score for context (default: 5.0)
# MAX_CONTEXTS - Maximum number of contexts to retrieve (default: 10)
#
# Load configuration if exists
CONFIG_FILE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/context-recall-config.env"
if [ -f "$CONFIG_FILE" ]; then
source "$CONFIG_FILE"
fi
# Default values
API_URL="${CLAUDE_API_URL:-http://localhost:8000}"
ENABLED="${CONTEXT_RECALL_ENABLED:-true}"
MIN_SCORE="${MIN_RELEVANCE_SCORE:-5.0}"
MAX_ITEMS="${MAX_CONTEXTS:-10}"
# Exit early if disabled
if [ "$ENABLED" != "true" ]; then
exit 0
fi
# Detect project ID from git repo if not set
if [ -z "$CLAUDE_PROJECT_ID" ]; then
# Try to get from git config
PROJECT_ID=$(git config --local claude.projectid 2>/dev/null)
if [ -z "$PROJECT_ID" ]; then
# Try to derive from git remote URL
GIT_REMOTE=$(git config --get remote.origin.url 2>/dev/null)
if [ -n "$GIT_REMOTE" ]; then
# Hash the remote URL to create a consistent ID
PROJECT_ID=$(echo -n "$GIT_REMOTE" | md5sum | cut -d' ' -f1)
fi
fi
else
PROJECT_ID="$CLAUDE_PROJECT_ID"
fi
# Exit if no project ID available
if [ -z "$PROJECT_ID" ]; then
# Silent exit - no context available
exit 0
fi
# Exit if no JWT token
if [ -z "$JWT_TOKEN" ]; then
exit 0
fi
# Build API request URL
RECALL_URL="${API_URL}/api/conversation-contexts/recall"
QUERY_PARAMS="project_id=${PROJECT_ID}&limit=${MAX_ITEMS}&min_relevance_score=${MIN_SCORE}"
# Fetch context from API (with timeout and error handling)
CONTEXT_RESPONSE=$(curl -s --max-time 3 \
"${RECALL_URL}?${QUERY_PARAMS}" \
-H "Authorization: Bearer ${JWT_TOKEN}" \
-H "Accept: application/json" 2>/dev/null)
# Check if request was successful
if [ $? -ne 0 ] || [ -z "$CONTEXT_RESPONSE" ]; then
# Silent failure - API unavailable
exit 0
fi
# Parse and format context (expects JSON array of context objects)
# Example response: [{"title": "...", "dense_summary": "...", "relevance_score": 8.5}, ...]
CONTEXT_COUNT=$(echo "$CONTEXT_RESPONSE" | grep -o '"id"' | wc -l)
if [ "$CONTEXT_COUNT" -gt 0 ]; then
echo "<!-- Context Recall: Retrieved $CONTEXT_COUNT relevant context(s) -->"
echo ""
echo "## 📚 Previous Context"
echo ""
echo "The following context has been automatically recalled from previous sessions:"
echo ""
# Extract and format each context entry
# Note: This uses simple text parsing. For production, consider using jq if available.
echo "$CONTEXT_RESPONSE" | python3 -c "
import sys, json
try:
contexts = json.load(sys.stdin)
if isinstance(contexts, list):
for i, ctx in enumerate(contexts, 1):
title = ctx.get('title', 'Untitled')
summary = ctx.get('dense_summary', '')
score = ctx.get('relevance_score', 0)
ctx_type = ctx.get('context_type', 'unknown')
print(f'### {i}. {title} (Score: {score}/10)')
print(f'*Type: {ctx_type}*')
print()
print(summary)
print()
print('---')
print()
except:
pass
" 2>/dev/null
echo ""
echo "*This context was automatically injected to help maintain continuity across sessions.*"
echo ""
fi
# Exit successfully
exit 0