# 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 // Save conversation async saveConversation(session: Session, messages: ChatMessage[]): Promise // Load conversation async loadConversation(sessionId: string): Promise // Get last conversation async getLastConversation(): Promise // List recent conversations async getRecentConversations(limit: number = 10): Promise // Search conversations async searchConversations(query: string, limit: number = 10): Promise // Delete conversation async deleteConversation(sessionId: string): Promise // Get statistics async getStatistics(): Promise // Cleanup old conversations async cleanupOldConversations(maxAge: number = 30): Promise // Export conversations async exportConversations(outputPath: string): Promise } ``` ### SessionManager Extensions ```typescript class SessionManager { // Continue from last conversation async continueLastConversation(): Promise // Continue from specific session async continueFromSession(sessionId: string): Promise // Save to history async saveToHistory(): Promise // Search history async searchHistory(query: string, limit: number = 10): Promise // Get statistics async getHistoryStatistics(): Promise // Delete from history async deleteFromHistory(sessionId: string): Promise } ``` ### 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