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.
- 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。 - Index first: before analysis-type sub-skills, confirm the index is available (
/indexorindex-builder.py build); to locate a session useindex.db(seeskills/common_paths.py)。 - combo wrap-up: after the main command or sub-skill completes, read
combo_map.jsonfor the corresponding next,suggest only 1–2 next steps, do not output the entire routing table. - 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.
- 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 →
/recapor/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-toolsis merged in only then; for targeted queries useindex-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
/indexbuild the index first → all subsequent searches go through SQLite FTS5, <50mssd-recall.py→ unified Python process, replacing the bash subprocess chain, 5-10x speedup- Incremental cache → unchanged sessions are no longer parsed (mtime check)
--decisionsmarker → 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-miningis a complementary perspective, not a replacement /applyWrite rules without prior user approval → must confirm item by item with y/n/e/a/q/importDo not perform WeChat decryption → WeChat data identification and analysis goes throughwechat-diggersub-skill (comes with read-only queries; key extraction and decryption implementation are not distributed, users must provide their own decrypted database)/optimizeAutomatically 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
/optimizeOutput should by default not contain absolute paths or usernames →skill-gap-finderalready 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.