Repository navigation
0.2.0 — Local usage metrics
0.2.0 — Local usage metrics
The memory plugin can now show you what it has actually been doing — count-only, on your machine, never sent anywhere. This is the first feature release since 0.1.0 (0.1.1 was release-automation only): every commit in it is the local metrics work (ADR-0008, design spec §5.12), plus review-driven hardening. No breaking changes — the five-option config contract stands and no memory file, budget, injection, or hook-outcome behavior changed.
Highlights
/memory-metrics — the dashboard, on demand
Renders a deterministic markdown table and posts it into the session with no model turn:
- Since / Explicit calls —
memory_recall/memory_applytool calls,/memory-reviewinvocations, and dashboard renders/resets (the read-onlymemory_metricsquery is not counted — it changes nothing). - Behind the scenes — hook activity (prompt, context, compaction, event-driven capture), budget-cascade outcomes (brief truncation, status sacrifice), capture results (captured / duplicate / retry / failed), and the hint → recall conversion: whether the tell-tale hint actually drives
memory_recall, which was previously unknowable in production. - Memory health — line counts of the six structural files vs their caps, handoff/archive/pending/seen counts (read-only, on request).
- Budget pressure — 7-day day-bucket view of where the 80-line injection budget went.
If the synthetic post is rejected, the command degrades to a single memory_metrics echo turn (§5.5 fallback) instead of failing. The memory_metrics tool returns the same table read-only.
Privacy contract
- Numbers only, everywhere. No prompt text, tool output, captured paths, identities, or prose ever enters a metric — every persisted value is a JSON number, published counter names come from an enumerated fail-closed vocabulary, and the renderer is pure (tests assert the number-only invariant as a literal gate).
- On-machine, bounded. Counters live in the plugin-scoped
ctx.storageunder<projectID>/metrics/…(inside the OpenCode user data dir): monotonic totals, ≤90-day UTC day buckets (pruned lazily, no daemon needed), per-session hint arm entries that age out after one UTC day, and a lazy first-writesincestamp. No network channel exists — dashboard and tool are the only surfaces. - No sixth option. Metrics are always on; the control is
/memory-metrics reset, which wipes the project's metrics keys under one lock and re-opens a freshsincewindow. Uninstall orphans the keys harmlessly, like the ledger.
Hardening (review-driven, same release)
- Hint → recall arm consumption is atomic (
consumeArm: read + clear in one locked body), so concurrent recalls convert an armed session at most once. - Arm entries store an arming timestamp and expire after one UTC day; stale hints can no longer inflate
hint.recall, and hinted-but-never-recalled sessions stop accumulating keys. - Bumps are fire-and-forget and never throw; a 1,000-bump burst against a saturated storage queue cannot delay a hook (acceptance-tested).
Upgrade
npm install opencode-nexusnv-memory@0.2.0Nothing to migrate: existing installs pick up metrics automatically; there are no new config options or file formats.
Compatibility
- Supported OpenCode range:
2.0.x, built and type-checked against@opencode/plugin 2.0.29(pinned exact). - Verify the install with
opencode plugin list(showsmemory). /memory-metricsdeploy check (G-M1): the first resolved synthetic post logs one line —[memory-metrics] synthetic posted (<session6>); confirm the table rendered without a model turn. A rejected post logs nothing and falls back to the echo turn.
Docs
docs/adr/0008-local-usage-metrics.md— the decision, storage model, and residual-risk statement.README.md→ "Metrics (local-only)" — what is counted, where keys live, reset/uninstall.- Design spec §5.12 — the normative component contract.
Full changelog: CHANGELOG.md