@mneme-ai/core 0.8.4 → 0.10.0

package/dist/wisdom/feedback.js

@@ -0,0 +1,116 @@
+/**
+ * Feedback collector — every `mneme ask` writes one row.
+ *
+ * was_helpful starts NULL and is filled by:
+ *   - explicit:        `mneme feedback <id> up|down`
+ *   - implicit-revisit: the user ran `mneme why <commit>` on a returned commit
+ *                       within 5 minutes — strong positive signal.
+ *   - implicit-reuse:   the user did not re-ask a slightly-different version of
+ *                       the same query within 60s — weak positive signal.
+ *
+ * Why these heuristics: they require zero UX work from the user. The
+ * explicit path exists for power users; the implicit paths cover the 95%.
+ */
+import { randomUUID } from "node:crypto";
+/** Insert a pending feedback row. Returns the id so callers can update it later. */
+export function recordQuery(store, input) {
+    const id = randomUUID();
+    const now = new Date().toISOString();
+    store.db
+        .prepare(`INSERT INTO wisdom_feedback
+       (id, query, result_hashes, top_score, was_helpful, source,
+        semantic_weight, min_sem_cosine, rrf_k, created_at)
+       VALUES (?, ?, ?, ?, NULL, 'pending', ?, ?, ?, ?)`)
+        .run(id, input.query, JSON.stringify(input.resultHashes), input.topScore ?? null, input.semanticWeight ?? null, input.minSemCosine ?? null, input.rrfK ?? null, now);
+    return id;
+}
+/** Set was_helpful for a feedback row. */
+export function setHelpful(store, id, wasHelpful, source = "explicit") {
+    const result = store.db
+        .prepare(`UPDATE wisdom_feedback SET was_helpful = ?, source = ? WHERE id = ?`)
+        .run(wasHelpful ? 1 : 0, source, id);
+    return result.changes > 0;
+}
+/**
+ * Implicit positive signal: the user looked at one of the returned commits
+ * via `mneme why`. We mark the most recent matching pending row as helpful.
+ */
+export function recordImplicitRevisit(store, commitHash) {
+    const recent = store.db
+        .prepare(`SELECT id, result_hashes FROM wisdom_feedback
+       WHERE was_helpful IS NULL
+         AND created_at >= datetime('now', '-5 minutes')
+       ORDER BY created_at DESC
+       LIMIT 20`)
+        .all();
+    let updated = 0;
+    for (const row of recent) {
+        try {
+            const hashes = JSON.parse(row.result_hashes);
+            if (hashes.includes(commitHash)) {
+                if (setHelpful(store, row.id, true, "implicit-revisit"))
+                    updated += 1;
+            }
+        }
+        catch {
+            // ignore corrupt JSON; the row is just an inert breadcrumb in that case
+        }
+    }
+    return updated;
+}
+export function listFeedback(store, opts = {}) {
+    const where = [];
+    const params = [];
+    if (opts.since) {
+        where.push("created_at >= ?");
+        params.push(opts.since);
+    }
+    const sql = `
+    SELECT id, query, result_hashes, top_score, was_helpful, source,
+           semantic_weight, min_sem_cosine, rrf_k, created_at
+    FROM wisdom_feedback
+    ${where.length ? "WHERE " + where.join(" AND ") : ""}
+    ORDER BY created_at DESC
+    LIMIT ?
+  `;
+    params.push(opts.limit ?? 1000);
+    const rows = store.db.prepare(sql).all(...params);
+    return rows.map((r) => ({
+        id: r.id,
+        query: r.query,
+        resultHashes: JSON.parse(r.result_hashes),
+        topScore: r.top_score ?? undefined,
+        wasHelpful: r.was_helpful === 1 ? 1 : r.was_helpful === 0 ? 0 : undefined,
+        source: r.source,
+        semanticWeight: r.semantic_weight ?? undefined,
+        minSemCosine: r.min_sem_cosine ?? undefined,
+        rrfK: r.rrf_k ?? undefined,
+        createdAt: r.created_at,
+    }));
+}
+export function summarizeFeedback(store, since) {
+    const params = [];
+    let where = "";
+    if (since) {
+        where = "WHERE created_at >= ?";
+        params.push(since);
+    }
+    const row = store.db
+        .prepare(`SELECT
+         COUNT(*) AS total,
+         SUM(CASE WHEN was_helpful = 1 THEN 1 ELSE 0 END) AS helpful,
+         SUM(CASE WHEN was_helpful = 0 THEN 1 ELSE 0 END) AS unhelpful,
+         SUM(CASE WHEN was_helpful IS NULL THEN 1 ELSE 0 END) AS pending
+       FROM wisdom_feedback ${where}`)
+        .get(...params);
+    const decided = row.helpful + row.unhelpful;
+    const hitRate = decided === 0 ? 0 : row.helpful / decided;
+    return {
+        total: row.total,
+        helpful: row.helpful,
+        unhelpful: row.unhelpful,
+        pending: row.pending,
+        hitRate,
+    };
+}
+//# sourceMappingURL=feedback.js.map

