core

@cleocode/core

CLEO core business logic kernel - tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store.

Overview

This package contains the complete business logic implementation for the CLEO ecosystem. It provides programmatic APIs for:

• Task Management: CRUD operations, dependencies, archival
• Session Management: Start, resume, end sessions with context
• Memory Systems: Brain storage, search, observation
• Orchestration: Multi-agent coordination, wave execution
• Lifecycle Management: Pipeline stages, gates, compliance
• Compliance & Validation: Protocol enforcement, rule checking

The package includes a bundled SQLite store via Drizzle ORM for persistence.

Installation

npm install @cleocode/core

pnpm add @cleocode/core

yarn add @cleocode/core

API Overview

Import Patterns

// Pattern 1: Facade (recommended for most use cases)
import { Cleo } from '@cleocode/core';
const cleo = await Cleo.init('./project');

// Pattern 2: Namespace access
import { tasks, sessions, memory, orchestration } from '@cleocode/core';

// Pattern 3: Direct function imports (tree-shakeable)
import { addTask, startSession, observeBrain } from '@cleocode/core';

The Cleo Facade

The Cleo class provides a unified interface to all CLEO functionality:

import { Cleo } from '@cleocode/core';

// Initialize CLEO for a project
const cleo = await Cleo.init('./my-project', {
  configPath: './.cleo/config.yaml',
  logLevel: 'info'
});

// Task operations
await cleo.tasks.add({ title: 'New task', priority: 'high' });
const task = await cleo.tasks.show('T1234');
await cleo.tasks.complete('T1234');

// Session operations
const session = await cleo.sessions.start({ scope: 'feature-branch' });
await cleo.sessions.end(session.id);

// Memory operations
await cleo.memory.observe({ topic: 'architecture', content: '...' });
const entries = await cleo.memory.search('auth pattern');

// Cleanup
await cleo.destroy();

Namespaces

All functionality is organized into namespaces:

Namespace	Purpose
tasks	Task CRUD, dependencies, archival
sessions	Session lifecycle, context, checkpoints
memory	Brain storage, search, observation
orchestration	Multi-agent coordination, waves, consensus
lifecycle	Pipeline stages, gates, compliance
compliance	Protocol enforcement, validation rules
codebaseMap	Project structure analysis
phases	Phase management and transitions
release	Release management, versioning
research	Research workflows, web extraction
skills	Skill management and execution
sticky	Ephemeral notes and context
validation	Task validation and verification
nexus	Multi-project sync and sharing
adrs	Architecture Decision Records
admin	Administrative operations
caamp	Context-aware agent memory protocol
context	Context management and injection
inject	Context injection utilities
issue	Issue tracking integration
metrics	Performance metrics and analytics
migration	Database migrations
observability	Logging, monitoring, tracing
otel	OpenTelemetry integration
pipeline	Pipeline execution
reconciliation	Task sync and reconciliation
remote	Remote operations
roadmap	Roadmap planning
routing	Request routing
security	Security utilities
sequence	Task sequencing
signaldock	Signal handling
snapshot	Project snapshots
spawn	Subagent spawning
stats	Statistics and reporting
system	System operations
taskWork	Active task tracking
templates	Template management
ui	UI utilities

Task Operations

import { tasks, addTask, listTasks, completeTask, updateTask, deleteTask } from '@cleocode/core';

// Create a task
const task = await addTask({
  title: 'Implement user authentication',
  description: 'Add JWT-based auth',
  priority: 'high',
  type: 'feature',
  size: 'medium',
  labels: ['backend', 'security']
});

// List tasks
const allTasks = await listTasks({ status: ['pending', 'in_progress'] });

// Update a task
await updateTask('T1234', { priority: 'urgent', labels: ['backend', 'security', 'urgent'] });

// Complete a task
await completeTask('T1234', { notes: 'Implemented with bcrypt and JWT' });

// Delete a task
await deleteTask('T1234');

// Using namespace
await tasks.add({ title: 'Another task' });
await tasks.archive(['T1234', 'T1235']);

Session Operations

import { sessions, startSession, endSession, listSessions, resumeSession } from '@cleocode/core';

// Start a session
const session = await startSession({
  scope: 'feature/authentication',
  notes: 'Working on auth system'
});

// List active sessions
const activeSessions = await listSessions({ status: 'active' });

// Resume a session
await resumeSession(session.id);

