@danielmarbach/mnemonic-mcp 0.21.0 → 0.23.0

package/build/lexical.d.ts

@@ -30,6 +30,41 @@ export declare function containsSubstring(haystack: string, needle: string): boo
  * - unigram Jaccard (0.25 weight) — token-level overlap
  */
 export declare function computeLexicalScore(query: string, projectionText: string): number;
+/**
+ * Compute normalized term frequency for a token list.
+ */
+export declare function computeTermFrequency(tokens: string[]): Map<string, number>;
+/**
+ * Compute smoothed inverse document frequency for a tokenized corpus.
+ */
+export declare function computeInverseDocumentFrequency(documents: string[][]): Map<string, number>;
+/**
+ * Compute cosine similarity between a query and document TF-IDF vectors.
+ */
+export declare function computeTfIdfCosineSimilarity(query: string, document: string, corpus: string[]): number;
+interface PreparedTfIdfDocument {
+    id: string;
+    text: string;
+    tokens: string[];
+}
+export interface PreparedTfIdfCorpus {
+    documents: PreparedTfIdfDocument[];
+    idf: Map<string, number>;
+}
+export declare function prepareTfIdfCorpus(documents: Array<{
+    id: string;
+    text: string;
+}>): PreparedTfIdfCorpus;
+/**
+ * Rank documents by TF-IDF cosine similarity for a query.
+ */
+export declare function rankDocumentsByTfIdf(query: string, documents: Array<{
+    id: string;
+    text: string;
+}>, limit: number, preparedCorpus?: PreparedTfIdfCorpus): Array<{
+    id: string;
+    score: number;
+}>;
 /**
  * Maximum number of candidates to consider for lexical rescue.
  */
@@ -50,4 +85,5 @@ export declare const LEXICAL_RESCUE_RESULT_LIMIT = 3;
  * OR when there are no semantic results.
  */
 export declare function shouldTriggerLexicalRescue(topSemanticScore: number | undefined, semanticResultCount: number): boolean;
+export {};
 //# sourceMappingURL=lexical.d.ts.map

