Episodes

An episode is the smallest unit of memory you write to Breeth. One sentence, one paragraph, or a conversation turn — Breeth ingests the prose, extracts the entities and relationships, and stores both the raw text and the structured graph.

What gets stored

For every episode:

The raw text — recoverable verbatim via GET /v1/episodes/{uuid}.
Entities — proper nouns and key concepts (people, projects, services, decisions). Stored as nodes.
Edges — directed relationships between entities, with a natural-language fact describing the connection.
Optional intent annotation — when you set extract_intent: true, each edge also gets a cognitive pattern, director vision, and reasoning trace. See Intents.

Anatomy of a write

{
  "content": "Nandini Kulkarni was promoted to Staff Engineer after she shipped the migration in Q1.",
  "group_id": "default",
  "extract_intent": false
}

Field	Required	Purpose
`content`	yes	The prose to ingest. No hard length cap, but very long content costs more inference time.
`group_id`	no, defaults `"default"`	A user-facing namespace inside your project. Use it to separate distinct memory contexts (e.g. `"candidates"`, `"competitors"`).
`extract_intent`	no, defaults `false`	When true, runs the intent annotation pipeline. Counts against your monthly `intents` cap.

What you get back

{
  "ok": true,
  "episode_name": "api_1778498269735",
  "extracted": { "entities": 4, "edges": 3 },
  "group_id": "default",
  "warning": null,
  "cogram": {
    "mode": "async",
    "status": "pipeline_running_in_background",
    "task_id": "0ef8c19d6381"
  }
}

extracted.entities / extracted.edges — counts from the synchronous extraction pass.
warning — present when graphiti extracted entities but no edges (usually means the content was too terse or used pronouns where it needed names).
cogram.task_id — the background pipeline (narration, profile distillation, knot synthesis) runs async. Poll GET /v1/tasks/{task_id} if you need to know when it completes.

Successful writes are eventually-rich

The synchronous response confirms entities and edges have landed. Narration, profiles, and knots populate in the background — typically within 15 seconds.

Idempotency

Episodes are append-only. The same content written twice creates two episodes, but Breeth's graph deduplication merges identical entities and edges across them — so you don't get inflated counts in your graph.

Storage and retention

Episodes are scoped to (team, project). They never cross either boundary. See Projects & Teams for the isolation model.