npm package: @majkapp/majk-chat-sessions
Description: Session management for Magic Chat conversations
Author: Jules White
Latest version: 1.0.32

# 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

```typescript
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

```typescript
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:

```typescript
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

```typescript
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