Chapter 2: Installation and Your First Agent

Install

npm install chronoai @chronoai/toolkit

ChronoAI is written in TypeScript and works in Node.js projects as a normal ESM package.

Minimal Example

import { Agent, createTimelineRef } from 'chronoai';

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

await agent.write(input, 'hello chrono');
console.log(agent.read(input)?.value);

This example creates an Agent, declares a timeline reference, writes a frame, and reads it back.

Line by Line

Agent

Agent is the runtime container. It owns the current time pointer, registered features, timelines, commands, and observers.

const agent = new Agent();

Timeline Reference

A timeline reference is a type-safe handle for a named timeline.

const input = createTimelineRef<string>('user-input');

You can pass the reference to write, set, read, and dependency definitions.

initialize

If you register features, the Agent initializes the graph before the first write. You can also call it explicitly:

agent.initialize();

Initialization validates dependencies, command executors, timeline ownership, and DAG rules.

write

write stores a key frame and triggers propagation.

await agent.write(input, 'hello');

Use write when you want downstream derived timelines and commands to react.

read

read returns a TimelineFrame<T> | null.

const frame = agent.read(input);
console.log(frame?.value);

A frame contains the value, timepoint, frame type, status, and metadata.

String Names

For quick experiments you can also use timeline names directly:

await agent.write('user-input', 'hello');
console.log(agent.read('user-input')?.value);

References are recommended for larger projects because they carry TypeScript types.

Multiple Timelines

const userInput = createTimelineRef<string>('user-input');
const response = createTimelineRef<string>('content-body');

await agent.write(userInput, 'What is ChronoAI?');
agent.set(response, 'A timeline-based AI engine.');

console.log(agent.read(response)?.value);

set writes silently. write writes and propagates.

TimelineFrame

A frame is more than the raw value:

const frame = agent.read(userInput);

if (frame) {
  console.log(frame.value);
  console.log(frame.at);
  console.log(frame.frameType); // key | auto | tween
}

Frame metadata makes it possible to inspect, replay, and debug application state.

Summary

You have now used the basic Agent API:

  • create an Agent
  • define a timeline reference
  • write a frame
  • read a frame
  • distinguish set from write

Next

Continue with Chapter 3: Timeline Basics.