lancedb-opencode-pro 0.1.3 → 0.1.4

package/README.md

@@ -41,7 +41,11 @@ If you already use other plugins, keep them and append `"lancedb-opencode-pro"`.
     "mode": "hybrid",
     "vectorWeight": 0.7,
     "bm25Weight": 0.3,
-    "minScore": 0.2
+    "minScore": 0.2,
+    "rrfK": 60,
+    "recencyBoost": true,
+    "recencyHalfLifeHours": 72,
+    "importanceWeight": 0.4
   },
   "includeGlobalScope": true,
   "minCaptureChars": 80,
@@ -173,7 +177,11 @@ Create `~/.config/opencode/lancedb-opencode-pro.json`:
     "mode": "hybrid",
     "vectorWeight": 0.7,
     "bm25Weight": 0.3,
-    "minScore": 0.2
+    "minScore": 0.2,
+    "rrfK": 60,
+    "recencyBoost": true,
+    "recencyHalfLifeHours": 72,
+    "importanceWeight": 0.4
   },
   "includeGlobalScope": true,
   "minCaptureChars": 80,
@@ -216,6 +224,10 @@ Supported environment variables:
 - `LANCEDB_OPENCODE_PRO_VECTOR_WEIGHT`
 - `LANCEDB_OPENCODE_PRO_BM25_WEIGHT`
 - `LANCEDB_OPENCODE_PRO_MIN_SCORE`
+- `LANCEDB_OPENCODE_PRO_RRF_K`
+- `LANCEDB_OPENCODE_PRO_RECENCY_BOOST`
+- `LANCEDB_OPENCODE_PRO_RECENCY_HALF_LIFE_HOURS`
+- `LANCEDB_OPENCODE_PRO_IMPORTANCE_WEIGHT`
 - `LANCEDB_OPENCODE_PRO_INCLUDE_GLOBAL_SCOPE`
 - `LANCEDB_OPENCODE_PRO_MIN_CAPTURE_CHARS`
 - `LANCEDB_OPENCODE_PRO_MAX_ENTRIES_PER_SCOPE`
@@ -298,6 +310,22 @@ Key fields:
 - `feedback.falsePositiveRate`: wrong-memory reports divided by stored memories.
 - `feedback.falseNegativeRate`: missing-memory reports relative to capture attempts.
 
+### Interpreting Low-Feedback Results
+
+In real OpenCode usage, auto-capture and recall happen in the background, so explicit `memory_feedback_*` events are often sparse.
+
+- Treat `capture.*` and `recall.*` as system-health metrics: they show whether the memory pipeline is running.
+- Treat repeated-context reduction, clarification burden, manual memory rescue, correction signals, and sampled audits as product-value signals: they show whether memory actually helped the user.
+- Treat `feedback.* = 0` as insufficient evidence, not proof that memory quality is good.
+- Treat a high `recall.hitRate` or `recall.injectionRate` as recall availability only; those values do not prove usefulness by themselves.
+
+Recommended review order in low-feedback environments:
+
+1. Check `capture.successRate`, `capture.skipReasons`, `recall.hitRate`, and `recall.injectionRate` for operational health.
+2. Review whether users repeated background context less often or needed fewer clarification turns.
+3. Check whether users still needed manual rescue through `memory_search` or issued correction-like responses.
+4. Run a bounded audit of recalled memories or skipped captures before concluding the system is helping.
+
 ## OpenAI Embedding Configuration
 
 Default behavior stays on Ollama. To use OpenAI embeddings, set `embedding.provider` to `openai` and provide API key + model.
@@ -318,7 +346,11 @@ Example sidecar:
     "mode": "hybrid",
     "vectorWeight": 0.7,
     "bm25Weight": 0.3,
-    "minScore": 0.2
+    "minScore": 0.2,
+    "rrfK": 60,
+    "recencyBoost": true,
+    "recencyHalfLifeHours": 72,
+    "importanceWeight": 0.4
   },
   "includeGlobalScope": true,
   "minCaptureChars": 80,

package/dist/config.js

