Repository navigation
Releases
0.3.0 — TUI sidebar status and explicit initialization
0.3.0 — TUI sidebar status and explicit initialization
This release adds the read-only TUI sidebar memory line and completes the explicit initialization gate, plus the Tier 0-3 hardening work since 0.2.0.
Highlights
TUI sidebar status (#29, ADR-0012)
- One additive
sidebar.footerline showsnot-initialized,healthy,pending, orattentionfor the current project. - Backed by the read-only
nexusnv.memory.sidebarStatusRPC, registered unconditionally by the server part. It returns only{ state, pending }. - The collector checks
isInitializedbefore any storage read, never writes or consumes notices, and coalesces overlapping probes so a stalled read cannot accumulate. - The TUI polls every 5 seconds with a 4-second timeout and unmount abort; invalid, rejected, or timed-out snapshots hide the line.
- No visibility option: OpenCode 2.2.5 does not deliver package
optionsto TUI plugin parts, so the line is always shown while the plugin is installed. Hiding it means removing the plugin.
Explicit initialization (E15, #20)
- New projects start inert.
/memory-initcreates.opencode/memory/(INDEX last) and is idempotent; existing installs with a regularINDEX.mdactivate automatically. - Before initialization only
/memory-init,/memory-status,memory_status, and the read-only sidebar RPC answer.
Search, status, INDEX cleanup, and hardening
memory_searchand the deterministic/memory-status+memory_statusreport.- INDEX pointer cleanup after
/memory-forget. - Tier 0-3 work: metrics dashboard meanings/two-step reset, ledger pruning, hint nudge, onboarding checklist, prompt-tail placement, cross-process write locking, and read-only security hardening.
Upgrade
npm install opencode-nexusnv-memory@0.3.0No migration is required for existing installs with INDEX.md. New projects must run /memory-init.
Compatibility
- OpenCode
2.0.x, built and type-checked against@opencode/plugin 2.0.29(pinned exact). - The TUI part requires the host TUI stack (
@opentui/core/@opentui/solidpeers). - Full changelog:
CHANGELOG.md.
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
0.1.1
First workflow-published release (validates npm trusted publishing).
- Release automation: OIDC trusted publishing replaces the default publish-token path; split gated build and minimal publish jobs with tag-on-main and tag/manifest guards.
- Staged only: CI stages the asserted tarball; approve on npmjs.com to publish.
- No plugin behavior changes since 0.1.0.
0.1.0
First npm release of the no-fuss memory plugin for OpenCode V2.
- Local-first project memory: six-file slice plus handoffs, budget-capped auto-inject, human-approved curation via /memory-review and memory_apply.
- Trust-boundary hardening from security review: column-0 section parsing, untrusted priors labelling, source-tag canonicalization, broadened secret redaction, project-scoped capture dedupe, location-less compaction drop.
- CI gates: typecheck, tests plus coverage thresholds on Node 20/22/24, gitleaks with canary-scoped allowlist, prod dependency audit, pack layout assertion.
- Published with provenance. Supported range: OpenCode 2.0.x.