Empower your AI agent to search, filter, and analyze its own historical conversation logs and usage metrics.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install mh-session-logs
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install mh-session-logs using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is session-logs?
The session-logs skill is a powerful utility designed for developers and power users who need to bridge the gap between current interactions and historical context. By providing a structured way to query the local storage of an agent, this addition to your library of Openclaw Skills allows for deep introspection into past sessions. It leverages standard Unix utilities to parse through JSONL files, ensuring that even large conversation histories remain searchable and accessible.
This skill is particularly valuable for maintaining continuity in long-running projects where an agent might need to recall specific decisions, code snippets, or instructions given in previous threads. Beyond simple recall, it serves as a diagnostic tool for monitoring agent performance, token consumption, and the financial cost of individual sessions.
session-logs Use Cases
- Retrieving technical details or code snippets from older parent conversations.
- Conducting a keyword search across all historical interactions to find specific references.
- Generating daily or session-based cost summaries to monitor API spend.
- Analyzing tool usage patterns to optimize agent workflows.
- Investigating agent behavior by reviewing full transcripts including thinking blocks and tool results.
How session-logs Works
- The AI agent identifies a request that requires information from outside the current active context.
- The skill points the agent to the specific directory located at ~/.openclaw/agents/
/sessions/. - The agent utilizes jq to parse the JSONL formatted logs, which contain structured data for every message and tool interaction.
- If a broad search is required, the agent uses ripgrep (rg) to scan multiple session files simultaneously for specific phrases.
- The filtered results are then synthesized and presented back to the user or used to inform the current task.
session-logs Setup
To use this skill effectively, ensure your environment has the necessary binary dependencies installed. The Openclaw Skills framework requires these for processing the log files.
# Install jq and ripgrep on Ubuntu/Debian
sudo apt-get update && sudo apt-get install jq ripgrep
# Install on macOS using Homebrew
brew install jq ripgrep
No additional configuration is needed as the skill automatically detects the session path based on the agentId provided in the system runtime.
session-logs Data Schema & Taxonomy
The session-logs skill interacts with two primary file types in the agent's storage directory:
| File Type | Purpose |
|---|---|
sessions.json |
An index file mapping session keys (from platforms like Discord or WhatsApp) to internal session IDs. |
<session-id>.jsonl |
An append-only log file containing the full transcript of a specific session. |
JSONL Message Structure
Each line in a .jsonl file is a valid JSON object containing:
type: Indicates if the entry is a "session" metadata block or a "message".timestamp: ISO-8601 timestamp of the event.message.role: The entity speaking (user, assistant, or toolResult).message.content[]: An array of content blocks, including text and tool calls.message.usage.cost.total: The calculated cost for that specific interaction.
session-logs Advanced Features
- Multi-session keyword search using rg to find relevant context without knowing the session ID.
- Automated cost aggregation to provide a daily financial summary of AI operations.
- Tool usage breakdown to see which Openclaw Skills are being triggered most frequently.
- Low-noise text extraction scripts that strip away metadata to focus on human-readable dialogue.
- Support for identifying deleted sessions via the .deleted timestamp suffix.
SKILL.md
Loading
Related Openclaw Skills
OpenAI Whisper (CLI)
A high-performance local speech-to-text engine that transcribes audio files without requiring an internet connection or API keys.
OpenAI Whisper API Transcription
A command-line utility for high-accuracy audio transcription leveraging the OpenAI Whisper API via Openclaw Skills.
Obsidian Vault Automation
A powerful integration for managing Obsidian vaults, enabling automated note creation, searching, and link-safe refactoring via the command line.
Notion
A professional-grade integration for Openclaw Skills to programmatically manage Notion pages, data sources, and content blocks.
Summarize
A high-performance CLI tool for extracting text and generating concise summaries from web links, videos, and local documents.
Things 3 CLI for macOS
A powerful macOS integration that enables AI agents to read from and write to the Things 3 task manager database and URL scheme.
Featured*
