> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs-beta.getzep.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-beta.getzep.com/_mcp/server. # Capture Trajectories > Create Trajectories, append ordered events, declare retries, and close each Trajectory with an outcome and a verification strength. Capture is the first step of the Agent Skills workflow. A Trajectory is the record of one bounded task attempt. Zep compiles Skills only from Trajectories, so the quality of the capture controls the quality of the Skills. For a complete example, see the [Agent Skills quickstart](/agent-skills/quickstart). ## Create a Trajectory | Field | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------- | | `objective` | Yes | The goal of this task instance | | `task_family` | Yes | A slug for the kind of task, for example `billing.support`. Use the same value for all attempts at the same kind of task. | | `trajectory_id` | No | Your identifier for the Trajectory | | `parent_trajectory_uuid` | No | The Trajectory that this attempt [retries](#retries) | | `learn_from` | No | Set to `false` to keep the Trajectory out of compilation. The default value is `true`. | | `metadata` | No | A JSON object of your own data | > **Tip** > > Choose task families that are specific enough to share one procedure. Zep compiles, admits, and filters Skills by task family. Two different tasks in one task family can give a Skill that applies to neither task. ## Append events Append the events in the order that they occur. Each event has an `event_type` and usually a `content` string. | Event type | Use for | | ----------------- | ---------------------------------------------------------------- | | `input_reference` | The task input or a reference to it | | `observation` | A fact that the agent found | | `decision` | A choice that the agent made and the reason for it | | `tool_call` | A call that the agent made to a tool | | `tool_result` | The result of a tool call | | `artifact` | An output that the agent produced, for example a reply or a file | | `checkpoint` | A milestone in the task | | `feedback` | Feedback from a user or a reviewer | | `correction` | A change to an earlier step after an error | | `reflection` | The agent's own review of its work | | `verification` | The result of a check on the work | Record decisions and the reasons for them. The compiler uses decision events to write the decision points of a Skill. A Trajectory that has only tool calls and results gives a less useful procedure. Set `context` on an event to give the `model`, the `tools`, and the `environments` that the agent used. A compiled Skill can name a model, a tool, or an environment only when the event context of a cited Trajectory contains that value. To retry a failed append safely, set `event_id` to your own identifier for the event. When you send the same `event_id` again, Zep returns the existing event and does not add a second event. For the other optional event fields, see the API reference. ## Close a Trajectory Close the Trajectory when the attempt ends. The close request sets the outcome and the verification strength. | `outcome` | Meaning | | ----------- | -------------------------------------- | | `succeeded` | The task is complete and correct | | `partial` | Some of the task is complete | | `failed` | The task did not complete | | `abandoned` | The agent or the user stopped the task | | `unknown` | The result is not known | | `verification` | Meaning | Verifier | | -------------- | ---------------------------------------- | ------------ | | `none` | No check confirmed the outcome | Not required | | `agent` | The agent reports the outcome | Not required | | `tool` | A tool or a test confirmed the outcome | Required | | `customer` | The customer confirmed the outcome | Required | | `external` | An external system confirmed the outcome | Required | Zep compiles Skills only from successful attempt families with strong verification. The strong values are `tool`, `customer`, and `external`. Zep keeps Trajectories with other values, but does not compile Skills from them. For strong verification, send one of these fields: * `verifier`: an inline verifier with `verifier_id`, `class`, and optional `outcome`, `assertion_id`, and `evidence_reference`. The `class` is necessary the first time that the Agent receives the `verifier_id`. Zep then registers the verifier. Later requests can omit `class`. If a later request sends a different `class`, the API returns a conflict. * `verifier_id`: the ID of a verifier that you registered for the Agent. If the request has strong verification and no verifier, the API returns `400` with the message `verifier is required for this verification strength`. The close request returns `202 Accepted`. Zep summarizes the Trajectory in the background. ## Retries A retry is a new Trajectory with `parent_trajectory_uuid` set to the earlier attempt. The initial attempt and its retries are one attempt family. Zep counts attempt families, not Trajectories, when it decides if it has sufficient evidence to compile or admit a Skill. Ten retries of one failed task are one attempt family. Close each attempt with its own outcome. Do not reopen a closed Trajectory. ## Idempotency Trajectory and event writes accept an optional `Idempotency-Key` header. The value must be a UUIDv4. Use a new key for each logical write, and send the same key again when you retry that write. ## Correct or remove captured data Use these operations to correct or remove data after capture. When an operation changes the evidence of a Skill, Zep repairs the affected summaries and Skills in the background. | Operation | Use when | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `client.agent.trajectory.correct_task_family` | A closed Trajectory has the wrong task family. | | `client.agent.trajectory.delete_event` | An event contains data that Zep must not keep. Zep removes the event content before the response. | | `client.agent.trajectory.delete` | Zep must not keep any event of the Trajectory. | | `client.agent.verifier.revoke` | You do not trust the later results of a verifier. The verifier cannot send new assertions after revocation. | | `client.agent.verifier.invalidate_evidence` | A verifier gave incorrect results in the past. Zep removes the Skills that depend on that evidence from search until it repairs them. | The correction, deletion, and revocation requests need the current `revision` of the Trajectory or the verifier as `expected_revision`. An evidence invalidation request names the verifier revisions that gave the incorrect results.