package/dist/wisdom/feedback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.js","sourceRoot":"","sources":["../../src/wisdom/feedback.ts"],"names":[],"mappings":"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"}

package/dist/wisdom/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Wisdom Mutant Engine — public surface.
+ *
+ * The engine has three appendable artifacts (feedback, calibrations,
+ * eval-runs) and three operations on them: collect, calibrate, self-eval.
+ *
+ * Inspired by AlphaGo Zero's loop — observe, adapt, measure, repeat —
+ * minus the reinforcement learning. We are not training a model. We are
+ * tuning a small set of search knobs against the user's own feedback
+ * over time. The point is the *loop*, not the algorithm.
+ */
+export * from "./types.js";
+export * from "./feedback.js";
+export * from "./calibrator.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/wisdom/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/wisdom/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC"}

package/dist/wisdom/index.js

@@ -0,0 +1,15 @@
+/**
+ * Wisdom Mutant Engine — public surface.
+ *
+ * The engine has three appendable artifacts (feedback, calibrations,
+ * eval-runs) and three operations on them: collect, calibrate, self-eval.
+ *
+ * Inspired by AlphaGo Zero's loop — observe, adapt, measure, repeat —
+ * minus the reinforcement learning. We are not training a model. We are
+ * tuning a small set of search knobs against the user's own feedback
+ * over time. The point is the *loop*, not the algorithm.
+ */
+export * from "./types.js";
+export * from "./feedback.js";
+export * from "./calibrator.js";
+//# sourceMappingURL=index.js.map

package/dist/wisdom/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/wisdom/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC"}

package/dist/wisdom/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Wisdom Mutant Engine — types.
+ *
+ * The "self-improving memory" subsystem. Three loops:
+ *   1. Feedback collector  — every query records what was returned.
+ *   2. Auto-calibrator     — periodically tunes search knobs against the
+ *                            feedback set, picks the config that maximizes
+ *                            hit rate.
+ *   3. Self-eval           — runs eval set against current config and writes
+ *                            a row to wisdom_eval_run. Detects regressions.
+ *
+ * The point: `mneme adapt` recommendations and the search thresholds in
+ * `mneme ask` are not hardcoded. They are derived from this engine's history.
+ */
+export interface FeedbackRow {
+    id: string;
+    query: string;
+    /** JSON array of commit hashes returned at query time. */
+    resultHashes: string[];
+    /** Top RRF score at query time (a confidence proxy). */
+    topScore?: number;
+    /**
+     * 1 = the user found the result useful (or an implicit signal said so).
+     * 0 = explicitly marked not useful.
+     * undefined = unknown — usually because no feedback has been collected yet.
+     */
+    wasHelpful?: 1 | 0;
+    /** How was_helpful was set. */
+    source: "explicit" | "implicit-reuse" | "implicit-revisit" | "pending";
+    /** Search config in effect when the query ran. */
+    semanticWeight?: number;
+    minSemCosine?: number;
+    rrfK?: number;
+    createdAt: string;
+}
+export interface CalibrationRow {
+    key: string;
+    /** Stored as JSON; parse with JSON.parse. */
+    value: unknown;
+    /** The metric this calibration achieved on the feedback set. */
+    metricValue?: number;
+    metricName?: string;
+    calibratedAt: string;
+    notes?: string;
+}
+export interface EvalRunRow {
+    id: number;
+    ranAt: string;
+    variant: string;
+    recallAt3: number;
+    mrr: number;
+    ndcgAt10?: number;
+    hitRate: number;
+    semanticWeight?: number;
+    minSemCosine?: number;
+    rrfK?: number;
+    numQueries: number;
+    notes?: string;
+}
+/** Search-time knobs the calibrator can tune. */
+export interface CalibrationConfig {
+    semanticWeight: number;
+    minSemCosine: number;
+    rrfK: number;
+}
+export declare const DEFAULT_CALIBRATION: CalibrationConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/wisdom/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/wisdom/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACnB,+BAA+B;IAC/B,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACvE,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,KAAK,EAAE,OAAO,CAAC;IACf,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,mBAAmB,EAAE,iBAIjC,CAAC"}

package/dist/wisdom/types.js

