/save-trajectory

name: save-trajectory
description: Save the current conversation as a trajectory JSON file in OpenAI chat completion format for analysis and fine-tuning
context: fork

Save Trajectory

Overview

This skill saves the current session's conversation history as a JSON file in OpenAI chat completion format. The trajectory is saved to `.evolve/trajectories/` in the project root. This enables trajectory analysis, fine-tuning data collection, and session review.

Workflow

Step 1: Walk Through Conversation Messages

Review all messages in the current conversation from start to finish. For each message, identify its type:

• **User text messages**
• **Assistant text responses** (may include thinking)
• **Assistant tool calls**
• **Tool results**

Step 2: Convert to OpenAI Chat Completion Format

Convert each message to the appropriate format:

**User text message:**

{"role": "user", "content": "the user's message text"}

**Assistant text response (no thinking):**

{"role": "assistant", "content": "the assistant's response text"}

**Assistant text response (with thinking):**

{"role": "assistant", "content": "the assistant's response text", "thinking": "the thinking/reasoning text"}

**Assistant tool call (no visible text):**

{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "tool_call_id_here",
      "type": "function",
      "function": {
        "name": "ToolName",
        "arguments": "{\"param\": \"value\"}"
      }
    }
  ]
}

**Assistant tool call with text:**

{
  "role": "assistant",
  "content": "text before/after the tool call",
  "tool_calls": [
    {
      "id": "tool_call_id_here",
      "type": "function",
      "function": {
        "name": "ToolName",
        "arguments": "{\"param\": \"value\"}"
      }
    }
  ]
}

**Tool result:**

{"role": "tool", "tool_call_id": "tool_call_id_here", "content": "the tool output text"}

Important Details

• **Tool call arguments must be a JSON string**, not a nested object. Use `json.dumps()` on the arguments object.
• **Tool call IDs**: Use the actual tool call ID from the conversation. If not available, generate a unique ID like `call_001`, `call_002`, etc.
• **Multiple tool calls**: If the assistant made multiple tool calls in one turn, include all of them in a single assistant message's `tool_calls` array, followed by separate tool result messages for each.
• **Thinking blocks**: If the assistant had both thinking and text in the same turn, combine them into one message with both `content` and `thinking` fields.

Step 3: Clean Content

Strip `<system-reminder>...</system-reminder>` tags and their contents from all message content. Use a non-greedy multiline match (e.g., `re.sub(r'<system-reminder>[\s\S]*?</system-reminder>', '', text).strip()`). If after stripping, a message has empty content and no tool calls, omit it.

Step 4: Build Envelope

Wrap the messages array in a trajectory envelope:

{
  "model": "<model-id-from-session>",
  "timestamp": "2025-01-15T10:30:00Z",
  "session_id": "<session-id-from-session>",
  "messages": [...]
}

• **model**: Use the exact model ID from the current session's environment context (e.g., the value after "You are powered by the model named …"). Do not hardcode a default — always read it from the session.
• **timestamp**: Current ISO 8601 timestamp
• **session_id**: The current session identifier. Read it from whatever the harness exposes — the `session_id` passed into the skill, the session id surfaced in the session context, or a runtime-provided environment variable (`CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, or `CODEX_SESSION_ID`). The helper uses these variables in that order when the JSON omits the id. Include it verbatim so offline provenance can match this trajectory to `recall` audit events for the same session. Omit the field only if no session id is truly available in this environment.

Step 5: Save via Helper Script

Write the trajectory JSON to a temporary file using the **Write** tool, then pass the file path to the helper script:

1. Write the JSON to `.evolve/tmp/trajectory_input.json` using the Write tool (create the directory if needed) 2. Run the helper script with the file path as an argument:

tmp=.evolve/tmp/trajectory_input.json; mkdir -p .evolve/tmp; python3 "${CLAUDE_PLUGIN_ROOT}/skills/evolve-lite/save-trajectory/scripts/save_trajectory.py" "$tmp" --delete-input

**Important**: Do NOT use inline Python scripts, heredocs, or stdin piping to pass the trajectory JSON. Always use the Write tool to create a temp file first. This avoids escaping issues with backslashes, quotes, and newlines in conversation content.

The script will:

• Read the trajectory JSON from the provided file path
• Create the `.evolve/trajectories/` directory if needed
• Generate a timestamped filename (`trajectory_YYYY-MM-DDTHH-MM-SS.json`)
• Write the formatted JSON, then remove the temporary input only after a successful save
• Print confirmation with file path and message count

Example Output

After saving, you should see output like:

Trajectory saved: /path/to/project/.evolve/trajectories/trajectory_2025-01-15T10-30-00.json
Messages: 12

Notes

• This skill captures what's visible in the current conversation context. Very long sessions may have earlier messages compressed or summarized by the system. Include these summarized messages as-is with `role: "user"` or `role: "assistant"` as appropriate — do not skip them, since they preserve the conversation flow.
• The trajectory format is compatible with OpenAI chat completion format for downstream tooling.
• Trajectories are saved per-project in `.evolve/trajectories/` and can be version-controlled or gitignored as preferred.