# 0001. Store explicit memory through the V2 plugin storage API

Date: 2026-10-08
Status: proposed

## Context

The toolkit needs persistent memory without assuming OpenCode's on-disk storage
layout, silently collecting session data, or mixing sessions and projects.
OpenCode 2.0.24 exposes plugin-scoped storage and supplies the active tool
session ID and session project/location through its public plugin API.

## Decision

Use `ctx.storage` for explicitly invoked memory operations. Disable memory unless
the plugin's `memory.enabled` option is true; default writes to a key namespace
derived from project identity and session ID. Permit canonical-project scope
only when `memory.project` is separately enabled. Return content only through an
explicit retrieval/list tool call, apply a configurable expiry, and do not
capture prompts or automatically inject stored content into model context.

## Consequences

- The implementation avoids dependence on private OpenCode database paths and
  makes opt-in boundaries visible in project configuration.
- Project/session key namespaces limit accidental data mixing, while project
  sharing deliberately spans sessions and worktrees with the same canonical
  project identity.
- Storage encryption, user-profile isolation, and persistence across a live
  OpenCode restart rely on the host implementation and remain unverified.
- Lazy expiration does not immediately reclaim inaccessible expired records;
  there is no background cleanup or automatic learning workflow.