opencode-working-memory/README.md

OpenCode Working Memory Plugin

Advanced four-tier memory architecture that keeps your AI agent sharp, focused, and never forgets what matters.

Stop losing context across compactions. Stop watching your agent repeat the same mistakes. This plugin gives your OpenCode agent a professional-grade memory system that scales with your project complexity.

What You Get

• 🧠 Core Memory - Persistent goal/progress/context blocks that survive compaction
• 💡 Working Memory - Smart slot-based system (errors, decisions, todos, dependencies)
• 🎯 Memory Pressure Monitoring - Real-time token tracking with automatic interventions
• 🧹 Auto Storage Governance - Prevents unbounded disk growth (300 files/session, 7-day TTL)
• 📊 Smart Pruning - Pressure-aware tool output compression
• ⚡ Zero Configuration - Works out of the box, highly customizable

Installation

For Humans

Option A: Let an LLM do it

Paste this into Claude Code, Cursor, or any AI agent:

Install opencode-working-memory plugin by following:
https://raw.githubusercontent.com/yourusername/opencode-working-memory/main/docs/installation.md

Option B: Manual setup

1. Add to your ~/.config/opencode/opencode.json:

{
  "plugin": ["opencode-working-memory"]
}

2. Restart OpenCode

That's it! The plugin is now active.

For LLM Agents

1. Read the OpenCode configuration file at ~/.config/opencode/opencode.json
2. Add "opencode-working-memory" to the plugin array
3. Verify installation by checking the config file

Quick Start

The plugin works automatically once installed. No configuration needed.

Use the tools:

# Update persistent memory
opencode run "use core_memory_update to set my goal"

# Read current memory state  
opencode run "use core_memory_read to show me what you remember"

# Add important items to working memory
opencode run "use working_memory_add to remember this file path"

The agent will automatically:

• Track memory pressure and warn when approaching compaction
• Preserve important context during compaction
• Clean up old tool-output cache files every 20 tool calls
• Remove artifacts when sessions are deleted

Features

🧠 Core Memory (Phase 1)

Persistent blocks that survive conversation resets:

• goal (1000 chars) - Current task/objective
• progress (2000 chars) - What's done, in-progress, next steps
• context (1500 chars) - Key file paths, conventions, patterns

💡 Working Memory (Phase 3)

Auto-extracts and ranks important information:

• Slots (guaranteed visibility): errors, decisions, todos, dependencies
• Pool (ranked by relevance): file paths, recent activity
• Exponential decay keeps memory fresh
• FIFO limits prevent bloat

🎯 Memory Pressure Monitoring (Phase 4)

Real-time token tracking from session database:

• Monitors context window usage (75% → 90% → 95% thresholds)
• Proactive intervention messages when pressure is high
• Pressure-aware smart pruning (adapts compression based on pressure)

🧹 Storage Governance (Phase 5)

Prevents unbounded disk growth:

• Layer 1: Auto-cleanup on session deletion (all artifacts removed)
• Layer 2: Active cache management (max 300 files/session, 7-day TTL)
• Triggers every 20 tool calls
• Silent background operation

📊 Smart Pruning (Phase 2)

Intelligent tool output compression:

• Per-tool strategies (keep-all, keep-ends, keep-last, discard)
• Pressure-aware limits (2k/5k/10k lines based on memory pressure)
• Preserves important context while reducing noise

Documentation

• Installation Guide - Detailed setup instructions
• Architecture Overview - How it works under the hood
• Configuration - Customization options
• Agent Developer Guide - For plugin developers

Tools Provided

The plugin exposes these tools to your OpenCode agent:

• core_memory_update - Update goal/progress/context blocks
• core_memory_read - Read current memory state
• working_memory_add - Manually add important items
• working_memory_clear - Clear all working memory
• working_memory_clear_slot - Clear specific slot (errors/decisions)
• working_memory_remove - Remove specific item by content

How It Works

┌─────────────────────────────────────────────────────────┐
│  Core Memory (Always Visible)                          │
│  ┌─────────┬──────────┬──────────┐                    │
│  │  Goal   │ Progress │ Context  │                    │
│  └─────────┴──────────┴──────────┘                    │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Working Memory (Auto-Extracted)                        │
│  ┌──────────────────┬──────────────────┐              │
│  │  Slots (FIFO)    │  Pool (Ranked)   │              │
│  │  • errors        │  • file-paths    │              │
│  │  • decisions     │  • recent        │              │
│  │  • todos         │  • mentions      │              │
│  │  • dependencies  │  • decay score   │              │
│  └──────────────────┴──────────────────┘              │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Memory Pressure Monitor                                │
│  • Tracks tokens from session DB                       │
│  • Warns at 75% / 90% / 95%                           │
│  • Sends proactive interventions                       │
│  • Adjusts pruning aggressiveness                      │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Storage Governance                                     │
│  • Session deletion → cleanup all artifacts            │
│  • Every 20 calls → sweep old cache (300 max, 7d TTL) │
│  • Silent background operation                         │
└─────────────────────────────────────────────────────────┘

Why This Plugin?

Without this plugin:

• 🔴 Agent forgets context after compaction
• 🔴 Repeats resolved errors
• 🔴 Loses track of project structure
• 🔴 Context window fills up uncontrollably
• 🔴 Disk space grows unbounded

With this plugin:

• ✅ Persistent memory across compactions
• ✅ Smart auto-extraction of important info
• ✅ Real-time pressure monitoring with interventions
• ✅ Automatic storage cleanup
• ✅ Pressure-aware compression
• ✅ Zero configuration, works immediately

Configuration (Optional)

The plugin works great with zero configuration. But if you want to customize:

Create ~/.config/opencode/working-memory.json:

{
  "storage_governance": {
    "tool_output_max_files": 300,
    "tool_output_max_age_ms": 604800000,
    "sweep_interval": 20
  },
  "memory_pressure": {
    "thresholds": {
      "moderate": 0.75,
      "high": 0.90,
      "critical": 0.95
    }
  }
}

See Configuration Guide for all options.

Requirements

• OpenCode >= 1.0.0
• Node.js >= 18.0.0
• @opencode-ai/plugin >= 1.2.0

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions

Credits

Inspired by the needs of real-world OpenCode usage and built to solve actual pain points in AI-assisted development.

---

Made with ❤️ for the OpenCode community