API Reference

cc-sessions can be used programmatically in your Node.js applications.

Installation

npm install @iam-dev/cc-sessions

Quick Start

import {
  SessionStore,
  loadConfig,
  parseLogFile
} from '@iam-dev/cc-sessions';

// Load configuration
const config = await loadConfig();

// Access session store
const store = new SessionStore();

// Get last session for a project
const lastSession = store.getLastForProject('/path/to/project');

// Search sessions
const results = store.search('authentication');

// Clean up
store.close();

Core Classes

SessionStore

SQLite-based storage for session memories.

import { SessionStore } from '@iam-dev/cc-sessions';

const store = new SessionStore();
// or with custom path
const store = new SessionStore('/custom/path/to/db.sqlite');

Methods

save(session: SessionMemory): void

Save a session to the database.

store.save({
  id: 'mem_abc123',
  claudeSessionId: 'session-456',
  projectPath: '/my/project',
  projectName: 'my-project',
  startedAt: new Date(),
  endedAt: new Date(),
  duration: 30,
  summary: 'Worked on feature X',
  description: 'Implemented new feature...',
  tasks: [],
  tasksCompleted: 0,
  tasksPending: 0,
  filesCreated: [],
  filesModified: ['src/index.ts'],
  filesDeleted: [],
  lastUserMessage: 'Thanks!',
  lastAssistantMessage: 'You\'re welcome!',
  nextSteps: [],
  keyDecisions: [],
  blockers: [],
  tokensUsed: 5000,
  messagesCount: 10,
  toolCallsCount: 5,
  tags: ['feature'],
  archived: false,
  logFile: '/path/to/log.jsonl'
});

getById(id: string): SessionMemory | null

Get a session by its ID.

const session = store.getById('mem_abc123');
if (session) {
  console.log(session.summary);
}

getLastForProject(projectPath: string): SessionMemory | null

Get the most recent session for a project.

const session = store.getLastForProject('/my/project');

getRecent(limit?: number, projectPath?: string): SessionMemory[]

Get recent sessions.

// Get last 10 sessions
const recent = store.getRecent(10);

// Get last 5 for specific project
const projectRecent = store.getRecent(5, '/my/project');

search(query: string, limit?: number): SearchResult[]

Full-text search across sessions.

const results = store.search('authentication', 20);

for (const result of results) {
  console.log(`${result.session.summary} (score: ${result.score})`);
  for (const match of result.matches) {
    console.log(`  ${match.field}: ${match.highlight}`);
  }
}

getUnsyncedSessions(): SessionMemory[]

Get sessions not yet synced to cloud.

const unsynced = store.getUnsyncedSessions();

markSynced(id: string): void

Mark a session as synced.

store.markSynced('mem_abc123');

archiveOld(olderThanDays: number): number

Archive sessions older than specified days.

const archived = store.archiveOld(365);
console.log(`Archived ${archived} sessions`);

getStats(): StorageStats

Get storage statistics.

const stats = store.getStats();
console.log(`Total: ${stats.totalSessions}`);
console.log(`Active: ${stats.activeSessions}`);
console.log(`Storage: ${stats.storageUsedBytes} bytes`);

close(): void

Close the database connection.

store.close();

---

CloudSync

Cloud storage sync with encryption.

import { CloudSync } from '@iam-dev/cc-sessions';

const cloudSync = new CloudSync({
  enabled: true,
  provider: 's3',
  bucket: 'my-bucket',
  accessKeyId: 'KEY',
  secretAccessKey: 'SECRET',
  region: 'us-east-1',
  encryptionKey: 'your-hex-key',
  syncIntervalMinutes: 30,
  syncOnSave: true,
  deviceId: 'auto'
});

Methods

testConnection(): Promise

Test connection to cloud storage.

const connected = await cloudSync.testConnection();

uploadSession(session: SessionMemory): Promise

Upload and encrypt a session.

await cloudSync.uploadSession(session);

downloadSession(info: RemoteSessionInfo): Promise

Download and decrypt a session.

const session = await cloudSync.downloadSession(info);

listRemoteSessions(): Promise<RemoteSessionInfo[]>

List all sessions in cloud storage.

const sessions = await cloudSync.listRemoteSessions();
for (const info of sessions) {
  console.log(`${info.sessionId} from ${info.deviceId}`);
}

sync(store: SessionStore): Promise

Perform full bidirectional sync.

const report = await cloudSync.sync(store);
console.log(`Uploaded: ${report.uploaded}`);
console.log(`Downloaded: ${report.downloaded}`);

getDeviceId(): string

Get the current device ID.

const deviceId = cloudSync.getDeviceId();

getKeyFingerprint(): string

