@ebowwa/state

State management library with SQLite persistence. Core library for MCP servers and other consumers.

Features

• Repository pattern with SQLite backend
• Token-aware response limiting for MCP protocol compliance
• Session-scoped isolation - state items belong to sessions
• Privacy flags for cross-session data
• Proper dependency injection - no global mutable state

Installation

npm install @ebowwa/state
# or
bun add @ebowwa/state

Usage

import {
  StateService,
  SessionRepository,
  StateRepository,
  createLogger,
} from '@ebowwa/state';

// Initialize
const logger = createLogger();
const sessionRepo = new SessionRepository({ filename: './state.db' });
const stateRepo = new StateRepository({ filename: './state.db' });
const stateService = new StateService(stateRepo, sessionRepo, logger);

await stateService.initialize();

// Get current session
const session = await stateService.getCurrentSession();

// Save state
const context = { sessionId: session.id, tokenConfig: {} };
await stateService.save({
  key: 'my-key',
  value: 'my-value',
  category: 'config',
  priority: 'high',
}, context);

// Get state
const item = await stateService.get('my-key', context);

// Query state
const result = await stateService.query({
  category: 'config',
  limit: 100,
}, context);

API

Repositories

• SessionRepository - Manages session persistence
• StateRepository - Manages state item persistence

Services

• StateService - Business logic for state operations

Types

• Session - Logical grouping of state items
• StateItem - Individual piece of stored state
• QueryOptions - Query filters and pagination
• SearchOptions - Full-text search options

License

MIT