opencode-memory-pro 1.3.8 → 1.4.0

package/README.md

@@ -40,7 +40,7 @@ Published on npm — install directly (requires OpenCode ≥ 1.x and Node.js ≥
 opencode plugin opencode-memory-pro
 ```
 
-The latest release is **v1.3.8** on [npm](https://www.npmjs.com/package/opencode-memory-pro); source and releases are on [GitHub](https://github.com/tman204-50/opencode-memory-pro).
+The latest release is **v1.4.0** on [npm](https://www.npmjs.com/package/opencode-memory-pro); source and releases are on [GitHub](https://github.com/tman204-50/opencode-memory-pro).
 
 Remove the old plugin pin at the same time:
 
@@ -48,6 +48,87 @@ Remove the old plugin pin at the same time:
 opencode plugin lancedb-opencode-pro -g   # removes pin (if installed)
 ```
 
+### Getting started
+
+**1. Install and restart OpenCode** — done above. That's it for a baseline
+setup: the plugin works with **zero configuration**.
+
+**2. What you get out of the box, and what needs config:**
+
+| Capability | Out of the box | Needs config to enhance |
+|---|---|---|
+| Recall | Works — falls back to pure BM25 if no embedder is reachable | **Embedding model** → semantic/hybrid vector search |
+| Capture (session → memories) | Works — offline heuristic keyword capture | **LLM summary model** → LLM-quality extraction + abstractive digests |
+| Digests (`memory_summarize` / `memory_expire`) | Extractive offline digests | Same LLM summary model → abstractive digests |
+
+> **Nothing below is required** — every enhancement has an offline fallback.
+> But configuring an embedding model makes recall dramatically better
+> (semantic similarity instead of keyword-only), and configuring an LLM
+> summary model makes captured memories higher quality and digests far more
+> useful.
+
+**3. (Optional) configure an embedding model.**
+
+The plugin stores memories in a vector store; the embedding model decides how
+well recall can find semantically related memories. Two options:
+
+- **Local (no API key, no cost):** default — `ollama` +
+  `nomic-embed-text` at `http://127.0.0.1:11434`. Requires Ollama running.
+- **OpenAI-compatible (hosted):** e.g. OpenAI, OpenRouter, or any endpoint
+  that serves the `/embeddings` API. Set `embedding.provider` to `"openai"`,
+  the model, the base URL, and an API key:
+
+```json
+{
+  "embedding": {
+    "provider": "openai",
+    "model": "openai/text-embedding-3-small",
+    "baseUrl": "https://openrouter.ai/api/v1",
+    "apiKey": "sk-..."
+  }
+}
+```
+
+If the embedder is unreachable, recall falls back to pure BM25 over the FTS
+index and capture still works — the plugin is offline-tolerant by design.
+
+**4. (Optional) configure an LLM summary model** (for LLM-quality
+capture/digests).
+
+With `capture.mode: "llm"`, on session idle the plugin sends the session
+buffer to an LLM (via an ephemeral OpenCode SDK session) which returns
+structured memories, and digests become LLM-written abstractive summaries.
+The LLM is addressed by **OpenCode provider + model IDs** — OpenCode owns
+routing, auth, and base URLs, so no API key or baseUrl lives in the plugin
+config. The provider must be resolvable in your `opencode.json`:
+
+```json
+{
+  "capture": {
+    "mode": "llm",
+    "llm": { "provider": "openrouter", "model": "z-ai/glm-5.3-flash" }
+  }
+}
+```
+
+On any LLM failure, capture **falls back to heuristics** and records an
+`llm-fallback` capture event — the plugin never breaks because the LLM is
+unavailable.
+
+**5. (Optional) start from the full annotated example** — the package includes
+`opencode-memory-pro.example.json` with every option documented in-file. Copy
+it to `~/.config/opencode/opencode-memory-pro.json` and edit:
+
+```bash
+cp node_modules/opencode-memory-pro/opencode-memory-pro.example.json ~/.config/opencode/opencode-memory-pro.json
+```
+
+**Healthy installs are never silent:** at startup the plugin logs a warning
+if it detects missing pieces (e.g. `capture.mode: "llm"` without a resolvable
+provider, or an OpenAI embedder without a key), and `memory_stats` reports the
+same as `degradedFlags`, plus `llmHealth` — so you can always tell what's
+running at full strength vs. degraded.
+
 ## Configuration
 
 The sidecar file `opencode-memory-pro.json` is resolved from (first match
@@ -408,6 +489,44 @@ so your memories and graph carry over untouched.
 
 ## Changelog
 
+### v1.4.0 (2026-09-06)
+
+Dedup correctness overhaul — the write-time duplicate check compared against
+the wrong score type, and the resulting flags were a one-way ratchet:
+
+- **Write-time dedup now compares a raw cosine similarity**: the capture path
+  went through the hybrid `search()` API, whose RRF score is algebraically
+  `>= 1.0` for `limit: 1` (and up to `1.4` with importance) — so every capture
+  in a non-empty scope compared `>= 1.0` against `dedup.writeThreshold`
+  (clamped to `[0,1]`) and got falsely flagged as a potential duplicate.
+  `storeCapturedMemory` now calls `findSimilarVectors` (the same raw cosine
+  primitive consolidation measures) and compares that to the threshold.
+  Consequence: recall scores can no longer exceed 100%, and
+  `dedup.enabled`'s write-time detection actually detects.
+- **False duplicate flags now self-correct**: `isPotentialDuplicate` was a
+  one-way ratchet — consolidation never cleared it, so `memory_stats`
+  `flaggedCount` only grew (153 flagged / 0 merged observed on a live store).
+  `consolidateDuplicates` now revalidates flags against the real cosine
+  threshold and clears (`isPotentialDuplicate`/`duplicateOf` removed) any
+  flagged row whose closest found neighbor never reaches the merge bar.
+  Returns `clearedFlags` so tools can report the correction.
+- **Auto-consolidation cooldown is per-scope**: the shared
+  `lastConsolidateAt` timestamp meant the first scope to consolidate blocked
+  all other scopes for 30 minutes. Cooldowns are now tracked per scope
+  (same for the retention sweep, which had the identical flaw).
+- **Scope cache staleness bound**: the per-process version counter can't see
+  writes from another opencode process sharing the same `dbPath`, so process A
+  could serve stale records indefinitely. Cache entries now reload after a
+  60s age bound even when the local version is unchanged (configurable via
+  `cache.staleAfterMs`; 0 restores pure version gating).
+- **Consistent truncation warnings**: `deleteByIdForce`'s 100k-row fallback
+  scan and `pruneScope`'s 100k-row read now log a warning when the cap is hit,
+  matching `getCachedScopes`.
+- **Tests**: three new integration tests — the dedup write-check primitive
+  returns cosine in `[0,1]` (plus a guard that the old RRF path still scores
+  `>= 1.0`), consolidation clears false flags, and the scope cache reloads
+  after the age bound when a second process writes behind its back.
+
 ### v1.3.8 (2026-09-06)
 
 Fixes `memory_forget(force=true)` being unable to permanently delete a memory

package/dist/index.js

@@ -11,7 +11,7 @@ import { requestLLMCapture, isOwnSession } from "./llm.js";
 import { createMemoryTools, createFeedbackTools, createEpisodicTools } from "./tools/index.js";
 import { sweepExpiredMemories } from "./tools/memory.js";
 import { createGraphStore } from "./graph.js";
-const PLUGIN_VERSION = "1.3.8";
+const PLUGIN_VERSION = "1.4.0";
 const SCHEMA_VERSION = 1;
 // Event-driven dedup: run consolidateDuplicates on session.idle (throttled to
 // this interval so chatty sessions aren't re-scanning the store every turn)
@@ -138,6 +138,23 @@ const plugin = async (input) => {
             if (!state.startupLogged) {
                 state.startupLogged = true;
                 log("info", `Plugin v${PLUGIN_VERSION} initialized`);
+                // STARTUP_DEGRADED (1.3.9): one proactive warning when the
+                // install can't reach full features, so fresh users know what
+                // to configure instead of discovering degraded mode later.
+                const missing = [];
+                const emb = state.config.embedding ?? {};
+                if (state.config.capture?.mode === "llm" && (!state.config.capture?.llm?.provider || !state.config.capture?.llm?.model)) {
+                    missing.push("capture.llm.{provider,model} (LLM capture will fall back to heuristics)");
+                }
+                if (emb.provider === "openai" && !emb.apiKey) {
+                    missing.push("embedding.apiKey (recall will fall back to BM25-only)");
+                }
+                if (emb.provider !== "openai" && !(emb.baseUrl ?? "")) {
+                    missing.push("embedding.baseUrl (defaults to http://127.0.0.1:11434)");
+                }
+                if (missing.length > 0) {
+                    log("warn", `Memory plugin running degraded: missing ${missing.join(", ")}. See README "Quick start" for full-feature setup.`);
+                }
             }
         },
         event: async ({ event }) => {
@@ -580,12 +597,16 @@ async function createRuntimeState(input) {
         activeEpisodes: new Map(),
         sessionErrors: new Map(),
         lastRecall: null,
+        // PER_SCOPE_COOLDOWN (1.4.0): cooldowns are per-scope (Map keyed by scope)
+        // instead of a single shared timestamp — one shared value meant the
+        // first scope to consolidate/sweep blocked every other scope for the
+        // whole 30-minute cooldown, even scopes that had never run.
         consolidationInProgress: new Map(),
-        lastConsolidateAt: 0,
+        lastConsolidateAt: new Map(),
         // MEMORY_RETENTION (1.0): digest-then-hide expiry sweep state — same
         // throttle pattern as consolidation (cooldown-gated, one per scope).
         sweepInProgress: new Map(),
-        lastSweepAt: 0,
+        lastSweepAt: new Map(),
         ensureInitialized: async () => {
             if (state.initialized)
                 return;
@@ -783,22 +804,19 @@ async function storeCapturedMemory(state, opts) {
     }
     let isPotentialDuplicate = false;
     let duplicateOf = null;
+    // DEDUP_COSINE_CHECK (1.4.0): the write-time dedup check used to go
+    // through the hybrid search() API, whose RRF score is algebraically >= 1.0
+    // for limit:1 (rrfScore = 1/(rrfK+1) * (rrfK+1) == 1.0, then multiplied by
+    // an importance factor in [1, 1.4]) — so every capture with any same-dim
+    // record in the scope compared >= 1.0 against writeThreshold (clamped
+    // [0,1]) and got falsely flagged as a duplicate. Now it uses
+    // findSimilarVectors, which returns a raw cosine similarity in [0,1], the
+    // same primitive consolidateDuplicates measures against.
     if (state.config.dedup.enabled) {
-        const similar = await state.store.search({
-            query: opts.text,
-            queryVector: vector,
-            scopes: [opts.scope],
-            limit: 1,
-            vectorWeight: 1.0,
-            bm25Weight: 0.0,
-            minScore: 0.0,
-            rrfK: 60,
-            recencyBoost: false,
-            globalDiscountFactor: 1.0,
-        });
+        const similar = await state.store.findSimilarVectors(vector, opts.scope, 1);
         if (similar.length > 0 && similar[0].score >= state.config.dedup.writeThreshold) {
             isPotentialDuplicate = true;
-            duplicateOf = similar[0].record.id;
+            duplicateOf = similar[0].id;
         }
     }
     const memoryId = generateId();
@@ -849,11 +867,12 @@ async function maybeConsolidateDuplicates(state, scope, force = false) {
     if (state.consolidationInProgress.get(scope))
         return;
     if (!force) {
-        const elapsed = Date.now() - state.lastConsolidateAt;
+        const last = state.lastConsolidateAt.get(scope) ?? 0;
+        const elapsed = Date.now() - last;
         if (elapsed < CONSOLIDATE_COOLDOWN_MS)
             return;
     }
-    state.lastConsolidateAt = Date.now();
+    state.lastConsolidateAt.set(scope, Date.now());
     state.consolidationInProgress.set(scope, true);
     state.store
         .consolidateDuplicates(scope, state.config.dedup.consolidateThreshold, state.config.dedup.candidateLimit)
@@ -871,11 +890,12 @@ async function maybeSweepExpiredMemories(state, scope, force = false) {
     if (state.sweepInProgress.get(scope))
         return;
     if (!force) {
-        const elapsed = Date.now() - state.lastSweepAt;
+        const last = state.lastSweepAt.get(scope) ?? 0;
+        const elapsed = Date.now() - last;
         if (elapsed < CONSOLIDATE_COOLDOWN_MS)
             return;
     }
-    state.lastSweepAt = Date.now();
+    state.lastSweepAt.set(scope, Date.now());
     state.sweepInProgress.set(scope, true);
     sweepExpiredMemories(state, { scope })
         .then((result) => {

package/dist/llm.js

@@ -46,6 +46,30 @@ const OWN_SESSION_IDS = new Set();
 export function isOwnSession(sessionID) {
     return typeof sessionID === "string" && OWN_SESSION_IDS.has(sessionID);
 }
+// LLM_HEALTH (1.3.9): module-level runtime health for the capture/summary LLM,
+// mirroring the embedder pattern so memory_stats can report both sides.
+const globalLlmHealth = {
+    status: "never-called", // never-called | healthy | error
+    lastError: null,
+    lastSuccess: null,
+    errorCount: 0,
+    lastConfig: null,
+};
+export function getLlmHealth() {
+    return { ...globalLlmHealth };
+}
+export function setLlmHealth(patch) {
+    Object.assign(globalLlmHealth, patch);
+}
+export function resetLlmHealth() {
+    Object.assign(globalLlmHealth, {
+        status: "never-called",
+        lastError: null,
+        lastSuccess: null,
+        errorCount: 0,
+        lastConfig: null,
+    });
+}
 /**
  * Tolerant JSON parse of the extraction model's reply. Accepts a bare array
  * or an object wrapping an array under "memories"/"items"; strips markdown
@@ -169,6 +193,7 @@ export async function requestLLMDigest(client, llmConfig, texts, targetChars, gr
 async function runEphemeralPrompt(client, llmConfig, system, userText, title) {
     let sessionId = null;
     try {
+        globalLlmHealth.lastConfig = { provider: llmConfig?.provider ?? null, model: llmConfig?.model ?? null };
         const created = await client.session.create({
             body: { title: `opencode-memory-pro ${title}` },
         });
@@ -176,6 +201,7 @@ async function runEphemeralPrompt(client, llmConfig, system, userText, title) {
         sessionId = createdPayload?.id;
         if (!sessionId) {
             log("warn", `[llm] ${title}: session.create did not return an id (got ${JSON.stringify(createdPayload)?.slice(0, 200)})`);
+            setLlmHealth({ status: "error", lastError: "session.create returned no id", lastSuccess: globalLlmHealth.lastSuccess, errorCount: globalLlmHealth.errorCount + 1 });
             return null;
         }
         OWN_SESSION_IDS.add(sessionId);
@@ -191,12 +217,15 @@ async function runEphemeralPrompt(client, llmConfig, system, userText, title) {
         const text = extractAssistantText(response);
         if (!text) {
             log("warn", `[llm] ${title}: session.prompt succeeded but returned no text parts (provider=${llmConfig.provider}, model=${llmConfig.model})`);
+            setLlmHealth({ status: "error", lastError: "session.prompt returned no text parts", lastSuccess: globalLlmHealth.lastSuccess, errorCount: globalLlmHealth.errorCount + 1 });
             return null;
         }
+        setLlmHealth({ status: "healthy", lastError: null, lastSuccess: Date.now(), errorCount: 0 });
         return text;
     }
     catch (error) {
         log("warn", `[llm] ${title}: ${error instanceof Error ? error.message : String(error)} (provider=${llmConfig.provider}, model=${llmConfig.model})`);
+        setLlmHealth({ status: "error", lastError: error instanceof Error ? error.message : String(error), lastSuccess: globalLlmHealth.lastSuccess, errorCount: globalLlmHealth.errorCount + 1 });
         return null;
     }
     finally {

package/dist/store.js

@@ -10,6 +10,13 @@ const DEFAULT_CACHE_CONFIG = {
     maxScopes: 10,
     maxRecordsPerScope: 1000,
     enabled: true,
+    // SCOPE_CACHE_STALENESS (1.4.0): the version counter only sees THIS
+    // process's writes, so when two opencode processes share one dbPath the
+    // scope cache could serve stale records forever. A modest age-based
+    // staleness bound forces a reload after staleAfterMs even when the local
+    // version is unchanged, bounding cross-process staleness without a schema
+    // change. 0 disables the age check (pure version gating, pre-1.4.0).
+    staleAfterMs: 60 * 1000,
 };
 // ANN_TUNABLES (1.3.0): nprobes controls IVF recall-vs-latency on filtered
 // vector searches; the consolidation query batch controls how many ANN
@@ -642,6 +649,9 @@ export class MemoryStore {
         }
         const table = this.requireTable();
         const rows = await table.query().limit(100000).toArray();
+        if (rows.length === 100000) {
+            log("warn", "[store] deleteByIdForce fallback scan hit the 100000-row cap; the target may not be found if it lives beyond the cap");
+        }
         const match = rows.find((row) => this.matchesId(row.id, id));
         if (!match)
             return false;
@@ -711,6 +721,9 @@ export class MemoryStore {
     }
     async pruneScope(scope, maxEntries) {
         const rows = await this.list(scope, 100000);
+        if (rows.length === 100000) {
+            log("warn", `[store] pruneScope scanned up to the 100000-row cap for scope=${scope}; entries older than the newest 100k are not candidates for pruning`);
+        }
         if (rows.length <= maxEntries)
             return 0;
         const flagged = rows.filter((r) => {
@@ -748,7 +761,7 @@ export class MemoryStore {
         let rows = await this.readByScopesIncludingMerged([scope]);
         rows = rows.filter((r) => r.status === undefined || r.status === null || r.status === "" || r.status === "active");
         if (rows.length === 0) {
-            return { mergedPairs: 0, updatedRecords: 0, skippedRecords: 0 };
+            return { mergedPairs: 0, updatedRecords: 0, skippedRecords: 0, clearedFlags: 0 };
         }
         const BATCH_SIZE = 100;
         const FALLBACK_THRESHOLD = 500;
@@ -763,12 +776,23 @@ export class MemoryStore {
             row,
             norm: this.scopeCache.get(scope)?.norms.get(row.id) ?? vecNorm(row.vector),
         }));
+        // DEDUP_FLAG_REVALIDATION (1.4.0): the write-time dedup check used to
+        // flag nearly every capture (RRF score >= 1.0 vs writeThreshold in
+        // [0,1]), and the flag was a one-way ratchet — nothing ever cleared it,
+        // so flaggedCount only grew. Consolidation is where a real cosine
+        // comparison happens, so flagged rows whose closest found neighbor
+        // stays below the consolidate threshold get the flag cleared; rows
+        // that DO have a near-duplicate keep it.
+        const metaById = new Map(rowsWithNorms.map(({ row }) => [row.id, parseMetadata(row.metadataJson)]));
+        const flaggedIds = new Set([...metaById].filter(([, meta]) => meta.isPotentialDuplicate === true).map(([id]) => id));
+        const bestSimByFlagged = new Map();
+        const mergedIds = new Set();
+        let clearedFlags = 0;
         log("debug", `[consolidate] scope=${scope} rows=${rows.length} threshold=${threshold} candidateLimit=${candidateLimit} batchSize=${BATCH_SIZE} fallbackThreshold=${FALLBACK_THRESHOLD}`);
         const processWithANN = async () => {
             let localMerged = 0;
             let localUpdated = 0;
             let localSkipped = 0;
-            const mergedIds = new Set();
             const totalChunks = Math.ceil(rowsWithNorms.length / BATCH_SIZE);
             for (let chunkIdx = 0; chunkIdx < totalChunks; chunkIdx++) {
                 const chunkStart = chunkIdx * BATCH_SIZE;
@@ -805,6 +829,12 @@ export class MemoryStore {
                             if (mergedIds.has(b.row.id))
                                 continue;
                             const sim = storeFastCosine(a.row.vector, b.row.vector, a.norm, b.norm);
+                            if (flaggedIds.has(a.row.id)) {
+                                bestSimByFlagged.set(a.row.id, Math.max(bestSimByFlagged.get(a.row.id) ?? -1, sim));
+                            }
+                            if (flaggedIds.has(b.row.id)) {
+                                bestSimByFlagged.set(b.row.id, Math.max(bestSimByFlagged.get(b.row.id) ?? -1, sim));
+                            }
                             if (sim < threshold)
                                 continue;
                             const aMeta = parseMetadata(a.row.metadataJson);
@@ -879,7 +909,6 @@ export class MemoryStore {
             let localMerged = 0;
             let localUpdated = 0;
             let localSkipped = 0;
-            const mergedIds = new Set();
             for (let i = 0; i < rowsWithNorms.length; i += 1) {
                 const a = rowsWithNorms[i];
                 if (mergedIds.has(a.row.id))
@@ -889,6 +918,12 @@ export class MemoryStore {
                     if (mergedIds.has(b.row.id))
                         continue;
                     const sim = storeFastCosine(a.row.vector, b.row.vector, a.norm, b.norm);
+                    if (flaggedIds.has(a.row.id)) {
+                        bestSimByFlagged.set(a.row.id, Math.max(bestSimByFlagged.get(a.row.id) ?? -1, sim));
+                    }
+                    if (flaggedIds.has(b.row.id)) {
+                        bestSimByFlagged.set(b.row.id, Math.max(bestSimByFlagged.get(b.row.id) ?? -1, sim));
+                    }
                     if (sim < threshold)
                         continue;
                     const aMeta = parseMetadata(a.row.metadataJson);
@@ -955,14 +990,33 @@ export class MemoryStore {
             }
             else {
                 log("warn", `[consolidate] Skipping fallback for large scope (${rows.length} >= ${FALLBACK_THRESHOLD})`);
-                return { mergedPairs: 0, updatedRecords: 0, skippedRecords: 0 };
+                return { mergedPairs: 0, updatedRecords: 0, skippedRecords: 0, clearedFlags: 0 };
             }
         }
-        if (mergedPairs > 0) {
+        // DEDUP_FLAG_REVALIDATION (1.4.0): clear false duplicate flags. Rows
+        // whose best found neighbor never reached the merge threshold were
+        // flagged by the pre-1.4.0 RRF write-check (or carry a flag made stale
+        // by later edits); unsetting isPotentialDuplicate lets flaggedCount
+        // self-correct instead of ratcheting up forever.
+        for (const [id, bestSim] of bestSimByFlagged) {
+            if (mergedIds.has(id) || bestSim >= threshold)
+                continue;
+            const meta = metaById.get(id);
+            if (!meta || meta.isPotentialDuplicate !== true)
+                continue;
+            delete meta.isPotentialDuplicate;
+            delete meta.duplicateOf;
+            await this.requireTable().update({
+                where: `id = '${escapeSql(id)}'`,
+                values: { metadataJson: JSON.stringify(meta) },
+            });
+            clearedFlags += 1;
+        }
+        if (mergedPairs > 0 || clearedFlags > 0) {
             this.invalidateScope(scope);
         }
         await this.maybeOptimizeAll(false);
-        return { mergedPairs, updatedRecords, skippedRecords };
+        return { mergedPairs, updatedRecords, skippedRecords, clearedFlags };
     }
     // ANN_CONSOLIDATION (1.1.7): previously this did
 // query().where(scope).limit(limit).toArray() — which returns the FIRST N
@@ -1647,7 +1701,9 @@ export class MemoryStore {
         for (const scope of scopes) {
             const currentVersion = this.scopeVersions.get(scope) ?? 0;
             let entry = this.scopeCache.get(scope);
-            if (!entry || entry.version !== currentVersion) {
+            const maxAgeMs = Number.isFinite(this.cacheConfig.staleAfterMs) ? this.cacheConfig.staleAfterMs : 0;
+            const staleByAge = maxAgeMs > 0 && (entry ? Date.now() - (entry.loadedAt ?? entry.lastAccessTimestamp) > maxAgeMs : false);
+            if (!entry || entry.version !== currentVersion || staleByAge) {
                 if (entry) {
                     this.cacheStats.evictions++;
                 }
@@ -1667,7 +1723,7 @@ export class MemoryStore {
                 for (const record of sortedRecords) {
                     norms.set(record.id, vecNorm(record.vector));
                 }
-                entry = { records: sortedRecords, tokenized, idf, norms, lastAccessTimestamp: Date.now(), version: currentVersion };
+                entry = { records: sortedRecords, tokenized, idf, norms, loadedAt: Date.now(), lastAccessTimestamp: Date.now(), version: currentVersion };
                 this.scopeCache.set(scope, entry);
                 this.cacheStats.misses++;
                 this.enforceMaxScopes();

package/dist/tools/memory.js

@@ -4,10 +4,36 @@ import { generateId } from "../utils.js";
 import { getEmbedderHealth } from "../embedder.js";
 import { extractiveDigest, retentionCandidates } from "../store.js";
 import { requestLLMDigest } from "../llm.js";
+import { getLlmHealth } from "../llm.js";
 import { log } from "../logger.js";
 function unavailableMessage(provider) {
     return `Memory store unavailable (${provider} embedding may be offline). Will retry automatically.`;
 }
+// DEGRADED_FLAGS (1.3.9): report what the user is missing for full features.
+// Returns a list of human-readable strings, empty when running at full strength.
+function computeDegradedFlags(state, embedderHealth, graphStats) {
+    const flags = [];
+    const emb = state.config?.embedding ?? {};
+    if (state.config?.capture?.mode === "llm") {
+        const cap = state.config.capture;
+        if (!cap?.llm?.provider || !cap?.llm?.model) {
+            flags.push("llm-capture-unconfigured: capture.mode=llm but capture.llm.provider/model is missing — capture will fall back to heuristics");
+        }
+    }
+    if (emb.provider === "openai" && !emb.apiKey) {
+        flags.push("embedding-api-key-missing: embedding.provider=openai but no apiKey (or OPENCODE_MEMORY_PRO_OPENAI_API_KEY) is set — recall will fall back to BM25-only");
+    }
+    if (emb.provider !== "openai" && !(emb.baseUrl ?? "")) {
+        flags.push("embedding-baseurl-missing: embedding.provider=ollama but no baseUrl (defaults to http://127.0.0.1:11434) — recall will fall back to BM25-only");
+    }
+    if (graphStats && graphStats.enabled === false && state.config?.graph?.enabled) {
+        flags.push("graph-disabled: graph.enabled=true but the graph store did not initialize (check graph.dbPath)");
+    }
+    if (state.config?.capture?.llm?.provider && state.config?.capture?.llm?.model && getLlmHealth().status === "error") {
+        flags.push("llm-unhealthy: last LLM capture/digest call failed — falling back to heuristics/extractive digests");
+    }
+    return flags;
+}
 // LLM_CAPTURE (1.1): mode-aware digest builder shared by memory_summarize
 // and the retention sweep. capture.mode === "llm" → abstractive LLM digest
 // via an ephemeral SDK session (falls back to the offline extractive digest
@@ -246,6 +272,7 @@ export function createMemoryTools(state) {
                 const incompatibleVectors = await state.store.countIncompatibleVectors(buildScopeFilter(scope, state.config.includeGlobalScope), await state.embedder.dim());
                 const health = state.store.getIndexHealth();
                 const embedderHealth = getEmbedderHealth();
+                const llmHealth = getLlmHealth();
                 const searchMode = embedderHealth.fallbackActive ? "bm25-only" : state.config.retrieval.mode;
                 const eventTtl = state.config.retention
                     ? await state.store.getEventTtlStatus()
@@ -276,9 +303,19 @@ export function createMemoryTools(state) {
                     embeddingModel: state.config.embedding.model,
                     searchMode,
                     embedderHealth,
+                    capture: {
+                        mode: state.config.capture?.mode ?? "heuristics",
+                        llm: {
+                            provider: state.config.capture?.llm?.provider ?? null,
+                            model: state.config.capture?.llm?.model ?? null,
+                            configured: Boolean(state.config.capture?.llm?.provider && state.config.capture?.llm?.model),
+                        },
+                        llmHealth,
+                    },
                     eventTtl,
                     graph: graphStats,
                     memoryRetention,
+                    degradedFlags: computeDegradedFlags(state, embedderHealth, graphStats),
                 }, null, 2);
             },
         }),

package/opencode-memory-pro.example.json

@@ -0,0 +1,169 @@
+{
+  "_comment": "opencode-memory-pro example configuration. Copy this file to ~/.config/opencode/opencode-memory-pro.json (or ~/.opencode/opencode-memory-pro.json) and edit. Every key is optional and matches the built-in defaults; delete anything you don't need. The plugin works with zero configuration — these options only tune/enhance it.",
+  "provider": "opencode-memory-pro",
+  "dbPath": "~/.opencode/memory/lancedb",
+  "embedding": {
+    "_comment": "Vector search / hybrid recall. Default: local Ollama, no key needed. For OpenAI-compatible endpoints (OpenAI, OpenRouter, etc.), set provider to \"openai\", add baseUrl + model + apiKey. If no embedder is reachable, recall falls back to pure BM25.",
+    "provider": "ollama",
+    "model": "nomic-embed-text",
+    "baseUrl": "http://127.0.0.1:11434",
+    "timeoutMs": 6000,
+    "retry": {
+      "enabled": true,
+      "maxAttempts": 3,
+      "initialDelayMs": 1000,
+      "backoffMultiplier": 2
+    }
+  },
+  "retrieval": {
+    "mode": "hybrid",
+    "vectorWeight": 0.7,
+    "bm25Weight": 0.3,
+    "minScore": 0.2,
+    "rrfK": 60,
+    "recencyBoost": true,
+    "recencyHalfLifeHours": 72,
+    "importanceWeight": 0.4,
+    "feedbackWeight": 0.3
+  },
+  "injection": {
+    "mode": "fixed",
+    "maxMemories": 3,
+    "minMemories": 1,
+    "budgetTokens": 4096,
+    "maxCharsPerMemory": 1200,
+    "summarization": "none",
+    "summaryTargetChars": 300,
+    "scoreDropTolerance": 0.15,
+    "injectionFloor": 0.2,
+    "codeSummarization": {
+      "enabled": true,
+      "pureCodeThreshold": 500,
+      "maxCodeLines": 15,
+      "codeTruncationMode": "smart",
+      "preserveComments": true,
+      "preserveImports": false
+    },
+    "taskTypeProfiles": {
+      "coding": {
+        "maxMemories": 4,
+        "budgetTokens": 5120,
+        "summaryTargetChars": 400,
+        "categoryWeights": {
+          "decision": 1.5,
+          "entity": 1.2,
+          "fact": 1,
+          "preference": 0.8,
+          "other": 0.5
+        }
+      },
+      "documentation": {
+        "maxMemories": 3,
+        "budgetTokens": 3072,
+        "summaryTargetChars": 500,
+        "categoryWeights": {
+          "decision": 1.4,
+          "fact": 1.3,
+          "entity": 1.2,
+          "preference": 0.8,
+          "other": 0.5
+        }
+      },
+      "review": {
+        "maxMemories": 3,
+        "budgetTokens": 4096,
+        "summaryTargetChars": 300,
+        "categoryWeights": {
+          "preference": 1.4,
+          "decision": 1.2,
+          "entity": 1,
+          "fact": 0.9,
+          "other": 0.5
+        }
+      },
+      "release": {
+        "maxMemories": 4,
+        "budgetTokens": 6144,
+        "summaryTargetChars": 350,
+        "categoryWeights": {
+          "decision": 1.5,
+          "entity": 1.3,
+          "fact": 1.2,
+          "preference": 0.8,
+          "other": 0.5
+        }
+      },
+      "general": {
+        "maxMemories": 3,
+        "budgetTokens": 4096,
+        "summaryTargetChars": 300,
+        "categoryWeights": {
+          "decision": 1.3,
+          "fact": 1,
+          "entity": 1,
+          "preference": 0.9,
+          "other": 0.5
+        }
+      }
+    }
+  },
+  "dedup": {
+    "enabled": true,
+    "writeThreshold": 0.92,
+    "consolidateThreshold": 0.95,
+    "candidateLimit": 50
+  },
+  "graph": {
+    "_comment": "Offline entity graph: co-occurrence + typed relations (uses/depends_on/...), powers [graph+X%] recall boosts and BFS expansion. No LLM needed.",
+    "enabled": true,
+    "dbPath": "~/.opencode/memory/graph.db",
+    "boostLambda": 0.3,
+    "maxEntitiesPerMemory": 20,
+    "maxEdgeProvenance": 20,
+    "typedEdges": true,
+    "expansionEnabled": true,
+    "maxHops": 2,
+    "expansionLimit": 5,
+    "expansionLambda": 0.3
+  },
+  "summarize": {
+    "enabled": true,
+    "minAgeDays": 30,
+    "minGroupSize": 3,
+    "targetChars": 500,
+    "replace": false
+  },
+  "capture": {
+    "_comment": "\"heuristics\" (default) = offline keyword capture, no LLM needed. \"llm\" = LLM-quality extraction + abstractive digests, addressed via OpenCode provider/model IDs — the provider must be resolvable in your opencode.json (e.g. \"openrouter\"). Falls back to heuristics on any failure.",
+    "mode": "heuristics",
+    "llm": {
+      "provider": "openrouter",
+      "model": "z-ai/glm-5.3-flash"
+    }
+  },
+  "scoping": "global",
+  "includeGlobalScope": true,
+  "globalDetectionThreshold": 2,
+  "globalDiscountFactor": 0.7,
+  "unusedDaysThreshold": 30,
+  "minCaptureChars": 80,
+  "maxEntriesPerScope": 3000,
+  "retention": {
+    "effectivenessEventsDays": 90,
+    "memory": {
+      "enabled": true,
+      "unusedDays": 60,
+      "minAgeDays": 180,
+      "minGroupSize": 2,
+      "targetChars": 500,
+      "minImportance": 0.3,
+      "protectedCategories": [
+        "digest"
+      ]
+    }
+  },
+  "logging": {
+    "level": "info",
+    "file": null
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-memory-pro",
-  "version": "1.3.8",
+  "version": "1.4.0",
   "description": "LanceDB-backed long-term memory provider for OpenCode — standalone fork of lancedb-opencode-pro with entity graph, lifecycle, and retention",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "opencode-memory-pro.example.json"
   ],
   "keywords": [
     "opencode",