// End a session
await endSession(session.id, { summary: 'Completed auth implementation' });

Memory Operations

import { memory, observeBrain, searchBrain, searchBrainCompact, timelineBrain, fetchBrainEntries } from '@cleocode/core';

// Observe (store) a memory
await observeBrain({
  topic: 'authentication-pattern',
  content: 'Using JWT with refresh tokens',
  tags: ['auth', 'pattern'],
  confidence: 0.95
});

// Search memories
const results = await searchBrain('authentication', { limit: 10 });

// Compact search (lightweight)
const compact = await searchBrainCompact('auth', { maxResults: 5 });

// Timeline view
const timeline = await timelineBrain({ from: '2026-01-01', to: '2026-03-01' });

// Fetch specific entries
const entries = await fetchBrainEntries(['entry-1', 'entry-2']);

Orchestration

import { orchestration } from '@cleocode/core';

// Analyze dependencies
const analysis = await orchestration.analyze({
  taskIds: ['T1234', 'T1235', 'T1236'],
  includeBlocked: true
});

// Execute in waves (parallel where possible)
const waves = await orchestration.waves({
  taskIds: ['T1234', 'T1235', 'T1236', 'T1237'],
  maxParallel: 3
});

// Bootstrap orchestration
await orchestration.bootstrap({
  projectPath: './my-project',
  config: { autoSpawn: true }
});

// Validate spawn context
const validation = await orchestration.validateSpawn({
  taskId: 'T1234',
  context: { memoryBudget: 100000 }
});

Compliance & Validation

import { compliance, validation } from '@cleocode/core';

// Check compliance
const report = await compliance.check({
  taskId: 'T1234',
  rules: ['has-description', 'has-acceptance-criteria']
});

// Validate task structure
const result = await validation.validateTask({
  taskId: 'T1234',
  schema: 'standard'
});

Configuration

import { loadConfig, getConfigValue, setConfigValue, getRawConfig } from '@cleocode/core';

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

// Get a config value
const logLevel = getConfigValue('logging.level');

// Set a config value
await setConfigValue('logging.level', 'debug');

Paths & Project Info

import { 
  getProjectRoot, 
  getCleoDir, 
  isProjectInitialized,
  getProjectInfo,
  resolveProjectPath
} from '@cleocode/core';

// Get project root
const root = getProjectRoot();

// Get .cleo directory
const cleoDir = getCleoDir();

// Check if initialized
if (isProjectInitialized()) {
  const info = await getProjectInfo();
  console.log(`Project: ${info.name}`);
}

Logging

import { getLogger, initLogger, closeLogger } from '@cleocode/core';

// Initialize logger
initLogger('./.cleo', {
  level: 'info',
  filePath: 'logs/cleo.log'
});

// Get logger instance
const logger = getLogger('my-module');
logger.info('Starting operation');
logger.debug({ taskId: 'T1234' }, 'Task details');

// Cleanup
closeLogger();

Hooks

import { hooks, HookRegistry } from '@cleocode/core';

// Register a hook
hooks.register('onTaskCreate', async (context) => {
  console.log(`Task created: ${context.taskId}`);
});

// Dispatch a hook
await hooks.dispatch('onTaskCreate', { taskId: 'T1234' });

Output Formatting

import { formatOutput, formatSuccess, formatError, pushWarning } from '@cleocode/core';

// Format successful response
const success = formatSuccess({ taskId: 'T1234', title: 'My Task' });

// Format error response
const error = formatError('E_TASK_NOT_FOUND', { taskId: 'T1234' });

// Add warning
pushWarning('Task is overdue');

Pagination

import { paginate, createPage } from '@cleocode/core';

// Paginate results
const page = paginate(allTasks, { page: 1, limit: 20 });

// Create a page object
const pageObj = createPage({
  items: tasks,
  total: 100,
  page: 1,
  limit: 20
});

Error Handling

import { CleoError, getErrorDefinition, ERROR_CATALOG } from '@cleocode/core';

// Throw CLEO error
throw new CleoError('E_TASK_NOT_FOUND', { taskId: 'T1234' });

// Get error definition
const def = getErrorDefinition('E_TASK_NOT_FOUND');
console.log(def.message); // "Task not found"

Platform Utilities

import { 
  getSystemInfo, 
  detectPlatform, 
  getIsoTimestamp,
  sha256,
  PLATFORM
} from '@cleocode/core';

