ClaudeTools cleanup: drop dead context-recall layer, unify /save + /sync
Deletions (~1,500 lines of dead docs): - .claude/hooks/ — docs-only directory, no executables. Referenced scripts setup-context-recall.sh / test-context-recall.sh did not exist. Hooks would have POSTed to localhost:8000; the API actually ran at 172.16.3.30:8001 and is no longer in use. - .claude/AUTO_CONTEXT_SYSTEM.md — 347-line duplicate spec of CLAUDE.md's Automatic Context Loading section, referencing unimplemented hooks. - .claude/URGENT-vault-path-bug.md — 217-line urgency note for a fix that already shipped weeks ago. - .claude/context-recall-config.env.example — config template for the same dead system. Refactors (~500 lines net removed): - /save and /sync now wrap bash .claude/scripts/sync.sh as the single source of truth for git ops. /save adds a session-log-writing step in front; /sync invokes the script directly. - Dropped /sync's manual git phases that contradicted sync.sh. - Dropped the cp -r ~/ClaudeTools/.claude/commands/* ~/.claude/commands/ step (clobbered per-user customization in the multi-user model). - Dropped auto-invoke of /refresh-directives (command does not exist). - Dropped references to directives.md (file does not exist). - /save now documents the rm -f save_narrative_prompt.txt step, fixing the stale-prompt bug Howard documented in feedback_tmp_path_windows.md. Fixes: - CLAUDE.md SESSION_STATE.md reference replaced with the canonical PROJECT_STATE.md (per-project, with protocol at .claude/PROJECT_STATE_PROTOCOL.md). 16 client folders already use PROJECT_STATE.md; SESSION_STATE.md was only a stale reference. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1,2 +0,0 @@
|
||||
# This directory contains Claude Code hooks for Context Recall
|
||||
# See README.md for documentation
|
||||
@@ -1,390 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,223 +0,0 @@
|
||||
# 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!** [OK]
|
||||
|
||||
Start using Claude Code and enjoy automatic context recall!
|
||||
@@ -1,323 +0,0 @@
|
||||
# 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]`
|
||||
Reference in New Issue
Block a user