# ClaudeTools Scripts

Utility scripts for managing the ClaudeTools system.

---

## Core Scripts

### Context Recall System

**`setup-context-recall.sh`**
- One-time setup for context recall system
- Configures JWT authentication
- Tests API connectivity

**`test-context-recall.sh`**
- Verify context recall system functionality
- Test API endpoints
- Check compression

### Conversation Import & Archive

**`import-conversations.py`**
- Import conversation JSONL files to database
- Extract and compress conversation context
- Tag extraction and categorization
- Optional tombstone creation with `--create-tombstones`

**`archive-imported-conversations.py`**
- Archive imported conversation files
- Create tombstone markers
- Move files to archived/ subdirectories
- Database verification (optional)

**`check-tombstones.py`**
- Verify tombstone integrity
- Validate JSON structure
- Check archived files exist
- Database context verification

**`TOMBSTONE_QUICK_START.md`**
- Quick reference for tombstone system
- Common commands
- Troubleshooting tips

### Database & Testing

**`test_db_connection.py`**
- Test database connectivity
- Verify credentials
- Check table access

**`test-server.sh`**
- Start development server
- Run basic API tests

### MCP Servers

**`setup-mcp-servers.sh`**
- Configure Model Context Protocol servers
- Setup GitHub, Filesystem, Sequential Thinking

---

## Tombstone System (NEW)

Archive imported conversation files with small marker files.

### Quick Start

```bash
# Archive all imported files
python scripts/archive-imported-conversations.py --skip-verification

# Verify tombstones
python scripts/check-tombstones.py

# Check space savings
du -sh imported-conversations/
```

### Documentation

- `TOMBSTONE_QUICK_START.md` - Quick reference
- `../TOMBSTONE_SYSTEM.md` - Complete documentation
- `../TOMBSTONE_IMPLEMENTATION_SUMMARY.md` - Implementation details

### Expected Results

- 549 tombstone files (~1 MB)
- 549 archived files in subdirectories
- 99%+ space reduction in active directory

---

## Usage Patterns

### Initial Setup

```bash
# 1. Setup context recall
bash scripts/setup-context-recall.sh

# 2. Setup MCP servers (optional)
bash scripts/setup-mcp-servers.sh

# 3. Test database connection
python scripts/test_db_connection.py
```

### Import Conversations

```bash
# Import with automatic tombstones
python scripts/import-conversations.py --create-tombstones

# Or import first, archive later
python scripts/import-conversations.py
python scripts/archive-imported-conversations.py --skip-verification
```

### Verify System

```bash
# Test context recall
bash scripts/test-context-recall.sh

# Check tombstones
python scripts/check-tombstones.py

# Test API
bash scripts/test-server.sh
```

---

## Script Categories

### Setup & Configuration
- `setup-context-recall.sh`
- `setup-mcp-servers.sh`

### Import & Archive
- `import-conversations.py`
- `archive-imported-conversations.py`
- `check-tombstones.py`

### Testing & Verification
- `test_db_connection.py`
- `test-context-recall.sh`
- `test-server.sh`
- `test-tombstone-system.sh`

### Utilities
- Various helper scripts

---

## Common Commands

```bash
# Start API server
uvicorn api.main:app --reload

# Import conversations
python scripts/import-conversations.py

# Archive files
python scripts/archive-imported-conversations.py --skip-verification

# Check system health
python scripts/check-tombstones.py
bash scripts/test-context-recall.sh

# Database connection test
python scripts/test_db_connection.py
```

---

## Requirements

Most scripts require:
- Python 3.8+
- Virtual environment activated (`api\venv\Scripts\activate`)
- `.env` file configured (see `.env.example`)
- Database access (172.16.3.30:3306)

---

## Environment Variables

Scripts use these from `.env`:

```bash
DATABASE_URL=mysql+pymysql://user:pass@172.16.3.30:3306/claudetools
JWT_TOKEN=your-jwt-token-here
API_USER_EMAIL=user@example.com
API_USER_PASSWORD=your-password
```

---

## Documentation

- `TOMBSTONE_QUICK_START.md` - Tombstone system quick start
- `../TOMBSTONE_SYSTEM.md` - Complete tombstone documentation
- `../.claude/CONTEXT_RECALL_QUICK_START.md` - Context recall guide
- `../CONTEXT_RECALL_SETUP.md` - Full setup instructions

---

**Last Updated:** 2026-01-18
**Version:** 1.0