Conversation Management

Conversation Management

This manual explains how to create, view, and search conversation sessions, and how to integrate with external services.

---

1. Session Management

Session Structure

Each conversation session is automatically saved as a JSON file in the ~/casabot/history/ directory.

{
  "id": "unique session ID",
  "startedAt": "2024-01-15T09:30:00.000Z",
  "messages": [
    {
      "role": "user | assistant | system | tool",
      "content": "message content",
      "toolCalls": [],
      "toolCallId": ""
    }
  ]
}

Session Lifecycle

• Creation: A new session is automatically created when you run the casabot command.
• Persistence: Messages are automatically appended as the conversation progresses.
• Termination: The session closes when the program exits.
• Preservation: Logs are permanently preserved in the history directory after termination.

2. Loading Conversations

View recent conversation list

# Recent 20 conversations (newest first)
ls -lt ~/casabot/history/ | head -20

# Check filenames and sizes
ls -lhS ~/casabot/history/

View specific conversation

# View full conversation (formatted)
cat ~/casabot/history/<conversation-id>.json | jq '.messages[] | {role, content: .content[:100]}'

# View only user messages
cat ~/casabot/history/<conversation-id>.json | jq '.messages[] | select(.role == "user") | .content'

# View only assistant responses
cat ~/casabot/history/<conversation-id>.json | jq '.messages[] | select(.role == "assistant") | .content'

Check session metadata

# Session ID and start time
cat ~/casabot/history/<conversation-id>.json | jq '{id, startedAt, messageCount: (.messages | length)}'

3. Searching Previous Conversations

Search by keyword

# Search all conversations for a keyword
grep -rl "keyword" ~/casabot/history/

# View context of conversations containing the keyword
grep -l "keyword" ~/casabot/history/*.json | while read f; do
  echo "=== $(basename $f) ==="
  cat "$f" | jq '.messages[] | select(.content | contains("keyword")) | {role, content: .content[:200]}'
done