history-explorer

name	history-explorer
description	Inspect recent session conversation turns and meta-run history. Returns structured JSON summaries of turn counts, role distribution, tool usage, meta-skill executions, and co-occurrence patterns. Use this before running meta-skill-creator or when the user asks about recent history, past tool usage, or session activity.
provenance	{"origin":"openclaw.net","license":"MIT"}
metadata	{"requires":{"anyBins":["python","python3"]}}
entrypoint	{"command":"python {baseDir}/scripts/explore.py","args":["--query","{{ with.query | truncate(512) }}","--window-days","{{ with.window_days | default('30') }}","--include","{{ with.include | join(',') if with.include is sequence and with.include is not string else with.include | default('turns,tools,meta_runs,co_occurrences') }}","--top-k","{{ with.top_k | default('10') }}"],"parse":"json","timeout":30}

History Explorer

Read-only helper that inspects OpenClaw.NET session history for downstream workflows (especially meta-skill-creator).

What It Does

Parses a JSON session snapshot and returns structured analytics:

Key	Description
turns	Turn count, role distribution (user vs assistant), time span, recent turn previews
tools	Tool invocation frequency, top tools, tool co-occurrence in the same turn
meta_runs	Meta-skill execution history: skill name, status, step counts, failure codes
co_occurrences	Skill/tool pairs that appear together across turns
placeholder	Emitted when no session data is available; downstream workflows treat this as a signal to rely on user intent only

Input Contract

The script expects JSON session data on stdin. The calling agent should pipe a JSON object matching the Session schema — specifically:

{
  "id": "session-guid",
  "history": [
    { "role": "user", "content": "...", "timestamp": "..." },
    { "role": "assistant", "content": "...", "timestamp": "...", "toolCalls": [...] }
  ],
  "metaRunHistory": [
    {
      "runId": "...", "skillName": "...", "status": "completed",
      "startedAtUtc": "...", "completedAtUtc": "...",
      "stepResults": [
        { "id": "...", "kind": "...", "status": "...", "durationMs": 123 }
      ]
    }
  ]
}

Output Contract

Always returns a JSON object. When session data is available, includes the requested analytics keys. When unavailable or unparseable, returns a single placeholder key so downstream workflows degrade deterministically.

When to Use

• Before running meta-skill-creator: feed co-occurrence and meta-usage data into the creator's proposal draft
• When the user asks "what skills did I use recently" or "show my session history"
• When debugging: inspect recent tool failures or meta-run error codes
• When the agent needs to recall conversation context from earlier turns

Limitations

• Read-only; never mutates session state
• Depends on the agent passing session JSON via stdin; does not access the persistence layer directly
• window_days filtering is best-effort on the timestamp field
• Session snapshots may be truncated by the agent for token budget reasons