package/build/lexical.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lexical.d.ts","sourceRoot":"","sources":["../src/lexical.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE/C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAQxE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAIpE;AAeD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAE3E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAkBjF;AAED;;GAEG;AACH,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,mBAAmB,EAAE,MAAM,GAC1B,OAAO,CAKT"}
+{"version":3,"file":"lexical.d.ts","sourceRoot":"","sources":["../src/lexical.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE/C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAQxE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAIpE;AAeD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAE3E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAkBjF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAa1E;AAED;;GAEG;AACH,wBAAgB,+BAA+B,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAgB1F;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAgCtG;AAED,UAAU,qBAAqB;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,qBAAqB,EAAE,CAAC;IACnC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1B;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,mBAAmB,CAWrB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAC9C,KAAK,EAAE,MAAM,EACb,cAAc,CAAC,EAAE,mBAAmB,GACnC,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAsBtC;AAuED;;GAEG;AACH,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,mBAAmB,EAAE,MAAM,GAC1B,OAAO,CAKT"}

package/build/lexical.js

@@ -82,6 +82,153 @@ export function computeLexicalScore(query, projectionText) {
     const unigramScore = jaccardSimilarity(queryTokens, projTokens);
     return 0.4 * substringScore + 0.35 * bigramScore + 0.25 * unigramScore;
 }
+/**
+ * Compute normalized term frequency for a token list.
+ */
+export function computeTermFrequency(tokens) {
+    const frequencies = new Map();
+    if (tokens.length === 0)
+        return frequencies;
+    for (const token of tokens) {
+        frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+    }
+    for (const [token, count] of frequencies) {
+        frequencies.set(token, count / tokens.length);
+    }
+    return frequencies;
+}
+/**
+ * Compute smoothed inverse document frequency for a tokenized corpus.
+ */
+export function computeInverseDocumentFrequency(documents) {
+    const idf = new Map();
+    if (documents.length === 0)
+        return idf;
+    const documentFrequencies = new Map();
+    for (const document of documents) {
+        for (const token of new Set(document)) {
+            documentFrequencies.set(token, (documentFrequencies.get(token) ?? 0) + 1);
+        }
+    }
+    for (const [token, frequency] of documentFrequencies) {
+        idf.set(token, Math.log((1 + documents.length) / (1 + frequency)) + 1);
+    }
+    return idf;
+}
+/**
+ * Compute cosine similarity between a query and document TF-IDF vectors.
+ */
+export function computeTfIdfCosineSimilarity(query, document, corpus) {
+    const corpusTokens = corpus.map((entry) => tokenize(entry));
+    const queryTokens = tokenize(query);
+    const documentTokens = tokenize(document);
+    if (queryTokens.length === 0 || documentTokens.length === 0 || corpusTokens.length === 0) {
+        return 0;
+    }
+    const idf = computeInverseDocumentFrequency(corpusTokens);
+    const queryTf = computeTermFrequency(queryTokens);
+    const documentTf = computeTermFrequency(documentTokens);
+    const vocabulary = new Set([...queryTf.keys(), ...documentTf.keys()]);
+    let dotProduct = 0;
+    let queryMagnitude = 0;
+    let documentMagnitude = 0;
+    for (const token of vocabulary) {
+        const weight = idf.get(token) ?? 0;
+        const queryWeight = (queryTf.get(token) ?? 0) * weight;
+        const documentWeight = (documentTf.get(token) ?? 0) * weight;
+        dotProduct += queryWeight * documentWeight;
+        queryMagnitude += queryWeight * queryWeight;
+        documentMagnitude += documentWeight * documentWeight;
+    }
+    if (queryMagnitude === 0 || documentMagnitude === 0) {
+        return 0;
+    }
+    return dotProduct / (Math.sqrt(queryMagnitude) * Math.sqrt(documentMagnitude));
+}
+export function prepareTfIdfCorpus(documents) {
+    const preparedDocuments = documents.map((document) => ({
+        id: document.id,
+        text: document.text,
+        tokens: tokenize(document.text),
+    }));
+    return {
+        documents: preparedDocuments,
+        idf: computeInverseDocumentFrequency(preparedDocuments.map((document) => document.tokens)),
+    };
+}
+/**
+ * Rank documents by TF-IDF cosine similarity for a query.
+ */
+export function rankDocumentsByTfIdf(query, documents, limit, preparedCorpus) {
+    if (limit <= 0 || documents.length === 0) {
+        return [];
+    }
+    const prepared = preparedCorpus ?? prepareTfIdfCorpus(documents);
+    const corpus = prepared.documents.map((document) => document.text);
+    const queryTokens = tokenize(query);
+    const idf = prepared.idf;
+    return prepared.documents
+        .map((document) => {
+        const tfIdfScore = computeTfIdfCosineSimilarityWithPreparedData(queryTokens, document.tokens, idf);
+        const coverageScore = computeTfIdfWeightedQueryCoverage(queryTokens, document.tokens, idf);
+        const titleScore = computeLexicalScore(query, extractProjectionTitle(document.text));
+        return {
+            id: document.id,
+            score: tfIdfScore + 0.35 * coverageScore + 0.2 * titleScore,
+        };
+    })
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+}
+function computeTfIdfCosineSimilarityWithPreparedData(queryTokens, documentTokens, idf) {
+    if (queryTokens.length === 0 || documentTokens.length === 0) {
+        return 0;
+    }
+    const queryTf = computeTermFrequency(queryTokens);
+    const documentTf = computeTermFrequency(documentTokens);
+    const vocabulary = new Set([...queryTf.keys(), ...documentTf.keys()]);
+    let dotProduct = 0;
+    let queryMagnitude = 0;
+    let documentMagnitude = 0;
+    for (const token of vocabulary) {
+        const weight = idf.get(token) ?? 0;
+        const queryWeight = (queryTf.get(token) ?? 0) * weight;
+        const documentWeight = (documentTf.get(token) ?? 0) * weight;
+        dotProduct += queryWeight * documentWeight;
+        queryMagnitude += queryWeight * queryWeight;
+        documentMagnitude += documentWeight * documentWeight;
+    }
+    if (queryMagnitude === 0 || documentMagnitude === 0) {
+        return 0;
+    }
+    return dotProduct / (Math.sqrt(queryMagnitude) * Math.sqrt(documentMagnitude));
+}
+function computeTfIdfWeightedQueryCoverage(queryTokens, documentTokens, idf) {
+    const uniqueQueryTokens = Array.from(new Set(queryTokens));
+    if (uniqueQueryTokens.length === 0) {
+        return 0;
+    }
+    const documentTokenSet = new Set(documentTokens);
+    let matchedWeight = 0;
+    let totalWeight = 0;
+    for (const token of uniqueQueryTokens) {
+        const weight = idf.get(token) ?? 0;
+        totalWeight += weight;
+        if (documentTokenSet.has(token)) {
+            matchedWeight += weight;
+        }
+    }
+    return totalWeight === 0 ? 0 : matchedWeight / totalWeight;
+}
+function extractProjectionTitle(text) {
+    const titleLine = text.split("\n", 1)[0]?.trim();
+    if (!titleLine) {
+        return "";
+    }
+    return titleLine.startsWith("Title:")
+        ? titleLine.slice("Title:".length).trim()
+        : titleLine;
+}
 /**
  * Maximum number of candidates to consider for lexical rescue.
  */

package/build/lexical.js.map

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

package/build/recall.d.ts

@@ -3,22 +3,42 @@ import type { EffectiveNoteMetadata } from "./role-suggestions.js";
 export interface ScoredRecallCandidate {
     id: string;
     score: number;
+    /** Semantic plausibility used to gate canonical explanation promotion. */
+    semanticScoreForPromotion?: number;
     boosted: number;
     vault: Vault;
     isCurrentProject: boolean;
     /** Lexical overlap score in [0, 1]. Undefined when not computed. */
     lexicalScore?: number;
+    /** Coverage of rarer query tokens across the current candidate set. */
+    coverageScore?: number;
+    /** Exact contiguous phrase coverage across significant query tokens. */
+    phraseScore?: number;
+    lifecycle?: "temporary" | "permanent";
+    relatedCount?: number;
+    connectionDiversity?: number;
+    structureScore?: number;
+    metadata?: EffectiveNoteMetadata;
+    canonicalExplanationScore?: number;
 }
 export declare function computeRecallMetadataBoost(metadata?: EffectiveNoteMetadata): number;
 /**
- * Compute a hybrid score that combines semantic similarity with lexical overlap.
+ * Compute a hybrid score that combines semantic similarity with additive
+ * lexical, coverage, phrase, and canonical explanation signals.
  *
- * The formula is: boosted + LEXICAL_HYBRID_WEIGHT * lexicalScore
+ * The formula is:
+ * boosted
+ *   + LEXICAL_HYBRID_WEIGHT * lexical
+ *   + COVERAGE_HYBRID_WEIGHT * coverage
+ *   + PHRASE_HYBRID_WEIGHT * phrase
+ *   + canonicalExplanation
  *
- * Lexical score acts as a tiebreaker and small reranking signal — it cannot
- * overcome a large semantic gap but can reorder close candidates.
+ * These additive signals act as tiebreakers and small reranking signals. They
+ * cannot overcome a large semantic gap but can reorder close candidates.
  */
 export declare function computeHybridScore(candidate: ScoredRecallCandidate): number;
+export declare function computeCanonicalExplanationScore(candidate: ScoredRecallCandidate): number;
+export declare function applyCanonicalExplanationPromotion(candidates: ScoredRecallCandidate[]): ScoredRecallCandidate[];
 /**
  * Apply lexical reranking to a set of semantic candidates.
  *

package/build/recall.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recall.d.ts","sourceRoot":"","sources":["../src/recall.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAWnE,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,gBAAgB,EAAE,OAAO,CAAC;IAC1B,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAsBnF;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,qBAAqB,GAAG,MAAM,CAG3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,MAAM,EACb,iBAAiB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GACpD,qBAAqB,EAAE,CASzB;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,qBAAqB,EAAE,EAC/B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,GAAG,QAAQ,GAAG,KAAK,GAClC,qBAAqB,EAAE,CAoBzB"}
+{"version":3,"file":"recall.d.ts","sourceRoot":"","sources":["../src/recall.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAcnE,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,gBAAgB,EAAE,OAAO,CAAC;IAC1B,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAsBnF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,qBAAqB,GAAG,MAAM,CAM3E;AAED,wBAAgB,gCAAgC,CAAC,SAAS,EAAE,qBAAqB,GAAG,MAAM,CAmBzF;AAED,wBAAgB,kCAAkC,CAAC,UAAU,EAAE,qBAAqB,EAAE,GAAG,qBAAqB,EAAE,CAM/G;AAmCD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,MAAM,EACb,iBAAiB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GACpD,qBAAqB,EAAE,CAezB;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,qBAAqB,EAAE,EAC/B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,GAAG,QAAQ,GAAG,KAAK,GAClC,qBAAqB,EAAE,CAoBzB"}

package/build/recall.js

@@ -1,10 +1,13 @@
-import { computeLexicalScore } from "./lexical.js";
+import { computeLexicalScore, tokenize } from "./lexical.js";
 const RECALL_ALWAYS_LOAD_BOOST = 0.01;
 const RECALL_SUMMARY_BOOST = 0.012;
 const RECALL_DECISION_BOOST = 0.009;
 const RECALL_HIGH_IMPORTANCE_BOOST = 0.006;
 /** Weight applied to lexical score when computing hybrid boosted score. */
 const LEXICAL_HYBRID_WEIGHT = 0.12;
+const COVERAGE_HYBRID_WEIGHT = 0.08;
+const PHRASE_HYBRID_WEIGHT = 0.16;
+const MIN_CANONICAL_EXPLANATION_SCORE = 0.5;
 export function computeRecallMetadataBoost(metadata) {
     if (!metadata) {
         return 0;
@@ -25,16 +28,76 @@ export function computeRecallMetadataBoost(metadata) {
     return boost;
 }
 /**
- * Compute a hybrid score that combines semantic similarity with lexical overlap.
+ * Compute a hybrid score that combines semantic similarity with additive
+ * lexical, coverage, phrase, and canonical explanation signals.
  *
- * The formula is: boosted + LEXICAL_HYBRID_WEIGHT * lexicalScore
+ * The formula is:
+ * boosted
+ *   + LEXICAL_HYBRID_WEIGHT * lexical
+ *   + COVERAGE_HYBRID_WEIGHT * coverage
+ *   + PHRASE_HYBRID_WEIGHT * phrase
+ *   + canonicalExplanation
  *
- * Lexical score acts as a tiebreaker and small reranking signal — it cannot
- * overcome a large semantic gap but can reorder close candidates.
+ * These additive signals act as tiebreakers and small reranking signals. They
+ * cannot overcome a large semantic gap but can reorder close candidates.
  */
 export function computeHybridScore(candidate) {
     const lexical = candidate.lexicalScore ?? 0;
-    return candidate.boosted + LEXICAL_HYBRID_WEIGHT * lexical;
+    const coverage = candidate.coverageScore ?? 0;
+    const phrase = candidate.phraseScore ?? 0;
+    const canonical = candidate.canonicalExplanationScore ?? 0;
+    return candidate.boosted + LEXICAL_HYBRID_WEIGHT * lexical + COVERAGE_HYBRID_WEIGHT * coverage + PHRASE_HYBRID_WEIGHT * phrase + canonical;
+}
+export function computeCanonicalExplanationScore(candidate) {
+    if ((candidate.semanticScoreForPromotion ?? 0) < MIN_CANONICAL_EXPLANATION_SCORE) {
+        return 0;
+    }
+    const permanence = candidate.lifecycle === "permanent" ? 0.05 : 0;
+    const role = candidate.metadata?.role === "decision"
+        ? 0.05
+        : candidate.metadata?.role === "context"
+            ? 0.04
+            : candidate.metadata?.role === "summary"
+                ? 0.02
+                : 0;
+    const centrality = Math.min(0.05, Math.log((candidate.relatedCount ?? 0) + 1) * 0.02);
+    const diversity = Math.min(0.04, (candidate.connectionDiversity ?? 0) * 0.015);
+    const structure = Math.min(0.03, candidate.structureScore ?? 0);
+    const wording = Math.min(0.01, candidate.lexicalScore ?? 0);
+    return permanence + role + centrality + diversity + structure + wording;
+}
+export function applyCanonicalExplanationPromotion(candidates) {
+    for (const candidate of candidates) {
+        candidate.canonicalExplanationScore = computeCanonicalExplanationScore(candidate);
+    }
+    return [...candidates].sort((a, b) => computeHybridScore(b) - computeHybridScore(a));
+}
+function computeSignificantPhraseScore(query, candidateText) {
+    const phraseTokens = Array.from(new Set(tokenize(query))).filter((token) => token.length >= 4);
+    if (phraseTokens.length < 2) {
+        return 0;
+    }
+    const normalizedCandidate = tokenize(candidateText).join(" ");
+    return normalizedCandidate.includes(phraseTokens.join(" ")) ? 1 : 0;
+}
+function computeWeightedQueryCoverage(query, candidateText, corpusTexts) {
+    const queryTokens = Array.from(new Set(tokenize(query))).filter((token) => token.length >= 4);
+    if (queryTokens.length === 0) {
+        return 0;
+    }
+    const candidateTokens = new Set(tokenize(candidateText));
+    const corpusTokenSets = corpusTexts.map((text) => new Set(tokenize(text)));
+    let matchedWeight = 0;
+    let totalWeight = 0;
+    for (const token of queryTokens) {
+        const documentFrequency = corpusTokenSets.reduce((count, tokens) => count + (tokens.has(token) ? 1 : 0), 0);
+        const weight = 1 / Math.max(documentFrequency, 1);
+        totalWeight += weight;
+        if (candidateTokens.has(token)) {
+            matchedWeight += weight;
+        }
+    }
+    return totalWeight === 0 ? 0 : matchedWeight / totalWeight;
 }
 /**
  * Apply lexical reranking to a set of semantic candidates.
@@ -46,10 +109,15 @@ export function computeHybridScore(candidate) {
  * undefined and contributes 0 to the hybrid score.
  */
 export function applyLexicalReranking(candidates, query, getProjectionText) {
+    const corpusTexts = candidates
+        .map((candidate) => getProjectionText(candidate.id))
+        .filter((text) => Boolean(text));
     for (const candidate of candidates) {
         const projText = getProjectionText(candidate.id);
         if (projText) {
             candidate.lexicalScore = computeLexicalScore(query, projText);
+            candidate.coverageScore = computeWeightedQueryCoverage(query, projText, corpusTexts);
+            candidate.phraseScore = computeSignificantPhraseScore(query, projText);
         }
     }
     return [...candidates].sort((a, b) => computeHybridScore(b) - computeHybridScore(a));

package/build/recall.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielmarbach/mnemonic-mcp",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "A local MCP memory server backed by markdown + JSON files, synced via git",
   "type": "module",
   "repository": {