@@ -0,0 +1,20 @@
+/**
+ * Wisdom Mutant Engine — types.
+ *
+ * The "self-improving memory" subsystem. Three loops:
+ *   1. Feedback collector  — every query records what was returned.
+ *   2. Auto-calibrator     — periodically tunes search knobs against the
+ *                            feedback set, picks the config that maximizes
+ *                            hit rate.
+ *   3. Self-eval           — runs eval set against current config and writes
+ *                            a row to wisdom_eval_run. Detects regressions.
+ *
+ * The point: `mneme adapt` recommendations and the search thresholds in
+ * `mneme ask` are not hardcoded. They are derived from this engine's history.
+ */
+export const DEFAULT_CALIBRATION = {
+    semanticWeight: 0.65,
+    minSemCosine: 0.4,
+    rrfK: 60,
+};
+//# sourceMappingURL=types.js.map

package/dist/wisdom/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/wisdom/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAyDH,MAAM,CAAC,MAAM,mBAAmB,GAAsB;IACpD,cAAc,EAAE,IAAI;IACpB,YAAY,EAAE,GAAG;IACjB,IAAI,EAAE,EAAE;CACT,CAAC"}

package/dist/wisdom/wisdom.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=wisdom.test.d.ts.map

package/dist/wisdom/wisdom.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wisdom.test.d.ts","sourceRoot":"","sources":["../../src/wisdom/wisdom.test.ts"],"names":[],"mappings":""}

package/dist/wisdom/wisdom.test.js

