Skip to content

feat(memory): add relevance-based auto-recall and opt-in dreaming #461

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
EyJunge1 merged 1 commit into from
Oct 30, 2026
Merged

feat(memory): add relevance-based auto-recall and opt-in dreaming #461

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 19 additions & 8 deletions .github/i18n/README.de.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -262,21 +262,32 @@ Wenn Markdown-Modus aktiv ist:

Diese Einstellungen liegen unter dem Schlüssel `chatMessage` in `~/.config/opencode/opencode-mem.jsonc`:

| Option | Standard | Was sie tut |
| ------------------------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | `true` | Verfasste User-Prompts erfassen und Speicher-Kontext injizieren. |
| `injectOn` | `"first"` | Speicher-Kontext bei der ersten User-Nachricht einer Sitzung injizieren, oder bei `"always"` bei jedem verfassten Turn. |
| `maxMemories` / `excludeCurrentSession` / `maxAgeDays` | `3` / `true` / — | Wie viele Memories der injizierte Kontext hält, ob Memories aus der aktuellen Sitzung ausgeschlossen werden, und optionaler Alters-Cutoff in Tagen. |
| `filterInjectedPrompts` | `true` | Prompt-Text überspringen, der vom Host oder anderen OpenCode-Plugins injiziert wurde (System-Reminders, Orchestrierungsanweisungen, Background-Task-Benachrichtigungen), damit er nie so gespeichert wird, als hätte ihn der User getippt. |
| `injectionMarkers` | Built-ins | Zusätzliche Marker zur Erkennung injizierter Blöcke; werden zur Built-in-Liste hinzugefügt, ersetzen sie nie. |
| `captureChildSessions` | `false` | Prompts aus Orchestrator-Child-Sitzungen erfassen (Sitzungen mit `parentID`, z. B. OpenCode-Task-/Subagent-Children). Deren „User“-Nachrichten schreibt der Parent-Agent, nicht du — daher werden sie standardmäßig nicht gespeichert, auto-captured, für Profil-Lernen genutzt oder mit injiziertem Speicher-Kontext versehen. |
| Option | Standard | Was sie tut |
| ------------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | `true` | Verfasste User-Prompts erfassen und Speicher-Kontext injizieren. |
| `injectOn` | `"first"` | Bei `recall: "recent"`: Kontext bei der ersten User-Nachricht oder bei `"always"` jedem Turn. Bei `recall: "relevant"` / `"both"` wird der Kontext bei jedem verfassten Turn neu geladen (Issue #460). |
| `recall` | `"relevant"` | Auswahl injizierter Memories: `"relevant"` bettet die User-Nachricht ein und sucht per Vektor (jeder Turn); `"recent"` behält die Legacy-Newest-N-Liste; `"both"` bevorzugt relevant und füllt mit recent auf. |
| `recallScope` | `"default"` | Scope für Auto-Recall: `"default"` folgt `memory.defaultScope`, oder `"project"` / `"all-projects"`. Bei All-Projects erhalten Treffer aus dem aktuellen Projekt einen kleinen Similarity-Boost. |
| `maxMemories` / `excludeCurrentSession` / `maxAgeDays` | `3` / `true` / — | Wie viele Memories der injizierte Kontext hält, ob Memories aus der aktuellen Sitzung ausgeschlossen werden, und optionaler Alters-Cutoff in Tagen. |
| `filterInjectedPrompts` | `true` | Prompt-Text überspringen, der vom Host oder anderen OpenCode-Plugins injiziert wurde (System-Reminders, Orchestrierungsanweisungen, Background-Task-Benachrichtigungen), damit er nie so gespeichert wird, als hätte ihn der User getippt. |
| `injectionMarkers` | Built-ins | Zusätzliche Marker zur Erkennung injizierter Blöcke; werden zur Built-in-Liste hinzugefügt, ersetzen sie nie. |
| `captureChildSessions` | `false` | Prompts aus Orchestrator-Child-Sitzungen erfassen (Sitzungen mit `parentID`, z. B. OpenCode-Task-/Subagent-Children). Deren „User“-Nachrichten schreibt der Parent-Agent, nicht du — daher werden sie standardmäßig nicht gespeichert, auto-captured, für Profil-Lernen genutzt oder mit injiziertem Speicher-Kontext versehen. |

Ausschlüsse nach Sitzung und Alter werden vor dem Limit für injizierte Memories
angewendet. Ausgeschlossene Memories belegen daher keine Plätze, die für geeignete
Memories verfügbar wären. Mit `chatMessage.maxMemories` auf `0` wird die Injektion
von Projekt-Memories deaktiviert; das Nutzerprofil kann weiterhin injiziert werden,
wenn es aktiviert ist.

### Dreaming (optionale Memory-Konsolidierung)

Opt-in-Hintergrundlauf, der Near-Duplikate findet (gleicher Similarity-Schwellwert wie
Deduplizierung), sie über `opencodeProvider`/`opencodeModel` zusammenführt und ersetzte
Einträge soft-deleten (wiederherstellbarer Papierkorb). Gepinnte Memories bleiben unberührt.
Konfiguration unter `dreaming` in `opencode-mem.jsonc` (`enabled` Standard `false`). Die
Web-UI bietet **Papierkorb** und **Dreaming**. Soft-gelöschte Zeilen werden nach
`dreaming.trashRetentionDays` beim Cleanup hart bereinigt.

### Embeddings wählen / konfigurieren

Embeddings treiben die Ähnlichkeitssuche für Memories und das Benutzerprofil. Konfiguration in derselben Datei (`~/.config/opencode/opencode-mem.jsonc`). Es gibt **kein MLX-Backend** — lokale Embeddings nutzen `@huggingface/transformers` mit ONNX, nicht Apple MLX.
Expand Down
14 changes: 13 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -265,7 +265,10 @@ These settings live under the `chatMessage` key in `~/.config/opencode/opencode-
| Option | Default | What it does |
| ------------------------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled` | `true` | Capture authored user prompts and inject memory context. |
| `injectOn` | `"first"` | Inject memory context on the first user message of a session, or on `"always"` every authored turn. |
| `injectOn` | `"first"` | For `recall: "recent"`, inject on the first user message or on `"always"` every authored turn. With `recall: "relevant"` / `"both"`, context always refreshes each authored turn (issue #460). |
| `recall` | `"relevant"` | How injected memories are chosen: `"relevant"` embeds the user message and runs vector search each turn; `"recent"` keeps the legacy newest-N listing; `"both"` prefers relevant then fills remaining slots with recent. |
| `recallScope` | `"default"` | Scope for auto-recall: `"default"` follows `memory.defaultScope`, or force `"project"` / `"all-projects"`. When searching all projects, hits from the current project get a small similarity boost. |
| `similarityThreshold` | (top-level) | Optional per-inject floor; otherwise uses the top-level `similarityThreshold`. |
| `maxMemories` / `excludeCurrentSession` / `maxAgeDays` | `3` / `true` / — | How many memories the injected context holds, whether memories captured in the current session are excluded, and an optional age cutoff in days. |
| `filterInjectedPrompts` | `true` | Skip prompt text injected by the host or by other OpenCode plugins (system reminders, orchestration directives, background-task notifications) so it is never stored as if the user had typed it. |
| `injectionMarkers` | built-ins | Extra markers identifying injected blocks; added to the built-in list, never replacing it. |
Expand All @@ -276,6 +279,15 @@ memories do not consume slots that could hold eligible memories. Setting
`chatMessage.maxMemories` to `0` disables project-memory injection while still allowing
the user profile to be injected when enabled.

### Dreaming (optional memory consolidation)

Opt-in background pass that finds near-duplicate memories (same similarity threshold as
deduplication), asks the configured `opencodeProvider` / `opencodeModel` to merge them,
and soft-deletes superseded rows into recoverable trash. Pinned memories are never
touched. Configure under `dreaming` in `opencode-mem.jsonc` (`enabled` default `false`).
The web UI exposes **Trash** (restore) and **Dream** (manual run). Soft-deleted rows are
hard-purged after `dreaming.trashRetentionDays` during normal cleanup.

### Choosing / configuring embeddings

Embeddings power similarity search for memories and the user profile. Configure them in the same file (`~/.config/opencode/opencode-mem.jsonc`). There is **no MLX backend** — local embeddings use `@huggingface/transformers` with ONNX, not Apple MLX.
Expand Down
17 changes: 17 additions & 0 deletions opencode-mem.example.jsonc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,14 @@
// "maxAgeDays": 30,
// "first" = only on the first user message in a session; "always" = every message
"injectOn": "first",
// "relevant" (default) = vector search against each authored user prompt
// (refreshes every turn even when injectOn is "first");
// "recent" = newest-N listing (honors injectOn); "both" = relevant first, then fill
"recall": "relevant",
// "default" follows memory.defaultScope; or "project" / "all-projects"
"recallScope": "default",
// Optional override of top-level similarityThreshold for relevant recall:
// "similarityThreshold": 0.6,
// Skip prompt text injected by the host or by other OpenCode plugins
// (system reminders, orchestration directives, background-task
// notifications) so it is never stored as if the user had typed it.
Expand All @@ -147,6 +155,15 @@
// "injectionMarkers": ["<my-plugin-banner>"],
},

// Opt-in background consolidation ("dreaming"): merge near-duplicates via LLM
// and soft-delete superseded memories into recoverable trash.
"dreaming": {
"enabled": false,
"intervalHours": 24,
"maxGroupsPerRun": 5,
"trashRetentionDays": 30,
},

// ============================================
// OpenCode Provider Settings (RECOMMENDED)
// ============================================
Expand Down
Loading
Loading