How do I install the Session Mining skill?

Run npx skillmds@latest add haowjy/session-mining in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Session Mining safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Session Mining?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Session Mining free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Session Mining?

haowjy (@haowjy) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Session Mining by haowjy — Agent Skill

Name: Session Mining
Author: haowjy

File contents

session-mining

Why Mining Matters

Design decisions, rejected alternatives, and discovered constraints often live in conversation instead of code or docs. Compaction makes that context expensive to recover later, so mine it before the next implementation or documentation step starts.

Recover From the Top-Level Session First

Start from the top-level conversation. $MERIDIAN_CHAT_ID points to the primary session at the root of the chat tree, regardless of how deep in the spawn tree you are. That root context holds the primary's decisions and framing: usually the highest-leverage read.

Use a recent-context read first, then widen or anchor only if needed:

meridian session log "$MERIDIAN_CHAT_ID" --tail 20

Bare meridian session log "$MERIDIAN_CHAT_ID" reads the last 5 interaction entries from the current segment with safe previews. Navigation is segment-local by default: --from/--before/--around are ordinals inside the selected segment, defaulting to the current one. Entry 0 of any segment is its setup slot (prologue/handoff); reach it with --from 0 --limit 1. Use --segment previous|current|N to switch segments, --full for the full selected segment (entry 0 included), --no-truncate for complete content, and --around N --context M for a deterministic window around a known entry.

Reach for --global only when you need one flat stream across all segments (every segment's entry 0 included, with unique global ordinals starting at 0). It conflicts with --segment and requires --from/--before/--around. Prefer segment-local navigation: it stays stable across compactions.

Search instead of paging when you know what you're looking for:

meridian session search "decision text" "$MERIDIAN_CHAT_ID"
meridian session search "auth" --work <work-id>     # scope to a work item
meridian session search "shape" --workspace         # current project + workspace

Each hit prints a deterministic Open: command: run it to jump straight to the entry instead of recomputing windows.

Delegate Bulk Reading, Don't Inline It

When the question spans long histories or multiple sessions, spawn @session-miner for transcript mining and synthesis. That keeps your context window focused on decisions instead of raw transcript paging.

meridian spawn -a session-miner \
  --prompt-file session-mine.md

If you are the @session-miner, mine directly rather than spawning recursively.

Discover Sessions Per Work Item

When work spans interruptions, reopenings, or multi-day execution, list all related sessions before mining. Reading only the current session misses prior decisions.

meridian work sessions <work_id> --all

When to Skip Mining Entirely

Skip mining if the spawning prompt already includes the needed rationale, or if current design/plan artifacts already capture the decisions you need. Skim artifacts first, and mine only the gaps.

---name: session-miningdescription: Use when recovering decisions or context from conversation history: session log navigation, transcript delegation.---# session-mining## Why Mining MattersDesign decisions, rejected alternatives, and discovered constraints often live in conversation instead of code or docs. Compaction makes that context expensive to recover later, so mine it before the next implementation or documentation step starts.## Recover From the Top-Level Session FirstStart from the top-level conversation. `$MERIDIAN_CHAT_ID` points to the primary session at the root of the chat tree, regardless of how deep in the spawn tree you are. That root context holds the primary's decisions and framing: usually the highest-leverage read.Use a recent-context read first, then widen or anchor only if needed:```bashmeridian session log "$MERIDIAN_CHAT_ID" --tail 20```Bare `meridian session log "$MERIDIAN_CHAT_ID"` reads the last 5 interactionentries from the current segment with safe previews. Navigation is**segment-local by default**: `--from/--before/--around` are ordinals insidethe selected segment, defaulting to the current one. Entry `0` of any segmentis its setup slot (prologue/handoff); reach it with `--from 0 --limit 1`. Use`--segment previous|current|N` to switch segments, `--full` for the fullselected segment (entry 0 included), `--no-truncate` for complete content, and`--around N --context M` for a deterministic window around a known entry.Reach for `--global` only when you need one flat stream across all segments(every segment's entry 0 included, with unique global ordinals starting at 0).It conflicts with `--segment` and requires `--from/--before/--around`. Prefersegment-local navigation: it stays stable across compactions.Search instead of paging when you know what you're looking for:```bashmeridian session search "decision text" "$MERIDIAN_CHAT_ID"meridian session search "auth" --work <work-id> # scope to a work itemmeridian session search "shape" --workspace # current project + workspace```Each hit prints a deterministic `Open:` command: run it to jump straight tothe entry instead of recomputing windows.## Delegate Bulk Reading, Don't Inline ItWhen the question spans long histories or multiple sessions, spawn @session-miner for transcript mining and synthesis. That keeps your context window focused on decisions instead of raw transcript paging.```bashmeridian spawn -a session-miner \ --prompt-file session-mine.md```If you are the @session-miner, mine directly rather than spawning recursively.## Discover Sessions Per Work ItemWhen work spans interruptions, reopenings, or multi-day execution, list all related sessions before mining. Reading only the current session misses prior decisions.```bashmeridian work sessions <work_id> --all```## When to Skip Mining EntirelySkip mining if the spawning prompt already includes the needed rationale, or if current design/plan artifacts already capture the decisions you need. Skim artifacts first, and mine only the gaps.

Frequently asked questions

Session Mining