--- 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 Restore checkpoint /checkpoint delete 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 ```typescript 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 ```typescript 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 ```typescript // 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 ```typescript // 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 ```typescript // Clear conversation but keep session await sessions.clearHistory(session.id); ``` ### Reset Session ```typescript // Full reset (new session) await sessions.reset({ userId: 'user-123', channelId: 'telegram-456', }); ``` ### Checkpoints ```typescript // 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 ```typescript // 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 ```typescript // 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 ```typescript // 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 --- Source attribution: alsk1992 Original project: https://github.com/alsk1992/CloddsBot/blob/c930628c47a4a745f497e29035a3b64622f97cc7/src/skills/bundled/sessions/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2026 alsk1992 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: alsk1992 Original project: https://github.com/alsk1992/CloddsBot/blob/c930628c47a4a745f497e29035a3b64622f97cc7/src/skills/bundled/sessions/SKILL.md Attribution basis: Source repository record Fields of work: Sales, Customer Support Roles: Customer Success Manager, Support Agent, Technical Support Specialties: API, Database Tools: SQLite Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 0886721b6bb343b74f28797f891354a97b62f2f91dbc1152ccbb7297a08ecfc5