You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CHANGELOG.md
+32Lines changed: 32 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
5
5
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
8
+
## [1.5.0] - 2026-04-29
9
+
10
+
### Added
11
+
12
+
- Strength-based workspace memory retention using exponential decay instead of additive priority scoring.
13
+
- Per-type rendered caps for workspace memory candidates: feedback 10, decision 10, project 8, and reference 6.
14
+
- Safety-critical memory weighting and type-cap exemption so important entries survive type floods while still competing under the global rendered cap.
15
+
- Dormant-workspace effective age: after 14 days without activity, additional dormant time counts at 0.25x for retention decay.
16
+
- Reinforcement tracking for repeated memories, with same-session and one-hour guards to prevent accidental reinforcement spam.
17
+
- Memory health diagnostics for stored vs rendered counts, type caps, global cap overflow, dormancy, retention monitoring, and strength-ranked top/weakest entries.
18
+
- CLI smoke tests and regression fixtures covering retention decay, stale-prune removal, type caps, reinforcement, invalid timestamps, and diagnostics.
19
+
20
+
### Changed
21
+
22
+
- Workspace memory rendering now ranks entries by retention strength, not the previous priority/penalty model.
23
+
- Confidence is retained for compatibility but no longer affects retention scoring.
24
+
- Old or stale-marked memories are no longer hard-pruned; they remain stored and only fall out of rendered context through strength and cap competition.
25
+
- Existing duplicate promotion and dedupe paths now reinforce the surviving memory instead of only absorbing the duplicate.
26
+
- Health output now separates stored active memories from rendered candidates to make cap behavior easier to understand.
27
+
- Default prompt budgets are lower after calibration against observed rendered output: workspace memory is 3600 characters and hot session state is 700 characters.
28
+
29
+
### Fixed
30
+
31
+
- Invalid `updatedAt` or `retentionClock` values no longer produce `NaN` retention strength or unstable sorting.
32
+
- Dormant age calculation only discounts the dormant overlap since an entry was created, so new memories do not inherit old workspace dormancy.
33
+
- Type max totals above the global cap are handled correctly: the global rendered limit still wins.
Copy file name to clipboardExpand all lines: README.md
+34-10Lines changed: 34 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,9 +5,9 @@
5
5
6
6
Automatic memory for OpenCode agents.
7
7
8
-
OpenCode Working Memory helps your agent keep useful context across compactions and sessions: project decisions, preferences, important references, active files, and unresolved errors.
8
+
Working memory is context that **remembers what matters, fades what changes, and stays out of the way.**
9
9
10
-
It works automatically, without manual memory tools or extra LLM/API calls.
10
+
OpenCode Working Memory preserves project decisions, preferences, and references across compactions and sessions, while keeping active files and unresolved errors fresh for the current session — with no manual tools or extra LLM/API calls.
11
11
12
12
## Why This Exists
13
13
@@ -31,6 +31,7 @@ Use it when you want your agent to remember things like:
-**No manual tools** — memory is injected automatically into the system prompt.
33
33
-**Quality guards** — filters noisy memories, temporary progress snapshots, stack traces, raw errors, and credentials.
34
+
-**Retention decay** — keeps the strongest memories in prompt context while older or weaker memories fade out naturally; important and reinforced memories decay more slowly.
34
35
35
36
## Installation
36
37
@@ -121,6 +122,27 @@ Memory types:
121
122
-`decision` — important implementation or architecture decisions
122
123
-`reference` — useful paths, commands, or configuration references
123
124
125
+
### Retention Decay
126
+
127
+
> **Memory should fade, so the agent can keep learning.**
128
+
>
129
+
> Important memories decay more slowly, but every memory must leave room for newer project reality.
130
+
131
+
Memories decay over time. The strongest stay visible in the prompt; weaker ones fade from context without being deleted.
132
+
133
+
```text
134
+
strength
135
+
│
136
+
██ │╲____ reinforced: slower decline
137
+
│ ╲______
138
+
▒▒ │ ╲__ ordinary memory
139
+
│ ╲
140
+
├ ─ ─ ─ ─ ─ ─ ─ ─╲─ dynamic cap competition zone
141
+
░░ │ ╲ easier for new memories to replace
142
+
│ ↑ still stored, not deleted
143
+
└──────────────────────────────→ time / sessions
144
+
```
145
+
124
146
## Explicit Memory Triggers
125
147
126
148
You can explicitly ask the agent to remember durable facts.
@@ -167,13 +189,15 @@ It includes guards for:
167
189
168
190
- Credential redaction
169
191
- Duplicate memory cleanup
170
-
-Superseding older decisions with newer ones
171
-
-Consolidation accounting so promoted, absorbed, superseded, and rejected memories are handled differently
192
+
-Accounting for promoted, absorbed, superseded, and rejected memories
193
+
-Strength-based retention so useful memories stay visible without hard age pruning
172
194
- Filtering stack traces, git hashes, raw errors, and noisy path-heavy facts
173
195
- Rejecting temporary project progress snapshots
174
196
175
197
The goal is to remember durable facts, not every detail.
176
198
199
+
**Good memory is selective memory.**
200
+
177
201
Historical cleanup is intentionally conservative: extraction-time filtering may reject more aggressively, but one-time migration cleanup only supersedes high-confidence garbage patterns. This protects existing durable memories written in declarative style, such as "API endpoint is X" or "Product branding is Y".
178
202
179
203
For local development cleanup, use:
@@ -191,21 +215,21 @@ OpenCode Working Memory works out of the box.
Copy file name to clipboardExpand all lines: RELEASE_NOTES.md
+101Lines changed: 101 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,106 @@
1
1
# Release Notes
2
2
3
+
## 1.5.0 (2026-04-29)
4
+
5
+
### Retention Decay Model
6
+
7
+
This release changes workspace memory retention from hard stale pruning and additive priority scoring to a strength-based decay model.
8
+
9
+
Think of it like a forgetting curve: memories fade over time, but important, reinforced, and safety-critical memories decay slower. Weak entries fall out of rendered prompt context by cap competition, not hard deletion.
10
+
11
+
> **Memory should fade, so the agent can keep learning.**
12
+
> Important memories decay slower, but every memory must leave room for newer project reality and avoid long-term memory pollution.
13
+
14
+
```text
15
+
strength
16
+
│
17
+
██ │╲____ reinforced: slower decline
18
+
│ ╲______
19
+
▒▒ │ ╲__ ordinary memory
20
+
│ ╲
21
+
├ ─ ─ ─ ─ ─ ─ ─ ─╲─ dynamic cap competition zone
22
+
░░ │ ╲ easier for new memories to replace
23
+
│ ↑ still stored, not deleted
24
+
└──────────────────────────────→ time / sessions
25
+
```
26
+
27
+
### What Changed
28
+
29
+
-**Strength-based retention**: workspace memory now uses exponential decay: initial strength × age decay.
30
+
-**Better initial strength**: type, source, user importance, and safety-critical status now determine how strong a memory starts.
31
+
-**No confidence scoring**: confidence remains in stored data for compatibility, but it no longer affects retention ranking.
32
+
-**Type caps**: rendered workspace memory now caps feedback, decisions, project facts, and references separately so one type cannot monopolize all 28 slots.
33
+
-**Safety-critical protection**: safety-critical entries get stronger retention and are exempt from per-type caps, while still competing under the global rendered cap.
34
+
-**Dormant-aware age**: after 14 inactive days, additional dormant workspace time counts at 0.25x so paused projects do not forget too aggressively.
35
+
-**Reinforcement**: repeated matching memories reinforce the survivor and slow future decay, with same-session and one-hour guards to avoid accidental spam.
36
+
-**No hard stale pruning**: old or stale-marked memories are no longer automatically dropped by age; they lose rendered space only through cap competition.
37
+
-**Calibrated prompt budgets**: observed rendered output was typically under ~2000 characters for workspace memory and ~500 characters for hot session state, so defaults were reduced to 3600 and 700 characters to keep overhead lower while retaining buffer.
38
+
-**Clearer health output**: `memory-diag health` now reports stored vs rendered counts, type caps, global cap overflow, dormancy, retention monitoring, and strength-ranked top/weakest entries.
39
+
40
+
### Why This Helps
41
+
42
+
- User preferences and explicit memories are less likely to disappear just because inferred project facts are newer.
43
+
- Feedback, decisions, project facts, and references share prompt space more fairly.
44
+
- Returning to an old workspace is less punishing because dormant time decays more slowly.
45
+
- Maintainers can see why memories are rendered or capped instead of guessing from a single active-memory count.
46
+
- Stale entries can fade out of prompt context without destructive cleanup.
47
+
48
+
### Diagnostics
49
+
50
+
Maintainers can inspect retention behavior with:
51
+
52
+
```bash
53
+
bun scripts/memory-diag.ts health
54
+
```
55
+
56
+
The health output now includes sections like:
57
+
58
+
```txt
59
+
Stored active memories: 28
60
+
Rendered candidates: 20
61
+
62
+
By type:
63
+
feedback stored=17 rendered=10 typeCap=10
64
+
decision stored=11 rendered=10 typeCap=10
65
+
66
+
Retention caps:
67
+
type-capped entries: 8
68
+
global-cap overflow: 0
69
+
70
+
Dormancy:
71
+
dormant discount active: no
72
+
73
+
Retention monitoring:
74
+
high_importance_ratio: 0.0% (alert > 30%)
75
+
```
76
+
77
+
### Not Included Yet
78
+
79
+
- Delete tombstones are not implemented in this release.
80
+
- Explicit `supersedes` chain enforcement is still deferred.
Initial strength is based on memory type, source, optional user importance, and safety-critical status. Confidence remains stored for compatibility but is not part of retention scoring.
113
+
114
+
Rendered candidates are selected in this order:
115
+
116
+
1. Exclude `status: "superseded"` entries.
117
+
2. Compute current retention strength.
118
+
3. Sort by strength descending.
119
+
4. Apply per-type caps, with safety-critical entries exempt from type caps.
120
+
5. Keep the top 28 rendered entries under the workspace memory character budget.
121
+
122
+
Default type caps:
123
+
124
+
| Type | Rendered cap |
125
+
|------|--------------|
126
+
|`feedback`| 10 |
127
+
|`decision`| 10 |
128
+
|`project`| 8 |
129
+
|`reference`| 6 |
130
+
131
+
The type-cap total is 34, intentionally above the global 28-entry cap. These are maximums, not quotas.
132
+
133
+
Dormant workspaces age more slowly: after 14 inactive days, additional dormant time counts at 0.25x for retention decay. Repeated duplicate memories reinforce the surviving entry and slow future decay, but same-session and under-one-hour repeats do not stack reinforcement.
134
+
105
135
### System Prompt Injection
106
136
107
137
Workspace memory is injected at the top of every message:
-`session.compacted`: Promote session decisions to workspace memory
242
272
-`session.deleted`: Clean up session state files
243
273
244
-
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.
274
+
Promotion uses accounting results from workspace memory normalization. Pending memories that are kept are promoted; duplicate memories are absorbed; exact decision replacements can be superseded; over-capacity compaction memories are rejected. Stale-marked memories are not hard-pruned by age; they lose rendered space through retention strength and cap competition.
0 commit comments