lancedb-opencode-pro 0.1.2 → 0.1.3

package/README.md

@@ -230,8 +230,74 @@ 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.
+
 ## OpenAI Embedding Configuration
 
 Default behavior stays on Ollama. To use OpenAI embeddings, set `embedding.provider` to `openai` and provide API key + model.
@@ -362,9 +428,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/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

@@ -57,11 +57,24 @@ const plugin = async (input) => {
                 bm25Weight: state.config.retrieval.mode === "vector" ? 0 : state.config.retrieval.bm25Weight,
                 minScore: state.config.retrieval.minScore,
             });
+            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);
@@ -167,6 +180,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 +428,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 +505,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[];
@@ -23,6 +25,9 @@ export declare class MemoryStore {
     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 +36,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,6 +75,28 @@ 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)
@@ -104,6 +153,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 +284,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,6 +396,52 @@ 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, "''");
 }

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;
@@ -47,3 +50,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.3",
   "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"