// Get system information
const info = getSystemInfo();
console.log(info.platform, info.arch, info.nodeVersion);

// Current platform
const platform = detectPlatform();

// ISO timestamp
const timestamp = getIsoTimestamp();

// Hash
const hash = sha256('content to hash');

Migration

import { 
  runMigration, 
  runAllMigrations, 
  getMigrationStatus,
  compareSemver,
  detectVersion
} from '@cleocode/core';

// Run a specific migration
await runMigration('v2.0.0');

// Run all pending migrations
await runAllMigrations();

// Check migration status
const status = await getMigrationStatus();

Store / Data Accessor

import { createDataAccessor, getAccessor } from '@cleocode/core';

// Create data accessor for a project
const accessor = createDataAccessor('./my-project');

// Get global accessor
const globalAccessor = getAccessor();

// Use accessor
const tasks = await accessor.queryTasks({ status: ['pending'] });
await accessor.updateTask('T1234', { status: 'completed' });

Usage Examples

Complete Workflow Example

import { Cleo } from '@cleocode/core';

async function main() {
  // Initialize CLEO
  const cleo = await Cleo.init('./my-project');
  
  try {
    // Create tasks for a feature
    const epic = await cleo.tasks.add({
      title: 'User Authentication System',
      type: 'epic',
      priority: 'high'
    });
    
    const task1 = await cleo.tasks.add({
      title: 'Implement login endpoint',
      parentId: epic.id,
      type: 'task',
      priority: 'high'
    });
    
    const task2 = await cleo.tasks.add({
      title: 'Add password hashing',
      parentId: epic.id,
      type: 'task',
      priority: 'high',
      dependsOn: [task1.id]
    });
    
    // Start a session
    const session = await cleo.sessions.start({
      scope: 'auth-feature',
      notes: 'Implementing authentication'
    });
    
    // Store architectural decision
    await cleo.memory.observe({
      topic: 'auth-architecture',
      content: 'Using bcrypt for password hashing with cost factor 12',
      tags: ['architecture', 'security', 'auth'],
      confidence: 0.95
    });
    
    // Complete work
    await cleo.tasks.start(task1.id);
    await cleo.tasks.complete(task1.id);
    
    // End session
    await cleo.sessions.end(session.id, {
      summary: 'Completed login endpoint'
    });
    
  } finally {
    await cleo.destroy();
  }
}

main().catch(console.error);

Working with Dependencies

import { tasks, orchestration } from '@cleocode/core';

async function manageDependencies() {
  // Add tasks with dependencies
  const backend = await tasks.add({ title: 'Backend API' });
  const frontend = await tasks.add({ 
    title: 'Frontend UI',
    dependsOn: [backend.id]
  });
  const tests = await tasks.add({
    title: 'Integration Tests',
    dependsOn: [backend.id, frontend.id]
  });
  
  // Analyze dependency tree
  const analysis = await orchestration.analyze({
    taskIds: [backend.id, frontend.id, tests.id]
  });
  
  // Get execution order
  console.log('Execution order:', analysis.sequence);
  
  // Find blocked tasks
  console.log('Blocked:', analysis.blocked);
}

Memory Bridge Example

import { memory } from '@cleocode/core';

async function buildKnowledge() {
  // Store observations
  await memory.observe({
    topic: 'database-choice',
    content: 'Selected PostgreSQL over MongoDB for ACID compliance',
    tags: ['database', 'decision'],
    confidence: 0.9
  });
  
  await memory.observe({
    topic: 'api-design',
    content: 'RESTful API with OpenAPI 3.0 spec',
    tags: ['api', 'design'],
    confidence: 0.95
  });
  
  // Search for patterns
  const results = await memory.search('database', { 
    tags: ['decision'],
    limit: 5 
  });
  
  // Build context for AI
  const context = results.map(r => ({
    topic: r.topic,
    content: r.content,
    confidence: r.confidence
  }));
}

Dependencies

Production Dependencies

• @cleocode/contracts - Type definitions
• @cleocode/caamp - Context-aware agent memory protocol
• @cleocode/lafs - Language-agnostic feedback schema
• drizzle-orm - Database ORM
• zod - Schema validation
• pino - Logging
• yaml - YAML parsing
• ajv - JSON Schema validation
• And more...

Development Dependencies

• typescript - Type checking
• vitest - Testing framework
• @types/* - Type definitions

License

MIT License - see LICENSE for details.