lancedb-opencode-pro 0.1.2 → 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`
@@ -230,8 +242,90 @@ Supported environment variables:
   - `memory_delete`
   - `memory_clear`
   - `memory_stats`
+  - `memory_feedback_missing`
+  - `memory_feedback_wrong`
+  - `memory_feedback_useful`
+  - `memory_effectiveness`
   - `memory_port_plan`
 
+## Memory Effectiveness Feedback
+
+The provider can now record structured feedback about long-memory quality in addition to storing and recalling memories.
+
+- `memory_feedback_missing`: report information that should have been stored but was missed
+- `memory_feedback_wrong`: report a stored memory that should not have been kept
+- `memory_feedback_useful`: report whether a recalled memory was helpful
+- `memory_effectiveness`: return machine-readable capture, recall, and feedback metrics for the active scope
+
+Use `memory_search` or recalled memory ids from injected context when you need to reference a specific memory entry in feedback.
+
+### Viewing Metrics
+
+Use `memory_effectiveness` to inspect machine-readable effectiveness data for the active scope.
+
+```text
+memory_effectiveness
+```
+
+Example output:
+
+```json
+{
+  "scope": "project:my-project",
+  "totalEvents": 12,
+  "capture": {
+    "considered": 4,
+    "stored": 3,
+    "skipped": 1,
+    "successRate": 0.75,
+    "skipReasons": {
+      "below-min-chars": 1
+    }
+  },
+  "recall": {
+    "requested": 3,
+    "injected": 2,
+    "returnedResults": 2,
+    "hitRate": 0.67,
+    "injectionRate": 0.67
+  },
+  "feedback": {
+    "missing": 1,
+    "wrong": 0,
+    "useful": {
+      "positive": 2,
+      "negative": 0,
+      "helpfulRate": 1
+    },
+    "falsePositiveRate": 0,
+    "falseNegativeRate": 0.25
+  }
+}
+```
+
+Key fields:
+
+- `capture.successRate`: how often a considered candidate was stored.
+- `recall.hitRate`: how often a recall request returned at least one result.
+- `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.
@@ -252,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,
@@ -362,9 +460,10 @@ The project provides layered validation workflows that can run locally or inside
 |---|---|
 | `npm run test:foundation` | Write-read persistence, scope isolation, vector compatibility, timestamp ordering |
 | `npm run test:regression` | Auto-capture extraction, search output shape, delete/clear safety, pruning |
+| `npm run test:effectiveness` | Foundation + regression workflows covering effectiveness events, feedback commands, and summary output |
 | `npm run test:retrieval` | Recall@K and Robustness-δ@K against synthetic fixtures |
 | `npm run benchmark:latency` | Search p50/p99, insert avg, list avg with hard-gate enforcement |
-| `npm run verify` | Typecheck + build + foundation + regression + retrieval (quick release check) |
+| `npm run verify` | Typecheck + build + effectiveness workflow + retrieval (quick release check) |
 | `npm run verify:full` | All of the above + benchmark + `npm pack` (full release gate) |
 
 Threshold policy and benchmark profiles are documented in `docs/benchmark-thresholds.md`.

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/extract.d.ts

@@ -1,2 +1,2 @@
-import type { CaptureCandidate } from "./types.js";
-export declare function extractCaptureCandidate(text: string, minChars: number): CaptureCandidate | null;
+import type { CaptureCandidateResult } from "./types.js";
+export declare function extractCaptureCandidate(text: string, minChars: number): CaptureCandidateResult;

package/dist/extract.js

