SuperAPI AI Directory

session-digger

General & other

View repository

Updated 10-16 08:43

About this skill

session-digger

What you said, what you did, what you learned—it's all here. Routing only, no analysis.

Supported environments: Claude Code, Grok Build, Kimi Code, Kimix CLI, Codex, Cursor, ZCode, WorkBuddy, Trae CN, DIM, Reasonix + generic conversation import (/import). Paths and data roots are all detected via environment probing, not bound to fixed local directories.

Sub-skill dispatch protocol (0.9.18)

In keep the four-layer architecture and streamlined main commands under the premise, sub-skills are specialized enhancement layers, not a second kernel.

  1. Specialization first: when user intent highly matches a sub-skill description ,load that sub-skill first, don't just idle with the generic main command.
    Example: "error root cause / intent classification" → deep-analysis; "environment is broken" → env-doctor / native-diag。
  2. Index first: before analysis-type sub-skills, confirm the index is available (/index or index-builder.py build); to locate a session use index.db(see skills/common_paths.py)。
  3. combo wrap-up: after the main command or sub-skill completes, read combo_map.json for the corresponding next,suggest only 1–2 next steps, do not output the entire routing table.
  4. Don't collapse layers: sub-skills do not write to the library on their own, do not replace echolib; L3 proposals (optimize / apply) must be human-reviewed.
  5. Goal: new main routes + tuned sub-skills is better than new main routes + unmounted old sub-skills (path alignment + combo reachability + specialization first).

Path resolution

All commands/scripts use the same set of root directory detection (Forbiddento write to personal repository paths):

SD_ROOT="${SESSION_DIGGER_ROOT:-${CLAUDE_PLUGIN_ROOT:-${HERDR_PLUGIN_ROOT:-}}}"
[[ -z "$SD_ROOT" ]] && SD_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." 2>/dev/null && pwd)"
if [[ -z "$SD_ROOT" || ! -f "$SD_ROOT/scripts/sd-recall.py" ]]; then
  for _c in \
    "$HOME/.agents/skills/session-digger" \
    "$HOME/.claude/plugins/session-digger" \
    "$HOME/.claude/skills/session-digger" \
    "$HOME/.grok/skills/session-digger"
  do
    [[ -f "$_c/scripts/sd-recall.py" ]] && SD_ROOT="$_c" && break
  done
fi

Priority:SESSION_DIGGER_ROOT → host plugin root → relative to this file → common skill install locations. When multiple copies coexist, be sure to export SESSION_DIGGER_ROOT。

Before routing, take a glance: if there's only "help me take a look" or "check it out" with no specific content → ask "check what—session? timeline? lessons learned?". If there's "before" or "last time" but no time/keyword → ask "roughly what time? what keyword do you remember?"

Main commands

What the user said go to
Recall/search a specific topic, how it was done before, recent sessions, topic browsing /recall(absorb /recap、/topics、/topic-scan)
token usage / how much was spent / model consumption /usage
usage review / time-period heatmap / multi-environment habit report /reflect(absorb /trend、/optimize)
find error patterns, retry loops, user corrections, lessons learned /analyze(absorb /lessons)
global overview, memory status /dashboard

After finishing, read combo_map.json to suggest the next step. Do not output the routing process.

/usage — cross-environment token observability

Cross-environment aggregation of each model's billing-level tokens and cache hit rate (notthe product-side quota panel). Collection method (family mode, main/sub not double-counted) and scope:references/usage.md。

/recall Common variants

  • Most recent session summary → /recap or /recall --recap
  • Topic segmentation / theme overview → /topics、/topic-scan
  • Cross-environment search → /recall --agent cross
  • Post-compaction recovery decision points → /recall --decisions

/reflect Common variants

  • Week/month-over-month, tool regression → /trend
  • Cross-session skill gaps, SKILL.md proposals → /optimize
  • HTML usage report → scripts/reflect-report.py

/analyze Common variants

  • Lessons learned / pitfall review → /lessons

Retrieval budget and stop conditions

Reading session history is the easiest action to lose control of: the hits from a single query grow in swaths, and every one of them has to go into context. By default, follow the quotas below.

