opencode-working-memory 1.0.0

package/AGENTS.md

@@ -0,0 +1,340 @@
+# AGENTS.md - OpenCode Working Memory Plugin Development Guide
+
+## Project Overview
+
+The **OpenCode Working Memory Plugin** provides a four-tier memory architecture for AI agents:
+- **Core Memory** - Persistent blocks (goal/progress/context) that survive compaction
+- **Working Memory** - Session-scoped context with slots (error/decision/todo/dependency) and memory pool
+- **Smart Pruning** - Automatic filtering of tool outputs before adding to context
+- **Pressure Monitoring** - Tracks context usage and triggers interventions at thresholds
+
+Written in **TypeScript** for the OpenCode agent environment.
+
+## Installation
+
+```bash
+# For development
+git clone https://github.com/sdwolf4103/opencode-working-memory.git
+cd opencode-working-memory
+npm install
+
+# For usage (see README.md)
+```
+
+## Build & Development Commands
+
+### Type Checking
+```bash
+# TypeScript strict mode - fix all type errors before committing
+npx tsc --noEmit
+```
+
+### Testing
+Tests are manually verified through OpenCode sessions:
+```bash
+# 1. Load plugin in OpenCode session
+# 2. Run commands that trigger hooks (e.g., tool execution, compaction)
+# 3. Inspect .opencode/memory-core/ and .opencode/memory-working/
+# 4. Verify memory blocks appear in system prompts
+```
+
+### File Structure
+```
+opencode-working-memory/
+├── index.ts               # Main plugin (1700+ lines)
+├── package.json           # Plugin manifest
+├── tsconfig.json          # TypeScript config
+├── LICENSE                # MIT license
+├── README.md              # User documentation
+├── AGENTS.md              # This file (developer guide)
+└── docs/                  # Detailed documentation
+    ├── installation.md
+    ├── architecture.md
+    └── configuration.md
+```
+
+## Code Style Guidelines
+
+### TypeScript Strict Mode
+
+```typescript
+// ✅ REQUIRED: Full type annotations, no implicit any
+async function loadCoreMemory(
+  directory: string,
+  sessionID: string
+): Promise<CoreMemory | null>
+
+// ❌ AVOID: Implicit any types
+async function loadCoreMemory(directory, sessionID) { }
+```
+
+### Type Definitions
+
+```typescript
+// ✅ REQUIRED: Define types at module top
+type CoreMemory = {
+  sessionID: string;
+  blocks: {
+    goal: CoreBlock;
+    progress: CoreBlock;
+    context: CoreBlock;
+  };
+  updatedAt: string;
+};
+
+// ✅ USE: Union types for variants (not enums)
+type PressureLevel = "safe" | "moderate" | "high" | "critical";
+
+// ✅ USE: Record<> for keyed configs
+const SLOT_CONFIG: Record<SlotType, number> = {
+  error: 3,
+  decision: 5,
+  todo: 3,
+  dependency: 3,
+};
+```
+
+### Imports & Module Organization
+
+```typescript
+// ✅ REQUIRED: Group and order imports
+// 1. Node.js built-ins
+import { existsSync } from "fs";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+
+// 2. Third-party (OpenCode SDK)
+import type { Plugin } from "@opencode-ai/plugin";
+import { tool } from "@opencode-ai/plugin";
+
+// 3. Local modules (if any)
+// (none currently)
+```
+
+### Naming Conventions
+
+```typescript
+// ✅ REQUIRED: camelCase for variables & functions
+const maxItems = 50;
+async function loadCoreMemory() { }
+
+// ✅ REQUIRED: SCREAMING_SNAKE_CASE for constants
+const CORE_MEMORY_LIMITS = { goal: 1000, progress: 2000, context: 1500 };
+const SLOT_CONFIG = { error: 3, decision: 5, todo: 3, dependency: 3 };
+
+// ✅ REQUIRED: PascalCase for types
+type CoreMemory = { ... };
+type WorkingMemoryItem = { ... };
+
+// ✅ REQUIRED: get*/set*/load*/save* naming for file operations
+function getCoreMemoryPath(directory: string, sessionID: string): string { }
+async function loadCoreMemory(directory: string, sessionID: string): Promise<CoreMemory | null> { }
+async function saveCoreMemory(directory: string, memory: CoreMemory): Promise<void> { }
+
+// ✅ REQUIRED: ensure*/validate* for pre-checks
+async function ensureCoreMemoryDir(directory: string): Promise<void> { }
+
+// ✅ REQUIRED: Prefix private/internal functions with _
+function _compressPath(filePath: string): string { }
+```
+
+### Function Signatures & Organization
+
+```typescript
+// ✅ REQUIRED: Parameters on separate lines if > 80 chars
+async function loadWorkingMemory(
+  directory: string,
+  sessionID: string
+): Promise<WorkingMemory | null> {
+  // ...
+}
+
+// ✅ REQUIRED: Explicit return types (no inference)
+function getCompactionLogPath(directory: string, sessionID: string): string {
+  return join(directory, ".opencode", "memory-working", `${sessionID}_compaction.json`);
+}
+
+// ✅ REQUIRED: Async for file/network I/O
+async function saveCoreMemory(directory: string, memory: CoreMemory): Promise<void> {
+  // ...
+}
+```
+
+### Error Handling
+
+```typescript
+// ✅ REQUIRED: Try-catch with descriptive console.error
+async function loadCoreMemory(directory: string, sessionID: string): Promise<CoreMemory | null> {
+  const path = getCoreMemoryPath(directory, sessionID);
+  if (!existsSync(path)) return null;
+
+  try {
+    const content = await readFile(path, "utf-8");
+    return JSON.parse(content) as CoreMemory;
+  } catch (error) {
+    console.error("Failed to load core memory:", error);
+    return null;  // Graceful degradation
+  }
+}
+
+// ✅ REQUIRED: Type guards for runtime safety
+if (!existsSync(path)) {
+  return null;
+}
+
+// ✅ REQUIRED: Validate JSON before use
+const data = JSON.parse(content);
+const typedData = data as CoreMemory;  // Explicit cast after validation
+```
+
+### Comments & Documentation
+
+```typescript
+// ✅ REQUIRED: Section headers for major sections
+// ============================================================================
+// Phase 1: Core Memory Foundation
+// ============================================================================
+
+// ✅ REQUIRED: Block comments for complex logic
+// Migration: Convert old format (items array) to new format (slots + pool)
+if (data.items && !data.slots) {
+  // ... migration logic
+}
+
+// ✅ USE: Inline comments sparingly
+const gamma = 0.85;  // Exponential decay rate (15% per event)
+
+// ✅ AVOID: Over-commenting obvious code
+const name = "test";  // Set name to test ❌ (obvious)
+```
+
+### Code Organization
+
+```typescript
+// ✅ REQUIRED: Organize plugin file by phase/feature
+// 1. Header & module documentation
+// 2. Imports
+// 3. Types & schemas (grouped by phase)
+// 4. Constants & configs
+// 5. Helper functions (private first, public after)
+// 6. Main plugin export
+// 7. Hook implementations
+
+export default {
+  // Plugin definition
+} as Plugin;
+```
+
+### Working with OpenCode Plugin SDK
+
+```typescript
+// ✅ REQUIRED: Use proper hook signatures
+import { tool, type Plugin } from "@opencode-ai/plugin";
+
+export default {
+  id: "working-memory",
+  name: "Working Memory Plugin",
+  
+  // ✅ Core hooks
+  hooks: {
+    "tool.execute.after": async (ctx) => {
+      // Tool just executed
+    },
+    "experimental.chat.system.transform": async (ctx) => {
+      // Transform system prompt before sending
+    },
+    "experimental.session.compacting": async (ctx) => {
+      // Session is being compacted (clearing old messages)
+    },
+  },
+  
+  // ✅ Exposed tools
+  tools: [
+    tool({
+      id: "core_memory_update",
+      name: "Update Core Memory",
+      description: "Update goal/progress/context blocks",
+      // ... schema & execute
+    }),
+  ],
+} as Plugin;
+```
+
+## Key Implementation Details
+
+### Core Memory Files
+- Location: `.opencode/memory-core/<sessionID>.json`
+- Schema: `{ sessionID, blocks: { goal, progress, context }, updatedAt }`
+- Limits: goal (1000 chars), progress (2000 chars), context (1500 chars)
+
+### Working Memory Files
+- Location: `.opencode/memory-working/<sessionID>.json`
+- Schema: `{ sessionID, slots, pool, eventCounter, updatedAt }`
+- Slot limits: error (3), decision (5), todo (3), dependency (3)
+- Pool decay: γ=0.85 per event
+
+### Pressure Monitoring
+- Triggers at: 70% (safe→moderate), 85% (moderate→high), 95% (high→critical)
+- Files: `.opencode/memory-working/<sessionID>_pressure.json`
+- Intervention: Sends `promptAsync()` with complete visible prompt
+
+### Storage Governance (Layer 1 & 2)
+- **Layer 1**: Session deletion cleanup - removes orphaned memory files
+- **Layer 2**: Tool output cache sweep - maintains 300 most recent files, 7-day TTL
+- Triggered at `eventCounter % 500 === 0` (automatic maintenance)
+
+## Debugging & Testing
+
+### Manual Testing Steps
+1. **Phase 1 (Core Memory)**: Check `.opencode/memory-core/` after `core_memory_update`
+2. **Phase 2 (Smart Pruning)**: Verify tool outputs are filtered before context injection
+3. **Phase 3 (Working Memory)**: Check `.opencode/memory-working/` for slot/pool items
+4. **Phase 4 (Pressure Monitoring)**: Monitor pressure % in system prompts, verify interventions
+5. **Phase 4.5 (Storage Governance)**: Run 500+ events, check sweep logs
+
+### Common Issues
+- **File not found**: Ensure `.opencode/` directory exists and is writable
+- **Type errors**: Check all imports use `import type { ... }` for types
+- **Lost memory**: Verify `.opencode/memory-*/` is in `.gitignore` (not committed)
+- **Sweep not running**: Check `eventCounter` in `<sessionID>.json`, should trigger at multiples of 500
+
+## Performance Considerations
+
+- **Memory budgets**: Core (5.5k chars total), Working (1.6k chars for system prompt)
+- **Pruning**: Hyper-aggressive mode activates at ≥85% pressure
+- **Compaction**: Preserves most recent 10 items when space-constrained
+- **Decay**: Pool items scored by exponential decay (γ=0.85) + mention count
+- **Storage sweep**: Limits cache to 300 files, removes files older than 7 days
+
+## File Path References
+
+When referencing code locations in documentation/comments, use:
+```
+path/to/file.ts:L123  or  path/to/file.ts:Line 123
+```
+
+Example: `Function sendPressureInterventionMessage() @ index.ts:L1286`
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make changes following the code style guidelines above
+4. Test manually in OpenCode session
+5. Commit with descriptive message: `git commit -m "Add feature: ..."`
+6. Push to your fork: `git push origin feature/my-feature`
+7. Open a pull request
+
+## Architecture Documentation
+
+See `docs/architecture.md` for detailed technical documentation including:
+- Memory tier hierarchy
+- Pruning algorithms
+- Decay formulas
+- Pressure monitoring logic
+- Storage governance policies
+
+---
+
+**Last Updated**: February 2026  
+**Plugin Status**: Production (Phases 1-4.5 complete)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenCode Working Memory Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,242 @@
+# OpenCode Working Memory Plugin
+
+[![npm version](https://img.shields.io/npm/v/opencode-working-memory.svg)](https://www.npmjs.com/package/opencode-working-memory)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**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/sdwolf4103/opencode-working-memory/main/docs/installation.md
+```
+
+**Option B: Manual setup**
+
+1. Add to your `~/.config/opencode/opencode.json`:
+
+```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:**
+
+```bash
+# 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% moderate → 90% high)
+- 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](docs/installation.md) - Detailed setup instructions
+- [Architecture Overview](docs/architecture.md) - How it works under the hood
+- [Configuration](docs/configuration.md) - Customization options
+- [Agent Developer Guide](AGENTS.md) - 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% (moderate) / 90% (high)                   │
+│  • 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`:
+
+```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](docs/configuration.md) for all options.
+
+## Requirements
+
+- OpenCode >= 1.0.0
+- Node.js >= 18.0.0
+- `@opencode-ai/plugin` >= 1.2.0
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
+
+## Support
+
+- 📖 [Documentation](docs/)
+- 🐛 [Report Issues](https://github.com/sdwolf4103/opencode-working-memory/issues)
+- 💬 [Discussions](https://github.com/sdwolf4103/opencode-working-memory/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**