# ClawTrace Self-Evolve

Adopt this skill: https://proskills.md/skills/other/epsilla-cloud-clawtrace-plugins-clawtrace-skills

Page: https://proskills.md/skills/other/epsilla-cloud-clawtrace-plugins-clawtrace-skills
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: plugins/clawtrace/skills/SKILL.md
size: 5619
upstream: https://github.com/epsilla-cloud/clawtrace/blob/main/plugins/clawtrace/skills/SKILL.md

````text
---
name: ClawTrace Self-Evolve
description: Ask Tracy to analyze your recent trajectories and improve your agent behavior based on data-driven recommendations.
version: 1.0.0
metadata: {"openclaw":{"emoji":"🔬","os":["linux","darwin","win32"],"homepage":"https://clawtrace.ai","requires":{"env":["CLAWTRACE_OBSERVE_KEY"]}}}
---

# ClawTrace Self-Evolve Skill

You have access to ClawTrace, an observability platform that captures and analyzes all your trajectories. Use this skill to understand your own performance and improve over time.

## When to Use This Skill

Invoke this skill when any of the following is true:
- A run just completed and cost more than expected
- A run failed or produced unexpected output
- You've completed 5 or more runs since your last self-analysis
- Your session is ending and you want to log learnings
- You notice repeated failures on the same type of task

## How to Call the Endpoint

Send a POST request to `https://api.clawtrace.ai/v1/evolve/ask`.

Authentication uses your observe key, which is already set in your environment as `CLAWTRACE_OBSERVE_KEY`.

```python
import httpx
import os

def ask_tracy(question: str, trace_id: str = None, session_id: str = None) -> str:
    """Ask Tracy to analyze trajectories and return recommendations."""
    observe_key = os.environ.get("CLAWTRACE_OBSERVE_KEY", "")
    if not observe_key:
        return "ClawTrace observe key not configured."

    payload = {"question": question}
    if trace_id:
        payload["trace_id"] = trace_id
    if session_id:
        payload["session_id"] = session_id

    full_response = []

    with httpx.stream(
        "POST",
        "https://api.clawtrace.ai/v1/evolve/ask",
        headers={
            "Authorization": f"Bearer {observe_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    ) as response:
        event_type = ""
        for line in response.iter_lines():
            if line.startswith("event: "):
                event_type = line[7:]
            elif line.startswith("data: ") and event_type == "text":
                import json
                data = json.loads(line[6:])
                full_response.append(data.get("text", ""))

    return "".join(full_response)
```

## What to Ask — Question Templates

Use these questions for maximum insight. Substitute actual values for placeholders.

### After a costly run
```
"My last run cost significantly more than usual. The trace_id is {trace_id}. 
What caused the cost spike and what should I change to prevent it?"
```

### After a failed run
```
"My last run failed. The trace_id is {trace_id}. 
What step failed, what was the input that caused it, and how should I handle this case differently?"
```

### Periodic self-analysis (every 5 runs)
```
"Analyze my last 10 trajectories. What patterns do you see in my failures? 
Where am I spending the most tokens? What one change would have the biggest impact on cost and reliability?"
```

### Before a high-stakes task
```
"I'm about to execute a complex multi-step task. Based on my recent trajectory history, 
what are my most common failure modes and how should I guard against them?"
```

### Context window management
```
"Is my context window growing too large across sessions? 
Review my recent traces and tell me if I should trim my history and when."
```

### Tool call efficiency
```
"Which of my tool calls are taking the longest or failing most often? 
What can I change to make my tool usage more reliable and efficient?"
```

## How to Act on Recommendations

When Tracy responds, follow these rules:

1. **Extract the core recommendation.** Tracy will identify 1–3 specific changes. Focus on the highest-impact one.

2. **Apply changes to this session immediately.** If Tracy says your context window is bloated, trim history now before continuing.

3. **Log the insight to your MEMORY.md.** Record what you learned so future sessions benefit:
   ```
   ## ClawTrace Learnings — {date}
   - Issue: {what Tracy found}
   - Fix: {what I changed}
   - Impact: {expected improvement}
   ```

4. **Confirm the change worked.** After applying a recommendation, mention it in your next response: "Based on trajectory analysis, I've adjusted X to prevent Y."

5. **Do not ask Tracy more than twice per session** unless a new failure occurs. Each call consumes credits and Tracy's value is in patterns across many runs, not micro-optimization within one session.

## Example — Full Interaction

```
# End of a session — periodic self-review
insight = ask_tracy(
    "Analyze my performance over the last 5 trajectories. "
    "What's costing the most, what's failing, and what's the single most important thing to fix?"
)

# Tracy responds with analysis
# You read it, extract the recommendation, and act:
# e.g. "Your context window averages 1,200 messages per LLM call. 
#       Trim to last 50 messages. This would cut input cost by ~90%."

# Apply immediately:
# → truncate conversation history to last 50 messages
# → log to MEMORY.md
# → confirm in next output
```

