@webdevtoday/grok-cli/docs/history-system.md

A sophisticated CLI tool for interacting with xAI Grok 4, featuring conversation history, file reference, custom commands, memory system, and genetic development workflows

# Conversation History System

## Overview

The Grok CLI conversation history system provides persistent storage, search, and continuation of chat sessions. All conversations are automatically saved and can be resumed at any time.

## Architecture

### Components

1. **HistoryManager** (`src/core/history.ts`)
   - Manages conversation persistence
   - Handles indexing and search
   - Provides cleanup and export functionality

2. **SessionManager Integration** (`src/core/session.ts`)
   - Enhanced with history awareness
   - Automatic saving after each message
   - Session continuation support

3. **CLI Integration** (`src/cli.ts`)
   - Command-line flags for continuation
   - Slash commands for history management
   - Interactive history browsing

### Storage Structure

```
~/.grok-cli/history/
├── conversations.json          # Index of all conversations
├── abc123def456.json          # Individual conversation file
├── def456ghi789.json          # Another conversation
└── ...
```

## Data Formats

### Conversation Index (`conversations.json`)

```json
{
  "lastUpdated": "2024-01-15T10:30:00Z",
  "conversations": [
    {
      "id": "abc123def456",
      "startTime": "2024-01-15T09:00:00Z",
      "lastUpdateTime": "2024-01-15T10:30:00Z",
      "cwd": "/Users/user/project",
      "messageCount": 15,
      "firstMessage": "Help me debug this Python script",
      "lastMessage": "Thanks! That fixed the issue.",
      "filePath": "/Users/user/.grok-cli/history/abc123def456.json"
    }
  ]
}
```

### Individual Conversation File

```json
{
  "session": {
    "id": "abc123def456",
    "cwd": "/Users/user/project",
    "startTime": "2024-01-15T09:00:00Z",
    "config": { /* GrokConfig */ },
    "transcriptPath": "/Users/user/.grok/sessions/abc123def456.jsonl"
  },
  "messages": [
    {
      "role": "user",
      "content": "Help me debug this Python script",
      "timestamp": "2024-01-15T09:00:00Z",
      "toolCalls": []
    },
    {
      "role": "assistant", 
      "content": "I'd be happy to help debug your Python script...",
      "timestamp": "2024-01-15T09:01:00Z",
      "toolCalls": [
        {
          "toolName": "Read",
          "params": { "file_path": "script.py" },
          "result": { "success": true, "output": "..." },
          "timestamp": "2024-01-15T09:01:30Z"
        }
      ]
    }
  ],
  "metadata": {
    "totalMessages": 15,
    "startTime": "2024-01-15T09:00:00Z",
    "lastUpdateTime": "2024-01-15T10:30:00Z",
    "cwd": "/Users/user/project"
  }
}
```

## Usage

### Command Line Flags

```bash
# Continue from last conversation
grok --continue

# Resume specific conversation
grok --resume abc123def456

# Start normally (no continuation)
grok
```

### Interactive Commands

```bash
# List recent conversations
/history list [limit]

# Search conversations by content
/history search "debugging python"

# Show usage statistics
/history stats

# Delete a conversation
/history delete abc123def456

# Continue from last conversation
/continue

# Continue from specific conversation  
/continue abc123def456

# Get help
/history help
```

## API Reference

### HistoryManager

```typescript
class HistoryManager {
  // Initialize history system
  async initialize(): Promise<void>

  // Save conversation
  async saveConversation(session: Session, messages: ChatMessage[]): Promise<void>

  // Load conversation
  async loadConversation(sessionId: string): Promise<HistorySession | null>

  // Get last conversation
  async getLastConversation(): Promise<ConversationHistory | null>

  // List recent conversations
  async getRecentConversations(limit: number = 10): Promise<ConversationHistory[]>

  // Search conversations
  async searchConversations(query: string, limit: number = 10): Promise<ConversationHistory[]>

  // Delete conversation
  async deleteConversation(sessionId: string): Promise<boolean>

  // Get statistics
  async getStatistics(): Promise<HistoryStatistics>

  // Cleanup old conversations
  async cleanupOldConversations(maxAge: number = 30): Promise<number>

  // Export conversations
  async exportConversations(outputPath: string): Promise<void>
}
```

