Checkpoints

Conversation: msg-1 → msg-2 → msg-3 → msg-4
                         ↑
              checkpoint('before-choice')

Restore creates a new branch from the checkpoint:
    main → msg-4
    main-v2 → msg-2 (restored, now active)

import {
  ContextEngine,
  SqliteContextStore,
  XmlRenderer,
  role,
  user,
  assistant,
} from '@deepagents/context';

const store = new SqliteContextStore('./chat.db');
const context = new ContextEngine({
  store,
  chatId: 'chat-001',
  userId: 'user-001',
}).set(role('You are helpful.'));

// Build conversation
context.set(user('I want to learn programming.'));
context.set(assistant('Great! Would you prefer Python or JavaScript?'));
await context.save();

// Save checkpoint before user's choice
const cp = await context.checkpoint('before-choice');
console.log(cp);
// {
//   id: 'uuid-xxx',
//   name: 'before-choice',
//   messageId: 'msg-xxx',  // points to the assistant message
//   createdAt: 1703123456789
// }

// User chose Python
context.set(user('I want to learn Python.'));
context.set(assistant('Python is great for beginners!'));
await context.save();
// main → ... → assistant → user → assistant

// User wants to try JavaScript path instead
await context.restore('before-choice');
// Creates 'main-v2' branch from checkpoint
// Now at: main-v2 → ... → assistant (the checkpoint message)

context.set(user('I want to learn JavaScript.'));
context.set(assistant('JavaScript is excellent for web development!'));
await context.save();
// main-v2 → ... → assistant → user → assistant

const checkpoints = await store.listCheckpoints(context.chatId);
// [
//   { id: 'uuid-1', name: 'before-choice', messageId: 'msg-2', createdAt: ... },
//   { id: 'uuid-2', name: 'before-analysis', messageId: 'msg-5', createdAt: ... },
// ]

await store.deleteCheckpoint(context.chatId, 'before-choice');

import { generateText } from 'ai';
import { groq } from '@ai-sdk/groq';

async function askWithRetry(
  context: ContextEngine,
  question: string,
  maxRetries = 3,
): Promise<string> {
  context.set(user(question));
  await context.save();

  // Checkpoint after saving question
  await context.checkpoint('before-response');

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const { systemPrompt, messages } = await context.resolve({
      renderer: new XmlRenderer(),
    });

    const response = await generateText({
      model: groq('gpt-oss-20b'),
      system: systemPrompt,
      messages,
      temperature: 0.7 + attempt * 0.1, // Increase temperature on retries
    });

    if (isGoodResponse(response.text)) {
      context.set(assistant(response.text));
      await context.save();
      return response.text;
    }

    // Bad response - restore and try again
    console.log(`Attempt ${attempt + 1} failed, retrying...`);
    await context.restore('before-response');
  }

  throw new Error('Max retries exceeded');
}

function isGoodResponse(text: string): boolean {
  return text.length > 10 && !text.includes('I cannot');
}

// Stage 1: Gather requirements
context.set(user('Help me build a todo app'));
context.set(assistant('What features do you need?'));
await context.save();
await context.checkpoint('requirements');

// Stage 2: Design
context.set(user('I need tasks with due dates and priorities'));
context.set(assistant('Here is the proposed architecture...'));
await context.save();
await context.checkpoint('design');

// Stage 3: Implementation
context.set(user('Start with the data model'));
context.set(assistant('Here is the schema...'));
await context.save();
await context.checkpoint('implementation');

// User wants to revisit design
await context.restore('design');
// Now back at design stage, can take different direction

// Good
await context.checkpoint('before-language-choice');
await context.checkpoint('after-requirements-gathered');
await context.checkpoint('pre-final-review');

// Less clear
await context.checkpoint('checkpoint-1');
await context.checkpoint('save');

try {
  await context.checkpoint('my-checkpoint');
} catch (error) {
  // "Cannot create checkpoint: no messages in conversation"
}

try {
  await context.restore('nonexistent');
} catch (error) {
  // 'Checkpoint "nonexistent" not found in chat "chat-001"'
}

const graph = await store.getGraph(context.chatId);
console.log(graph.checkpoints);
// [
//   { id: '...', name: 'before-choice', messageId: 'msg-2', createdAt: ... },
// ]