History learning
Turns what the user has already told agents, across every tool and project, into skills that
stop the same mistakes from recurring. The pipeline is deterministic until the last step; the
only model involvement is a reviewing agent (you) reading a small, redacted, budgeted digest.
HL="node ~/agent-skills/history-learning/scripts/hl.mjs"
Hard rules
- Read-only history. Never write to, move, or "clean up" any transcript or database. SQLite
stores are opened read-only; OpenCode's
credential/account tables are never queried.
The only exception is archiving, when the user asks for it after learning (archive.md).
- Consent first. Sources start disabled. Ask the user before
$HL consent --enable, and
before $HL consent --model allow. Reading a digest is sending excerpts to a model.
- Private state. Inventory, evidence, clusters, digests and reports live in the state
directory. Never copy them, quotes from them, project names or paths into a public repo.
- No raw archives anywhere. Never upload transcripts or the state directory to any service.
- Proposals, not publications. Skill changes go on a local
learning/<date> branch for the
user to review. Never push, merge, or edit installed skill directories directly.
- Do not skip silently. Every store found is reported, including unsupported and empty ones.
Workflow
- Discover (no consent needed):
$HL inventory then $HL catalog. Read
reports/coverage.md (sessions by agent, project, month; duplicates; unsupported stores)
and reports/catalog.md (existing skills and instruction files). Sources: sources.md.
- Ask the user which sources to enable, whether a reviewing model may read digests and
with what token budget, and where project-specific skills belong. Record the answers:
$HL consent --enable claude-code,codex --model allow --budget 60000 [--redact "Acme,Bob"].
- Extract and cluster locally:
$HL extract then $HL cluster. Only human-typed turns from
interactive sessions; automated (claude -p, codex exec) and subagent sessions are
excluded. How signals, redaction and the evidence bar work: extraction.md.
- Digest:
$HL digest. One file per category under digest/, capped by the budget.
- Synthesize by reading the digest and the catalog, following
synthesis.md: improve
existing skills before creating new ones, separate global from project scope, keep cluster
ids as evidence and a confidence level on every rule, reject one-off or temporary asks.
Write proposals.json to the state directory, run $HL support (it recomputes every
rule's sessions and confidence from its clusters and fails on overstated or unknown ones),
then $HL mark --digest.
- Stage the changes on a
learning/<date> branch (in a separate worktree when the repo's
main checkout is shared with other agents), write each skill's evidence file with
$HL support --write, run scripts/validate.sh, commit locally, and produce $HL report. Review, approval, sync and
undo: review.md.
- Archive (only when the user asks): zip sessions older than N days with
scripts/Archive-ChatHistory.ps1, which verifies every file by hash before deleting the
original and never touches memory folders or the Codex thread databases. Learned evidence
survives. Order, /insights and Claude's cleanupPeriodDays: archive.md.
Taste (UI look, motion, writing voice) is mostly described, not commanded, so cue-based
extraction under-reads it. For such a subject run a topic pass, $HL topic <name> --categories ui-visual,animation --match <vocabulary> --budget <n>, read the whole digest, draft rules by
judgement, then give each rule a keyword pattern and check its support with $HL topic-support
(see "Topic passes" in synthesis.md).
Incremental learning
$HL learn re-inventories, extracts only sessions whose files changed, re-clusters, and (if
model review is consented) writes a digest containing only new or grown clusters. It is safe to
run from a night loop or a scheduled task because it makes no model calls and writes only to
the state directory. A human-started agent session then performs step 5 on that digest.
Automatic daily capture
node scripts/install.mjs --learning-hooks on (from the repo root; off removes it all) sets up:
- A daily run (
hl schedule on|off|status [--at HH:MM], default 03:30): a Task Scheduler
task on Windows, a marked crontab line elsewhere. It runs hl auto-run --background, a
detached worker that runs learn and re-runs every saved topic pass (topics/<name>.json,
e.g. ui-taste) with its own parameters. Sessions left open for days are covered, because
learn re-reads any transcript that changed. About a minute, local, no model calls, nothing
outside the state directory. Logs: auto/logs/.
- A SessionStart hook in every Claude profile. If no run happened in the last 26 hours
(machine off at run time), it starts one. On new sessions, at most once a day, it tells the
user how many new or grown clusters and new taste statements wait for review. A failed run is
reported at every start until a run succeeds, and is not retried more than once a day.
Capture used to run from a SessionEnd hook; the installer removes that entry, and hl hook session-end is a no-op for any profile that still has it.
When the user asks to review it: $HL pending --write (writes topics/<name>.new.md with only
the statements first seen since the last review), then synthesis step 5 on the digest plus those
delta files, then stage as in step 6. $HL mark --digest sets the review date that both the
cluster digest and the topic deltas count from.
ShadowClone
ShadowClone natively learns from ~/.claude, Codex, OpenCode, Pi, the Cursor CLI and the
Antigravity CLI. This skill covers the stores it does not (Claude profiles such as
~/.claude-work, the Cursor IDE database and agent transcripts, Antigravity IDE, Kiro, Qwen)
and the cross-agent deduplication. How to run both without letting either publish or edit
agent configs: shadowclone.md. On native Windows ShadowClone 0.0.34 cannot initialise its
store (an ownership check that needs POSIX uids); hl covers every source there.
Commands
| Command |
Effect |
inventory |
metadata-only scan of every store; inventory.json, reports/coverage.md |
catalog |
existing skills and instruction files; reports/catalog.md |
consent [--enable a,b] [--disable c] [--model allow|deny] [--budget n] [--redact t] |
record consent |
extract [--full] [--limit n] |
redacted signal statements, changed sessions only |
cluster |
near-duplicate clusters with confidence |
digest [--budget n] [--all] |
budgeted per-category digest of new or grown clusters |
learn |
the incremental pipeline above |
evidence <cluster-id> |
every redacted statement behind a cluster |
mark <ids>|--digest |
clusters reviewed; omitted from the next digest |
support [--write] |
per-rule sessions, projects and computed confidence; --write emits each skill's evidence file |
topic <name> --categories a,b [--match re] [--budget n] |
every statement on one subject, cue or not; budgeted topics/<name>.md |
topic-support <name> --patterns f [--write f] |
sessions and projects behind rules drafted from a topic, counts only |
report |
reports/learning.md and refreshed coverage |
forget [--source s] |
delete derived evidence (all, or one source); history untouched |
status |
consent and state summary |
pending [--write] |
what waits for review; --write emits topics/<name>.new.md deltas |
schedule on|off|status [--at HH:MM] |
the daily run (Task Scheduler or cron); installed by --learning-hooks on |
auto-run [--background] |
learn plus saved topic passes; --background detaches with a log |
hook session-start |
SessionStart hook (JSON on stdin): review notice, catch-up of a missed day |
1---2name: history-learning3description: Learn durable preferences, corrections, decisions and working patterns from historical coding-agent conversations (Claude Code, Codex, Cursor, OpenCode, Antigravity, Kiro, Qwen) and turn them into reviewed, evidence-backed skill updates. Use when asked to learn from past conversations or chat history, mine repeated corrections or preferences, update skills from experience, run incremental history learning, or audit what has been learned. Read-only over history, consent-gated per source, redacts before any model sees text, and never publishes or overwrites skills on its own.4license: MIT5metadata:6 source: https://skillmd.com/skills/amsborse/history-learning7 aliases: "learn from past conversations, mine my chat history, incremental history learning, audit what has been learned"8 keywords: "history, learning, conversations, transcripts, preferences, corrections"9 composes: "manage-skills"10 requires: "shell"11 risk: "medium"12 version: "1.0.0"13 state: "~/.agent-history-learning (private; never inside a repository)"14---1516# History learning1718Turns what the user has already told agents, across every tool and project, into skills that19stop the same mistakes from recurring. The pipeline is deterministic until the last step; the20only model involvement is a reviewing agent (you) reading a small, redacted, budgeted digest.2122```sh23HL="node ~/agent-skills/history-learning/scripts/hl.mjs"24```2526## Hard rules27281. **Read-only history.** Never write to, move, or "clean up" any transcript or database. SQLite29 stores are opened read-only; OpenCode's `credential`/`account` tables are never queried.30 The only exception is archiving, when the user asks for it after learning (`archive.md`).312. **Consent first.** Sources start disabled. Ask the user before `$HL consent --enable`, and32 before `$HL consent --model allow`. Reading a digest *is* sending excerpts to a model.333. **Private state.** Inventory, evidence, clusters, digests and reports live in the state34 directory. Never copy them, quotes from them, project names or paths into a public repo.354. **No raw archives anywhere.** Never upload transcripts or the state directory to any service.365. **Proposals, not publications.** Skill changes go on a local `learning/<date>` branch for the37 user to review. Never push, merge, or edit installed skill directories directly.386. **Do not skip silently.** Every store found is reported, including unsupported and empty ones.3940## Workflow41421. **Discover** (no consent needed): `$HL inventory` then `$HL catalog`. Read43 `reports/coverage.md` (sessions by agent, project, month; duplicates; unsupported stores)44 and `reports/catalog.md` (existing skills and instruction files). Sources: `sources.md`.452. **Ask** the user which sources to enable, whether a reviewing model may read digests and46 with what token budget, and where project-specific skills belong. Record the answers:47 `$HL consent --enable claude-code,codex --model allow --budget 60000 [--redact "Acme,Bob"]`.483. **Extract and cluster** locally: `$HL extract` then `$HL cluster`. Only human-typed turns from49 interactive sessions; automated (`claude -p`, `codex exec`) and subagent sessions are50 excluded. How signals, redaction and the evidence bar work: `extraction.md`.514. **Digest**: `$HL digest`. One file per category under `digest/`, capped by the budget.525. **Synthesize** by reading the digest and the catalog, following `synthesis.md`: improve53 existing skills before creating new ones, separate global from project scope, keep cluster54 ids as evidence and a confidence level on every rule, reject one-off or temporary asks.55 Write `proposals.json` to the state directory, run `$HL support` (it recomputes every56 rule's sessions and confidence from its clusters and fails on overstated or unknown ones),57 then `$HL mark --digest`.586. **Stage** the changes on a `learning/<date>` branch (in a separate worktree when the repo's59 main checkout is shared with other agents), write each skill's evidence file with60 `$HL support --write`, run `scripts/validate.sh`, commit locally, and produce `$HL report`. Review, approval, sync and61 undo: `review.md`.627. **Archive** (only when the user asks): zip sessions older than N days with63 `scripts/Archive-ChatHistory.ps1`, which verifies every file by hash before deleting the64 original and never touches memory folders or the Codex thread databases. Learned evidence65 survives. Order, `/insights` and Claude's `cleanupPeriodDays`: `archive.md`.6667Taste (UI look, motion, writing voice) is mostly described, not commanded, so cue-based68extraction under-reads it. For such a subject run a topic pass, `$HL topic <name> --categories69ui-visual,animation --match <vocabulary> --budget <n>`, read the whole digest, draft rules by70judgement, then give each rule a keyword pattern and check its support with `$HL topic-support`71(see "Topic passes" in `synthesis.md`).7273## Incremental learning7475`$HL learn` re-inventories, extracts only sessions whose files changed, re-clusters, and (if76model review is consented) writes a digest containing only new or grown clusters. It is safe to77run from a night loop or a scheduled task because it makes no model calls and writes only to78the state directory. A human-started agent session then performs step 5 on that digest.7980## Automatic daily capture8182`node scripts/install.mjs --learning-hooks on` (from the repo root; `off` removes it all) sets up:8384- **A daily run** (`hl schedule on|off|status [--at HH:MM]`, default 03:30): a Task Scheduler85 task on Windows, a marked crontab line elsewhere. It runs `hl auto-run --background`, a86 detached worker that runs `learn` and re-runs every saved topic pass (`topics/<name>.json`,87 e.g. `ui-taste`) with its own parameters. Sessions left open for days are covered, because88 `learn` re-reads any transcript that changed. About a minute, local, no model calls, nothing89 outside the state directory. Logs: `auto/logs/`.90- **A SessionStart hook** in every Claude profile. If no run happened in the last 26 hours91 (machine off at run time), it starts one. On new sessions, at most once a day, it tells the92 user how many new or grown clusters and new taste statements wait for review. A failed run is93 reported at every start until a run succeeds, and is not retried more than once a day.9495Capture used to run from a SessionEnd hook; the installer removes that entry, and `hl hook96session-end` is a no-op for any profile that still has it.9798When the user asks to review it: `$HL pending --write` (writes `topics/<name>.new.md` with only99the statements first seen since the last review), then synthesis step 5 on the digest plus those100delta files, then stage as in step 6. `$HL mark --digest` sets the review date that both the101cluster digest and the topic deltas count from.102103## ShadowClone104105ShadowClone natively learns from `~/.claude`, Codex, OpenCode, Pi, the Cursor CLI and the106Antigravity CLI. This skill covers the stores it does not (Claude profiles such as107`~/.claude-work`, the Cursor IDE database and agent transcripts, Antigravity IDE, Kiro, Qwen)108and the cross-agent deduplication. How to run both without letting either publish or edit109agent configs: `shadowclone.md`. On native Windows ShadowClone 0.0.34 cannot initialise its110store (an ownership check that needs POSIX uids); `hl` covers every source there.111112## Commands113114| Command | Effect |115| --- | --- |116| `inventory` | metadata-only scan of every store; `inventory.json`, `reports/coverage.md` |117| `catalog` | existing skills and instruction files; `reports/catalog.md` |118| `consent [--enable a,b] [--disable c] [--model allow\|deny] [--budget n] [--redact t]` | record consent |119| `extract [--full] [--limit n]` | redacted signal statements, changed sessions only |120| `cluster` | near-duplicate clusters with confidence |121| `digest [--budget n] [--all]` | budgeted per-category digest of new or grown clusters |122| `learn` | the incremental pipeline above |123| `evidence <cluster-id>` | every redacted statement behind a cluster |124| `mark <ids>\|--digest` | clusters reviewed; omitted from the next digest |125| `support [--write]` | per-rule sessions, projects and computed confidence; `--write` emits each skill's evidence file |126| `topic <name> --categories a,b [--match re] [--budget n]` | every statement on one subject, cue or not; budgeted `topics/<name>.md` |127| `topic-support <name> --patterns f [--write f]` | sessions and projects behind rules drafted from a topic, counts only |128| `report` | `reports/learning.md` and refreshed coverage |129| `forget [--source s]` | delete derived evidence (all, or one source); history untouched |130| `status` | consent and state summary |131| `pending [--write]` | what waits for review; `--write` emits `topics/<name>.new.md` deltas |132| `schedule on\|off\|status [--at HH:MM]` | the daily run (Task Scheduler or cron); installed by `--learning-hooks on` |133| `auto-run [--background]` | `learn` plus saved topic passes; `--background` detaches with a log |134| `hook session-start` | SessionStart hook (JSON on stdin): review notice, catch-up of a missed day |