Conversations and Storage

Kollab CLI automatically persists every conversation with intelligent logging, session management, and resume capabilities. All data is stored in a centralized project-aware directory structure.

Overview

The conversation storage system provides:

Automatic conversation logging - every message saved in JSONL format
Project-specific isolation - conversations organized by working directory
Multiple export formats - transcript, markdown, JSONL, clipboard support
Intelligence features - pattern learning, conversation memory, context awareness

Directory Structure

All conversation data is centralized under ~/.kollabor-cli/projects/ using project-aware path encoding:

~/.kollabor-cli/
  projects/
    Users_dev_myproject/              # Encoded project path
      conversations/
        2601071530-crimson-wave.jsonl # Session file (YYMMDDHHMM-name)
        2601071615-jade-echo.jsonl
        memory/                       # Intelligence cache
          user_patterns.json          # Learned user patterns
          project_context.json        # Project awareness data
          solution_history.json       # Solution patterns
        raw/                          # Raw API logs
          req_1736275830.json         # Raw request
          resp_1736275831.json        # Raw response
        snapshots/                    # Conversation snapshots
      logs/
        kollabor.log                  # Daily application logs

Path encoding example: /Users/dev/myproject becomes Users_dev_myproject

JSONL Conversation Format

Each conversation is logged as JSON Lines (one JSON object per line) with structured metadata:

// First line: conversation metadata
{
  "type": "conversation_metadata",
  "sessionId": "2601071530-crimson-wave",
  "startTime": "2026-01-07T15:30:00Z",
  "cwd": "/Users/dev/myproject",
  "gitBranch": "main",
  "version": "0.1.0",
  "provider": "anthropic"
}

// User messages with intelligence context
{
  "type": "user",
  "uuid": "a1b2c3d4-...",
  "timestamp": "2026-01-07T15:30:15Z",
  "message": {"role": "user", "content": "Fix the login bug"},
  "kollabor_intelligence": {
    "user_context": {
      "detected_intent": "debugging",
      "has_code": false
    },
    "session_context": {
      "conversation_phase": "initiation",
      "message_count": 1
    }
  }
}

// Assistant responses with usage stats
{
  "type": "assistant",
  "uuid": "e5f6g7h8-...",
  "timestamp": "2026-01-07T15:30:20Z",
  "message": {
    "role": "assistant",
    "model": "claude-sonnet-4-5",
    "content": [{"type": "text", "text": "I'll help..."}],
    "usage": {
      "input_tokens": 150,
      "output_tokens": 300
    }
  }
}

Key features of the JSONL format:

Each line is valid JSON (easy parsing, streaming-friendly)
UUID-based message threading with parentUuid field
Git branch and working directory tracking
Token usage statistics per response
Intelligence metadata for pattern learning

The /save Command

Export conversations in multiple formats with flexible destination options:

# Save formats
/save transcript          # Plain text transcript (default)
/save markdown           # Markdown with metadata
/save jsonl              # JSON Lines format
/save raw                # Exact API payload

# Destinations
/save file               # Save to ~/.kollabor-cli/.../transcripts/
/save clipboard          # Copy to system clipboard
/save both               # File + clipboard
/save local              # Save to current directory

# Combined examples
/save markdown clipboard # Markdown to clipboard
/save jsonl local        # JSONL to current dir
/save both               # Transcript to file + clipboard

Format	Description	Extension
`transcript`	Plain text with role markers (--- user ---, --- llm ---)	.txt
`markdown`	Formatted markdown with timestamps and metadata	.md
`jsonl`	JSON Lines format (one message per line)	.jsonl
`raw`	Exact API payload (for debugging/replay)	.json

Resume Conversations

Resume previous conversations with an interactive menu:

/resume                  # Show interactive menu
/resume search bug       # Search conversations
/resume --today          # Today's conversations only
/resume --limit 10       # Show last 10 sessions

The interactive menu displays:

Session names (e.g., "2601071530-crimson-wave")
Message counts and timestamps
First message preview
Working directory and git branch
Conversation topics/themes

Navigation: ↑↓ navigate, Enter select, / search, ESC cancel

Intelligence and Memory

Kollab CLI learns from conversations to improve over time:

User Patterns

Learns preferences from your messages:

- prefers_direct_commands
- provides_detailed_context
- shares_code_frequently
- asks_clarifying_questions

Project Context

Tracks project awareness:

- File mentions and frequency
- Technologies discussed
- Recent changes
- Coding standards

Solution History

Records successful solution patterns (last 100 solutions) including:

- uses_terminal_commands
- provides_code_examples
- explains_reasoning
- uses_mcp_tools

Memory files are stored in ~/.kollabor-cli/projects/<project>/conversations/memory/

Raw API Logs

Every API interaction is logged for debugging and analysis:

~/.kollabor-cli/projects/<project>/conversations/raw/
  req_1736275830.json     # Request payload
  resp_1736275831.json    # Response payload

# View raw logs
cat ~/.kollabor-cli/projects/*/conversations/raw/*.json | jq .

Raw logs contain:

Complete request payload (model, messages, temperature, tools)
Full response including thinking content (extended thinking models)
Token usage and timing information
Stop reason and completion metadata

Session Naming

Conversations use memorable session names with timestamp prefixes:

# Format: YYMMDDHHMM-adjective-noun
2601071530-crimson-wave.jsonl
2601071615-jade-echo.jsonl
2601080930-silver-frost.jsonl

# YYMMDDHHMM = Year(26) Month(01) Day(07) Hour(15) Minute(30)
# Followed by randomly generated memorable name

Session names are:

Sortable by timestamp (newest first)
Human-readable and memorable
Globally unique (timestamp + random name)

Application Logging

Application logs use daily rotation:

~/.kollabor-cli/projects/<project>/logs/
  kollabor.log            # Current day's logs
  kollabor.log.2026-01-06 # Previous day (auto-rotated)
  kollabor.log.2026-01-05

# View logs
tail -f ~/.kollabor-cli/projects/*/logs/kollabor.log

Logs include:

Plugin lifecycle events
Hook execution traces
API communication status
Error messages and stack traces

Pipe Mode and Scripting

Conversations work in pipe mode for non-interactive usage:

# Single query
kollab "fix the bug in auth.py"

# Pipe mode
echo "explain this code" | kollab -p

# With timeout
kollab --timeout 5min "implement the login feature"

# Scripting example
cat task.txt | kollab -p > result.txt

Pipe mode features:

Still logs conversations automatically
Suppresses interactive UI elements
Returns result to stdout
Full plugin support via app.pipe_mode flag

Configuration

Customize conversation storage via config.json:

{
  "plugins": {
    "save_conversation": {
      "enabled": true,
      "default_format": "transcript",
      "default_destination": "file",
      "auto_timestamp": true,
      "output_directory": "logs/transcripts"
    }
  },
  "core": {
    "conversation_logger": {
      "enable_intelligence": true,
      "max_solution_history": 100
    }
  }
}