@@ -20,6 +20,10 @@ export function resolveMemoryConfig(config, worktree) {
     const weightSum = vectorWeight + bm25Weight;
     const normalizedVectorWeight = weightSum > 0 ? vectorWeight / weightSum : 0.7;
     const normalizedBm25Weight = weightSum > 0 ? bm25Weight / weightSum : 0.3;
+    const rrfK = Math.max(1, Math.floor(toNumber(process.env.LANCEDB_OPENCODE_PRO_RRF_K ?? retrievalRaw.rrfK, 60)));
+    const recencyBoost = toBoolean(process.env.LANCEDB_OPENCODE_PRO_RECENCY_BOOST ?? retrievalRaw.recencyBoost, true);
+    const recencyHalfLifeHours = Math.max(1, toNumber(process.env.LANCEDB_OPENCODE_PRO_RECENCY_HALF_LIFE_HOURS ?? retrievalRaw.recencyHalfLifeHours, 72));
+    const importanceWeight = clamp(toNumber(process.env.LANCEDB_OPENCODE_PRO_IMPORTANCE_WEIGHT ?? retrievalRaw.importanceWeight, 0.4), 0, 2);
     const embeddingProvider = resolveEmbeddingProvider(firstString(process.env.LANCEDB_OPENCODE_PRO_EMBEDDING_PROVIDER, embeddingRaw.provider));
     const embeddingModel = embeddingProvider === "openai"
         ? firstString(process.env.LANCEDB_OPENCODE_PRO_OPENAI_MODEL, process.env.LANCEDB_OPENCODE_PRO_EMBEDDING_MODEL, embeddingRaw.model)
@@ -49,6 +53,10 @@ export function resolveMemoryConfig(config, worktree) {
             vectorWeight: normalizedVectorWeight,
             bm25Weight: normalizedBm25Weight,
             minScore: clamp(toNumber(process.env.LANCEDB_OPENCODE_PRO_MIN_SCORE ?? retrievalRaw.minScore, 0.2), 0, 1),
+            rrfK,
+            recencyBoost,
+            recencyHalfLifeHours,
+            importanceWeight,
         },
         includeGlobalScope: toBoolean(process.env.LANCEDB_OPENCODE_PRO_INCLUDE_GLOBAL_SCOPE ?? raw.includeGlobalScope, true),
         minCaptureChars: Math.max(30, Math.floor(toNumber(process.env.LANCEDB_OPENCODE_PRO_MIN_CAPTURE_CHARS ?? raw.minCaptureChars, 80))),

package/dist/index.js

@@ -56,6 +56,10 @@ const plugin = async (input) => {
                 vectorWeight: state.config.retrieval.mode === "vector" ? 1 : state.config.retrieval.vectorWeight,
                 bm25Weight: state.config.retrieval.mode === "vector" ? 0 : state.config.retrieval.bm25Weight,
                 minScore: state.config.retrieval.minScore,
+                rrfK: state.config.retrieval.rrfK,
+                recencyBoost: state.config.retrieval.recencyBoost,
+                recencyHalfLifeHours: state.config.retrieval.recencyHalfLifeHours,
+                importanceWeight: state.config.retrieval.importanceWeight,
             });
             await state.store.putEvent({
                 id: generateId(),
@@ -108,6 +112,10 @@ const plugin = async (input) => {
                         vectorWeight: state.config.retrieval.mode === "vector" ? 1 : state.config.retrieval.vectorWeight,
                         bm25Weight: state.config.retrieval.mode === "vector" ? 0 : state.config.retrieval.bm25Weight,
                         minScore: state.config.retrieval.minScore,
+                        rrfK: state.config.retrieval.rrfK,
+                        recencyBoost: state.config.retrieval.recencyBoost,
+                        recencyHalfLifeHours: state.config.retrieval.recencyHalfLifeHours,
+                        importanceWeight: state.config.retrieval.importanceWeight,
                     });
                     if (results.length === 0)
                         return "No relevant memory found.";

package/dist/store.d.ts

@@ -19,6 +19,10 @@ export declare class MemoryStore {
         vectorWeight: number;
         bm25Weight: number;
         minScore: number;
+        rrfK?: number;
+        recencyBoost?: boolean;
+        recencyHalfLifeHours?: number;
+        importanceWeight?: number;
     }): Promise<SearchResult[]>;
     deleteById(id: string, scopes: string[]): Promise<boolean>;
     clearScope(scope: string): Promise<number>;

package/dist/store.js