Action Default quota Stop condition
search --limit 5 Stop once the session is located; don't comb through every hit for one sentence
sessions --limit 20 Stop once the target is located on the timeline
Read messages one by one Single session ≤ 50 messages Stop when two consecutive pages yield no new evidence
Cross-session statistics Aggregate first, then sample Don't page through session by session for statistics
  • Body text and tool output are two separate layers: by default, match only human-written body text. Tool output is a separate facet (facet=TOOL),--include-tools is merged in only then; for targeted queries use index-builder.py search <词> --tools-only. Empirical basis: when merged into default retrieval, a word that appeared only in command output turned 7 of the top-20 lines into tool summaries (35% of the space), while the unique hits it brought back were only 10%.
  • An empty result is not a conclusion: a single empty query only means "there is none in this scope." An empty result prints the scope, index status, and the hit count for the same word in a larger scope—switch scopes as prompted and ask again, and only then draw a conclusion.

Subcommands

The following commands are still available, entered via flags, subcommand files, or dedicated skills (no need to memorize them from the main table):

Lookup table:references/command-map.md(the complete entry point for subcommands / dedicated skills; read it when the main table has no hit).

Sub-skill list (skills/)

Sub-skill Layer When to use
jsonl-core L0–L1 Parsing/recovery/format
deep-analysis L2 Single-session error root cause + intent
experience-synthesis L3 Cross-session lesson distillation
git-mining Bypass Session ↔ git
memory-management L3 Memory lifecycle
skill-insight L3 Skill usage + asset self-check
env-doctor Operations Cross-environment comprehensive diagnosis
native-diag Operations Native command collection (for env-doctor)

Shared paths:skills/common_paths.py(SESSION_DIGGER_DATA_DIR / index.db)。

Architecture (four-layer model)

Layer Script / skill What it does Trust level
0 PARSE echolib/ + jsonl-core Raw transcript → stats (ground truth) Exact
1 INDEX index-builder.py Stats → SQLite(jsonl_path for sub-skills to locate) Rebuildable
2 TREND trend-engine + deep-analysis Aggregation + single-session deep dive Pure / extractive
3 DECISION skill-gap + skill-health + experience-synthesis Proposals require human review Judgment call

Never collapse layers: each has a different cost and a different trust level.

Speed tier

  1. /index build the index first → all subsequent searches go through SQLite FTS5, <50ms
  2. sd-recall.py → unified Python process, replacing the bash subprocess chain, 5-10x speedup
  3. Incremental cache → unchanged sessions are no longer parsed (mtime check)
  4. --decisions marker → extract only decision points, reducing token consumption by 60-80%

DO NOT

  • Create a new skill from scratch → skill-search(full lifecycle backbone: create/audit/optimize/publish)
  • Real-time session monitoring → Claude Code native capability
  • Modify/edit session JSONL files → read-only analysis, do not write raw data
  • Replace git log → git-mining is a complementary perspective, not a replacement
  • /apply Write rules without prior user approval → must confirm item by item with y/n/e/a/q
  • /import Do not perform WeChat decryption → WeChat data identification and analysis goes through wechat-digger sub-skill (comes with read-only queries; key extraction and decryption implementation are not distributed, users must provide their own decrypted database)
  • /optimize Automatically edit SKILL.md → only draft proposals, must be manually applied after user confirmation
  • Trend analysis replacing single-session analysis → trends show direction, single sessions show details; the two are complementary
  • Hardcoding personal machine paths in commands/documents (e.g., a private repository under some user's home directory) → use only Path resolution
  • /optimize Output should by default not contain absolute paths or usernames → skill-gap-finder already desensitized; when paths are needed, explicitly --include-paths

Cache hit rate reporting (mandatory specification)

User-facing cache tables / environment comparisons,report only the session mean hit rate(rate > 0 the arithmetic mean of sessions).

  • Do notoutput Token-weighted hit rate by default (unless the user explicitly requests "weighted by token")
  • Zero cache / no field / unlabeled model / valid sessions < 3 → goes into the exclusion list, not the main table
  • API:echolib.build_cache_hit_tables / mean_cache_hit_rate / cache_rate_eligible
  • Full text:references/cache-report-rules.md

Changelog

Version history (v0.3 → current, including side-line entries) is in CHANGELOG.md. It is no longer inlined here: it accounts for 79% of the length, and this file enters the context in full every time it is activated. To check "what was changed and why" read there.