@jaybeeuu/agent-cortex 2.7.0 → 2.9.0

package/extensions/skill-stats/README.md

@@ -16,7 +16,63 @@ A skill that is *loaded* frequently but *never read* may be burning context budg
 
 ## Data
 
-Usage data is stored in `~/.pi/agent-cortex/skill-usage.json` — a single file across all projects, with per-project breakdowns so you can slice by project.
+Usage data is stored in `~/.pi/agent-cortex/` — global, across all projects, with per-project
+breakdowns so you can slice by project. There are two files, with different fidelity:
+
+| File | Fidelity | Kept for |
+|---|---|---|
+| `skill-usage.json` | Per-skill counters, per-project breakdown, and a 200-event ring of recent events | Until a skill has been unused for ~3 months (existing age-out) |
+| `skill-usage-daily.json` | One record per skill per day: loaded / invoked / read counts and the distinct projects seen that day | 365 days by default, pruned on every write |
+
+The counters answer "what is my all-time shape, and what happened in the last few minutes". The
+daily rollups answer "how has my usage changed over months" without scanning session transcripts.
+The rollups are a second file beside the counters, not a replacement: the counters and their
+200-event ring are unchanged by this feature.
+
+### Retention and size policy
+
+- **Retention window: 365 days by default.** Override it per machine with
+  `AGENT_CORTEX_SKILL_STATS_RETENTION_DAYS` (a positive whole number of days). Invalid values fall
+  back to the default.
+- **Pruning happens on write, not on read.** Every save drops day records older than the window, so a
+  long-lived install can never accumulate more than the window's worth of days. The `timeline` view
+  only reads; it prunes nothing.
+- **Each record is fixed-size.** Counts are numbers, the distinct-project list per skill-day is capped
+  at 50 entries, and a stored project path is truncated to 120 characters, so one skill-day's record
+  cannot grow with the number of events that day or with working-directory depth. Two long paths that
+  share their first 120 characters count as one project.
+- **The file has a hard ceiling of 2,920,000 bytes, enforced on every write.** That is 365 days x 40
+  skills x 200 bytes per skill-day (the counts plus one realistic project path); the 40 sizes the
+  budget and is not a limit on how many skills an install may have. A realistic file is far smaller:
+  994,668 bytes for 40 skills used every day of the window, two events each and a short project path
+  (`/proj/a`), and 1,272,068 bytes for the same usage with a 26-character project path. A retention
+  window longer than 365 days does not raise the ceiling, so the detail it implies is shed by the
+  rule below.
+  When a write would exceed the ceiling, `saveRollups` drops the per-skill-day project lists first —
+  the loaded / invoked / read counts and every day survive, and every number the timeline renders is
+  unchanged. Only if the counts alone exceed the ceiling does it drop the oldest days, continuing the
+  direction pruning already takes. `saveRollups` returns what this write gave up
+  (`shedProjectLists`, `droppedDays`) and the size it wrote, and it keeps running totals in the file
+  under `shed`, so `/skill-stats timeline` reports the loss after a reload rather than leaving the
+  user to find out only by looking. The rendered line names the day of the most recent shedding
+  write, how many project lists and how many days went in total, and the ceiling that forced it.
+- **A ceiling shed moves the reported start; ordinary pruning does not.** When shedding drops whole
+  days, those days were inside the retention window, so `since` moves to the oldest day the file
+  still holds and the header can never claim a day that was deleted. Days that age out of the window
+  are different: they were real history and the rendered retention line explains them, so `since`
+  keeps the first-ever day.
+- **The file is written minified** — it is read by the extension, not by a human. The suite fills
+  every cap at once (40 skills x 365 days x 50 project paths), asserts the 22,033,268 raw bytes are
+  written as at most 2,920,000, and asserts a second year of data leaves the file byte-for-byte
+  unchanged.
+
+### History before the rollups
+
+Rollups start with the first skill event recorded after this version was installed. Anything earlier
+is reported as **unavailable**, not as zero usage, and no data point is invented for it. A ceiling
+shed that deletes days reports on the same screen, so a moved start is explained rather than silent.
+Backfilling from old session transcripts is a possible follow-up, and deliberately not part of this
+feature.
 
 ## Installation
 
@@ -43,7 +99,8 @@ ln -sf $(pwd)/extensions/skill-stats ~/.pi/agent/extensions/skill-stats
 |---|---|
 | `/skill-stats` | Show usage dashboard with per-project slicing |
 | `/skill-stats --project ./relative/path` | Filter to a specific project |
-| `/skill-usage-reset` | Wipe all recorded data |
+| `/skill-stats timeline` | Per-day, per-week and per-month counts and distinct skills, from the daily rollups |
+| `/skill-usage-reset` | Wipe all recorded data, counters and rollups |
 
 ## Raw data
 
