@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-protocol - 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.