Ralph ChangOpenCode Working Memory Plugin
Automatic memory for OpenCode agents.
This plugin helps your agent keep useful context across compactions and sessions: project decisions, preferences, important references, active files, and unresolved errors.
It works automatically, without manual memory tools or extra LLM/API calls.
Why This Exists
OpenCode compaction keeps conversations manageable, but important context can still get lost over time.
This plugin adds a workspace-aware memory layer so your agent can remember durable facts while keeping short-term session state fresh and lightweight.
Use it when you want your agent to remember things like:
- Project conventions
- User preferences
- Architecture decisions
- Important file paths or references
- Current active files and unresolved errors
Features
- Workspace memory — durable project facts, preferences, decisions, and references across sessions.
- Hot session state — active files, open errors, and current working context for the current session.
- Explicit memory triggers — users can say “remember this”, “記住”, “覚えて”, or “기억해” to save durable facts.
- Compaction-based extraction — memory extraction piggybacks on OpenCode’s existing compaction flow.
- No manual tools — memory is injected automatically into the system prompt.
- Quality guards — filters noisy memories, temporary progress snapshots, stack traces, raw errors, and credentials.
Installation
Add the plugin to your OpenCode config:
{
"plugin": ["opencode-working-memory"]
}
Then restart OpenCode. The plugin activates automatically.
How It Works
OpenCode Working Memory adds durable memory without making extra LLM/API calls.
┌──────────────────────────────────────┐
│ 🧭 Conversation Events │
│ edits, commands, errors, remembers │
└──────────────────┬───────────────────┘
▼
┌──────────────────────────────────────┐
│ 🔥 Hot Session State │
│ active files, open errors, pending │
│ │
│ ~/.local/share/opencode-working- │
│ memory/workspaces/{hash}/sessions/ │
│ {sessionID}.json │
└──────────────────┬───────────────────┘
│ when OpenCode compacts
▼
┌──────────────────────────────────────┐
│ 🧠 OpenCode Compaction │
│ existing LLM/API call │
│ + memory extraction instructions │
│ │
│ zero extra API calls │
└──────────────────┬───────────────────┘
│ filter, redact, dedupe
▼
┌──────────────────────────────────────┐
│ 📦 Workspace Memory │
│ decisions, preferences, refs │
│ │
│ ~/.local/share/opencode-working- │
│ memory/workspaces/{hash}/ │
│ workspace-memory.json │
└──────────────────┬───────────────────┘
▼
┌──────────────────────────────────────┐
│ ⚡ Prompt Context │
│ system[1]: frozen workspace memory │
│ system[2+]: hot session state │
└──────────────────────────────────────┘
Zero extra API calls: the plugin does not call the model on its own. Memory extraction is folded into OpenCode's built-in compaction request.
Cache-friendly layout: durable workspace memory is rendered as a stable frozen snapshot for the session, while fast-changing hot session state is appended separately. Compaction starts a new cache epoch, refreshing the workspace snapshot after pending memories are promoted.
The runtime context has three layers:
| Layer | Purpose | Lifetime |
|---|---|---|
| Workspace Memory | Durable decisions, preferences, project facts, references | Cross-session |
| Hot Session State | Active files, open errors, recent context | Current session |
| Native OpenCode State | Todos and built-in state | OpenCode-managed |
Workspace Memory
Workspace memory is for durable information that should help future sessions.
Examples:
- [decision] Use npm cache for plugin loading, not npm link.
- [project] This repo uses TypeScript and Node.js test runner.
- [feedback] User prefers concise implementation summaries.
- [reference] Storage lives under ~/.local/share/opencode-working-memory/.
Memory types:
feedback— user preferences or recurring feedbackproject— stable project-level factsdecision— important implementation or architecture decisionsreference— useful paths, commands, or configuration references
Explicit Memory Triggers
You can explicitly ask the agent to remember durable facts.
Examples:
Remember this: we prefer Vitest for new frontend tests.
記住：這個 repo 發 release 前要先跑 npm test。
覚えておいて: API clients should use the shared retry helper.
기억해줘: this project uses pnpm, not npm.
Supported trigger languages include:
| Language | Examples |
|---|---|
| English | remember this, save to memory, from now on, my preference |
| Chinese | 記住, 记住, 記得, 请帮我记住 |
| Japanese | 覚えて, 覚えておいて, メモして |
| Korean | 기억해, 기억해줘, 메모해줘 |
Negative requests are respected too:
Don't remember this.
不要記住這個。
覚えないで。
기억하지 마.
Avoid saving:
- Secrets, passwords, tokens, or credentials
- Temporary progress updates
- Raw command output
- Short-lived session details
Quality Guards
The plugin tries to keep memory useful and low-noise.
It includes guards for:
- Credential redaction
- Duplicate memory cleanup
- Superseding older decisions with newer ones
- Filtering stack traces, git hashes, raw errors, and noisy path-heavy facts
- Rejecting temporary project progress snapshots
The goal is to remember durable facts, not every detail.
Configuration
The plugin works out of the box.
Default behavior:
- Workspace memory budget: 5200 characters
- Workspace memory limit: 28 entries
- Hot session state budget: 1200 characters
- Active files shown: 8
- Open errors shown: 3
See Configuration for customization options.
Ongoing Work
Current focus:
- Improve memory recording quality so only durable, useful facts are kept.
- Strengthen deduplication and supersession so stale memories do not pile up.
- Add better forgetting behavior for obsolete decisions, preferences, and project facts.
Documentation
Development
git clone https://github.com/sdwolf4103/opencode-working-memory.git
cd opencode-working-memory
npm install
npm test
npm run typecheck
Requirements
- OpenCode >= 1.0.0
- Node.js >= 18.0.0
License
MIT License. See LICENSE for details.
Support
Made with ❤️ for the OpenCode community.