## Important Notes

- Tracy has access to your real trajectory data. Her analysis reflects actual runs, not simulations.
- Responses stream as SSE — parse the `text` events to build the full response.
- The `session_id` returned in the first SSE event can be reused to continue a conversation with Tracy across multiple calls.
- Tracy respects tenant isolation — she can only see your own trajectories.
- If you don't have a specific `trace_id`, omit it and Tracy will analyze recent trajectories automatically.
````

## File: README.md
upstream: https://github.com/epsilla-cloud/clawtrace/blob/main/README.md

````text
<p align="center">
  <img src="packages/clawtrace-ui/public/clawtrace-logo.png" alt="ClawTrace" width="260" />
</p>

<h3 align="center">Cost-aware tracing &amp; skill distillation for LLM agents</h3>

<p align="center">
  <a href="https://clawtrace.ai">Website</a> &nbsp;·&nbsp;
  <a href="https://clawtrace.ai/docs">Docs</a> &nbsp;·&nbsp;
  <a href="https://arxiv.org/abs/2604.23853">Paper</a> &nbsp;·&nbsp;
  <a href="https://clawtrace.ai/docs/ask-tracy">Ask Tracy</a> &nbsp;·&nbsp;
  <a href="#getting-started">Quickstart</a>
</p>

<p align="center">
  <a href="https://arxiv.org/abs/2604.23853"><img src="https://img.shields.io/badge/arXiv-2604.23853-b31b1b?logo=arxiv&logoColor=white" alt="arXiv" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License" /></a>
  <img src="https://img.shields.io/badge/OpenClaw-compatible-orange" alt="OpenClaw" />
  <img src="https://img.shields.io/badge/Next.js-15-black?logo=nextdotjs" alt="Next.js" />
  <img src="https://img.shields.io/badge/FastAPI-Python-009688?logo=fastapi&logoColor=white" alt="FastAPI" />
</p>

---

## Paper

