Magic Chat Sessions

Session management for Magic Chat conversations. This package provides persistent conversation storage and retrieval capabilities.

Features

• Persistent Sessions: Store complete conversation histories with metadata
• Working Directory Organization: Sessions are organized by the working directory where they were created
• Automatic Cleanup: Configurable session cleanup based on age and count limits
• UUID-based Session IDs: Each session has a unique identifier for easy reference
• Flexible Storage: Pluggable storage interface with filesystem implementation

Usage

Basic Session Management

import { SessionManager } from '@majkapp/majk-chat-sessions';

const sessionManager = new SessionManager();

// Create a new session
const sessionId = await sessionManager.createSession('/path/to/project', {
  title: 'My Chat Session',
  provider: 'openai',
  model: 'gpt-4',
  initialMessages: []
});

// Add messages to the session
await sessionManager.addMessage({
  role: 'user',
  content: 'Hello, how are you?'
});

// Continue the most recent session in a directory
const sessionData = await sessionManager.continueLatestSession('/path/to/project');

// Load a specific session
const sessionData = await sessionManager.loadSession(sessionId, '/path/to/project');

// List all sessions in a directory
const sessions = await sessionManager.listSessions('/path/to/project');

CLI Integration

The sessions package is integrated into the Magic Chat CLI with the following flags:

• --continue: Continue the most recent session in the current directory
• --session <uuid>: Continue a specific session by UUID
• --session-title <title>: Set a title for new sessions
• --list-sessions: List all sessions in the current directory
• --delete-session <uuid>: Delete a specific session

Directory Organization

Sessions are stored in ~/.majk/chat-sessions/ organized by sanitized working directory names:

~/.majk/chat-sessions/
├── home_user_projects_myapp/
│   ├── 550e8400-e29b-41d4-a716-446655440000.json
│   └── 6ba7b810-9dad-11d1-80b4-00c04fd430c8.json
└── home_user_documents/
    └── f47ac10b-58cc-4372-a567-0e02b2c3d479.json

Configuration

import { SessionManager, FileSystemSessionStorage } from '@majkapp/majk-chat-sessions';

const sessionManager = new SessionManager({
  baseDirectory: '/custom/sessions/path',  // Default: ~/.majk/chat-sessions
  maxSessions: 500,                        // Default: 1000
  autoCleanup: true,                       // Default: true
  cleanupAfterDays: 30                     // Default: 90
});

Custom Storage

You can implement custom storage backends by implementing the SessionStorage interface:

import { SessionStorage, SessionData, SessionListItem } from '@majkapp/majk-chat-sessions';

class CustomStorage implements SessionStorage {
  async save(sessionData: SessionData): Promise<void> {
    // Your implementation
  }
  
  async load(sessionId: string, workingDirectory: string): Promise<SessionData | null> {
    // Your implementation
  }
  
  // ... implement other methods
}

const sessionManager = new SessionManager({
  storage: new CustomStorage()
});

Session Data Structure

interface SessionData {
  metadata: {
    id: string;
    workingDirectory: string;
    createdAt: Date;
    updatedAt: Date;
    title?: string;
    provider?: string;
    model?: string;
    totalMessages: number;
  };
  messages: Message[];  // Array of chat messages
  context?: Record<string, any>;  // Additional context data
}

License

MIT