/sessions

name: sessions
description: "Session management, conversation history, and checkpoints"
emoji: "💬"

Sessions - Complete API Reference

Manage conversation sessions, history, checkpoints, and resets across channels.

---

Chat Commands

Session Control

/new                                        Start new conversation
/reset                                      Reset current session
/session                                    View session info
/session list                               List active sessions

Checkpoints

/checkpoint save "before refactor"          Save checkpoint
/checkpoint list                            List checkpoints
/checkpoint restore <id>                    Restore checkpoint
/checkpoint delete <id>                     Delete checkpoint

History

/history                                    View conversation history
/history export                             Export as markdown
/history clear                              Clear history (keeps session)

Settings

/session scope main                         Use main session
/session scope channel                      Per-channel sessions
/session scope peer                         Per-user sessions
/session reset-time 00:00                   Set daily reset time
/session idle-reset 30                      Reset after 30 min idle

---

TypeScript API Reference

Create Session Manager

import { createSessionManager } from 'clodds/sessions';

const sessions = createSessionManager({
  // Session scope
  scope: 'per-channel-peer',  // 'main' | 'per-peer' | 'per-channel-peer'

  // Auto-reset
  dailyResetHour: 0,  // Reset at midnight
  idleResetMinutes: 30,  // Reset after 30 min idle

  // Storage
  storage: 'sqlite',
  dbPath: './sessions.db',

  // Encryption
  encryptTranscripts: true,
  encryptionKey: process.env.SESSION_KEY,
});

Get or Create Session

const session = await sessions.getOrCreateSession({
  userId: 'user-123',
  channelId: 'telegram-456',
  peerId: 'peer-789',
});

console.log(`Session ID: ${session.id}`);
console.log(`Created: ${session.createdAt}`);
console.log(`Messages: ${session.messageCount}`);
console.log(`Last activity: ${session.lastActivityAt}`);

Add Message to History

// Add user message
await sessions.addMessage({
  sessionId: session.id,
  role: 'user',
  content: 'What is my portfolio value?',
});

// Add assistant message
await sessions.addMessage({
  sessionId: session.id,
  role: 'assistant',
  content: 'Your portfolio is worth $10,234.56',
  usage: {
    inputTokens: 500,
    outputTokens: 200,
  },
});

Get History

// Get conversation history
const history = await sessions.getHistory(session.id, {
  limit: 50,
  format: 'messages',  // 'messages' | 'markdown' | 'text'
});

for (const msg of history) {
  console.log(`[${msg.role}] ${msg.content}`);
}

Clear History

// Clear conversation but keep session
await sessions.clearHistory(session.id);

Reset Session

// Full reset (new session)
await sessions.reset({
  userId: 'user-123',
  channelId: 'telegram-456',
});

Checkpoints

// Save checkpoint
const checkpoint = await sessions.saveCheckpoint({
  sessionId: session.id,
  name: 'Before major change',
  description: 'Saving state before refactoring trading strategy',
});

console.log(`Checkpoint ID: ${checkpoint.id}`);
console.log(`Messages saved: ${checkpoint.messageCount}`);

// List checkpoints
const checkpoints = await sessions.listCheckpoints(session.id);

for (const cp of checkpoints) {
  console.log(`${cp.id}: ${cp.name} (${cp.messageCount} messages)`);
}

// Restore checkpoint
await sessions.restoreCheckpoint(checkpoint.id);

// Delete checkpoint
await sessions.deleteCheckpoint(checkpoint.id);

Export Session

// Export as markdown
const markdown = await sessions.export(session.id, {
  format: 'markdown',
  includeMetadata: true,
});

// Export as JSON
const json = await sessions.export(session.id, {
  format: 'json',
});

Session Cleanup

// Delete old sessions
await sessions.cleanup({
  olderThan: '30d',  // Delete sessions older than 30 days
  keepCheckpoints: true,
});

---

Session Scopes

| Scope | Description | Use Case | |-------|-------------|----------| | `main` | Single global session | Personal use | | `per-peer` | Session per user | Multi-user, shared channels | | `per-channel-peer` | Session per user per channel | Full isolation |

---

Auto-Reset Behavior

| Trigger | Behavior | |---------|----------| | **Daily reset** | New session at configured hour | | **Idle reset** | New session after inactivity | | **Manual reset** | User runs `/new` or `/reset` |

---

Encryption

When `encryptTranscripts: true`:

• All messages encrypted with AES-256-GCM
• Per-session encryption keys
• Secure key derivation from master key

---

Context Window Management

// Get context-aware history (for LLM)
const context = await sessions.getContextHistory({
  sessionId: session.id,
  maxTokens: 100000,  // Fit in context window
  strategy: 'smart',  // 'recent' | 'smart' | 'summarize'
});

// 'smart' keeps system messages + recent + important messages
// 'summarize' compresses old messages into summaries

---

Best Practices

1. **Choose appropriate scope** — Per-channel-peer for multi-user 2. **Use checkpoints** — Before major changes or experiments 3. **Export regularly** — Keep backups of important conversations 4. **Set idle reset** — Prevents stale context 5. **Enable encryption** — For sensitive conversations