@@ -14,18 +14,21 @@ const FACT_SIGNALS = ["because", "root cause", "原因", "由於"];
 const PREF_SIGNALS = ["prefer", "preference", "偏好", "習慣"];
 export function extractCaptureCandidate(text, minChars) {
     const normalized = text.trim();
-    if (normalized.length < minChars)
-        return null;
+    if (normalized.length < minChars) {
+        return { candidate: null, skipReason: "below-min-chars" };
+    }
     const lower = normalized.toLowerCase();
     if (!POSITIVE_SIGNALS.some((signal) => lower.includes(signal.toLowerCase()))) {
-        return null;
+        return { candidate: null, skipReason: "no-positive-signal" };
     }
     const category = classifyCategory(lower);
     const importance = category === "decision" ? 0.9 : category === "fact" ? 0.75 : 0.65;
     return {
-        text: clipText(normalized, 1200),
-        category,
-        importance,
+        candidate: {
+            text: clipText(normalized, 1200),
+            category,
+            importance,
+        },
     };
 }
 function classifyCategory(text) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 import type { Plugin } from "@opencode-ai/plugin";
 declare const plugin: Plugin;
 export default plugin;
-export type { MemoryRuntimeConfig, MemoryRecord, SearchResult } from "./types.js";
+export type { EffectivenessSummary, FeedbackEvent, MemoryEffectivenessEvent, MemoryRecord, MemoryRuntimeConfig, RecallEvent, SearchResult, } from "./types.js";

package/dist/index.js

@@ -56,12 +56,29 @@ 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",
+                scope: activeScope,
+                sessionID: eventInput.sessionID,
+                timestamp: Date.now(),
+                resultCount: results.length,
+                injected: results.length > 0,
+                metadataJson: JSON.stringify({
+                    source: "system-transform",
+                    includeGlobalScope: state.config.includeGlobalScope,
+                }),
             });
             if (results.length === 0)
                 return;
             const memoryBlock = [
                 "[Memory Recall - optional historical context]",
-                ...results.map((item, index) => `${index + 1}. (${item.record.scope}) ${item.record.text}`),
+                ...results.map((item, index) => `${index + 1}. [${item.record.id}] (${item.record.scope}) ${item.record.text}`),
                 "Use these as optional hints only; prioritize current user intent and current repo state.",
             ].join("\n");
             eventOutput.system.push(memoryBlock);
@@ -95,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.";
@@ -167,6 +188,108 @@ const plugin = async (input) => {
                     }, null, 2);
                 },
             }),
