Conversation Miner - Extract Unlogged Skills from Past Sessions

Scan past Claude Code conversations to discover critical patterns, workflows, and knowledge that were never formally logged as skills or memories. A person explains the same workaround three times, corrects the same misunderstanding twice, or fights through a debugging session that never turns into a memory — this skill's job is to notice that and turn it into something a future session can find.

When to Use

• Periodic knowledge-base audit (whatever cadence works for you — weekly, monthly, or only when asked)
• After noticing repeated questions across sessions
• When asked "what patterns are we missing?"
• Before major refactoring, to capture tribal knowledge

There is no bundled slash command or cron job for this — invoke the skill directly ("mine my last 30 days of conversations", "mine conversations about authentication") and it runs the steps below in that turn. If you want it running on a schedule, wire it into your own cron or into Claude Code's scheduled-task feature yourself; nothing here does that automatically.

---

What It Mines

Pattern	Signal	Action
Repeated questions	Same question asked 3+ times	Create FAQ or skill
Multi-step workflows	Sequential tool calls with explanation	Create workflow skill
Hard-won solutions	Long debugging → resolution	Create memory + skill
"Always do X before Y"	Causal patterns	Create checklist skill
Corrections	"Actually, what I meant was..."	Create/update an intent entry

---

Mining Algorithm

Step 1: Locate Conversation Logs

Claude Code writes real session history to ~/.claude/projects/<project-slug>/*.jsonl (respecting CLAUDE_CONFIG_DIR if it's set) — one folder per project you've worked in, one file per session, JSON Lines format (one JSON object per line). There is no ~/.claude/conversations folder and no .json (non-JSONL) format — don't look for either.

This plugin already ships a script that reads these files correctly: <plugin>/scripts/memory-search.js (find the plugin folder with alignment-harness paths). Reuse its approach rather than re-deriving it:

# List every project's session files, newest first
ls -1dt ~/.claude/projects/*/ 2>/dev/null

# Within a project folder, each *.jsonl file is one session.
# Filter to a date window with mtime, e.g. sessions touched in the last 30 days:
find ~/.claude/projects -name '*.jsonl' -mtime -30

To scan a single topic across all projects, grep the raw files first to shortlist candidates before parsing JSON (much cheaper than parsing everything):

grep -l -i "authentication" ~/.claude/projects/*/*.jsonl

Step 2: Parse Each Line and Extract the Real Text

Each line is a JSON object. The text you want to pattern-match lives at message.content, which is either a plain string or an array of content blocks (only {type: "text", text: "..."} blocks count — skip tool calls and tool results). Concretely, for each line:

1. JSON.parse(line) — skip the line if that throws (some lines are huge tool outputs; skip anything absurdly long before parsing, e.g. >200,000 chars).
2. Read entry.message; skip if role is not user or assistant.
3. If content is a string, that's your text. If it's an array, join the .text of every block where type === "text".
4. Keep entry.timestamp and the session file's name (its id) attached to every match — a finding is only useful if it can point back at exactly which session and date it came from.

Step 3: Score and Rank Candidates

Pattern-match the extracted text (not the raw JSON) against signals like:

• Repeated questions: the same question-shaped sentence recurring across multiple sessions
• Multi-step workflows: "first... then... finally" / "step 1... step 2..." explanations
• Insight markers: "the trick is...", "the key insight is..."
• Corrections: "actually, what I meant...", "no, what I want/need is..."
• Debugging resolutions: "finally found/fixed/solved...", "the issue/problem/bug was..."

SKILL_SCORE = (frequency × recency × complexity) / existing_coverage

Where:
  frequency = times pattern appeared across distinct sessions
  recency = decay factor (recent = higher)
  complexity = length/depth of the explanation
  existing_coverage = 0 if nothing already covers it, 0.5 if partially covered, 1 if fully covered

If you find only one or two sessions total, say so plainly ("I found 2 sessions, not enough to see a repeated pattern yet") rather than reporting a "3+ occurrence" pattern you can't actually back with more than one occurrence.

---

Output Format

Conversation Mining Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Period: Last 30 days | Sessions scanned: 47 | Projects: 3

TOP UNLOGGED PATTERNS

1. [Score: 8.5] "How to test a gated feature as different account tiers"
   Frequency: 7 occurrences across 4 sessions
   Pattern: Multi-step workflow
   Existing coverage: Partial (a user-simulator tool exists, workflow undocumented)
   Sessions: <session-id-1> (2026-08-02), <session-id-2> (2026-08-14), ...

   Proposed: create a skill documenting the exact steps found in those sessions

2. [Score: 7.2] "Why does the session expire when..."
   Frequency: 5 occurrences
   Pattern: repeated question → explanation
   Existing coverage: none

   Proposed: create a memory or intent entry with the causes, so the next
   session answers it from that instead of re-deriving it

ACTIONS RECOMMENDED:
  - N new skills to create
  - N memories to log
  - N intent entries to update

---

Turning a Finding Into Something Future Sessions Can Use

Once you've identified a pattern worth keeping, write it somewhere a future session will actually look:

• If this repo has a memory-logging skill set up (for example /log-new-mems-in-swarm, if it and its backing store are configured), use it as written.
• Otherwise, write the finding as a markdown file under the folder printed by alignment-harness records mined-patterns — one file per finding, with the trigger condition, the lesson, a confidence estimate, and the session ids/dates it came from. Tell the person the path so they can find it later.

For a finding about intended UX/behavior rather than a workflow trick:

• If an intent-tracking skill is set up (for example /intent-db or /intent, if configured for this project), propose the intent through it as it documents.
• Otherwise, write it as a markdown file under alignment-harness records intents with the same shape: trigger condition, what should happen, and where the evidence for it came from.

Never call a private script path directly (no $AGENT_SWARM_PATH/..., no hardcoded ~/.codex/... paths) — those belong to one person's machine. Use the skill if it's there; use the local records folder if it isn't.

---

Privacy & Security

• Only mines local conversation logs already on this machine
• Never sends conversation content externally
• A report should extract patterns and short snippets with their source, not paste entire raw sessions
• Respects .gitignore for any logged artifacts