[FEATURE]: Treat external memory as a first-class extension category (docs + reference example) #52934

External memory backends are a growing class of OpenCode extension — local-first libraries, MCP memory servers, and daemons that keep long-lived project knowledge out of the transcript and recall it on demand. Today there is no first-class story for them; each one independently rediscovers the same seam and lands on the same two workarounds (summarise the kept history into the compaction context[], or prune in the context hook and race the host — see #50862 and #47810).

I'd like OpenCode to treat "external memory" as a supported category, even before the underlying hooks are widened:

1. Document the pattern. A short plugin-docs page on "external memory": what the compaction hook can and cannot do today, the summary-only ceiling, the experimental.chat.system.transform option for durable rules, and the current limitations. Right now this is only discoverable by reading the plugin type definitions and filing issues.
2. Ship a reference example. A minimal official example (or a curated "memory" example under the plugin docs) that wires a local memory backend through the native plugin API — so a user can get persistent, cross-session memory in minutes instead of porting a Claude Code compactor.
3. Name the seam. If a first-class memory seam is out of scope for now, state that explicitly (and why), so backends stop building on internal-gated mechanisms (refactor(core): move native compaction mechanisms into a plugin #49575) and know the current contract.

Why now / evidence

• Multiple memory libraries already ship partial OpenCode integrations, and every one re-solves the same seam. Awareness — open-source (Apache-2.0), local-first, offline, with a real OpenCode plugin (@awareness.market/opencode-plugin) and a local daemon — is a concrete reference implementation we would happily contribute as the example. https://awareness.market · https://github.com/everest-an/Awareness-SDK
• Long-context dilution ([FEATURE]: mechanism to keep critical rules visible against long-context dilution #41590) and session/state growth ([FEATURE]: Session Lifecycle Management — unified storage reclamation, auto-archival, and child session cleanup #16101, [Bug]: sustained high CPU and memory growth in long-running web sessions with large SQLite history #46341) are already recognised; external memory is the natural, supported way to address them, and it should be documented as such.

Motivating case (reference implementation)

Awareness keeps a small, stable active window and recalls only what's relevant:

• registers awareness_init / recall / record / lookup as native tools,
• auto-recalls before work, auto-captures a non-blocking session brief on idle,
• injects a structured handoff (not raw history) at compaction via experimental.session.compacting,
• scopes memory per project, works fully offline, no account.

It works today — but it is capped by the summary-only compaction return (#50862) and by not owning the compaction trigger (#47810). Documenting the pattern + shipping an example would let users adopt it now, and give the wider hooks work (#50862, #47810) real integrations to validate against.

Related

#50862 (compaction hook return type) · #47810 (compaction trigger) · #41590 (long-context dilution) · #16101 (session lifecycle) · #49575 (internal-only native seam)

Acceptance criteria

• A documented "external memory" pattern in the plugin docs, including current limitations.
• A runnable reference example wiring a local memory backend through the native plugin API.
• A stated position on whether a first-class memory seam is in scope (even if the answer is "not yet, because …").