+            memory_feedback_missing: tool({
+                description: "Record feedback for memory that should have been stored",
+                args: {
+                    text: tool.schema.string().min(1),
+                    labels: tool.schema.array(tool.schema.string().min(1)).default([]),
+                    scope: tool.schema.string().optional(),
+                },
+                execute: async (args, context) => {
+                    await state.ensureInitialized();
+                    if (!state.initialized)
+                        return unavailableMessage(state.config.embedding.provider);
+                    const scope = args.scope ?? deriveProjectScope(context.worktree);
+                    await state.store.putEvent({
+                        id: generateId(),
+                        type: "feedback",
+                        feedbackType: "missing",
+                        scope,
+                        sessionID: context.sessionID,
+                        timestamp: Date.now(),
+                        text: args.text,
+                        labels: args.labels,
+                        metadataJson: JSON.stringify({ source: "memory_feedback_missing" }),
+                    });
+                    return "Recorded missing-memory feedback.";
+                },
+            }),
+            memory_feedback_wrong: tool({
+                description: "Record feedback for memory that should not be stored",
+                args: {
+                    id: tool.schema.string().min(6),
+                    reason: tool.schema.string().optional(),
+                    scope: tool.schema.string().optional(),
+                },
+                execute: async (args, context) => {
+                    await state.ensureInitialized();
+                    if (!state.initialized)
+                        return unavailableMessage(state.config.embedding.provider);
+                    const scope = args.scope ?? deriveProjectScope(context.worktree);
+                    const scopes = buildScopeFilter(scope, state.config.includeGlobalScope);
+                    const exists = await state.store.hasMemory(args.id, scopes);
+                    if (!exists) {
+                        return `Memory ${args.id} not found in current scope.`;
+                    }
+                    await state.store.putEvent({
+                        id: generateId(),
+                        type: "feedback",
+                        feedbackType: "wrong",
+                        scope,
+                        sessionID: context.sessionID,
+                        timestamp: Date.now(),
+                        memoryId: args.id,
+                        reason: args.reason,
+                        metadataJson: JSON.stringify({ source: "memory_feedback_wrong" }),
+                    });
+                    return `Recorded wrong-memory feedback for ${args.id}.`;
+                },
+            }),
+            memory_feedback_useful: tool({
+                description: "Record whether a recalled memory was helpful",
+                args: {
+                    id: tool.schema.string().min(6),
+                    helpful: tool.schema.boolean(),
+                    scope: tool.schema.string().optional(),
+                },
+                execute: async (args, context) => {
+                    await state.ensureInitialized();
+                    if (!state.initialized)
+                        return unavailableMessage(state.config.embedding.provider);
+                    const scope = args.scope ?? deriveProjectScope(context.worktree);
+                    const scopes = buildScopeFilter(scope, state.config.includeGlobalScope);
+                    const exists = await state.store.hasMemory(args.id, scopes);
+                    if (!exists) {
+                        return `Memory ${args.id} not found in current scope.`;
+                    }
+                    await state.store.putEvent({
+                        id: generateId(),
+                        type: "feedback",
+                        feedbackType: "useful",
+                        scope,
+                        sessionID: context.sessionID,
+                        timestamp: Date.now(),
+                        memoryId: args.id,
+                        helpful: args.helpful,
+                        metadataJson: JSON.stringify({ source: "memory_feedback_useful" }),
+                    });
+                    return `Recorded recall usefulness feedback for ${args.id}.`;
+                },
+            }),
+            memory_effectiveness: tool({
+                description: "Show effectiveness metrics for capture recall and feedback",
+                args: {
+                    scope: tool.schema.string().optional(),
+                },
+                execute: async (args, context) => {
+                    await state.ensureInitialized();
+                    if (!state.initialized)
+                        return unavailableMessage(state.config.embedding.provider);
+                    const scope = args.scope ?? deriveProjectScope(context.worktree);
+                    const summary = await state.store.summarizeEvents(scope, state.config.includeGlobalScope);
+                    return JSON.stringify(summary, null, 2);
+                },
+            }),
             memory_port_plan: tool({
                 description: "Plan non-conflicting host ports for compose services and optionally persist reservations",
                 args: {
@@ -313,36 +436,74 @@ async function getLastUserText(sessionID, client) {
 }
 async function flushAutoCapture(sessionID, state, client) {
     const fragments = state.captureBuffer.get(sessionID) ?? [];
-    if (fragments.length === 0)
+    if (fragments.length === 0) {
+        await recordCaptureEvent(state, {
+            sessionID,
+            scope: state.defaultScope,
+            outcome: "skipped",
+            skipReason: "empty-buffer",
+            text: "",
+        });
         return;
+    }
     state.captureBuffer.delete(sessionID);
     const combined = fragments.join("\n").trim();
-    const candidate = extractCaptureCandidate(combined, state.config.minCaptureChars);
-    if (!candidate)
-        return;
+    const activeScope = await resolveSessionScope(sessionID, client, state.defaultScope);
     await state.ensureInitialized();
-    if (!state.initialized)
+    if (!state.initialized) {
         return;
+    }
+    await recordCaptureEvent(state, {
+        sessionID,
+        scope: activeScope,
+        outcome: "considered",
+        text: combined,
+    });
+    const result = extractCaptureCandidate(combined, state.config.minCaptureChars);
+    if (!result.candidate) {
+        await recordCaptureEvent(state, {
+            sessionID,
+            scope: activeScope,
+            outcome: "skipped",
+            skipReason: result.skipReason,
+            text: combined,
+        });
+        return;
+    }
     let vector = [];
     try {
-        vector = await state.embedder.embed(candidate.text);
+        vector = await state.embedder.embed(result.candidate.text);
     }
     catch (error) {
         console.warn(`[lancedb-opencode-pro] embedding unavailable during auto-capture: ${toErrorMessage(error)}`);
+        await recordCaptureEvent(state, {
+            sessionID,
+            scope: activeScope,
+            outcome: "skipped",
+            skipReason: "embedding-unavailable",
+            text: combined,
+        });
         vector = [];
     }
     if (vector.length === 0) {
         console.warn("[lancedb-opencode-pro] auto-capture skipped because embedding vector is empty");
+        await recordCaptureEvent(state, {
+            sessionID,
+            scope: activeScope,
+            outcome: "skipped",
+            skipReason: "empty-embedding",
+            text: combined,
+        });
         return;
     }
-    const activeScope = await resolveSessionScope(sessionID, client, state.defaultScope);
+    const memoryId = generateId();
     await state.store.put({
-        id: generateId(),
-        text: candidate.text,
+        id: memoryId,
+        text: result.candidate.text,
         vector,
-        category: candidate.category,
+        category: result.candidate.category,
         scope: activeScope,
-        importance: candidate.importance,
+        importance: result.candidate.importance,
         timestamp: Date.now(),
         schemaVersion: SCHEMA_VERSION,
         embeddingModel: state.config.embedding.model,
@@ -352,8 +513,31 @@ async function flushAutoCapture(sessionID, state, client) {
             sessionID,
         }),
     });
+    await recordCaptureEvent(state, {
+        sessionID,
+        scope: activeScope,
+        outcome: "stored",
+        memoryId,
+        text: result.candidate.text,
+    });
     await state.store.pruneScope(activeScope, state.config.maxEntriesPerScope);
 }
+async function recordCaptureEvent(state, input) {
+    if (!state.initialized)
+        return;
+    await state.store.putEvent({
+        id: generateId(),
+        type: "capture",
+        scope: input.scope,
+        sessionID: input.sessionID,
+        timestamp: Date.now(),
+        outcome: input.outcome,
+        skipReason: input.skipReason,
+        memoryId: input.memoryId,
+        text: input.text,
+        metadataJson: JSON.stringify({ source: "auto-capture" }),
+    });
+}
 async function resolveSessionScope(sessionID, client, fallback) {
     try {
         const response = await client.session.get({ path: { id: sessionID } });

package/dist/store.d.ts

@@ -1,14 +1,16 @@
-import type { MemoryRecord, SearchResult } from "./types.js";
+import type { EffectivenessSummary, MemoryEffectivenessEvent, MemoryRecord, SearchResult } from "./types.js";
 export declare class MemoryStore {
     private readonly dbPath;
     private lancedb;
     private connection;
     private table;
+    private eventTable;
     private indexState;
     private scopeCache;
     constructor(dbPath: string);
     init(vectorDim: number): Promise<void>;
     put(record: MemoryRecord): Promise<void>;
+    putEvent(event: MemoryEffectivenessEvent): Promise<void>;
     search(params: {
         query: string;
         queryVector: number[];
@@ -17,12 +19,19 @@ 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>;
     list(scope: string, limit: number): Promise<MemoryRecord[]>;
     pruneScope(scope: string, maxEntries: number): Promise<number>;
     countIncompatibleVectors(scopes: string[], expectedDim: number): Promise<number>;
+    hasMemory(id: string, scopes: string[]): Promise<boolean>;
+    listEvents(scopes: string[], limit: number): Promise<MemoryEffectivenessEvent[]>;
+    summarizeEvents(scope: string, includeGlobalScope: boolean): Promise<EffectivenessSummary>;
     getIndexHealth(): {
         vector: boolean;
         fts: boolean;
@@ -31,6 +40,8 @@ export declare class MemoryStore {
     private invalidateScope;
     private getCachedScopes;
     private requireTable;
+    private requireEventTable;
+    private readEventsByScopes;
     private readByScopes;
     private ensureIndexes;
 }

package/dist/store.js

@@ -2,11 +2,13 @@ import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { tokenize } from "./utils.js";
 const TABLE_NAME = "memories";
+const EVENTS_TABLE_NAME = "effectiveness_events";
 export class MemoryStore {
     dbPath;
     lancedb = null;
     connection = null;
     table = null;
+    eventTable = null;
     indexState = {
         vector: false,
         fts: false,
@@ -41,6 +43,31 @@ export class MemoryStore {
             this.table = await this.connection.createTable(TABLE_NAME, [bootstrap]);
             await this.table.delete("id = '__bootstrap__'");
         }
+        try {
+            this.eventTable = await this.connection.openTable(EVENTS_TABLE_NAME);
+        }
+        catch {
+            const bootstrapEvent = {
+                id: "__bootstrap__",
+                type: "capture",
+                scope: "global",
+                sessionID: "",
+                timestamp: 0,
+                memoryId: "",
+                text: "",
+                outcome: "considered",
+                skipReason: "",
+                resultCount: 0,
+                injected: false,
+                feedbackType: "",
+                helpful: -1,
+                reason: "",
+                labelsJson: "[]",
+                metadataJson: "{}",
+            };
+            this.eventTable = await this.connection.createTable(EVENTS_TABLE_NAME, [bootstrapEvent]);
+            await this.eventTable.delete("id = '__bootstrap__'");
+        }
         await this.ensureIndexes();
     }
     async put(record) {
@@ -48,20 +75,78 @@ export class MemoryStore {
         await table.add([record]);
         this.invalidateScope(record.scope);
     }
+    async putEvent(event) {
+        await this.requireEventTable().add([
+            {
+                id: event.id,
+                type: event.type,
+                scope: event.scope,
+                sessionID: event.sessionID ?? "",
+                timestamp: event.timestamp,
+                memoryId: event.memoryId ?? "",
+                text: event.text ?? "",
+                outcome: event.type === "capture" ? event.outcome : "",
+                skipReason: event.type === "capture" ? event.skipReason ?? "" : "",
+                resultCount: event.type === "recall" ? event.resultCount : 0,
+                injected: event.type === "recall" ? event.injected : false,
+                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 ?? "" : "",
+                labelsJson: event.type === "feedback" ? JSON.stringify(event.labels ?? []) : "[]",
+                metadataJson: event.metadataJson,
+            },
+        ]);
+    }
     async search(params) {
         const cached = await this.getCachedScopes(params.scopes);
         if (cached.records.length === 0)
             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)
@@ -104,6 +189,93 @@ export class MemoryStore {
         const rows = await this.readByScopes(scopes);
         return rows.filter((row) => row.vectorDim !== expectedDim).length;
     }
+    async hasMemory(id, scopes) {
+        const rows = await this.readByScopes(scopes);
+        return rows.some((row) => row.id === id);
+    }
+    async listEvents(scopes, limit) {
+        const rows = await this.readEventsByScopes(scopes);
+        return rows.sort((a, b) => b.timestamp - a.timestamp).slice(0, limit);
+    }
+    async summarizeEvents(scope, includeGlobalScope) {
+        const scopes = includeGlobalScope && scope !== "global" ? [scope, "global"] : [scope];
+        const events = await this.readEventsByScopes(scopes);
+        const captureSkipReasons = {};
+        let captureConsidered = 0;
+        let captureStored = 0;
+        let captureSkipped = 0;
+        let recallRequested = 0;
+        let recallInjected = 0;
+        let recallReturnedResults = 0;
+        let feedbackMissing = 0;
+        let feedbackWrong = 0;
+        let feedbackUsefulPositive = 0;
+        let feedbackUsefulNegative = 0;
+        for (const event of events) {
+            if (event.type === "capture") {
+                if (event.outcome === "considered")
+                    captureConsidered += 1;
+                if (event.outcome === "stored")
+                    captureStored += 1;
+                if (event.outcome === "skipped") {
+                    captureSkipped += 1;
+                    if (event.skipReason) {
+                        captureSkipReasons[event.skipReason] = (captureSkipReasons[event.skipReason] ?? 0) + 1;
+                    }
+                }
+            }
+            if (event.type === "recall") {
+                recallRequested += 1;
+                if (event.resultCount > 0)
+                    recallReturnedResults += 1;
+                if (event.injected)
+                    recallInjected += 1;
+            }
+            if (event.type === "feedback") {
+                if (event.feedbackType === "missing")
+                    feedbackMissing += 1;
+                if (event.feedbackType === "wrong")
+                    feedbackWrong += 1;
+                if (event.feedbackType === "useful") {
+                    if (event.helpful)
+                        feedbackUsefulPositive += 1;
+                    else
+                        feedbackUsefulNegative += 1;
+                }
+            }
+        }
+        const totalCaptureAttempts = captureStored + captureSkipped;
+        const totalUsefulFeedback = feedbackUsefulPositive + feedbackUsefulNegative;
+        return {
+            scope,
+            totalEvents: events.length,
+            capture: {
+                considered: captureConsidered,
+                stored: captureStored,
+                skipped: captureSkipped,
+                successRate: totalCaptureAttempts === 0 ? 0 : captureStored / totalCaptureAttempts,
+                skipReasons: captureSkipReasons,
+            },
+            recall: {
+                requested: recallRequested,
+                injected: recallInjected,
+                returnedResults: recallReturnedResults,
+                hitRate: recallRequested === 0 ? 0 : recallReturnedResults / recallRequested,
+                injectionRate: recallRequested === 0 ? 0 : recallInjected / recallRequested,
+            },
+            feedback: {
+                missing: feedbackMissing,
+                wrong: feedbackWrong,
+                useful: {
+                    positive: feedbackUsefulPositive,
+                    negative: feedbackUsefulNegative,
+                    helpfulRate: totalUsefulFeedback === 0 ? 0 : feedbackUsefulPositive / totalUsefulFeedback,
+                },
+                falsePositiveRate: captureStored === 0 ? 0 : feedbackWrong / captureStored,
+                falseNegativeRate: totalCaptureAttempts === 0 ? 0 : feedbackMissing / totalCaptureAttempts,
+            },
+        };
+    }
     getIndexHealth() {
         return {
             vector: this.indexState.vector,
@@ -148,6 +320,44 @@ export class MemoryStore {
         }
         return this.table;
     }
+    requireEventTable() {
+        if (!this.eventTable) {
+            throw new Error("MemoryStore event table is not initialized");
+        }
+        return this.eventTable;
+    }
+    async readEventsByScopes(scopes) {
+        const table = this.requireEventTable();
+        if (scopes.length === 0)
+            return [];
+        const whereExpr = scopes.map((scope) => `scope = '${escapeSql(scope)}'`).join(" OR ");
+        const rows = await table
+            .query()
+            .where(`(${whereExpr})`)
+            .select([
+            "id",
+            "type",
+            "scope",
+            "sessionID",
+            "timestamp",
+            "memoryId",
+            "text",
+            "outcome",
+            "skipReason",
+            "resultCount",
+            "injected",
+            "feedbackType",
+            "helpful",
+            "reason",
+            "labelsJson",
+            "metadataJson",
+        ])
+            .limit(100000)
+            .toArray();
+        return rows
+            .map((row) => normalizeEventRow(row))
+            .filter((row) => row !== null);
+    }
     async readByScopes(scopes) {
         const table = this.requireTable();
         if (scopes.length === 0)
@@ -222,9 +432,92 @@ function normalizeRow(row) {
         metadataJson: String(row.metadataJson ?? "{}"),
     };
 }
+function normalizeEventRow(row) {
+    if (typeof row.id !== "string" || typeof row.type !== "string" || typeof row.scope !== "string") {
+        return null;
+    }
+    const base = {
+        id: row.id,
+        scope: row.scope,
+        sessionID: typeof row.sessionID === "string" && row.sessionID.length > 0 ? row.sessionID : undefined,
+        timestamp: Number(row.timestamp ?? Date.now()),
+        memoryId: typeof row.memoryId === "string" && row.memoryId.length > 0 ? row.memoryId : undefined,
+        text: typeof row.text === "string" && row.text.length > 0 ? row.text : undefined,
+        metadataJson: String(row.metadataJson ?? "{}"),
+    };
+    if (row.type === "capture") {
+        return {
+            ...base,
+            type: "capture",
+            outcome: row.outcome === "stored" || row.outcome === "skipped" ? row.outcome : "considered",
+            skipReason: typeof row.skipReason === "string" && row.skipReason.length > 0
+                ? row.skipReason
+                : undefined,
+        };
+    }
+    if (row.type === "recall") {
+        return {
+            ...base,
+            type: "recall",
+            resultCount: Number(row.resultCount ?? 0),
+            injected: Boolean(row.injected),
+        };
+    }
+    if (row.type === "feedback") {
+        const labelsJson = typeof row.labelsJson === "string" ? row.labelsJson : "[]";
+        const labels = JSON.parse(labelsJson);
+        const helpfulValue = Number(row.helpful ?? -1);
+        return {
+            ...base,
+            type: "feedback",
+            feedbackType: row.feedbackType === "missing" || row.feedbackType === "wrong" ? row.feedbackType : "useful",
+            helpful: helpfulValue < 0 ? undefined : helpfulValue === 1,
+            labels: Array.isArray(labels) ? labels.filter((item) => typeof item === "string") : [],
+            reason: typeof row.reason === "string" && row.reason.length > 0 ? row.reason : undefined,
+        };
+    }
+    return null;
+}
 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

@@ -1,6 +1,9 @@
 export type EmbeddingProvider = "ollama" | "openai";
 export type RetrievalMode = "hybrid" | "vector";
 export type MemoryCategory = "preference" | "fact" | "decision" | "entity" | "other";
+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 interface EmbeddingConfig {
     provider: EmbeddingProvider;
     model: string;
@@ -13,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;
@@ -47,3 +54,64 @@ export interface CaptureCandidate {
     category: MemoryCategory;
     importance: number;
 }
+export interface CaptureCandidateResult {
+    candidate: CaptureCandidate | null;
+    skipReason?: CaptureSkipReason;
+}
+interface MemoryEffectivenessEventBase {
+    id: string;
+    scope: string;
+    sessionID?: string;
+    timestamp: number;
+    memoryId?: string;
+    text?: string;
+    metadataJson: string;
+}
+export interface CaptureEvent extends MemoryEffectivenessEventBase {
+    type: "capture";
+    outcome: CaptureOutcome;
+    skipReason?: CaptureSkipReason;
+}
+export interface RecallEvent extends MemoryEffectivenessEventBase {
+    type: "recall";
+    resultCount: number;
+    injected: boolean;
+}
+export interface FeedbackEvent extends MemoryEffectivenessEventBase {
+    type: "feedback";
+    feedbackType: FeedbackType;
+    helpful?: boolean;
+    labels?: string[];
+    reason?: string;
+}
+export type MemoryEffectivenessEvent = CaptureEvent | RecallEvent | FeedbackEvent;
+export interface EffectivenessSummary {
+    scope: string;
+    totalEvents: number;
+    capture: {
+        considered: number;
+        stored: number;
+        skipped: number;
+        successRate: number;
+        skipReasons: Partial<Record<CaptureSkipReason, number>>;
+    };
+    recall: {
+        requested: number;
+        injected: number;
+        returnedResults: number;
+        hitRate: number;
+        injectionRate: number;
+    };
+    feedback: {
+        missing: number;
+        wrong: number;
+        useful: {
+            positive: number;
+            negative: number;
+            helpfulRate: number;
+        };
+        falsePositiveRate: number;
+        falseNegativeRate: number;
+    };
+}
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lancedb-opencode-pro",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "LanceDB-backed long-term memory provider for OpenCode",
   "type": "module",
   "main": "dist/index.js",
@@ -46,10 +46,11 @@
     "test": "npm run typecheck",
     "test:foundation": "npm run build:test && node --test dist-test/test/foundation/foundation.test.js",
     "test:regression": "npm run build:test && node --test dist-test/test/regression/plugin.test.js",
+    "test:effectiveness": "npm run test:foundation && npm run test:regression",
     "test:retrieval": "npm run build:test && node --test dist-test/test/retrieval/retrieval.test.js",
     "benchmark:latency": "npm run build:test && node dist-test/test/benchmark/latency.js",
     "test:e2e": "node scripts/e2e-opencode-memory.mjs",
-    "verify": "npm run typecheck && npm run build && npm run test:foundation && npm run test:regression && npm run test:retrieval",
+    "verify": "npm run typecheck && npm run build && npm run test:effectiveness && npm run test:retrieval",
     "verify:full": "npm run verify && npm run benchmark:latency && npm pack",
     "release:check": "npm run verify:full && npm publish --dry-run",
     "prepublishOnly": "npm run verify:full"