OpenCode Persistent Memory
Solving Desktop RAM Leaks & CLI Session Reset.

TL;DR

Give OpenCode persistent memory across every session. The Memwyre plugin auto-injects past project context when you start a session and auto-captures decisions when it ends — no manual context management needed.

The Problem: OpenCode Forgets Everything

Every time you close an OpenCode session, the context window resets. Your debugging breakthroughs, architecture decisions, and code patterns — all gone. You spend the first minutes of every session re-explaining your project.

OpenCode doesn't ship with built-in persistent memory. If you use OpenCode and Claude Code and Cursor, each tool maintains its own isolated silo.

The OpenCode Memory Dilemma: Desktop RAM vs CLI Persistence

When engineers search for "OpenCode memory", they typically struggle with one of two distinct bottlenecks:

1. Desktop App RAM Leaks (10–20 GB Footprint)

The OpenCode Desktop GUI renders all active and past chat sessions inside an Electron/Chromium runtime. Over hours of coding, in-memory DOM nodes and token buffers accumulate, causing memory consumption to balloon into tens of gigabytes and freeze your system.

2. CLI Terminal Statelessness

Developers seeking to avoid GUI bloat switch to the OpenCode CLI, which is lightweight and fast. However, the CLI resets completely after each run. All knowledge of architectural decisions, database models, and bug fixes vanishes as soon as the terminal closes.

The Solution: Memwyre bridges the gap. By connecting the lightweight OpenCode CLI to Memwyre's remote cloud vault, you get instant persistent context on session launch with zero local memory leak overhead.

V8 Garbage Collection Limits & Node.js Out-Of-Memory (OOM) Crashes

When developers run deep, multi-turn coding sessions with the OpenCode Desktop app, they frequently hit catastrophic UI freezes and crashes caused by V8 garbage collector thrashing and Node.js heap exhaustion.

Here is why OpenCode experiences severe memory leaks and garbage collection bottlenecks:

• Retained DOM & Token Buffer Trees: Because Chromium renders every past code diff, terminal log, and conversational turn inside a single renderer process, objects remain referenced in the V8 heap. The garbage collector cannot safely sweep these objects, leading to unbounded heap growth.
• Stop-the-World Scavenge Cycles: As heap usage approaches the default Node.js limit (typically 4 GB or 8 GB), V8 initiates full-generation Mark-Sweep-Compact passes. These synchronous pauses freeze the GUI, causing typed characters to lag and editor interactions to lock up.
• Fatal Heap Out-of-Memory (OOM): Once total memory breaches the OS or container allocation boundary, the Node process terminates with FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory. Developers are forced to kill the process and discard unsaved context.

The Memwyre Decoupling Architecture: Memwyre circumvents V8 garbage collection limits by shifting memory management out of the local process. Using the stateless OpenCode CLI with the Memwyre hook, terminal sessions discard active token buffers cleanly after each interaction. Relevant project architecture is queried on demand via low-latency API calls, keeping local process memory rock-solid under 150 MB indefinitely.

OpenCode RAM Requirements: CLI vs. Desktop GUI

Depending on whether you use the full Electron desktop build or the headless CLI with Memwyre, the system hardware requirements diverge dramatically:

Four Approaches to OpenCode Memory

These approaches are complementary, not exclusive. Use manual files for static rules and Memwyre for dynamic OpenCode session memory — they work together.

Memwyre vs. Mem0 & Supermemory for OpenCode

Developers looking for long-term memory in OpenCode often evaluate general-purpose memory systems like Mem0 (API-first memory SDK) or Supermemory (web bookmarking & second brain engine). While both offer vector storage capabilities, neither includes a native plugin built for OpenCode's internal architecture.

Why OpenCode developers prefer Memwyre:

• Native OpenCode SQLite Integration: Memwyre's plugin reads session transcripts directly from OpenCode's local database (`~/.local/share/opencode/opencode.db`) using native `node:sqlite`. It requires zero custom API integration code.
• Automatic Lifecycle Hooks: Hooks into OpenCode's `create`/`start` events to inject past architectural context and `idle`/`end` events to capture newly learned facts seamlessly.
• LoCoMo-10 Benchmark Scores: Memwyre's two-stage cross-encoder engine achieves 70.5% overall accuracy on the LoCoMo-10 benchmark vs. 43.7% for standard vector RAG systems. (Compare features on our Memwyre vs. Mem0 and Memwyre vs. Supermemory pages.)

Memwyre vs. Manual memory.md & opencode-working-memory

To work around OpenCode's lack of native session memory, many engineers attempt to maintain a static memory.md or .opencode/working-memory file in their repository root. While this seems straightforward initially, it quickly degrades agent performance:

• Context Window Bloat: Prepending a 1,000-line memory.md file into every prompt wastes 4,000–8,000 tokens per interaction, ballooning LLM API costs and slowing down response latency.
• Attention Distraction & Hallucination: Large flat files force the model to parse dozens of outdated or irrelevant historical notes, leading to prompt confusion and degraded code generation quality.
• Manual Overhead & Stale Rules: Developers must manually edit, prune, and reorganize Markdown notes. Obsolete architectural patterns persist indefinitely because flat files lack recency weighting or decay models.
• Zero Cross-Tool Sync: A local memory.md file stays locked inside that specific git repository and branch. It cannot inform Claude Code, Cursor, or teammate workflows.

The Memwyre Difference: Instead of dumping static files into the prompt, Memwyre performs dynamic, AST-aware contextual injection. On session start, it retrieves only the top 3–5 high-confidence facts relevant to the active workspace. As your architecture evolves, an integrated Ebbinghaus decay model automatically deprioritizes stale conventions without manual editing.

How Cross-Tool Sync Actually Works

• OpenCode (plugin): hooks into session lifecycle. On start → retrieval API. On end → POST transcript.
• Claude Code / Cursor / VS Code (MCP) / Claude Desktop / OpenClaw: connect via MCP or their respective plugins to same vault.
• Same API key = same vault.

How the Memwyre OpenCode Plugin Works

① Session Start — Context Injection

When you start an OpenCode session (create/start/init events), the plugin calls the Memwyre retrieval engine for past memories matching the current project and injects them into the session prompt.

<memwyre-context>
## Past Memories for my-project
- Database uses PostgreSQL 15 with pgvector
- Auth flow: JWT + refresh tokens in httpOnly cookies
- Fixed: race condition in worker queue (use Redis lock)
</memwyre-context>

② Session End — Session Capture

When the session goes idle or ends, the plugin reads the session transcript — from the client API, event payload, or directly from OpenCode's local SQLite database at ~/.local/share/opencode/opencode.db. Sends it to Memwyre's background worker for extraction. Uses deduplication tracking to prevent double-captures.

Troubleshooting & Edge Cases

• Misclassified memory: view/edit/delete via dashboard or API
• Stale facts: Ebbinghaus decay auto-deprioritizes
• Deduplication: capturedSessions Set prevents duplicate captures
• SQLite fallback: if the client API doesn't provide messages, the plugin reads directly from OpenCode's local database

Install in 60 Seconds

Choose between automated CLI setup or direct npm package configuration:

npx -y install-memwyre --opencode

What OpenCode Remembers With Memwyre

• 🧠 Architecture Decisions
• 🐛 Debugging Solutions
• 🔗 Entity Relationships
• ✂️ Dynamic Pruning

Benchmark: Why Retrieval Quality Matters

We evaluated Memwyre's retrieval engine against a flat vector RAG baseline on the LoCoMo-10 benchmark (Snap Research, ACL 2024):

View the full LoCoMo-10 benchmark results →Read our Vector DB vs. Agent Memory research paper →

Real-World Workflow: Iterative Feature Development

Scenario: building a payment integration over multiple sessions. Session 1 establishes the Stripe webhook architecture. Session 2 implements the subscription billing logic. Session 3 adds the retry/idempotency layer. Without memory, Session 3 doesn't know about the webhook signing secret rotation decision from Session 1. With Memwyre, all sessions share context.

Token Costs, Noise, & Security

Noise Filtration

Not every CLI error needs to be remembered. Memwyre's backend uses a specialized extraction model that differentiates between ephemeral noise and structural knowledge. Only the structural knowledge is saved to your vector vault, keeping your persistent memory highly relevant and dense.

Token Efficiency

By summarizing and deduplicating past sessions, the plugin injects a concise <memwyre-context> block that rarely exceeds 1,500 tokens. Compared to manually pasting in megabytes of old transcript logs, this targeted injection saves API costs while providing superior context.

Enterprise Security

Your code is yours. The Memwyre extraction engine uses zero-retention policies—meaning your transcripts are processed in memory and immediately discarded. For enterprise environments with strict compliance requirements, the entire Memwyre backend can be self-hosted behind your firewall.

License & Requirements

• Apache-2.0
• Node.js 18+, any OS
• Self-hosting: Docker deployment
• No special profile requirements (unlike OpenClaw)

Why Not Just Use Manual Context?

Manual files are good for static rules, but limited by maintenance, flat storage, and tool-locking. They don't update automatically as your architecture evolves.

FAQ