### SessionManager Extensions

```typescript
class SessionManager {
  // Continue from last conversation
  async continueLastConversation(): Promise<Session | null>

  // Continue from specific session
  async continueFromSession(sessionId: string): Promise<Session | null>

  // Save to history
  async saveToHistory(): Promise<void>

  // Search history
  async searchHistory(query: string, limit: number = 10): Promise<ConversationHistory[]>

  // Get statistics
  async getHistoryStatistics(): Promise<HistoryStatistics>

  // Delete from history
  async deleteFromHistory(sessionId: string): Promise<boolean>
}
```

### Data Types

```typescript
interface ConversationHistory {
  id: string;
  startTime: Date;
  lastUpdateTime: Date;
  cwd: string;
  messageCount: number;
  firstMessage: string;
  lastMessage: string;
  filePath: string;
}

interface HistorySession {
  session: Session;
  messages: ChatMessage[];
  metadata: {
    totalMessages: number;
    startTime: Date;
    lastUpdateTime: Date;
    cwd: string;
  };
}

interface HistoryStatistics {
  totalConversations: number;
  totalMessages: number;
  oldestConversation: Date | null;
  newestConversation: Date | null;
  avgMessagesPerConversation: number;
}
```

## Implementation Details

### Automatic Saving

Conversations are automatically saved:
- After each message is added
- When session is created
- When session ends gracefully

### Session Continuation

When continuing a conversation:
1. Load previous session data
2. Create new session with copied history
3. Add system message indicating continuation
4. Preserve working directory context

### Search Implementation

Search functionality:
- Case-insensitive text matching
- Searches first and last messages
- Returns results sorted by relevance
- Configurable result limits

### Performance Considerations

- Lazy loading of conversation data
- Indexed metadata for fast searches
- Configurable cleanup of old conversations
- Efficient JSON storage format

## Configuration

### History Settings

```json
{
  "history": {
    "enabled": true,
    "maxConversations": 1000,
    "maxAge": 90,
    "autoCleanup": true,
    "searchLimit": 50
  }
}
```

### Storage Location

Default: `~/.grok-cli/history/`

Override with environment variable:
```bash
export GROK_HISTORY_DIR="/custom/path"
```

## Maintenance

### Cleanup Old Conversations

```typescript
// Delete conversations older than 30 days
const deleted = await historyManager.cleanupOldConversations(30);
```

### Export Conversations

```typescript
// Export all conversations to JSON
await historyManager.exportConversations('./backup.json');
```

### Repair Index

If the conversation index becomes corrupted:

```bash
# Manual repair (scan directory and rebuild index)
node -e "
const { HistoryManager } = require('./dist/core/history');
const hm = new HistoryManager();
await hm.rebuildIndex();
"
```

## Privacy and Security

### Data Privacy

- All data stored locally
- No cloud synchronization by default
- User controls retention policies
- Configurable cleanup schedules

### Security Considerations

- File permissions restricted to user
- No sensitive data logging by default
- API keys stored separately from history
- Conversation data not transmitted externally

## Troubleshooting

### Common Issues

**History not saving**
- Check write permissions on `~/.grok-cli/`
- Verify disk space availability
- Check for file system errors

**Search not working**
- Rebuild conversation index
- Check for corrupted JSON files
- Verify search query syntax

**Continuation failing**
- Verify session ID exists
- Check conversation file integrity
- Review error logs

### Debug Commands

```bash
# Check history status
/history stats

# Verify specific conversation
/history list 1

# Test continuation
/continue --dry-run
```

## Future Enhancements

### Planned Features

- Cloud synchronization options
- Conversation sharing and export
- Advanced search with filters
- Conversation branching and merging
- Automated conversation summarization
- Integration with external note systems

### Performance Improvements

- Database backend option
- Full-text search indexing
- Conversation compression
- Streaming conversation loading