Skip to content

diagnostics.md

Latest commit

 

History

History
100 lines (74 loc) · 6.25 KB

diagnostics.md

File metadata and controls

100 lines (74 loc) · 6.25 KB

Memory Diagnostics

Use the read-only diagnostics CLI when you want to understand what OpenCode Working Memory is doing for the current workspace.

The npm package is opencode-working-memory; the installed bin is memory-diag, so package-qualified npx avoids resolving a different package named memory-diag.

Commands

Question Command
Is memory healthy? npx --package opencode-working-memory memory-diag or npx --package opencode-working-memory memory-diag status
Why was something rejected? npx --package opencode-working-memory memory-diag rejected
Where did my memory go? npx --package opencode-working-memory memory-diag missing
Why is this memory shown or hidden? npx --package opencode-working-memory memory-diag explain <memory-id>
How are numbered memory commands behaving? npx --package opencode-working-memory memory-diag commands
What reinforcement evidence exists for one memory? npx --package opencode-working-memory memory-diag commands --memory <memory-id>
How do I review memory quality without automatic cleanup? npx --package opencode-working-memory memory-diag quality
Revert a numbered replacement? npx --package opencode-working-memory memory-diag revert --memory <replacement-memory-id>

Global Options

  • --workspace <path> — inspect another workspace; defaults to the current directory.
  • --verbose — show detailed diagnostics.
  • --json — print machine-readable output where supported.

Diagnostic Answerability Contract

Every diagnostic section must document:

  1. Question: What does the reviewer want to know?
  2. Decision: What action could the answer inform?
  3. Competing explanations: At least two interpretations of the same metric.
  4. Required signals: What fields/events distinguish those explanations?
  5. Current signals: What currently exists?
  6. Answerability level: supported | partial | inventory_only | not_instrumented
  7. Output permission: What the tool may say without overclaiming.

For memory-diag quality:

  • reinforcementRules: inventory_only (cannot distinguish spam from legitimate blocks)
  • evictionAndCaps: inventory_only (cannot distinguish healthy turnover from premature eviction)
  • Old evidence remains ambiguous. Answerability improves for producer-instrumented events, including instrumentation version 2 block details and instrumentation version 3 elapsed-window details. Mixed old/new logs will show a mix of inventory_only and partial sections.
  • Producer-instrumented reinforcement blocks can upgrade reinforcementRules to partial by showing exact block reasons and, when available, rolling elapsed-window fields; they still require human content judgment.
  • Producer-instrumented capacity removals with rank/strength snapshots can upgrade evictionAndCaps to partial; fullness alone remains occupancy inventory, not proof of a capacity problem.

Examples

npx --package opencode-working-memory memory-diag status
npx --package opencode-working-memory memory-diag rejected --verbose
npx --package opencode-working-memory memory-diag missing --workspace /path/to/project
npx --package opencode-working-memory memory-diag status --json
npx --package opencode-working-memory memory-diag commands --verbose
npx --package opencode-working-memory memory-diag commands --memory <memory-id>
npx --package opencode-working-memory memory-diag quality
npx --package opencode-working-memory memory-diag revert --memory <replacement-memory-id>

Quality Review Board

Use memory-diag quality for a read-only, answerability-scoped evidence inventory without automatic cleanup.

  • Primarily provides memory-system mechanism observations for human/agent interpretation.
  • Secondarily helps review active memory content quality.
  • Prints answerability labels and output permissions so inventory facts are not presented as conclusions.
  • Separates system-mechanism facts, memory-content facts, heuristic flags, and review questions.
  • Includes inferred evidence provenance because historical records do not record producer package version.
  • Labels uncertain provenance as unversioned_ambiguous so old artifacts are not treated as current mechanism failures.
  • Does not decide what to delete or mutate.
  • Use --json for agent/objective review.

Numbered Memory Command Reports

Use memory-diag commands to inspect REINFORCE [M#] and REPLACE [M#] outcomes from compaction.

npx --package opencode-working-memory memory-diag commands
npx --package opencode-working-memory memory-diag commands --verbose
npx --package opencode-working-memory memory-diag commands --memory <memory-id>

The report includes successful reinforcements, refresh-only reinforcements, successful replacements, malformed commands, stale refs, protected replacement blocks, and latest command events in verbose mode.

Use commands --memory <memory-id> when you need a focused, evidence-only reinforcement view for one memory. It reports current memory status separately from recorded reinforcement attempts, block reasons, missing block details, elapsed-window fields (elapsedMs, requiredElapsedMs), sameSession evidence, reinforcementMode (increment or refresh_only), legacyMissingTimestamp when true, and historical UTC-day evidence without judging whether the policy is correct.

Current reinforcement policy uses a rolling 7-day elapsed window. Below reinforcement count 6, allowed attempts increment the count and refresh retention timestamps; at count 6 or higher, allowed attempts refresh retention timestamps without increasing the count. Historical evidence can still show older block reasons such as same_session, same_utc_day, min_interval, max_count, or missing block details because evidence logs are append-only and are not backfilled.

Dry-run Recovery

memory-diag revert is dry-run by default. Add --apply only after reviewing the planned original/replacement status changes.

npx --package opencode-working-memory memory-diag revert --memory <replacement-memory-id>
npx --package opencode-working-memory memory-diag revert --memory <replacement-memory-id> --apply

You can also target a replacement evidence event directly:

npx --package opencode-working-memory memory-diag revert --event <event-id>