Chapter 1: What is ChronoAI

In One Sentence

ChronoAI is a timeline-based AI engine core: state lives on timelines, derived values propagate through a DAG, and side effects are triggered through explicit commands.

What Problem Does It Solve?

Most AI applications eventually need to manage several things at once:

  • user input and assistant output
  • system prompts and runtime context
  • streaming model responses
  • rewind, replay, snapshots, and branching
  • derived data such as message history or rendered UI

A plain message array works for the first demo, but it becomes fragile once the application needs history, streaming updates, or multiple derived states. ChronoAI gives these concerns a stable model.

The Core Idea: Everything Is a Timeline

A timeline is a named axis of state. Each timepoint can hold one frame. The Agent moves a pointer along the axis and all reads and writes are resolved relative to that pointer.

import { Agent, createTimelineRef } from 'chronoai';

const agent = new Agent();
const userInput = createTimelineRef<string>('user-input');

await agent.write(userInput, 'Hello');
console.log(agent.read(userInput)?.value);

Because state is indexed by time, history is not an afterthought. Rewind, seek, snapshot, and replay are all natural operations.

Three Core Concepts

1. Timeline

A timeline is the owner of a piece of state. Examples include user-input, system-prompt, messages-ready, ai-response, and content-body.

A timeline can also define how missing timepoints are filled:

  • none: empty timepoints stay empty
  • hold: the previous value is carried forward
  • reactionFrame: the value is computed from other timelines
  • lazyFrame, intervalFill, and customFill: advanced strategies

2. Feature

A Feature is a module that declares timelines, derived values, commands, observers, and lifecycle hooks.

import { defineFeature, useTimeline } from 'chronoai';

export const ChatFeature = defineFeature('chat', () => {
  useTimeline<string>({ name: 'user-input' });
  useTimeline<string>({ name: 'content-body', retain: 'all' });
});

Features keep application behavior modular. A chat app might use separate features for prompt loading, message building, model calling, output parsing, and rendering.

3. Command

Commands represent side effects. A command is planned after the DAG reaches a stable state, then executed by a registered executor.

This split keeps computation deterministic and side effects explicit.

const ModelCall = defineCommandKind<{ messages: unknown[] }>('model-call');

useCommand('call-model', {
  runAt: 'after-commit',
  plan({ read }) {
    return ModelCall.plan({ messages: read('messages-ready')?.value ?? [] });
  },
});

The Engine Rhythm

write(value)
  -> settle derived timelines through the DAG
  -> plan commands from the stable state
  -> execute side effects
  -> stream or write results back into timelines

This is the reason ChronoAI can handle both deterministic state propagation and real-world AI calls in one model.

Summary

ChronoAI gives AI applications a time-aware state model. You describe timelines, derivations, and side effects; the Agent keeps them coordinated.

Next

Continue with Chapter 2: Installation and Your First Agent.