ai-space/opencode-working-memory
3
0
Fork 0
mirror of https://github.com/sdwolf4103/opencode-working-memory.git synced 2026-06-02 06:19:36 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: prepare v1.3.0 release notes

Browse Source
This commit is contained in:
Ralph Chang
2026-04-27 17:06:43 +08:00
parent ef1248f23a
commit 909fec9abb
7 changed files with 132 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+3 -3
View File
@@ -1,8 +1,8 @@
# AGENTS.md - OpenCode Working Memory Plugin Development Guide
# AGENTS.md - OpenCode Working Memory Development Guide
## Project Overview
The **OpenCode Working Memory Plugin** provides a **three-layer memory architecture** for AI agents:
**OpenCode Working Memory** provides a **three-layer memory architecture** for AI agents:
1. **Workspace Memory** - Long-term memory that persists across sessions (decisions, project info, references)
2. **Hot Session State** - Automatic tracking of active files, open errors, and recent decisions
@@ -325,4 +325,4 @@ See `docs/architecture.md` for detailed technical documentation including:
---
**Last Updated**: April 2026
**Plugin Status**: Production (Memory V2 architecture)
**Plugin Status**: Production (Memory V2 architecture)
CHANGELOG.md
+30 -12
View File
@@ -13,10 +13,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Accounting-aware deduplication (`dedupeLongTermEntriesWithAccounting`).
- Accounting-aware normalization (`normalizeWorkspaceMemoryWithAccounting`).
- Promotion classification: promoted, absorbed, superseded, rejected.
- Clear terminal low-value compaction candidates after promotion review.
- Remove absorbed/superseded keys from rejected set to avoid duplicate rejection tracking.
- Memory quality evaluation fixtures covering accepted durable facts and rejected noisy facts.
- Sharper compaction memory extraction prompt with concrete good/bad memory examples.
### Fixed
- Promotion accounting now clears only pending memories that survive workspace normalization/cap limits.
- `session.deleted` now uses shared session ID extraction, matching `session.compacted` behavior.
- Absorbed duplicate pending memories are accounted for instead of retrying forever.
- Active vs superseded boundary when promoting pending memories (superseded entries no longer block promotion of same-key active memories).
- Removed unused `rejected_duplicate_lower_quality` type.
@@ -24,34 +29,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Deferred pending journal safety cap implementation (see TODO in `src/pending-journal.ts`).
- Clarified superseded accounting semantics: P0 emits events only, does not archive newly superseded records.
- README structure was streamlined around the automatic memory flow and ongoing memory-quality work.
- Architecture docs now describe `Memory candidates:` as the primary extraction format and XML candidate blocks as legacy.
- Superpowers implementation plans are no longer tracked in git.
## [1.2.3] - 2026-04-26
### Added
- Frozen workspace memory snapshot in `system[1]` for better OpenCode prompt-cache stability.
- Ephemeral hot session state and pending memories in later system messages.
- Durable pending journal so explicit memories survive until promotion.
### Fixed
- Account for absorbed pending memories in promotion accounting.
- Clarify cache epoch semantics and add regression tests.
- Explicit memories no longer mutate the frozen workspace snapshot mid-session.
- Pending memories are promoted at safe cache-epoch boundaries.
## [1.2.0] - 2026-04-25
### Added
- Memory quality evaluation fixtures (5 accepted, 7 rejected cases).
- Compaction prompt examples for better memory extraction.
- Promotion accounting for pending memories.
- Memory V2 three-layer architecture.
- Workspace memory for durable cross-session decisions, preferences, project facts, and references.
- Hot session state for active files, open errors, and recent context.
- Hook-based memory extraction during OpenCode compaction.
### Changed
- Removed manual memory tools in favor of automatic prompt injection.
- Moved storage to `~/.local/share/opencode-working-memory/`.
## [1.1.0] - 2026-04-24
### Added
### Changed
- Workspace memory cache optimization with frozen snapshots.
- Pending journal durability for same-session visibility.
- Credential redaction always-on.
- Improved pre-V2 memory documentation and installation flow.
## [1.0.0] - 2026-04-23
### Added
- Initial release with three-layer memory architecture.
- Hot session state, workspace memory, pending journal.
- Memory extraction from user messages and compaction summaries.
- Initial OpenCode memory integration.
- Basic memory extraction and prompt injection.
README.md
+9 -8
View File
@@ -1,11 +1,11 @@
# OpenCode Working Memory Plugin
# OpenCode Working Memory
[![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)
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.
OpenCode Working Memory 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.
@@ -13,7 +13,7 @@ It works automatically, without manual memory tools or extra LLM/API calls.
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.
It 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:
@@ -34,7 +34,7 @@ Use it when you want your agent to remember things like:
## Installation
Add the plugin to your OpenCode config:
Add OpenCode Working Memory to your OpenCode config:
```json
{
@@ -42,7 +42,7 @@ Add the plugin to your OpenCode config:
}
```
Then restart OpenCode. The plugin activates automatically.
Then restart OpenCode. It activates automatically.
## How It Works
@@ -89,7 +89,7 @@ OpenCode Working Memory adds durable memory without making extra LLM/API calls.
└──────────────────────────────────────┘
```
**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.
**Zero extra API calls:** OpenCode Working Memory 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.
@@ -161,13 +161,14 @@ Avoid saving:
## Quality Guards
The plugin tries to keep memory useful and low-noise.
OpenCode Working Memory tries to keep memory useful and low-noise.
It includes guards for:
- Credential redaction
- Duplicate memory cleanup
- Superseding older decisions with newer ones
- Consolidation accounting so promoted, absorbed, superseded, and rejected memories are handled differently
- Filtering stack traces, git hashes, raw errors, and noisy path-heavy facts
- Rejecting temporary project progress snapshots
@@ -175,7 +176,7 @@ The goal is to remember durable facts, not every detail.
## Configuration
The plugin works out of the box.
OpenCode Working Memory works out of the box.
Default behavior:
RELEASE_NOTES.md
+45 -2
View File
@@ -1,10 +1,53 @@
# Release Notes
## 1.3.0 (2026-04-27)
### Better Memory Consolidation
This release makes OpenCode Working Memory smarter about what happens to saved memories after compaction. Instead of treating every pending memory as simply "kept" or "not kept", it now understands four outcomes:
- **Promoted** — a new memory was saved to workspace memory.
- **Absorbed** — the memory was a duplicate of something already remembered.
- **Superseded** — a newer same-topic decision or preference replaced an older one.
- **Rejected** — the memory was stale, noisy, or over the workspace memory limit.
### What This Improves
- **Fewer repeated pending memories**: duplicate or superseded memories no longer keep coming back for promotion.
- **Cleaner long-term memory**: old same-topic decisions are replaced more predictably.
- **Safer promotion accounting**: pending memories are only cleared when the final normalized workspace memory confirms what happened to them.
- **More useful compaction output**: the compaction prompt now includes clearer examples of what should and should not become durable memory.
### Also Included
- Memory quality regression fixtures: 5 examples that should be kept and 7 noisy examples that should be rejected.
- Fix for `session.deleted` session ID extraction so cleanup and promotion use the same event parsing path.
- Fix for active-vs-superseded promotion behavior: archived superseded entries no longer block a fresh active memory.
- README and architecture documentation updates.
### Upgrade Notes
- No user migration is required.
- Existing workspace memory files remain compatible.
- The OpenCode config entry stays the same:
```json
{
"plugin": ["opencode-working-memory"]
}
```
### Tests
- **135 tests pass**.
---
## 1.2.3 (2026-04-27)
### Prompt Cache Optimization — Frozen Snapshot + Ephemeral Delta
This release optimizes the plugin's impact on OpenCode's prompt cache, following Hermes-style architecture patterns.
This release optimizes OpenCode Working Memory's impact on OpenCode's prompt cache, following Hermes-style architecture patterns.
### Key Features
@@ -219,4 +262,4 @@ LICENSE
- Core Memory blocks (goal/progress/context)
- Working Memory with slots and pool
- Pressure monitoring with interventions
- Smart pruning of tool outputs
- Smart pruning of tool outputs
docs/architecture.md
+27 -18
View File
@@ -2,7 +2,7 @@
## Overview
The Working Memory Plugin implements a **three-layer memory architecture** designed to preserve context across OpenCode session compactions.
OpenCode Working Memory implements a **three-layer memory architecture** designed to preserve context across OpenCode session compactions.
```
┌─────────────────────────────────────────────────────────────┐
@@ -73,7 +73,7 @@ Long-term memory that persists across sessions within the same workspace. Perfec
### Memory Extraction
During compaction, the plugin scans for `Memory candidates:` sections:
During compaction, OpenCode Working Memory scans for `Memory candidates:` sections:
```
Memory candidates:
@@ -81,32 +81,39 @@ Memory candidates:
- [project] This repo uses TypeScript with strict mode
```
**Legacy Format**: The plugin also accepts `<workspace_memory_candidates>` XML blocks for backward compatibility, but this format is deprecated.
**Legacy Format**: OpenCode Working Memory also accepts `<workspace_memory_candidates>` XML blocks for backward compatibility, but this format is deprecated.
**Quality Gate**: Not all candidates become memories. The plugin rejects:
**Quality Gate**: Not all candidates become memories. OpenCode Working Memory rejects:
- Git commit hashes (e.g., `abc1234`)
- Raw errors (e.g., `Error: something failed`)
- Stack traces
- Path-heavy facts (>50% paths)
- Very short text (<20 chars)
### Deduplication
### Consolidation and Deduplication
Memories are deduplicated using **canonical text matching**:
1. Normalize: lowercase, strip punctuation, collapse whitespace
2. Hash the canonical text
3. Keep the entry with highest confidence
Memories are deduplicated and consolidated with accounting:
1. Normalize exact text: lowercase, strip punctuation, collapse whitespace.
2. Group project/reference entries by identity where possible.
3. Group decisions and feedback by topic where possible.
4. Keep the best surviving entry by source, confidence, type, and freshness rules.
5. Emit accounting events so pending memories can be classified as promoted, absorbed, superseded, or rejected.
This prevents absorbed or superseded pending memories from retrying forever while still preserving the active surviving memory.
### System Prompt Injection
Workspace memory is injected at the top of every message:
```
<workspace_memory>
- [decision] Use npm cache for plugin loading, not npm link
- [project] This repo uses opencode-agenthub plugin system
- [reference] Storage: ~/.local/share/opencode-working-memory/...
</workspace_memory>
Workspace memory (cross-session, verify if stale):
decision:
- Use npm cache for plugin loading, not npm link
project:
- This repo uses the opencode-agenthub plugin system
reference:
- Storage: ~/.local/share/opencode-working-memory/...
```
## Layer 2: Hot Session State
@@ -211,7 +218,7 @@ Delegate task tracking to OpenCode's native features.
## Plugin Hooks
The plugin hooks into OpenCode lifecycle events:
OpenCode Working Memory hooks into OpenCode lifecycle events:
### `experimental.chat.system.transform`
@@ -227,13 +234,15 @@ Injects workspace memory and hot session state into system prompt.
### `experimental.session.compacting`
Extracts workspace memory candidates from conversation.
Applies quality gate, deduplication, and source priority.
Applies quality gate, redaction, migration, consolidation accounting, deduplication, and source priority.
### `event` (session.compacted, session.deleted)
- `session.compacted`: Promote session decisions to workspace memory
- `session.deleted`: Clean up session state files
Promotion uses accounting results from workspace memory normalization. Pending memories that are kept are promoted; duplicate memories are absorbed; obsolete same-topic memories are superseded; stale or over-capacity compaction memories are rejected.
## Quality Guarantees
### No False Positive Errors
@@ -349,9 +358,9 @@ Modify `src/extractors.ts` to add new extraction patterns.
### Memory V1 to V2
The plugin automatically migrates old format files to the new three-layer architecture. No manual intervention needed.
OpenCode Working Memory automatically migrates old format files to the new three-layer architecture. No manual intervention needed.
---
**Last Updated**: April 2026
**Implementation**: `src/plugin.ts`, `src/extractors.ts`, `src/workspace-memory.ts`, `src/session-state.ts`
**Implementation**: `src/plugin.ts`, `src/extractors.ts`, `src/workspace-memory.ts`, `src/session-state.ts`
docs/configuration.md
+5 -5
View File
@@ -2,7 +2,7 @@
## Overview
The Working Memory Plugin works out-of-the-box with sensible defaults. Configuration is defined in `src/types.ts` as constants.
OpenCode Working Memory works out-of-the-box with sensible defaults. Configuration is defined in `src/types.ts` as constants.
## Workspace Memory Limits
@@ -192,21 +192,21 @@ rm ~/.local/share/opencode-working-memory/workspaces/*/sessions/*.json
## Best Practices
1. **Workspace Memory Hygiene**:
- Let the plugin extract memories automatically
- Let OpenCode Working Memory extract memories automatically
- Use explicit "remember this" for important information
- Don't manually edit memory files unless testing
2. **Session State**:
- Let the plugin track active files automatically
- Let OpenCode Working Memory track active files automatically
- Errors are cleared when commands succeed
- No manual intervention needed
3. **Memory Extraction**:
- Use `<workspace_memory_candidates>` during compaction
- Use `Memory candidates:` during compaction
- Follow the pattern: `- [type] text`
- Quality gate rejects invalid candidates
---
**Last Updated**: April 2026
**Configuration File**: `src/types.ts`
**Configuration File**: `src/types.ts`
docs/installation.md
+13 -13
View File
@@ -10,7 +10,7 @@ Add to your `~/.config/opencode/opencode.json`:
}
```
Restart OpenCode. The plugin activates automatically — no manual setup needed.
Restart OpenCode. OpenCode Working Memory activates automatically — no manual setup needed.
> **Note**: The correct key is `plugin` (singular), not `plugins`.
@@ -25,22 +25,22 @@ Restart OpenCode. The plugin activates automatically — no manual setup needed.
After restarting OpenCode, memory context appears automatically in system prompts. You'll see:
```
<workspace_memory>
- [decision] ... (if any long-term memories exist)
</workspace_memory>
Workspace memory (cross-session, verify if stale):
decision:
- ... (if any long-term memories exist)
---
<workspace_memory_candidates>
Memory candidates:
- [project] ... (candidates for long-term memory)
</workspace_memory_candidates>
Active Files:
Hot session state (current session):
active_files:
- path/to/file.ts (action, count)
Open Errors: (none, or listed)
open_errors: (none, or listed)
```
**No tools to call**. The plugin works automatically via hooks.
**No tools to call**. OpenCode Working Memory works automatically via hooks.
## How Memory Works
@@ -72,8 +72,8 @@ Tracks current session:
**Solution**:
1. Ensure OpenCode has write permissions in home directory
2. Trigger memory operations by working normally (plugin creates files on-demand)
3. Check that plugin is listed in config
2. Trigger memory operations by working normally (memory files are created on-demand)
3. Check that `opencode-working-memory` is listed in config
### Memory Not Persisting
@@ -81,7 +81,7 @@ Tracks current session:
**Solution**:
1. Verify you're in the same workspace (different workspace = different memory)
2. Ensure `<workspace_memory_candidates>` were captured during compaction
2. Ensure `Memory candidates:` were captured during compaction
3. Check `workspace-memory.json` exists
### Type Errors During Development
@@ -132,4 +132,4 @@ rm -rf ~/.local/share/opencode-working-memory/workspaces/*/sessions/*.json
---
**Last Updated**: April 2026
**Last Updated**: April 2026