lancedb-opencode-pro 0.1.3 → 0.1.5

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`
@@ -260,7 +272,7 @@ Example output:
 ```json
 {
   "scope": "project:my-project",
-  "totalEvents": 12,
+  "totalEvents": 14,
   "capture": {
     "considered": 4,
     "stored": 3,
@@ -271,11 +283,24 @@ Example output:
     }
   },
   "recall": {
-    "requested": 3,
+    "requested": 4,
     "injected": 2,
-    "returnedResults": 2,
-    "hitRate": 0.67,
-    "injectionRate": 0.67
+    "returnedResults": 3,
+    "hitRate": 0.75,
+    "injectionRate": 0.5,
+    "auto": {
+      "requested": 3,
+      "injected": 2,
+      "returnedResults": 2,
+      "hitRate": 0.67,
+      "injectionRate": 0.67
+    },
+    "manual": {
+      "requested": 1,
+      "returnedResults": 1,
+      "hitRate": 1
+    },
+    "manualRescueRatio": 0.33
   },
   "feedback": {
     "missing": 1,
@@ -294,10 +319,31 @@ Example output:
 Key fields:
 
 - `capture.successRate`: how often a considered candidate was stored.
-- `recall.hitRate`: how often a recall request returned at least one result.
+- `recall.hitRate`: blended rate across auto and manual recall — how often any recall request returned at least one result.
+- `recall.auto.*`: metrics for automatic recall injected into the system prompt during `experimental.chat.system.transform`.
+- `recall.manual.*`: metrics for user-initiated `memory_search` calls; `injected` is always false for manual searches.
+- `recall.manualRescueRatio`: `manual.requested / auto.requested` — a proxy for how often users still need to search manually despite automatic recall.
 - `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 `recall.auto.*` and `recall.manual.*` separately: auto metrics reflect pipeline health; manual metrics reflect whether users still need to rescue context manually.
+- Treat `recall.manualRescueRatio` as a proxy for manual rescue rate: a high ratio suggests automatic recall is not surfacing relevant context on its own.
+- 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 +364,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,10 +56,15 @@ 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(),
                 type: "recall",
+                source: "system-transform",
                 scope: activeScope,
                 sessionID: eventInput.sessionID,
                 timestamp: Date.now(),
@@ -108,6 +113,21 @@ 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(),
+                        type: "recall",
+                        source: "manual-search",
+                        scope: activeScope,
+                        sessionID: context.sessionID,
+                        timestamp: Date.now(),
+                        resultCount: results.length,
+                        injected: false,
+                        metadataJson: JSON.stringify({ source: "manual-search" }),
                     });
                     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

@@ -59,6 +59,7 @@ export class MemoryStore {
                 skipReason: "",
                 resultCount: 0,
                 injected: false,
+                source: "",
                 feedbackType: "",
                 helpful: -1,
                 reason: "",
@@ -89,6 +90,7 @@ export class MemoryStore {
                 skipReason: event.type === "capture" ? event.skipReason ?? "" : "",
                 resultCount: event.type === "recall" ? event.resultCount : 0,
                 injected: event.type === "recall" ? event.injected : false,
+                source: event.type === "recall" ? event.source ?? "" : "",
                 feedbackType: event.type === "feedback" ? event.feedbackType : "",
                 helpful: event.type === "feedback" ? (event.helpful === undefined ? -1 : event.helpful ? 1 : 0) : -1,
                 reason: event.type === "feedback" ? event.reason ?? "" : "",
@@ -103,14 +105,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)
@@ -171,6 +209,11 @@ export class MemoryStore {
         let recallRequested = 0;
         let recallInjected = 0;
         let recallReturnedResults = 0;
+        let autoRecallRequested = 0;
+        let autoRecallInjected = 0;
+        let autoRecallReturnedResults = 0;
+        let manualRecallRequested = 0;
+        let manualRecallReturnedResults = 0;
         let feedbackMissing = 0;
         let feedbackWrong = 0;
         let feedbackUsefulPositive = 0;
@@ -194,6 +237,19 @@ export class MemoryStore {
                     recallReturnedResults += 1;
                 if (event.injected)
                     recallInjected += 1;
+                const recallSource = event.source ?? "system-transform";
+                if (recallSource === "manual-search") {
+                    manualRecallRequested += 1;
+                    if (event.resultCount > 0)
+                        manualRecallReturnedResults += 1;
+                }
+                else {
+                    autoRecallRequested += 1;
+                    if (event.resultCount > 0)
+                        autoRecallReturnedResults += 1;
+                    if (event.injected)
+                        autoRecallInjected += 1;
+                }
             }
             if (event.type === "feedback") {
                 if (event.feedbackType === "missing")
@@ -226,6 +282,19 @@ export class MemoryStore {
                 returnedResults: recallReturnedResults,
                 hitRate: recallRequested === 0 ? 0 : recallReturnedResults / recallRequested,
                 injectionRate: recallRequested === 0 ? 0 : recallInjected / recallRequested,
+                auto: {
+                    requested: autoRecallRequested,
+                    injected: autoRecallInjected,
+                    returnedResults: autoRecallReturnedResults,
+                    hitRate: autoRecallRequested === 0 ? 0 : autoRecallReturnedResults / autoRecallRequested,
+                    injectionRate: autoRecallRequested === 0 ? 0 : autoRecallInjected / autoRecallRequested,
+                },
+                manual: {
+                    requested: manualRecallRequested,
+                    returnedResults: manualRecallReturnedResults,
+                    hitRate: manualRecallRequested === 0 ? 0 : manualRecallReturnedResults / manualRecallRequested,
+                },
+                manualRescueRatio: autoRecallRequested === 0 ? 0 : manualRecallRequested / autoRecallRequested,
             },
             feedback: {
                 missing: feedbackMissing,
@@ -310,6 +379,7 @@ export class MemoryStore {
             "skipReason",
             "resultCount",
             "injected",
+            "source",
             "feedbackType",
             "helpful",
             "reason",
@@ -420,11 +490,14 @@ function normalizeEventRow(row) {
         };
     }
     if (row.type === "recall") {
+        const sourceRaw = typeof row.source === "string" && row.source.length > 0 ? row.source : "system-transform";
+        const source = sourceRaw === "manual-search" ? "manual-search" : "system-transform";
         return {
             ...base,
             type: "recall",
             resultCount: Number(row.resultCount ?? 0),
             injected: Boolean(row.injected),
+            source,
         };
     }
     if (row.type === "feedback") {
@@ -445,6 +518,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

@@ -4,6 +4,7 @@ export type MemoryCategory = "preference" | "fact" | "decision" | "entity" | "ot
 export type CaptureOutcome = "considered" | "skipped" | "stored";
 export type CaptureSkipReason = "empty-buffer" | "below-min-chars" | "no-positive-signal" | "initialization-unavailable" | "embedding-unavailable" | "empty-embedding";
 export type FeedbackType = "missing" | "wrong" | "useful";
+export type RecallSource = "system-transform" | "manual-search";
 export interface EmbeddingConfig {
     provider: EmbeddingProvider;
     model: string;
@@ -16,6 +17,10 @@ export interface RetrievalConfig {
     vectorWeight: number;
     bm25Weight: number;
     minScore: number;
+    rrfK: number;
+    recencyBoost: boolean;
+    recencyHalfLifeHours: number;
+    importanceWeight: number;
 }
 export interface MemoryRuntimeConfig {
     provider: string;
@@ -72,6 +77,7 @@ export interface RecallEvent extends MemoryEffectivenessEventBase {
     type: "recall";
     resultCount: number;
     injected: boolean;
+    source?: RecallSource;
 }
 export interface FeedbackEvent extends MemoryEffectivenessEventBase {
     type: "feedback";
@@ -97,6 +103,19 @@ export interface EffectivenessSummary {
         returnedResults: number;
         hitRate: number;
         injectionRate: number;
+        auto: {
+            requested: number;
+            injected: number;
+            returnedResults: number;
+            hitRate: number;
+            injectionRate: number;
+        };
+        manual: {
+            requested: number;
+            returnedResults: number;
+            hitRate: number;
+        };
+        manualRescueRatio: number;
     };
     feedback: {
         missing: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lancedb-opencode-pro",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "LanceDB-backed long-term memory provider for OpenCode",
   "type": "module",
   "main": "dist/index.js",
@@ -63,5 +63,10 @@
   "devDependencies": {
     "@types/node": "^22.13.9",
     "typescript": "^5.8.2"
-  }
+  },
+  "directories": {
+    "doc": "docs",
+    "test": "test"
+  },
+  "author": ""
 }