@@ -0,0 +1,144 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { MnemeStore } from "../store/sqlite.js";
+import { recordQuery, setHelpful, recordImplicitRevisit, listFeedback, summarizeFeedback, } from "./feedback.js";
+import { calibrate, readCalibration, persistCalibration, listCalibrations, } from "./calibrator.js";
+import { DEFAULT_CALIBRATION } from "./types.js";
+let tmpDir;
+let store;
+beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "mneme-wisdom-test-"));
+    store = new MnemeStore(join(tmpDir, "mneme.db"));
+});
+afterEach(() => {
+    store.close();
+    rmSync(tmpDir, { recursive: true, force: true });
+});
+describe("wisdom_feedback — recordQuery + setHelpful", () => {
+    it("records a pending feedback row and lets it be marked helpful", () => {
+        const id = recordQuery(store, {
+            query: "why does payment retry",
+            resultHashes: ["abc123", "def456"],
+            topScore: 0.087,
+            semanticWeight: 0.65,
+            minSemCosine: 0.4,
+            rrfK: 60,
+        });
+        expect(id).toMatch(/^[0-9a-f-]{36}$/);
+        const list = listFeedback(store);
+        expect(list).toHaveLength(1);
+        expect(list[0].wasHelpful).toBeUndefined();
+        expect(list[0].source).toBe("pending");
+        expect(list[0].resultHashes).toEqual(["abc123", "def456"]);
+        expect(setHelpful(store, id, true)).toBe(true);
+        expect(listFeedback(store)[0].wasHelpful).toBe(1);
+        expect(listFeedback(store)[0].source).toBe("explicit");
+    });
+    it("setHelpful with false records as unhelpful", () => {
+        const id = recordQuery(store, { query: "x", resultHashes: ["h1"] });
+        setHelpful(store, id, false);
+        expect(listFeedback(store)[0].wasHelpful).toBe(0);
+    });
+    it("setHelpful returns false when id does not exist", () => {
+        expect(setHelpful(store, "nonexistent-id", true)).toBe(false);
+    });
+});
+describe("recordImplicitRevisit — implicit positive signal from `mneme why`", () => {
+    it("marks recent pending row helpful when commit was in result set", () => {
+        const id = recordQuery(store, { query: "x", resultHashes: ["abc", "def"] });
+        const updated = recordImplicitRevisit(store, "abc");
+        expect(updated).toBe(1);
+        const row = listFeedback(store).find((r) => r.id === id);
+        expect(row.wasHelpful).toBe(1);
+        expect(row.source).toBe("implicit-revisit");
+    });
+    it("does not touch rows that did not return that commit", () => {
+        const id = recordQuery(store, { query: "x", resultHashes: ["xxx"] });
+        const updated = recordImplicitRevisit(store, "abc");
+        expect(updated).toBe(0);
+        expect(listFeedback(store).find((r) => r.id === id).wasHelpful).toBeUndefined();
+    });
+    it("does not touch already-decided rows", () => {
+        const id = recordQuery(store, { query: "x", resultHashes: ["abc"] });
+        setHelpful(store, id, false, "explicit");
+        recordImplicitRevisit(store, "abc");
+        expect(listFeedback(store)[0].wasHelpful).toBe(0); // stays unhelpful
+        expect(listFeedback(store)[0].source).toBe("explicit");
+    });
+});
+describe("summarizeFeedback", () => {
+    it("counts helpful / unhelpful / pending and computes hit rate", () => {
+        recordQuery(store, { query: "1", resultHashes: ["a"] });
+        const id2 = recordQuery(store, { query: "2", resultHashes: ["b"] });
+        setHelpful(store, id2, true);
+        const id3 = recordQuery(store, { query: "3", resultHashes: ["c"] });
+        setHelpful(store, id3, false);
+        const id4 = recordQuery(store, { query: "4", resultHashes: ["d"] });
+        setHelpful(store, id4, true);
+        const summary = summarizeFeedback(store);
+        expect(summary.total).toBe(4);
+        expect(summary.helpful).toBe(2);
+        expect(summary.unhelpful).toBe(1);
+        expect(summary.pending).toBe(1);
+        // hit rate = helpful / decided = 2 / 3
+        expect(summary.hitRate).toBeCloseTo(2 / 3, 4);
+    });
+    it("returns 0 hit rate when no rows are decided yet", () => {
+        recordQuery(store, { query: "x", resultHashes: ["a"] });
+        expect(summarizeFeedback(store).hitRate).toBe(0);
+    });
+});
+describe("calibrator — readCalibration + persistCalibration", () => {
+    it("returns DEFAULT_CALIBRATION when nothing is stored", () => {
+        expect(readCalibration(store)).toEqual(DEFAULT_CALIBRATION);
+    });
+    it("returns the latest stored calibration", () => {
+        persistCalibration(store, "search", { semanticWeight: 0.85, minSemCosine: 0.3, rrfK: 30, hitRate: 0.92 }, "hit_rate");
+        const c = readCalibration(store);
+        expect(c.semanticWeight).toBe(0.85);
+        expect(c.minSemCosine).toBe(0.3);
+        expect(c.rrfK).toBe(30);
+    });
+    it("listCalibrations returns rows ordered by calibrated_at desc", async () => {
+        persistCalibration(store, "search", { semanticWeight: 0.4, minSemCosine: 0.5, rrfK: 60, hitRate: 0.5 }, "hit_rate");
+        await new Promise((r) => setTimeout(r, 10)); // ensure different timestamps
+        persistCalibration(store, "search", { semanticWeight: 0.85, minSemCosine: 0.3, rrfK: 30, hitRate: 0.9 }, "hit_rate");
+        const list = listCalibrations(store);
+        expect(list).toHaveLength(1); // PRIMARY KEY=key, only one row per key
+        expect(list[0].value.semanticWeight).toBe(0.85);
+    });
+});
+describe("calibrate — the actual loop", () => {
+    it("returns defaults and does not run when fewer than 10 positive examples", async () => {
+        for (let i = 0; i < 5; i++) {
+            const id = recordQuery(store, { query: `q${i}`, resultHashes: [`h${i}`] });
+            setHelpful(store, id, true);
+        }
+        const result = await calibrate(store);
+        expect(result.calibrated).toBe(false);
+        expect(result.positiveExamples).toBe(5);
+        expect(result.config).toEqual(DEFAULT_CALIBRATION);
+    });
+    it("runs grid search and returns the best config when >= 10 positives", async () => {
+        // Note: this calibrates against real search() runs, which need an indexed
+        // store. Here we use ZERO commits — so search() returns [] for everything.
+        // The grid still runs; every config produces 0% hit rate. That's a valid
+        // edge case to verify: calibration is robust even with no corpus.
+        for (let i = 0; i < 12; i++) {
+            const id = recordQuery(store, { query: `q${i}`, resultHashes: [`h${i}`] });
+            setHelpful(store, id, true);
+        }
+        const result = await calibrate(store);
+        expect(result.calibrated).toBe(true);
+        expect(result.positiveExamples).toBe(12);
+        expect(result.grid.length).toBeGreaterThan(0);
+        // With an empty corpus, every grid point has hit rate 0 — but the
+        // calibrator still picks one and persists it.
+        expect(result.hitRate).toBe(0);
+        const stored = readCalibration(store);
+        expect(stored.semanticWeight).toBeDefined();
+    });
+});
+//# sourceMappingURL=wisdom.test.js.map

package/dist/wisdom/wisdom.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wisdom.test.js","sourceRoot":"","sources":["../../src/wisdom/wisdom.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mneme-ai/core",
-  "version": "0.8.4",
+  "version": "0.10.0",
   "description": "Core indexing, retrieval, and graph engine for Mneme",
   "type": "module",
   "main": "./dist/index.js",