> **ClawTrace: Cost-Aware Tracing for LLM Agent Skill Distillation** &nbsp;—&nbsp;
> Boqin Yuan, Renchu Song, Yue Su, Sen Yang, Jing Qin · arXiv [2604.23853](https://arxiv.org/abs/2604.23853)

Skill-distillation pipelines learn reusable rules from LLM agent trajectories, but they lack a key signal — **how much each step costs**. ClawTrace records every LLM call, tool use, and sub-agent spawn during a session and compiles it into a **TraceCard**: a ~1.5 kB YAML summary with per-step USD cost, token counts, and redundancy flags. On top of TraceCards, **CostCraft** produces three patch types — *preserve*, *prune* (with counterfactual evidence), and *repair* — that improve agent skills without inflating cost.

<p align="center">
  <img src="packages/clawtrace-ui/public/docs/images/paper-workflow.png" alt="ClawTrace + CostCraft workflow: capture, compile, distill" width="860" />
</p>

<p align="center"><sub><b>Capture → Compile → Distill.</b> ClawTrace instruments the agent (Substrate), compiles each session into a TraceCard (IR), and merges TraceCards into evolved skills via a preserve / prune / repair typology (Methodology).</sub></p>

📄 **Read the paper:** <https://arxiv.org/abs/2604.23853> &nbsp;·&nbsp; [BibTeX](#citation)

---

## Why this exists

My OpenClaw agent burned ~40× its normal token budget in under an hour. Root cause: it was appending ~1,500 messages of history to every LLM call. By the time I noticed, it had already spent a few dollars on what should have been a 3-cent task — and I couldn't see it from logs, because OpenClaw flattens everything into a wall of JSON. The loop was invisible.

ClawTrace was built after that incident, and the paper above is what came out of using it at scale.

---

**ClawTrace records every agent run as a tree of spans and lets you inspect it.**

```bash
openclaw plugins install @epsilla/clawtrace
openclaw clawtrace setup
openclaw gateway restart
```

Then open [clawtrace.ai](https://clawtrace.ai). Your next run appears automatically.

---

## What it shows

- **Token usage per step** — see exactly which LLM call ate your budget
- **Tool calls and retries** — spot loops before they compound
- **Execution timeline** — Gantt chart of every span, parallel and sequential
- **Full input/output** — click any step to see what went in and what came back

<p align="center">
  <img src="packages/clawtrace-ui/public/docs/images/2.2.1-see-detail-trajectory---tracing-view.png" alt="Trace tree view" width="720" />
</p>

---

## Ask Tracy

You can also ask questions in plain English. Tracy is an AI analyst wired directly to your trajectory graph. She runs live Cypher queries against your data, generates charts, and tells you specifically what to fix.

> "Why did my last run cost so much?"
> "Which tool is failing most often?"
> "Is my context window growing across sessions?"

<p align="center">
  <img src="packages/clawtrace-ui/public/docs/images/ask_tracy_4_result.png" alt="Tracy analyzing trajectory costs" width="600" />
</p>

---

## Three views per trace

Every trajectory has three views — click any node/span/bar to open step detail with full payloads, token counts, duration, cost, and errors.

**Execution path** — collapsible tree, parent-child relationships, per-node cost badges

<p align="center">
  <img src="packages/clawtrace-ui/public/docs/images/2.2.1-see-detail-trajectory---tracing-view.png" alt="Execution Path" width="720" />
</p>

**Call graph** — force-directed diagram of every agent, model, and tool in the run

<p align="center">
  <img src="packages/clawtrace-ui/public/docs/images/2.2.1-see-detail-trajectory---graph-view.png" alt="Call Graph" width="720" />
</p>

**Timeline** — Gantt chart showing where time actually went

<p align="center">
  <img src="packages/clawtrace-ui/public/docs/images/2.2.3-see-detail-trajectory---timeline-view.png" alt="Timeline" width="720" />
</p>

---

## Getting started

### 1. Install the plugin on your OpenClaw agent

```bash
openclaw plugins install @epsilla/clawtrace
```

### 2. Authenticate

```bash
openclaw clawtrace setup
```

Paste your observe key from [clawtrace.ai](https://clawtrace.ai) when prompted. 200 free credits, no credit card.

### 3. Restart the gateway

```bash
openclaw gateway restart
```

Done. Every run now streams to ClawTrace automatically.

---

## Self-evolving agents

The plugin also exposes a `/v1/evolve/ask` endpoint so your agent can query Tracy about its own trajectories. Install the ClawTrace Self-Evolve skill and your agent will periodically check its own cost and failure patterns, apply fixes, and log what it changed.

```bash
openclaw skills install clawtrace-self-evolve
```

---

## Architecture

```mermaid
graph TB
    subgraph Agent Runtime
        OC[OpenClaw Agent]
        PLG["@epsilla/clawtrace plugin<br/>8 hook types"]
    end

    subgraph Ingest Layer
        ING[Ingest Service<br/>FastAPI + Cloud Storage]
    end

    subgraph Data Lake
        RAW[Raw JSON Events<br/>Azure Blob / GCS / S3]
        DBX[Databricks Lakeflow<br/>SQL Pipeline]
        ICE[Iceberg Silver Tables<br/>events_all, pg_traces,<br/>pg_spans, pg_agents]
    end

    subgraph Graph Layer
        PG[PuppyGraph<br/>Cypher over Delta Lake]
    end

    subgraph Backend Services
        API[Backend API<br/>FastAPI + asyncpg]
        PAY[Payment Service<br/>Credits + Stripe]
        MCP[Tracy MCP Server<br/>Cypher queries]
    end

    subgraph AI Layer
        TRACY[Tracy Agent<br/>Anthropic Managed Harness<br/>Claude Sonnet 4.6]
    end

    subgraph Frontend
        UI[ClawTrace UI<br/>Next.js 15 + React 19]
        DOCS[Documentation<br/>Server-rendered Markdown]
    end

    subgraph External
        NEON[(Neon PostgreSQL<br/>Users, API Keys,<br/>Credits, Sessions)]
        STRIPE[Stripe<br/>Payments]
    end

    OC --> PLG
    PLG -->|"POST /v1/traces/events"| ING
    ING --> RAW
    RAW --> DBX
    DBX --> ICE
    ICE --> PG

    PG -->|Cypher| API
    PG -->|Cypher| MCP

    API --> NEON
    PAY --> NEON
    PAY --> STRIPE

    MCP -->|tool results| TRACY
    TRACY -->|SSE stream| API

    UI -->|REST API| API
    UI -->|SSE| API
    API -->|deficit check| PAY
```

### Data flow

1. **Capture** — The plugin intercepts 8 OpenClaw hook types: `session_start`, `session_end`, `llm_input`, `llm_output`, `before_tool_call`, `after_tool_call`, `subagent_spawning`, `subagent_ended`
2. **Ingest** — Events are batched and POSTed to the ingest service, which writes partitioned JSON to cloud storage (`tenant={id}/agent={id}/dt=YYYY-MM-DD/hr=HH/`)
3. **Transform** — Databricks Lakeflow SQL pipeline materializes raw events into 8 Iceberg silver tables every 3 minutes
4. **Query** — PuppyGraph virtualizes the Delta Lake tables as a Cypher-queryable graph (Tenant → Agent → Trace → Span with CHILD_OF edges)
5. **Serve** — Backend API runs Cypher queries; Tracy's MCP s
````
