docs: prepare v1.3.0 release notes

Author: sdwolf4103

AGENTS.md

@@ -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

@@ -13,45 +13,63 @@ 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.
 
 ### Changed
 
 - 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

@@ -1,19 +1,19 @@
-# 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.
 
 ## 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.
+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,15 +34,15 @@ 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
 {
   "plugin": ["opencode-working-memory"]
 }
 ```
 
-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,21 +161,22 @@ 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
 
 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

@@ -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

@@ -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,40 +73,47 @@ 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:
 - [decision] Use npm cache for plugin loading
 - [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

@@ -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`