@@ -103,14 +103,50 @@ export class MemoryStore {
             return [];
         const queryTokens = tokenize(params.query);
         const queryNorm = vecNorm(params.queryVector);
-        const scored = cached.records
+        const useVectorChannel = params.queryVector.length > 0 && params.vectorWeight > 0;
+        const useBm25Channel = queryTokens.length > 0 && params.bm25Weight > 0;
+        const { vectorWeight, bm25Weight } = normalizeChannelWeights(useVectorChannel ? params.vectorWeight : 0, useBm25Channel ? params.bm25Weight : 0);
+        const rrfK = Math.max(1, Math.floor(params.rrfK ?? 60));
+        const recencyBoostEnabled = params.recencyBoost ?? true;
+        const recencyHalfLifeHours = Math.max(1, params.recencyHalfLifeHours ?? 72);
+        const importanceWeight = clampImportanceWeight(params.importanceWeight ?? 0.4);
+        const candidates = cached.records
             .filter((record) => params.queryVector.length === 0 || record.vector.length === params.queryVector.length)
             .map((record, index) => {
             const recordNorm = cached.norms.get(record.id) ?? vecNorm(record.vector);
-            const vectorScore = fastCosine(params.queryVector, record.vector, queryNorm, recordNorm);
-            const bm25Score = bm25LikeScore(queryTokens, cached.tokenized[index], cached.idf);
-            const score = params.vectorWeight * vectorScore + params.bm25Weight * bm25Score;
-            return { record, score, vectorScore, bm25Score };
+            const vectorScore = useVectorChannel ? fastCosine(params.queryVector, record.vector, queryNorm, recordNorm) : 0;
+            const bm25Score = useBm25Channel ? bm25LikeScore(queryTokens, cached.tokenized[index], cached.idf) : 0;
+            return { record, vectorScore, bm25Score };
+        });
+        if (candidates.length === 0)
+            return [];
+        const vectorRanks = useVectorChannel ? buildRankMap(candidates, (item) => item.vectorScore) : null;
+        const bm25Ranks = useBm25Channel ? buildRankMap(candidates, (item) => item.bm25Score) : null;
+        const scored = candidates
+            .map((item) => {
+            let rrfScore = 0;
+            if (vectorRanks) {
+                const rank = vectorRanks.get(item.record.id);
+                if (rank !== undefined)
+                    rrfScore += vectorWeight / (rrfK + rank);
+            }
+            if (bm25Ranks) {
+                const rank = bm25Ranks.get(item.record.id);
+                if (rank !== undefined)
+                    rrfScore += bm25Weight / (rrfK + rank);
+            }
+            rrfScore *= rrfK + 1;
+            const recencyFactor = recencyBoostEnabled
+                ? computeRecencyMultiplier(item.record.timestamp, recencyHalfLifeHours)
+                : 1;
+            const importanceFactor = 1 + importanceWeight * clampImportance(item.record.importance);
+            const score = rrfScore * recencyFactor * importanceFactor;
+            return {
+                record: item.record,
+                score,
+                vectorScore: item.vectorScore,
+                bm25Score: item.bm25Score,
+            };
         })
             .filter((item) => item.score >= params.minScore)
             .sort((a, b) => b.score - a.score)
@@ -445,6 +481,43 @@ function normalizeEventRow(row) {
 function escapeSql(value) {
     return value.replace(/'/g, "''");
 }
+function buildRankMap(items, scoreOf) {
+    const ranked = [...items].sort((a, b) => scoreOf(b) - scoreOf(a));
+    const ranks = new Map();
+    for (let i = 0; i < ranked.length; i += 1) {
+        ranks.set(ranked[i].record.id, i + 1);
+    }
+    return ranks;
+}
+function normalizeChannelWeights(vectorWeight, bm25Weight) {
+    const sum = vectorWeight + bm25Weight;
+    if (sum <= 0) {
+        return { vectorWeight: 0.5, bm25Weight: 0.5 };
+    }
+    return {
+        vectorWeight: vectorWeight / sum,
+        bm25Weight: bm25Weight / sum,
+    };
+}
+function computeRecencyMultiplier(timestamp, halfLifeHours) {
+    const now = Date.now();
+    const ageMs = Math.max(0, now - timestamp);
+    const ageHours = ageMs / 3_600_000;
+    if (ageHours === 0)
+        return 1;
+    const decay = Math.pow(0.5, ageHours / halfLifeHours);
+    return 0.5 + 0.5 * decay;
+}
+function clampImportance(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.min(1, value));
+}
+function clampImportanceWeight(value) {
+    if (!Number.isFinite(value))
+        return 0.4;
+    return Math.max(0, Math.min(2, value));
+}
 function computeIdf(docs) {
     const df = new Map();
     for (const doc of docs) {

package/dist/types.d.ts

@@ -16,6 +16,10 @@ export interface RetrievalConfig {
     vectorWeight: number;
     bm25Weight: number;
     minScore: number;
+    rrfK: number;
+    recencyBoost: boolean;
+    recencyHalfLifeHours: number;
+    importanceWeight: number;
 }
 export interface MemoryRuntimeConfig {
     provider: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lancedb-opencode-pro",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "LanceDB-backed long-term memory provider for OpenCode",
   "type": "module",
   "main": "dist/index.js",