claudetools/.claude/claude.md

ClaudeTools Project Context

Project Type: MSP Work Tracking System with AI Context Recall Status: Production-Ready (95% Complete) Database: MariaDB 10.6.22 @ 172.16.3.30:3306 (RMM Server)

---

Quick Facts

• 130 API Endpoints across 21 entities
• 43 Database Tables (fully migrated)
• Context Recall System with cross-machine persistent memory
• JWT Authentication on all endpoints
• AES-256-GCM Encryption for credentials

---

Project Structure

D:\ClaudeTools/
├── api/                    # FastAPI application
│   ├── main.py            # API entry point (130 endpoints)
│   ├── models/            # SQLAlchemy models (42 models)
│   ├── routers/           # API endpoints (21 routers)
│   ├── schemas/           # Pydantic schemas (84 classes)
│   ├── services/          # Business logic (21 services)
│   ├── middleware/        # Auth & error handling
│   └── utils/             # Crypto & compression utilities
├── migrations/            # Alembic database migrations
├── .claude/              # Claude Code hooks & config
│   ├── hooks/            # Auto-inject/save context
│   └── context-recall-config.env  # Configuration
└── scripts/              # Setup & test scripts

---

Database Connection

UPDATED 2026-01-17: Database is centralized on RMM server (172.16.3.30)

Connection String:

Host: 172.16.3.30:3306
Database: claudetools
User: claudetools
Password: CT_e8fcd5a3952030a79ed6debae6c954ed

Environment Variables:

DATABASE_URL=mysql+pymysql://claudetools:CT_e8fcd5a3952030a79ed6debae6c954ed@172.16.3.30:3306/claudetools?charset=utf8mb4

API Base URL: http://172.16.3.30:8001

See: .claude/agents/DATABASE_CONNECTION_INFO.md for complete details.

---

Starting the API

# Activate virtual environment
api\venv\Scripts\activate

# Start API server
python -m api.main
# OR
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

# Access documentation
http://localhost:8000/api/docs

---

Context Recall System

How It Works

Automatic context injection via Claude Code hooks:

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

Setup (One-Time)

bash scripts/setup-context-recall.sh

Manual Context Recall

API Endpoint:

GET http://localhost:8000/api/conversation-contexts/recall
  ?project_id={uuid}
  &tags[]=fastapi&tags[]=database
  &limit=10
  &min_relevance_score=5.0

Test Context Recall:

bash scripts/test-context-recall.sh

Save Context Manually

curl -X POST http://localhost:8000/api/conversation-contexts \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "uuid-here",
    "context_type": "session_summary",
    "title": "Current work session",
    "dense_summary": "Working on API endpoints...",
    "relevance_score": 7.0,
    "tags": ["api", "fastapi", "development"]
  }'

---

Key API Endpoints

Core Entities (Phase 4)

• /api/machines - Machine inventory
• /api/clients - Client management
• /api/projects - Project tracking
• /api/sessions - Work sessions
• /api/tags - Tagging system

MSP Work Tracking (Phase 5)

• /api/work-items - Work item tracking
• /api/tasks - Task management
• /api/billable-time - Time & billing

Infrastructure (Phase 5)

• /api/sites - Physical locations
• /api/infrastructure - IT assets
• /api/services - Application services
• /api/networks - Network configs
• /api/firewall-rules - Firewall documentation
• /api/m365-tenants - M365 tenant management

Credentials (Phase 5)

• /api/credentials - Encrypted credential storage
• /api/credential-audit-logs - Audit trail (read-only)
• /api/security-incidents - Incident tracking

Context Recall (Phase 6)

• /api/conversation-contexts - Context storage & recall
• /api/context-snippets - Knowledge fragments
• /api/project-states - Project state tracking
• /api/decision-logs - Decision documentation

---

Common Workflows

1. Create New Project with Context

# Create project
POST /api/projects
{
  "name": "New Website",
  "client_id": "client-uuid",
  "status": "planning"
}

# Initialize project state
POST /api/project-states
{
  "project_id": "project-uuid",
  "current_phase": "requirements",
  "progress_percentage": 10,
  "next_actions": ["Gather requirements", "Design mockups"]
}

2. Log Important Decision

POST /api/decision-logs
{
  "project_id": "project-uuid",
  "decision_type": "technical",
  "decision_text": "Using FastAPI for API layer",
  "rationale": "Async support, automatic OpenAPI docs, modern Python",
  "alternatives_considered": ["Flask", "Django"],
  "impact": "high",
  "tags": ["api", "framework", "python"]
}

3. Track Work Session

# Create session
POST /api/sessions
{
  "project_id": "project-uuid",
  "machine_id": "machine-uuid",
  "started_at": "2026-01-16T10:00:00Z"
}

