agent-trajectories 0.3.1 → 0.5.0

package/README.md

@@ -30,6 +30,18 @@ Works with any task system: Beads, Linear, Jira, GitHub Issues, or standalone. T
 - **Timeline** - Linear-style chronological view
 - **JSON** - Full structured data for tooling
 
+### Native Multi-Agent Support
+
+Trajectories is built for teams of agents working together:
+
+- **Shared trajectory** — Multiple agents collaborate on a single task record
+- **Agent participation** — Each agent logged as lead, contributor, or reviewer with timestamps
+- **Chapter handoffs** — When work moves between agents, chapters capture the context shift
+- **Cross-agent messaging** — Integrates with [agent-relay](https://github.com/khaliqgant/agent-relay) to record inter-agent communication as trajectory events
+- **Parallel coordination** — Multiple agents working in parallel on related tasks can reference each other's trajectories
+
+This is a key differentiator: no other tool in the AI dev stack tracks *who* (which agent, which model) made *which decisions* and *why*, across a coordinated multi-agent workflow.
+
 ### Integration Ready
 - Complements [claude-mem](https://github.com/thedotmack/claude-mem) for observation-level memory
 - Integrates with [agent-relay](https://github.com/khaliqgant/agent-relay) for multi-agent messaging
@@ -80,6 +92,8 @@ Over time, trajectories become a searchable knowledge base:
 
 ## Quick Start
 
+### CLI
+
 ```bash
 # Install globally (trail command available directly)
 npm install -g agent-trajectories
@@ -112,6 +126,67 @@ trail export traj_abc123 --format markdown
 trail export --format html --open  # Opens in browser
 ```
 
+### SDK
+
+For programmatic usage, install the package and use the SDK:
+
+```bash
+npm install agent-trajectories
+```
+
+**Using the Client (with storage):**
+
+```typescript
+import { TrajectoryClient } from 'agent-trajectories';
+
+const client = new TrajectoryClient({ defaultAgent: 'my-agent' });
+await client.init();
+
+// Start a new trajectory
+const session = await client.start('Implement auth module');
+
+// Record work in chapters
+await session.chapter('Research');
+await session.note('Found existing auth patterns');
+await session.finding('Current system uses sessions');
+
+// Record decisions
+await session.decide(
+  'JWT vs Sessions?',
+  'JWT',
+  'Better for horizontal scaling'
+);
+
+// Complete with retrospective
+await session.done('Implemented JWT-based authentication', 0.9);
+
+await client.close();
+```
+
+**Using the Builder (in-memory, no storage):**
+
+```typescript
+import { trajectory } from 'agent-trajectories';
+
+const result = trajectory('Fix login bug')
+  .withSource({ system: 'github', id: 'GH#456' })
+  .chapter('Investigation', 'claude')
+    .finding('Null pointer in session handler')
+    .decide('Fix approach', 'Add null check', 'Minimal change')
+  .chapter('Implementation', 'claude')
+    .note('Added validation')
+  .done('Fixed null pointer exception', 0.95);
+
+// Export the trajectory
+console.log(result);  // Full trajectory object
+```
+
+**SDK Features:**
+- **Auto-save**: Changes persist automatically with the client
+- **Fluent API**: Chain operations naturally
+- **Resume support**: Pick up where you left off with `client.resume()`
+- **Multiple exports**: Markdown, JSON, timeline, PR summary
+
 ## Why "Trail"?
 
 > **Trajectory** = the complete path an agent takes through a task
@@ -216,6 +291,36 @@ When an agent starts a new task, it can query the workspace for:
 
 Each layer is independent and can be used alone, but together they form a complete agent memory stack.
 
+## The Narrative Layer in Your AI Stack
+
+Trajectories sits at the top of an emerging ecosystem of AI development tools. Each layer answers a different question:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  AGENT-TRAJECTORIES                                             │
+│  "Why was this built this way?"                                 │
+│  Narrative, decisions, retrospectives, institutional memory     │
+│                            ▲                                    │
+│                            │ gives meaning to                   │
+│  ENTIRE (entireio/cli)                                          │
+│  "What happened in this session?"                               │
+│  Raw session capture, transcripts, recovery, rewind             │
+│                            ▲                                    │
+│                            │ attributes                         │
+│  AGENT-TRACE (agent-trace.dev)                                  │
+│  "Who wrote this line of code?"                                 │
+│  Line-level code attribution, model identification              │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Agent Trace** ([agent-trace.dev](https://agent-trace.dev)) is the attribution spec — trajectories implements it automatically, generating `.trace.json` files that comply with the spec on every `trail complete`.
+
+**Entire** ([entireio/cli](https://github.com/entireio/cli)) captures raw session transcripts via git hooks — a complementary layer focused on recovery and rewind.
+
+**Trajectories** is the narrative layer: structured meaning on top of raw events. Where entire captures *what happened*, trajectories captures *why decisions were made* and *what was learned*. Where agent-trace says *who wrote the code*, trajectories explains *why this approach was chosen*.
+
+Used together, these tools give you a complete audit trail of AI-assisted development from attribution through narrative.
+
 ## The Trajectory Format
 
 ```json
@@ -299,10 +404,130 @@ Agent-generated code faces a trust problem. Developers hesitate to ship code the
 
 The result: teams can ship agent code with the same confidence as human-written code—because they understand it just as well.
 
-## Status
+## Installation
+
+```bash
+npm install agent-trajectories
+```
+
+The package provides:
+- **CLI** (`trail` command) - For command-line usage
+- **SDK** - For programmatic integration
+
+```typescript
+// Main import (includes SDK)
+import { TrajectoryClient, trajectory } from 'agent-trajectories';
+
+// Or import from SDK subpath
+import { TrajectoryClient, TrajectoryBuilder } from 'agent-trajectories/sdk';
+```
+
+## SDK Reference
+
+### TrajectoryClient
+
+The client manages trajectories with persistent storage.
+
+```typescript
+const client = new TrajectoryClient({
+  defaultAgent: 'my-agent',    // Default agent name
+  dataDir: '.trajectories',     // Storage directory
+  autoSave: true,               // Auto-save after operations
+});
+
+await client.init();            // Required before use
+
+// Lifecycle
+const session = await client.start('Task title');
+const session = await client.resume();     // Resume active trajectory
+const traj = await client.get('traj_xxx'); // Get by ID
+
+// Query
+const list = await client.list({ status: 'completed' });
+const results = await client.search('auth');
+
+// Export
+const md = await client.exportMarkdown('traj_xxx');
+const json = await client.exportJSON('traj_xxx');
+
+await client.close();
+```
+
+### TrajectorySession
+
+Sessions provide chainable operations on active trajectories.
+
+```typescript
+const session = await client.start('Task');
+
+// Chapters organize work phases
+await session.chapter('Research');
+await session.chapter('Implementation');
+
+// Events record what happened
+await session.note('Observation or note');
+await session.finding('Important discovery');
+await session.error('Something went wrong');
+
+// Decisions capture choices
+await session.decide('Question?', 'Choice', 'Reasoning');
+
+// Complete or abandon
+await session.done('Summary of work', 0.9);
+await session.abandon('Reason for abandoning');
+```
+
+### TrajectoryBuilder
+
+The builder creates trajectories in memory without storage.
+
+```typescript
+import { trajectory, TrajectoryBuilder } from 'agent-trajectories';
+
+// Shorthand function
+const t = trajectory('Task title')
+  .chapter('Work', 'agent-name')
+  .note('Did something')
+  .done('Completed', 0.9);
+
+// Or use the class directly
+const t = TrajectoryBuilder.create('Task')
+  .withDescription('Detailed description')
+  .withSource({ system: 'linear', id: 'ENG-123' })
+  .withTags('feature', 'auth')
+  .chapter('Phase 1', 'claude')
+  .complete({
+    summary: 'What was done',
+    approach: 'How it was done',
+    confidence: 0.85,
+    challenges: ['What was hard'],
+    learnings: ['What was learned'],
+  });
+```
+
+## Roadmap
 
 This project is in early development. See [PROPOSAL-trajectories.md](./PROPOSAL-trajectories.md) for the full design document.
 
+**v1.0 (current)**
+- [x] File-based storage (`.trajectories/`)
+- [x] Core CLI commands (`start`, `decision`, `complete`, `list`, `show`, `export`)
+- [x] Agent Trace spec compliance (`.trace.json` generation)
+- [x] Multi-agent participation tracking
+- [x] Rich export formats (Markdown, JSON, Timeline, HTML)
+
+**v1.1 (next)**
+- [ ] **MCP server** — Real-time bidirectional queries so Claude Code, Cursor, and other tools can read and write trajectories directly within agent sessions
+- [ ] **Claude Code hooks** — Auto-capture on `PostToolUse` and session boundaries
+- [ ] **SQLite storage** — Full-text search across all trajectories
+- [ ] **Git hook integration** — Auto-start/complete trajectories on commit events
+- [ ] **`CLAUDE.md` generation** — Extract patterns from trajectories into reusable context files
+
+**Future**
+- Workspace knowledge base (decisions, patterns, conventions as queryable memory)
+- PostgreSQL/S3 storage for teams
+- Training data export for project-specific model fine-tuning
+
 ## License
 
 MIT