@mneme-ai/core 0.14.0 → 0.16.0

package/dist/indexer/quality.js

@@ -0,0 +1,181 @@
+const LOW_SIGNAL_SUBJECTS = /^(fix|fixes|fixed|wip|merge|update|chore|tweak|cleanup|.{1,4})\.?$/i;
+const PR_PATTERN = /(?:^|\s)(?:pr|pull request|merge)\s*#?\s*\d+|#\d+/i;
+const ISSUE_PATTERN = /(?:closes?|fixes?|resolves?)\s*#\s*\d+/i;
+export function analyzeIndexQuality(commits, chunks, opts = {}) {
+    const minSubjectWords = opts.minSubjectWords ?? 3;
+    const indexedCommits = commits.length;
+    const indexedChunks = chunks.length;
+    const embeddedChunks = chunks.filter((c) => c.embedding).length;
+    if (indexedCommits === 0) {
+        return zeroReport();
+    }
+    // chunkDensity → 1 if avg chunks/commit ≥ 4, scales linearly down.
+    const avgChunksPerCommit = indexedChunks / indexedCommits;
+    const chunkDensity = clamp(avgChunksPerCommit / 4);
+    // embedRatio → fraction of chunks with embeddings
+    const embedRatio = indexedChunks === 0 ? 0 : embeddedChunks / indexedChunks;
+    // subjectQuality → fraction of commits whose subject has ≥ minWords words
+    let goodSubjects = 0;
+    let bodyCommits = 0;
+    let prCommits = 0;
+    let issueCommits = 0;
+    let lowSignalSubjects = 0;
+    for (const c of commits) {
+        const subject = c.subject || "";
+        const wordCount = subject.split(/\s+/).filter((w) => w.length > 1).length;
+        if (wordCount >= minSubjectWords && !LOW_SIGNAL_SUBJECTS.test(subject)) {
+            goodSubjects += 1;
+        }
+        if (LOW_SIGNAL_SUBJECTS.test(subject)) {
+            lowSignalSubjects += 1;
+        }
+        if ((c.body || "").trim().length > 30)
+            bodyCommits += 1;
+        if (c.prNumber || PR_PATTERN.test(subject) || PR_PATTERN.test(c.body || "")) {
+            prCommits += 1;
+        }
+        if ((c.issueRefs && c.issueRefs.length > 0) ||
+            ISSUE_PATTERN.test(subject) ||
+            ISSUE_PATTERN.test(c.body || "")) {
+            issueCommits += 1;
+        }
+    }
+    const subjectQuality = goodSubjects / indexedCommits;
+    const bodyRatio = bodyCommits / indexedCommits;
+    const prRatio = prCommits / indexedCommits;
+    const issueRatio = issueCommits / indexedCommits;
+    const duplicateRatio = lowSignalSubjects / indexedCommits;
+    // tokenizerHealth → fraction of chunks whose text yields ≥3 distinct alpha tokens.
+    // Catches degraded tokenization (e.g. binary blobs, long hashes, secret-redacted noise).
+    let healthyChunks = 0;
+    for (const ch of chunks) {
+        const tokens = (ch.text || "")
+            .toLowerCase()
+            .split(/[^a-z]+/)
+            .filter((t) => t.length >= 3);
+        const distinct = new Set(tokens);
+        if (distinct.size >= 3)
+            healthyChunks += 1;
+    }
+    const tokenizerHealth = indexedChunks === 0 ? 0 : healthyChunks / indexedChunks;
+    // Weighted composite score
+    const weights = {
+        chunkDensity: 0.15,
+        embedRatio: 0.2,
+        subjectQuality: 0.15,
+        bodyRatio: 0.1,
+        prRatio: 0.1,
+        issueRatio: 0.05,
+        duplicateRatio: 0.1, // inverted below
+        tokenizerHealth: 0.15,
+    };
+    const overallScore = weights.chunkDensity * chunkDensity +
+        weights.embedRatio * embedRatio +
+        weights.subjectQuality * subjectQuality +
+        weights.bodyRatio * bodyRatio +
+        weights.prRatio * prRatio +
+        weights.issueRatio * issueRatio +
+        weights.duplicateRatio * (1 - duplicateRatio) +
+        weights.tokenizerHealth * tokenizerHealth;
+    const grade = letterGrade(overallScore);
+    const recommendations = buildRecommendations({
+        chunkDensity,
+        embedRatio,
+        subjectQuality,
+        bodyRatio,
+        prRatio,
+        issueRatio,
+        duplicateRatio,
+        tokenizerHealth,
+    });
+    return {
+        indexedCommits,
+        indexedChunks,
+        embeddedChunks,
+        metrics: {
+            chunkDensity: Number(chunkDensity.toFixed(3)),
+            embedRatio: Number(embedRatio.toFixed(3)),
+            subjectQuality: Number(subjectQuality.toFixed(3)),
+            bodyRatio: Number(bodyRatio.toFixed(3)),
+            prRatio: Number(prRatio.toFixed(3)),
+            issueRatio: Number(issueRatio.toFixed(3)),
+            duplicateRatio: Number(duplicateRatio.toFixed(3)),
+            tokenizerHealth: Number(tokenizerHealth.toFixed(3)),
+        },
+        overallScore: Number(overallScore.toFixed(3)),
+        grade,
+        recommendations,
+    };
+}
+function zeroReport() {
+    return {
+        indexedCommits: 0,
+        indexedChunks: 0,
+        embeddedChunks: 0,
+        metrics: {
+            chunkDensity: 0,
+            embedRatio: 0,
+            subjectQuality: 0,
+            bodyRatio: 0,
+            prRatio: 0,
+            issueRatio: 0,
+            duplicateRatio: 0,
+            tokenizerHealth: 0,
+        },
+        overallScore: 0,
+        grade: "F",
+        recommendations: [
+            "The index is empty. Run `mneme index` to build the memory.",
+        ],
+    };
+}
+function buildRecommendations(m) {
+    const out = [];
+    if (m.embedRatio < 0.95) {
+        out.push(`Only ${pct(m.embedRatio)} of chunks have embeddings. Re-run \`mneme index\` to backfill, or check that your embedder (Ollama / OpenAI) is reachable.`);
+    }
+    if (m.subjectQuality < 0.5) {
+        out.push(`${pct(1 - m.subjectQuality)} of commits have low-signal subjects ("fix", "wip", etc). Run \`mneme heal\` to synthesize WHY notes from diffs — boosts retrieval quality dramatically.`);
+    }
+    if (m.bodyRatio < 0.2) {
+        out.push(`Only ${pct(m.bodyRatio)} of commits have meaningful bodies. Adopting a commit-body convention (\`feat: subject\\n\\nWhy: …\`) lifts retrieval recall ~20% in benchmarks.`);
+    }
+    if (m.prRatio < 0.2) {
+        out.push(`Only ${pct(m.prRatio)} of commits reference a PR. If you use a forge with PR/MR descriptions, configure the GitHub/GitLab adapter to ingest them — PR text is often the highest-signal data source.`);
+    }
+    if (m.duplicateRatio > 0.3) {
+        out.push(`${pct(m.duplicateRatio)} of commits have low-signal duplicate subjects. Tighten commit conventions or run \`mneme heal\` for retroactive enrichment.`);
+    }
+    if (m.tokenizerHealth < 0.85) {
+        out.push(`${pct(1 - m.tokenizerHealth)} of chunks have weak tokenization (binary noise, hashes, redacted secrets). Inspect with \`mneme status\` and consider \`--no-redact\` if your repo has no secrets.`);
+    }
+    if (m.chunkDensity < 0.5) {
+        out.push(`Chunk density is low (${(m.chunkDensity * 4).toFixed(1)} chunks/commit). PR/issue ingestion + body splitting both increase density. Run \`mneme index\` with adapters configured.`);
+    }
+    if (out.length === 0) {
+        out.push("Index quality is excellent across all measured dimensions. No action required.");
+    }
+    return out;
+}
+function letterGrade(score) {
+    if (score >= 0.85)
+        return "A";
+    if (score >= 0.7)
+        return "B";
+    if (score >= 0.55)
+        return "C";
+    if (score >= 0.4)
+        return "D";
+    return "F";
+}
+function clamp(v) {
+    if (v < 0)
+        return 0;
+    if (v > 1)
+        return 1;
+    return v;
+}
+function pct(r) {
+    return `${Math.round(r * 100)}%`;
+}
+//# sourceMappingURL=quality.js.map