# Log billable time
POST /api/billable-time
{
  "session_id": "session-uuid",
  "work_item_id": "work-item-uuid",
  "client_id": "client-uuid",
  "start_time": "2026-01-16T10:00:00Z",
  "end_time": "2026-01-16T12:00:00Z",
  "duration_hours": 2.0,
  "hourly_rate": 150.00,
  "total_amount": 300.00
}

4. Store Encrypted Credential

POST /api/credentials
{
  "credential_type": "api_key",
  "service_name": "OpenAI API",
  "username": "api_key",
  "password": "sk-1234567890",  # Auto-encrypted
  "client_id": "client-uuid",
  "notes": "Production API key"
}
# Password automatically encrypted with AES-256-GCM
# Audit log automatically created

---

Important Files

Session State: SESSION_STATE.md - Complete project history and status Documentation:

• .claude/CONTEXT_RECALL_QUICK_START.md - Context recall usage
• CONTEXT_RECALL_SETUP.md - Full setup guide
• TEST_PHASE5_RESULTS.md - Phase 5 test results
• TEST_CONTEXT_RECALL_RESULTS.md - Context recall test results

Configuration:

• .env - Environment variables (gitignored)
• .env.example - Template with placeholders
• .claude/context-recall-config.env - Context recall settings (gitignored)

Tests:

• test_api_endpoints.py - Phase 4 tests (34/35 passing)
• test_phase5_api_endpoints.py - Phase 5 tests (62/62 passing)
• test_context_recall_system.py - Context recall tests (53 total)
• test_context_compression_quick.py - Compression tests (10/10 passing)

---

Recent Work (from SESSION_STATE.md)

Last Session: 2026-01-16 Phases Completed: 0-6 (95% complete)

Phase 6 - Just Completed:

• Context Recall System with cross-machine memory
• 35 new endpoints for context management
• 90-95% token reduction via compression
• Automatic hooks for inject/save
• One-command setup script

Current State:

• 130 endpoints operational
• 99.1% test pass rate (106/107 tests)
• All migrations applied (43 tables)
• Context recall ready for activation

---

Token Optimization

Context Compression:

• compress_conversation_summary() - 85-90% reduction
• format_for_injection() - Token-efficient markdown
• extract_key_decisions() - Decision extraction
• Auto-tag extraction (30+ tech tags)

Typical Compression:

Original: 500 tokens (verbose conversation)
Compressed: 60 tokens (structured JSON)
Reduction: 88%

---

Security

Authentication: JWT tokens (Argon2 password hashing) Encryption: AES-256-GCM (Fernet) for credentials Audit Logging: All credential operations logged Token Storage: .claude/context-recall-config.env (gitignored)

Get JWT Token:

# Via setup script (recommended)
bash scripts/setup-context-recall.sh

# Or manually via API
POST /api/auth/token
{
  "email": "user@example.com",
  "password": "your-password"
}

---

Troubleshooting

API won't start:

# Check if port 8000 is in use
netstat -ano | findstr :8000

# Check database connection
python test_db_connection.py

Context recall not working:

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

# Check configuration
cat .claude/context-recall-config.env

# Verify hooks are executable
ls -l .claude/hooks/

Database migration issues:

# Check current revision
alembic current

# Show migration history
alembic history

# Upgrade to latest
alembic upgrade head

---

Next Steps (Optional Phase 7)

Remaining entities (from original spec):

• File Changes API - Track file modifications
• Command Runs API - Command execution history
• Problem Solutions API - Knowledge base
• Failure Patterns API - Error pattern recognition
• Environmental Insights API - Contextual learning

These are optional - the system is fully functional without them.

---

Coding Guidelines

IMPORTANT: Follow coding standards in .claude/CODING_GUIDELINES.md

Key Rules:

• NO EMOJIS - EVER (causes encoding/parsing issues)
• Use ASCII text markers: [OK], [ERROR], [WARNING], [SUCCESS]
• Follow PEP 8 for Python, PSScriptAnalyzer for PowerShell
• No hardcoded credentials
• All endpoints must have docstrings

---

Quick Reference

Start API: uvicorn api.main:app --reload API Docs: http://localhost:8000/api/docs (local) or http://172.16.3.30:8001/api/docs (RMM) Setup Context Recall: bash scripts/setup-context-recall.sh Test System: bash scripts/test-context-recall.sh Database: 172.16.3.30:3306/claudetools (RMM Server) Virtual Env: api\venv\Scripts\activate Coding Guidelines: .claude/CODING_GUIDELINES.md

---

Last Updated: 2026-01-17 (Database migrated to RMM server) Project Progress: 95% Complete (Phase 6 of 7 done)