opencode-memory-pro 1.3.8 → 1.3.9

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.3.9** 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

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.3.9";
 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 }) => {

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/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.3.9",
   "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",