Get encryption key fingerprint.

const fingerprint = cloudSync.getKeyFingerprint();

---

Encryptor

AES-256-GCM encryption utilities.

import { Encryptor } from '@iam-dev/cc-sessions';

// Auto-generate key
const encryptor = new Encryptor();

// Use existing key
const encryptor = new Encryptor('your-64-char-hex-key');

Methods

encrypt(data: string): Buffer

Encrypt a string.

const encrypted = encryptor.encrypt('secret data');

decrypt(data: Buffer): string

Decrypt data.

const decrypted = encryptor.decrypt(encrypted);

static generateKey(): string

Generate a new encryption key.

const key = Encryptor.generateKey();

getKeyHex(): string

Get the current key as hex string.

const keyHex = encryptor.getKeyHex();

getKeyFingerprint(): string

Get 8-character key fingerprint.

const fingerprint = encryptor.getKeyFingerprint();

---

RetentionManager

Manage session retention and cleanup.

import { RetentionManager, SessionStore } from '@iam-dev/cc-sessions';

const store = new SessionStore();
const retention = new RetentionManager(store, {
  fullSessions: '1y',
  archives: 'forever',
  searchIndex: 'forever',
  overrideClaudeRetention: true,
  maxStorageGb: 10
});

Methods

runCleanup(): Promise

Run retention cleanup.

const report = await retention.runCleanup();
console.log(`Archived: ${report.sessionsArchived}`);
console.log(`Deleted: ${report.sessionsDeleted}`);
console.log(`Freed: ${report.bytesFreed} bytes`);

parseDays(retention: string): number

Parse retention string to days.

retention.parseDays('1y');  // 365
retention.parseDays('30d'); // 30
retention.parseDays('forever'); // Infinity

---

Parser Functions

parseLogFile(path: string): ParsedSession

Parse a Claude Code JSONL log file.

import { parseLogFile } from '@iam-dev/cc-sessions';

const parsed = parseLogFile('/path/to/session.jsonl');

console.log(`Duration: ${parsed.duration} minutes`);
console.log(`Messages: ${parsed.messagesCount}`);
console.log(`Tokens: ${parsed.tokensUsed}`);
console.log(`Files modified: ${parsed.filesModified.join(', ')}`);

generateSummary(parsed: ParsedSession, config: SummaryConfig): Promise

Generate AI summary for a parsed session.

import { generateSummary } from '@iam-dev/cc-sessions';

const summary = await generateSummary(parsed, {
  model: 'haiku',
  maxLength: 500,
  include: ['description', 'tasks_completed', 'next_steps']
});

console.log(summary.summary);
console.log(summary.nextSteps);

---

Configuration Functions

loadConfig(): Promise

Load configuration from file.

import { loadConfig } from '@iam-dev/cc-sessions';

const config = await loadConfig();
console.log(`Retention: ${config.retention.fullSessions}`);

saveConfig(config: Config): Promise

Save configuration to file.

import { saveConfig, loadConfig } from '@iam-dev/cc-sessions';

const config = await loadConfig();
config.retention.fullSessions = '2y';
await saveConfig(config);

---

Types

SessionMemory

interface SessionMemory {
  id: string;
  claudeSessionId: string;
  projectPath: string;
  projectName: string;
  startedAt: Date;
  endedAt: Date;
  duration: number;
  summary: string;
  description: string;
  tasks: Task[];
  tasksCompleted: number;
  tasksPending: number;
  filesCreated: string[];
  filesModified: string[];
  filesDeleted: string[];
  lastUserMessage: string;
  lastAssistantMessage: string;
  nextSteps: string[];
  keyDecisions: string[];
  blockers: string[];
  tokensUsed: number;
  messagesCount: number;
  toolCallsCount: number;
  tags: string[];
  archived: boolean;
  archivedAt?: Date;
  synced?: boolean;
  syncedAt?: Date;
  logFile: string;
  logFileArchived?: string;
}

SearchResult

interface SearchResult {
  session: SessionMemory;
  score: number;
  matches: SearchMatch[];
}

interface SearchMatch {
  field: string;
  text: string;
  highlight: string;
}

SyncReport

interface SyncReport {
  uploaded: number;
  downloaded: number;
  conflicts: number;
}

StorageStats

interface StorageStats {
  totalSessions: number;
  activeSessions: number;
  archivedSessions: number;
  storageUsedBytes: number;
  oldestSession?: Date;
  newestSession?: Date;
}

---

Constants

import { VERSION, NAME, DEFAULT_CONFIG } from '@iam-dev/cc-sessions';

console.log(`${NAME} v${VERSION}`);
// cc-sessions v1.1.0