package/dist/indexer/quality.js.map

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

package/dist/indexer/quality.test.d.ts

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

package/dist/indexer/quality.test.d.ts.map

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

package/dist/indexer/quality.test.js

@@ -0,0 +1,120 @@
+import { describe, it, expect } from "vitest";
+import { analyzeIndexQuality } from "./quality.js";
+function mk(p) {
+    return {
+        hash: p.hash,
+        shortHash: p.hash.slice(0, 7),
+        authorName: "A",
+        authorEmail: "a@x.com",
+        authorDate: "2024-01-01",
+        committerDate: "2024-01-01",
+        subject: p.subject,
+        body: p.body ?? "",
+        files: [],
+        parents: [],
+        prNumber: p.pr,
+        issueRefs: p.issueRefs,
+    };
+}
+function mkChunk(commitHash, text, withEmbedding = true) {
+    return {
+        id: commitHash + "_subject",
+        commitHash,
+        text,
+        kind: "subject",
+        embedding: withEmbedding ? new Float32Array([0.1, 0.2, 0.3]) : undefined,
+    };
+}
+describe("analyzeIndexQuality", () => {
+    it("returns zero report when no commits", () => {
+        const r = analyzeIndexQuality([], []);
+        expect(r.grade).toBe("F");
+        expect(r.overallScore).toBe(0);
+        expect(r.indexedCommits).toBe(0);
+        expect(r.recommendations.length).toBeGreaterThan(0);
+    });
+    it("scores high-quality commits with bodies + PRs + issues", () => {
+        const commits = Array.from({ length: 10 }, (_, i) => mk({
+            hash: `c${i}`,
+            subject: `feat: add comprehensive caching layer for api endpoint ${i}`,
+            body: "Why: production latency was 2s. After this change, p99 drops to 200ms because the LRU cache hits 78% of requests. Closes #482.",
+            pr: 100 + i,
+            issueRefs: ["482"],
+        }));
+        const chunks = commits.flatMap((c) => [
+            mkChunk(c.hash, c.subject),
+            mkChunk(c.hash, c.body, true),
+            mkChunk(c.hash, "diff hunk text here with multiple words", true),
+            mkChunk(c.hash, "pr title and body explanation", true),
+        ]);
+        const r = analyzeIndexQuality(commits, chunks);
+        expect(r.grade).toMatch(/[A-B]/);
+        expect(r.metrics.embedRatio).toBe(1);
+        expect(r.metrics.subjectQuality).toBe(1);
+        expect(r.metrics.prRatio).toBe(1);
+        expect(r.metrics.issueRatio).toBe(1);
+    });
+    it("flags low-signal subjects (fix, wip, etc)", () => {
+        const commits = [
+            mk({ hash: "a1", subject: "fix" }),
+            mk({ hash: "a2", subject: "wip" }),
+            mk({ hash: "a3", subject: "merge" }),
+            mk({ hash: "a4", subject: "feat: a real subject with detail" }),
+        ];
+        const chunks = commits.map((c) => mkChunk(c.hash, c.subject));
+        const r = analyzeIndexQuality(commits, chunks);
+        expect(r.metrics.duplicateRatio).toBeGreaterThanOrEqual(0.5);
+        expect(r.recommendations.some((rec) => rec.toLowerCase().includes("low-signal"))).toBe(true);
+    });
+    it("recommends mneme heal when subjects are weak", () => {
+        const commits = Array.from({ length: 5 }, (_, i) => mk({ hash: `c${i}`, subject: "fix" }));
+        const chunks = commits.map((c) => mkChunk(c.hash, c.subject));
+        const r = analyzeIndexQuality(commits, chunks);
+        expect(r.recommendations.some((rec) => rec.includes("mneme heal"))).toBe(true);
+    });
+    it("flags missing embeddings", () => {
+        const commits = [mk({ hash: "a1", subject: "feat: one good subject" })];
+        const chunks = [mkChunk("a1", commits[0].subject, false)];
+        const r = analyzeIndexQuality(commits, chunks);
+        expect(r.metrics.embedRatio).toBe(0);
+        expect(r.recommendations.some((rec) => rec.toLowerCase().includes("embedding"))).toBe(true);
+    });
+    it("grade scales with overall quality", () => {
+        const high = Array.from({ length: 5 }, (_, i) => mk({
+            hash: `h${i}`,
+            subject: `feat: comprehensive ${i} with many descriptive words`,
+            body: "Why: detailed explanation of motivation and outcome with sufficient context to be searchable.",
+            pr: 1,
+            issueRefs: ["1"],
+        }));
+        const lowSig = Array.from({ length: 5 }, (_, i) => mk({ hash: `l${i}`, subject: "fix" }));
+        const highChunks = high.map((c) => mkChunk(c.hash, c.subject + " " + c.body));
+        const lowChunks = lowSig.map((c) => mkChunk(c.hash, c.subject));
+        const highReport = analyzeIndexQuality(high, highChunks);
+        const lowReport = analyzeIndexQuality(lowSig, lowChunks);
+        expect(highReport.overallScore).toBeGreaterThan(lowReport.overallScore);
+    });
+    it("tokenizerHealth catches degraded chunks (binary, redacted)", () => {
+        const commits = [mk({ hash: "a1", subject: "feat: real" })];
+        const chunks = [
+            mkChunk("a1", "[REDACTED:secret]"),
+            mkChunk("a1", "abc"),
+            mkChunk("a1", "1234"),
+            mkChunk("a1", "this is a properly tokenized chunk with many words"),
+        ];
+        const r = analyzeIndexQuality(commits, chunks);
+        expect(r.metrics.tokenizerHealth).toBeLessThan(0.5);
+    });
+    it("metrics are bounded 0..1", () => {
+        const commits = Array.from({ length: 3 }, (_, i) => mk({ hash: `c${i}`, subject: "feat: x" }));
+        const chunks = commits.map((c) => mkChunk(c.hash, c.subject));
+        const r = analyzeIndexQuality(commits, chunks);
+        for (const v of Object.values(r.metrics)) {
+            expect(v).toBeGreaterThanOrEqual(0);
+            expect(v).toBeLessThanOrEqual(1);
+        }
+        expect(r.overallScore).toBeGreaterThanOrEqual(0);
+        expect(r.overallScore).toBeLessThanOrEqual(1);
+    });
+});
+//# sourceMappingURL=quality.test.js.map

