Chapter 8: Prompt System

ChronoAI includes a prompt fragment system for building prompts from files, metadata, and dynamic timeline values.

.prompt File Format

A .prompt file is Markdown-like text with YAML frontmatter.

---
name: system.identity
tags: [system]
priority: 100
---
You are a concise AI assistant.

The body becomes the prompt fragment content.

Frontmatter Fields

More Examples

---
name: output.json
tags: [output]
priority: 80
---
Return valid JSON only.

parsePromptFile()

parsePromptFile() parses a raw .prompt string without doing file I/O.

import { parsePromptFile } from 'chronoai';

const { id, definition } = parsePromptFile(raw, 'system.identity.prompt');

This makes it easy to keep file loading in your own infrastructure while letting ChronoAI handle the format.

usePromptFragment()

Register parsed fragments inside a feature.

usePromptFragment('system.identity', {
  tags: ['system'],
  priority: 100,
  content: 'You are a concise AI assistant.',
});

Fragments become available to prompt timelines and agent.selectFragments().

Prompt Timelines

A timeline can define a prompt template. It is evaluated lazily when read.

const systemPrompt = useTimeline<string>({
  name: 'system-prompt',
  prompt: 'You are {{ identity }}.\n{% select "system" sort="priority:desc" %}',
});

{{ }} Timeline Variables

{{ identity }} reads the current value of the identity timeline.

prompt: 'Current user: {{ user-name }}'

{% select %} Fragment Selection

{% select "system" %} selects registered fragments by tag.

prompt: '{% select "system" sort="priority:desc" limit=5 %}'

The selected fragments are sorted and joined into the final prompt.

Complete Example: From Files to Prompt

1. Create Prompt Files

---
name: system.identity
tags: [system]
priority: 100
---
You are ChronoAI Assistant.

2. Create a Feature

export const SystemPromptFeature = defineFeature('system-prompt', config => {
  for (const file of config.files) {
    const { id, definition } = parsePromptFile(file.raw, file.name);
    usePromptFragment(id, definition);
  }

  useTimeline<string>({
    name: 'system-prompt',
    prompt: '{% select "system" sort="priority:desc" %}',
  });
});

3. Use It

agent.use(SystemPromptFeature, { files });
agent.initialize();

console.log(agent.read('system-prompt')?.value);

selectFragments() and selectAndJoin()

You can use the selector directly:

const fragments = agent.selectFragments({
  tags: ['system'],
  sort: { by: 'priority', order: 'desc' },
});

Or join selected fragments in one step:

const prompt = selectAndJoin(fragments, { tags: 'system' });

Summary

• .prompt files store reusable prompt fragments.
• parsePromptFile() is pure and I/O-free.
• usePromptFragment() registers fragments.
• Prompt timelines combine timeline variables and fragment selectors.

Next

Continue with Chapter 9: Realtime Rendering.