using-trajectories-sdk

name	using-trajectories-sdk
description	Use when programmatically creating or managing agent trajectories in TypeScript - provides TrajectoryClient for persistent storage and TrajectoryBuilder for in-memory construction

Using the Trajectories SDK

Overview

The agent-trajectories SDK provides two APIs for programmatically capturing agent work trajectories: TrajectoryClient (persistent, async) and TrajectoryBuilder (in-memory, sync).

When to Use

• Building tools or agents that need to record their work programmatically
• Integrating trajectory capture into CI/CD or automation pipelines
• Creating trajectories from code rather than CLI
• Not for: Manual CLI usage (use trail CLI instead)

Quick Reference

Need	Use
Persist trajectories to disk	TrajectoryClient
Build trajectories in memory	TrajectoryBuilder or trajectory()
One-liner start	trajectory('title') shorthand
Export formats	.toMarkdown(), .toJSON(), .toTimeline(), .toPRSummary()

Installation

npm install agent-trajectories

TrajectoryClient (Persistent Storage)

Use when you need trajectories saved to .trajectories/ on disk.

import { TrajectoryClient } from 'agent-trajectories/sdk';

const client = new TrajectoryClient({ defaultAgent: 'my-agent' });
await client.init(); // Required before use

// Start a trajectory
const session = await client.start('Implement feature X');

// Record work in chapters
await session.chapter('Research');
await session.note('Found existing auth patterns');
await session.finding('Current implementation uses JWT');

await session.chapter('Implementation');
await session.decide(
  'JWT vs Session tokens',
  'JWT',
  'Better for stateless API clients',
  [{ option: 'Session tokens', reason: 'Simpler but requires server state' }]
);

// Complete with retrospective
await session.done('Implemented JWT auth', 0.9, {
  approach: 'Extended existing auth module',
  learnings: ['JWT refresh flow needs careful error handling'],
});

await client.close();

Client Options

new TrajectoryClient({
  dataDir: '.trajectories',    // Storage location (default)
  defaultAgent: 'agent-name',  // Default agent for chapters
  autoSave: true,              // Auto-persist after each operation (default)
});

Key Client Methods

Method	Description
client.start(title)	Start new trajectory, returns session
client.resume()	Resume active trajectory
client.get(id)	Get trajectory by ID
client.list(query?)	List trajectories with optional filter
client.search(text)	Full-text search

Session Methods

Method	Description
session.chapter(title, agent?)	Start a new chapter
session.note(content)	Record a note
session.finding(content)	Record a finding (medium significance)
session.reflect(content, confidence?)	Record a reflection (high significance)
session.error(content)	Record an error (high significance)
session.decide(question, chosen, reasoning, alts?)	Record a decision
session.done(summary, confidence, opts?)	Complete trajectory
session.abandon(reason?)	Abandon trajectory

TrajectoryBuilder (In-Memory)

Use when you don't need persistence - just building a trajectory data structure.

import { TrajectoryBuilder, trajectory } from 'agent-trajectories/sdk';

// Shorthand
const result = trajectory('Fix auth bug')
  .chapter('Investigation', 'claude')
  .finding('Null pointer in login handler')
  .decide('Fix approach', 'Add null check', 'Simplest correct fix')
  .done('Fixed null pointer exception', 0.95);

// Export
console.log(TrajectoryBuilder.create('Task')
  .chapter('Work', 'agent')
  .note('Did the thing')
  .toMarkdown());

Builder is synchronous and chainable. Call .done(), .complete(), or .build() to get the Trajectory object.

Export Formats

Both Client sessions and Builder support:

session.toMarkdown();    // Human-readable markdown
session.toJSON();        // Raw JSON data
session.toJSON(true);    // Compact JSON
session.toTimeline();    // Chronological timeline view
session.toPRSummary();   // Optimized for PR descriptions

Common Mistakes

Mistake	Fix
Forgetting await client.init()	Always call init before using client
Using Builder when you need persistence	Use TrajectoryClient instead
Not calling client.close()	Always close when done
Starting a trajectory when one is active	Complete or abandon the active one first
Missing await on session methods	Client session methods are async