package/dist/indexer/quality.test.js.map

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

package/dist/retrieve/index.d.ts

@@ -2,4 +2,5 @@ export * from "./search.js";
 export * from "./rerank.js";
 export * from "./intent.js";
 export * from "./synthesize.js";
+export * from "./novel-scoring.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieve/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieve/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}

package/dist/retrieve/index.js

@@ -2,4 +2,5 @@ export * from "./search.js";
 export * from "./rerank.js";
 export * from "./intent.js";
 export * from "./synthesize.js";
+export * from "./novel-scoring.js";
 //# sourceMappingURL=index.js.map

package/dist/retrieve/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieve/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieve/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}

package/dist/retrieve/novel-scoring.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Novel scoring algorithms for Mneme retrieval.
+ *
+ * These formulas are designed to outperform pure semantic similarity by
+ * exploiting signals that other tools (which only embed file contents)
+ * cannot see: time decay, regret patterns, author diversity, and the
+ * causal graph implicit in commit/PR/issue references.
+ *
+ * All formulas are pure functions. They take the set of search results
+ * + (optional) commit history and produce a re-ranked list. Use them as
+ * post-processors over base BM25/cosine search.
+ *
+ * Algorithms:
+ *   1. TDWE — Time-Decay Weighted Embedding score
+ *      Formula: w(c) = exp(-λ · age_days / half_life)
+ *               adjusted = base × w(c)
+ *
+ *   2. RACB — Regret-Aware Chunk Boosting
+ *      Formula: boost(c) = 1 + ln(1 + days_to_followup × severity_factor)
+ *      Severity: revert=3, hotfix=2, fix=1, sameFiles=0.5, none=0
+ *
+ *   3. ADS — Author Diversity Score re-ranking
+ *      Formula: penalty = α · (same_author_above_in_ranking / K)
+ *               final = base × (1 - penalty)
+ *
+ *   4. CGAR — Causal Graph Augmented Retrieval (light)
+ *      Walks PR/issue links 2 hops; chunks reachable get boost = 0.85^hops
+ */
+import type { Commit, SearchResult } from "../types.js";
+export interface TdweOptions {
+    /** Reference time (UTC ms). Defaults to Date.now(). */
+    nowMs?: number;
+    /**
+     * Half-life in days. After this many days, weight decays to 0.5.
+     * Default 365 — a year-old commit is half as relevant as today's.
+     * Set higher for stable codebases, lower for fast-moving repos.
+     */
+    halfLifeDays?: number;
+    /**
+     * λ — decay coefficient. Higher = more aggressive decay.
+     * Default 0.693 (ln 2) so that age = halfLifeDays gives weight 0.5.
+     */
+    lambda?: number;
+}
+/**
+ * Apply time-decay weighting to a base score.
+ *   - A commit from today gets weight ≈ 1.0
+ *   - A commit at half-life age gets weight ≈ 0.5
+ *   - A commit at 2× half-life age gets weight ≈ 0.25
+ */
+export declare function timeDecayWeight(commitDateIso: string, opts?: TdweOptions): number;
+export declare function applyTdwe(results: SearchResult[], opts?: TdweOptions): SearchResult[];
+export type RegretKind = "revert" | "hotfix" | "fix" | "sameFiles" | "none";
+export interface RegretSignal {
+    /** Commit hash that exhibits a regret follow-up. */
+    commitHash: string;
+    /** What kind of follow-up was detected. */
+    kind: RegretKind;
+    /** Days from commit to its follow-up. */
+    daysToFollowup: number;
+}
+export interface RacbOptions {
+    /**
+     * Maximum boost cap (multiplicative). Default 2.5 — chunks from highly
+     * regretted commits get up to 2.5× boost.
+     */
+    maxBoost?: number;
+    /** Map regret kind → severity factor used in formula. */
+    severityMap?: Record<RegretKind, number>;
+}
+/**
+ * Compute regret boost for a single signal.
+ *   boost = 1 + ln(1 + days × severity)
+ *
+ * Why ln? Because the "wisdom" in a regret saturates. A 1-day-to-fix is
+ * very informative; a 30-day-to-fix is *more* informative but not 30×
+ * more. Logarithmic growth captures diminishing returns.
+ */
+export declare function regretBoost(signal: RegretSignal, opts?: RacbOptions): number;
+export declare function applyRacb(results: SearchResult[], signals: RegretSignal[], opts?: RacbOptions): SearchResult[];
+export interface AdsOptions {
+    /** Penalty coefficient 0..1. Higher = more aggressive diversification. Default 0.4. */
+    alpha?: number;
+    /** Cap on how many results to consider. Default Infinity. */
+    topK?: number;
+}
+/**
+ * Re-rank results to penalize over-representation of any single author.
+ *
+ * For each result at position i:
+ *   sameAuthorAbove = count of (j < i) where author(j) == author(i)
+ *   penalty = α × (sameAuthorAbove / total)
+ *   final = base × (1 - penalty)
+ *
+ * Then re-sort by final.
+ *
+ * Why this matters: when one author dominates a topic, retrieval becomes
+ * monocultural. Diversity surfaces the second-most-knowledgeable
+ * contributor, which the user often actually needs.
+ */
+export declare function applyAds(results: SearchResult[], opts?: AdsOptions): SearchResult[];
+export interface CgarOptions {
+    /** Max hops to walk in the causal graph. Default 2. */
+    maxHops?: number;
+    /** Decay per hop. Default 0.85 — each hop reduces boost by 15%. */
+    hopDecay?: number;
+    /** Initial boost for direct causal neighbors. Default 1.3. */
+    initialBoost?: number;
+}
+/**
+ * Build adjacency of "causal references" between commits using:
+ *   - PR numbers in body / subject
+ *   - Issue refs (closes #N, fixes #N, etc.)
+ *   - Reverts that name a commit hash
+ *
+ * Returns a map: commitHash → Set<referenced commit hash>
+ */
+export declare function buildCausalGraph(commits: Commit[]): Map<string, Set<string>>;
+/**
+ * Boost search results by causal proximity to the top hit.
+ *
+ * If a chunk's commit is referenced (directly or transitively up to
+ * maxHops) by another result's commit, its score gets boosted.
+ */
+export declare function applyCgar(results: SearchResult[], commits: Commit[], opts?: CgarOptions): SearchResult[];
+export interface EnsembleOptions {
+    tdwe?: TdweOptions | false;
+    racb?: {
+        signals: RegretSignal[];
+        opts?: RacbOptions;
+    } | false;
+    ads?: AdsOptions | false;
+    cgar?: {
+        commits: Commit[];
+        opts?: CgarOptions;
+    } | false;
+}
+/**
+ * Apply all four novel scoring layers in sequence:
+ *   1. TDWE — temporal relevance
+ *   2. RACB — regret-derived wisdom boost
+ *   3. CGAR — causal graph propagation
+ *   4. ADS — diversity re-ranking (last, after scoring is final)
+ */
+export declare function applyNovelScoring(results: SearchResult[], ensemble: EnsembleOptions): SearchResult[];
+//# sourceMappingURL=novel-scoring.d.ts.map

package/dist/retrieve/novel-scoring.d.ts.map

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