@@ -59,7 +116,7 @@ The JSON file at `~/.pi/agent-cortex/skill-usage.json` contains the full record:
       "readCount": 18,
       "lastUsed": "2026-06-07T...",
       "byProject": {
-        "/home/jaybeeuu/src/agent-cortex": {
+        "/home/user/projects/app": {
           "loadedCount": 40,
           "invokedCount": 3,
           "readCount": 16,
@@ -72,3 +129,27 @@ The JSON file at `~/.pi/agent-cortex/skill-usage.json` contains the full record:
   "lastUpdated": "2026-06-07T..."
 }
 ```
+
+The rollups in `~/.pi/agent-cortex/skill-usage-daily.json` are minified and keyed by day:
+
+```json
+{
+  "version": 1,
+  "since": "2026-06-01",
+  "days": {
+    "2026-06-07": {
+      "bd-tool": { "loaded": 2, "invoked": 1, "read": 3, "projects": ["/home/user/projects/app"] }
+    }
+  },
+  "shed": { "on": "2026-06-08", "projectLists": 14600, "days": 0 }
+}
+```
+
+`since` is the first day a rollup is held for. It survives pruning, so the timeline can say where
+the recorded history starts; it moves forward only when a ceiling shed deletes days, which nothing
+else explains.
+
+`shed` appears only after a write had to give up detail for the size ceiling, and holds the totals
+dropped by shedding (`projectLists`, `days`) plus the day of the most recent such write. A file
+written before this field existed has no `shed` key, and such a file loads and renders unchanged:
+an absent record means nothing was shed.

package/extensions/skill-stats/index.ts

@@ -4,13 +4,56 @@ import path from "node:path";
 // Re-export public API for tests and consumers
 export { type ProjectCounts, type SkillStats, type UsageStore, type RawEvent, loadStore, saveStore, ageOutStore } from "./store.js";
 export { recordUsage } from "./record.js";
+export {
+  type DaySkillCounts,
+  type Granularity,
+  type RollupStore,
+  type SaveRollupsResult,
+  type ShedRecord,
+  type TimelineBucket,
+  DEFAULT_RETENTION_DAYS,
+  MAX_PROJECT_PATH_CHARS,
+  MAX_PROJECTS_PER_DAY,
+  MAX_ROLLUP_FILE_BYTES,
+  RETENTION_ENV,
+  bucketKey,
+  dayKey,
+  loadRollups,
+  oldestDay,
+  pruneRollups,
+  recordDailyUsage,
+  retentionCutoff,
+  retentionDays,
+  rollupFilePath,
+  saveRollups,
+  shiftDay,
+  timeline,
+} from "./rollup.js";
+export { formatTimeline, isTimelineRequest } from "./timeline.js";
 export { type SkillRecord, globalSkillDirs, scanSkills, extractSkillName, discoverProjectSkills, resolveSkillFromPath } from "./discover.js";
 export { formatTable } from "./format.js";
 
-import { loadStore, saveStore } from "./store.js";
+import { loadStore, saveStore, type RawEvent } from "./store.js";
 import { recordUsage } from "./record.js";
 import { resolveSkillFromPath, globalSkillDirs, scanSkills, discoverProjectSkills } from "./discover.js";
 import { formatTable } from "./format.js";
+import { loadRollups, recordDailyUsage, saveRollups } from "./rollup.js";
+import { formatTimeline, isTimelineRequest } from "./timeline.js";
+
+/**
+ * Record one usage event into the long-range rollups. The counters and the
+ * recent-event ring in the store are written by `recordUsage`/`saveStore` as
+ * before; this adds the per-day record beside them.
+ */
+function recordRollup(
+  skillName: string,
+  source: RawEvent["source"],
+  project: string,
+): void {
+  const rollups = loadRollups();
+  recordDailyUsage(rollups, skillName, source, project);
+  saveRollups(rollups);
+}
 
 // ── Extension entry point ─────────────────────────────────────────────────────
 
@@ -32,12 +75,16 @@ export default function (pi: ExtensionAPI) {
     if (!skills?.length) return;
 
     const store = loadStore();
+    const rollups = loadRollups();
     const project = ctx.cwd;
     for (const skill of skills) {
       const name = typeof skill === "string" ? skill : skill.name;
-      if (name) recordUsage(store, name, "loaded", project);
+      if (!name) continue;
+      recordUsage(store, name, "loaded", project);
+      recordDailyUsage(rollups, name, "loaded", project);
     }
     saveStore(store);
+    saveRollups(rollups);
   });
 
   // ── 2. Track /skill:name invocations ──────────────────────────────────
@@ -48,6 +95,7 @@ export default function (pi: ExtensionAPI) {
     const store = loadStore();
     recordUsage(store, m[1], "invoked", ctx.cwd);
     saveStore(store);
+    recordRollup(m[1], "invoked", ctx.cwd);
   });
 
   // ── 3. Track SKILL.md reads by the LLM ────────────────────────────────
@@ -64,6 +112,7 @@ export default function (pi: ExtensionAPI) {
     const store = loadStore();
     recordUsage(store, skillName, "read", ctx.cwd);
     saveStore(store);
+    recordRollup(skillName, "read", ctx.cwd);
   });
 
   // ── 4. Track turns ────────────────────────────────────────────────────
@@ -88,8 +137,17 @@ export default function (pi: ExtensionAPI) {
   // ── 5. /skill-stats command ───────────────────────────────────────────
   pi.registerCommand("skill-stats", {
     description:
-      "Show skill usage stats. Filter by project: /skill-stats --project <path>",
+      "Show skill usage stats. Filter by project: /skill-stats --project <path>. Long-range history: /skill-stats timeline",
     handler: async (args, ctx) => {
+      // The timeline view reads the daily rollups and nothing else — not the
+      // counters, and never a session transcript.
+      if (isTimelineRequest(args)) {
+        const output = formatTimeline(loadRollups());
+        ctx.ui.notify("Skill usage timeline from daily rollups.", "info");
+        console.log(output);
+        return;
+      }
+
       const store = loadStore();
 
       let projectFilter: string | null = null;
@@ -216,6 +274,7 @@ export default function (pi: ExtensionAPI) {
         lastUpdated: new Date().toISOString(),
         recentEvents: [],
       });
+      saveRollups({ version: 1, since: null, days: {} });
       ctx.ui.notify("Skill usage statistics reset.", "info");
     },
   });

package/extensions/skill-stats/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "test": "node --test --import tsx/esm index.test.ts",
+    "test": "node --test --import tsx/esm index.test.ts rollup.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {