feat(memory): add opt-in scoped memory tools

docs/IMPLEMENTATION-PLAN.md

@@ -159,14 +159,24 @@ matched its recorded SHA-256.
 **Acceptance:** another user can install from documented instructions and
 verify the deterministic behavior without credentials.
 
-### Phase 6 — Optional memory and learning features (not started)
+### Phase 6 — Optional memory and learning features (memory milestone implemented)
 
 - Design persistent memory and session-learning APIs separately.
 - Prefer V2 public APIs over assumptions about OpenCode's storage layout.
 - Add opt-in, scope controls, retention behavior, and isolation tests.
 
+**Progress:** explicit memory tools now use the V2 plugin storage API. They are
+disabled by default, session-scoped by project/session, and support separately
+opted-in canonical-project scope, explicit retrieval/deletion, and configurable
+expiry. Deterministic tests cover scope isolation and expiry. Live profile
+storage persistence and user-profile isolation, along with provider-backed
+learning proposals, remain unverified; automatic prompt/session capture is
+deliberately not implemented.
+
 **Acceptance:** explicit consent and tests prove project/session/user data
-cannot be mixed or silently uploaded.
+cannot be mixed or silently uploaded. This phase remains in progress until
+storage behavior is verified in OpenCode 2.0.24 and learning proposals receive a
+separate design and validation.
 
 ## Verification strategy
 

docs/SECURITY-REVIEW.md

@@ -42,3 +42,23 @@ files, symlinked install directories, and a tampered manifest.
   branches.
 - `npm pack --dry-run` — passed; included runtime files, selected content,
   licenses, notice, and README.
+
+## Optional memory review (2026-10-08)
+
+Memory tools are not registered unless `memory.enabled` is explicitly true.
+Session keys include hashes of the OpenCode project identity and session ID;
+project-scope access additionally requires `memory.project: true` and is keyed
+to the canonical project. Each operation checks the session's project ID. Data
+is only stored or returned through explicit tool calls; list previews and
+retrieval become ordinary tool output visible to the active provider. The
+package does not encrypt storage, capture session content, or background-upload
+memory. Retention is lazy: expired entries are rejected and removed on access,
+not by a scheduled purge. Provider-backed learning and persistence across live
+OpenCode restarts have not been verified, so this is not a security audit or a
+claim about the underlying storage implementation.
+
+Deterministic checks cover disabled-by-default behavior, session separation,
+project opt-in, project separation, cross-project rejection, explicit deletion,
+and expiry. A plugin config object containing user options is preserved during
+uninstall; users must remove that entry themselves if they converted the
+installer-added string to configure memory.

docs/adr/0001-opt-in-plugin-storage-memory.md

@@ -0,0 +1,32 @@
+# 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.