Episodes

Temporal

Group related entities into temporal episodes - work sessions, deployments, sprints, or any meaningful time period

What Are Episodes?

Temporal grouping of related entities

Episodes are containers that group related entities (issues, decisions, work logs, memories) into meaningful time-bounded collections. They provide a "chapter" structure for your project history.

Work Sessions

Group everything from a coding session

Deployments

Track what went into each release

Sprints

Organize work by sprint boundaries

Create an Episode

curl -X POST http://localhost:7777/api/v1/my-namespace/episodes \
  -H "Authorization: Bearer $ACE_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sprint 14",
    "description": "Authentication overhaul and performance improvements",
    "started_at": "2026-02-01T00:00:00Z",
    "ended_at": "2026-02-14T00:00:00Z",
    "tags": ["sprint", "auth", "performance"]
  }'

Add Entities to an Episode

Link issues, decisions, and other entities to an episode

# Add an issue to an episode
curl -X POST http://localhost:7777/api/v1/my-namespace/episodes/1/entities \
  -H "Authorization: Bearer $ACE_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "issue",
    "entity_id": 42
  }'

# Add a decision to the same episode
curl -X POST http://localhost:7777/api/v1/my-namespace/episodes/1/entities \
  -H "Authorization: Bearer $ACE_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "decision",
    "entity_id": 15
  }'

List & Query Episodes

# List all episodes
curl "http://localhost:7777/api/v1/my-namespace/episodes" \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

# Get a specific episode with its entities
curl "http://localhost:7777/api/v1/my-namespace/episodes/1" \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

# Filter by tags
curl "http://localhost:7777/api/v1/my-namespace/episodes?tags=sprint" \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

Auto-Episode Creation

Observer can automatically create episodes

When the ACE Observer detects significant work sessions, it can automatically create episodes grouping related observations, issues, and decisions together. This happens transparently as you work.

Session Detection

Observer detects when a focused work session starts and ends based on activity patterns

Entity Grouping

Related entities created during the session are automatically linked to the episode

Use Cases

Sprint Retrospectives

Group all work from a sprint to review what was accomplished, decisions made, and issues encountered.

Release Tracking

Create an episode per release to track which issues, decisions, and architecture changes went into each version.

Incident Response

Group all entities related to an incident - the bug report, investigation decisions, fix work logs, and post-mortem.

Onboarding Sessions

Track what a new team member learned during onboarding for future reference.