Skip to content

0.2.0 — Local usage metrics

Choose a tag to compare

@azaharizaman azaharizaman released this 17 Oct 16:25
efe65ba

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_apply tool calls, /memory-review invocations, and dashboard renders/resets (the read-only memory_metrics query 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.storage under <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-write since stamp. 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 fresh since window. 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.0

Nothing 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 (shows memory).
  • /memory-metrics deploy 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