@danielmarbach/mnemonic-mcp 0.19.4 → 0.20.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `mnemonic` will be documented in this file.
 
 The format is loosely based on Keep a Changelog and uses semver-style version headings.
 
+## [0.20.0] - 2026-04-04
+
+### Added
+
+- Hybrid recall: semantic search is now enhanced with lightweight lexical reranking over note projections. When semantic results are weak, a bounded lexical rescue path scans projections for additional candidates, improving exact-match and partial-query recall without changing the storage model or adding new infrastructure.
+
+### Changed
+
+- `recall` results now include a `lexicalScore` field in structured output when computed, showing the lexical overlap contribution alongside the semantic score.
+
+## [0.19.5] - 2026-04-04
+
+### Fixed
+
+- `discover_tags` now returns schema-compliant structured output in both suggest and browse modes. Previously, internal ranking fields leaked into tag items, causing MCP callers to fail with `-32602` schema validation errors.
+- `discover_tags` exact context matching now respects tag boundaries, so short tags like `io` no longer get boosted from substring hits inside larger words such as `mnemonic`.
+
 ## [0.19.4] - 2026-04-02
 
 ### Changed

package/README.md

@@ -308,6 +308,8 @@ Project identity derives from the **git remote URL**, normalized to a stable slu
 
 `recall` with `cwd` searches both vaults. Project notes get a **+0.15 similarity boost** — a soft signal, not a hard filter — so global memories remain accessible while project context floats to the top.
 
+**Hybrid recall** enhances semantic search with lightweight lexical reranking over note projections. When semantic results are weak, a bounded lexical rescue path scans projections for additional candidates, improving exact-match and partial-query recall without changing the storage model or adding new infrastructure. Lexical scores act as tiebreakers — they cannot overcome a large semantic gap but can reorder close candidates.
+
 Temporal recall is opt-in via `mode: "temporal"`. It keeps semantic selection first, then enriches only the top matches with compact git-backed history so agents can inspect how a note evolved without turning recall into raw log or diff output.
 
 **What temporal mode shows:**

package/build/index.js

@@ -10,10 +10,11 @@ import { embed, cosineSimilarity, embedModel } from "./embeddings.js";
 import { buildTemporalHistoryEntry, computeConfidence, getNoteProvenance } from "./provenance.js";
 import { enrichTemporalHistory } from "./temporal-interpretation.js";
 import { getOrBuildProjection } from "./projections.js";
-import { invalidateActiveProjectCache, getOrBuildVaultEmbeddings, getOrBuildVaultNoteList, getSessionCachedNote, } from "./cache.js";
+import { invalidateActiveProjectCache, getOrBuildVaultEmbeddings, getOrBuildVaultNoteList, getSessionCachedNote, getSessionCachedProjection, setSessionCachedProjection, } from "./cache.js";
 import { performance } from "perf_hooks";
 import { filterRelationships, mergeRelationshipsFromNotes, normalizeMergePlanSourceIds, resolveEffectiveConsolidationMode, } from "./consolidate.js";
-import { computeRecallMetadataBoost, selectRecallResults } from "./recall.js";
+import { computeRecallMetadataBoost, computeHybridScore, selectRecallResults, applyLexicalReranking } from "./recall.js";
+import { shouldTriggerLexicalRescue, computeLexicalScore, LEXICAL_RESCUE_CANDIDATE_LIMIT, LEXICAL_RESCUE_THRESHOLD, LEXICAL_RESCUE_RESULT_LIMIT, } from "./lexical.js";
 import { getRelationshipPreview } from "./relationships.js";
 import { cleanMarkdown } from "./markdown.js";
 import { MnemonicConfigStore, readVaultSchemaVersion } from "./config.js";
@@ -1727,6 +1728,52 @@ server.registerTool("get_project_memory_policy", {
         structuredContent,
     };
 });
+// ── Lexical rescue helper ─────────────────────────────────────────────────────
+async function collectLexicalRescueCandidates(vaults, query, project, scope, tags, existingIds) {
+    const existingIdSet = new Set(existingIds.map((c) => c.id));
+    const candidates = [];
+    for (const vault of vaults) {
+        const notes = await vault.storage.listNotes().catch(() => []);
+        for (const note of notes) {
+            if (existingIdSet.has(note.id))
+                continue;
+            if (tags && tags.length > 0) {
+                const noteTags = new Set(note.tags);
+                if (!tags.every((t) => noteTags.has(t)))
+                    continue;
+            }
+            const isProjectNote = note.project !== undefined;
+            const isCurrentProject = project && note.project === project.id;
+            if (scope === "project" && !isCurrentProject)
+                continue;
+            if (scope === "global" && isProjectNote)
+                continue;
+            const projection = await getOrBuildProjection(vault.storage, note).catch(() => undefined);
+            if (!projection)
+                continue;
+            const lexicalScore = computeLexicalScore(query, projection.projectionText);
+            if (lexicalScore < LEXICAL_RESCUE_THRESHOLD)
+                continue;
+            const metadataBoost = computeRecallMetadataBoost(getEffectiveMetadata(note));
+            const boost = (isCurrentProject ? 0.15 : 0) + metadataBoost;
+            candidates.push({
+                id: note.id,
+                score: 0,
+                boosted: boost,
+                vault,
+                isCurrentProject: Boolean(isCurrentProject),
+                lexicalScore,
+            });
+            if (candidates.length >= LEXICAL_RESCUE_CANDIDATE_LIMIT)
+                break;
+        }
+        if (candidates.length >= LEXICAL_RESCUE_CANDIDATE_LIMIT)
+            break;
+    }
+    return candidates
+        .sort((a, b) => computeHybridScore(b) - computeHybridScore(a))
+        .slice(0, LEXICAL_RESCUE_RESULT_LIMIT);
+}
 // ── recall ────────────────────────────────────────────────────────────────────
 server.registerTool("recall", {
     title: "Recall",
@@ -1831,7 +1878,42 @@ server.registerTool("recall", {
             scored.push({ id: rec.id, score: rawScore, boosted: rawScore + boost, vault, isCurrentProject: Boolean(isCurrentProject) });
         }
     }
-    const top = selectRecallResults(scored, limit, scope);
+    const projectionTexts = new Map();
+    for (const candidate of scored) {
+        const note = await readCachedNote(candidate.vault, candidate.id).catch(() => null);
+        if (!note) {
+            continue;
+        }
+        const projection = await getOrBuildProjection(candidate.vault.storage, note).catch(() => undefined);
+        if (!projection) {
+            continue;
+        }
+        projectionTexts.set(candidate.id, projection.projectionText);
+        if (project) {
+            setSessionCachedProjection(project.id, candidate.id, projection);
+        }
+    }
+    // Apply lexical reranking over semantic candidates (fail-soft)
+    const getProjectionText = (id) => {
+        const inlineProjection = projectionTexts.get(id);
+        if (inlineProjection) {
+            return inlineProjection;
+        }
+        if (project) {
+            const cached = getSessionCachedProjection(project.id, id);
+            if (cached)
+                return cached.projectionText;
+        }
+        return undefined;
+    };
+    const reranked = applyLexicalReranking(scored, query, getProjectionText);
+    // Lexical rescue: when semantic results are weak, scan projections for additional candidates
+    const topScore = reranked.length > 0 ? reranked[0].score : undefined;
+    if (shouldTriggerLexicalRescue(topScore, reranked.length)) {
+        const rescueCandidates = await collectLexicalRescueCandidates(vaults, query, project ?? undefined, scope, tags, reranked);
+        reranked.push(...rescueCandidates);
+    }
+    const top = selectRecallResults(reranked, limit, scope);
     if (top.length === 0) {
         const structuredContent = { action: "recalled", query, scope: scope || "all", results: [] };
         return { content: [{ type: "text", text: "No memories found matching that query." }], structuredContent };
@@ -2441,9 +2523,13 @@ function countTokenOverlap(tokens, other) {
     }
     return matches;
 }
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function hasExactTagContextMatch(tag, values) {
     const normalizedTag = tag.toLowerCase();
-    return values.some(value => value?.toLowerCase().includes(normalizedTag) ?? false);
+    const pattern = new RegExp(`(^|[^a-z0-9_-])${escapeRegex(normalizedTag)}([^a-z0-9_-]|$)`);
+    return values.some(value => value ? pattern.test(value.toLowerCase()) : false);
 }
 server.registerTool("discover_tags", {
     title: "Discover Tags",
@@ -2572,7 +2658,10 @@ server.registerTool("discover_tags", {
                 (tag.usageCount * 0.1) -
                 genericPenalty -
                 (!isTemporaryTarget && tag.isTemporaryOnly ? 2 : 0)
-            : (tag.usageCount * 1.5) +
+            : (tag.exactContextMatch ? 6 : 0) +
+                (tag.tagTokenOverlap * 3) +
+                (tag.averageContextMatch * 2) +
+                (tag.usageCount * 1.5) +
                 (tag.isTemporaryOnly ? -3 : 1) -
                 (!isTemporaryTarget && tag.isTemporaryOnly ? 2 : 0);
         return {
@@ -2637,7 +2726,13 @@ server.registerTool("discover_tags", {
             project: project ? { id: project.id, name: project.name } : undefined,
             mode,
             scope: scope || "all",
-            tags: tags.slice(0, effectiveLimit).map(({ score, example, reason, ...tag }) => tag),
+            tags: tags.slice(0, effectiveLimit).map(tag => ({
+                tag: tag.tag,
+                usageCount: tag.usageCount,
+                examples: tag.examples,
+                lifecycleTypes: tag.lifecycleTypes,
+                isTemporaryOnly: tag.isTemporaryOnly,
+            })),
             totalTags: tags.length,
             totalNotes: entries.length,
             vaultsSearched,
@@ -2648,7 +2743,14 @@ server.registerTool("discover_tags", {
             project: project ? { id: project.id, name: project.name } : undefined,
             mode,
             scope: scope || "all",
-            recommendedTags: tags.slice(0, effectiveLimit).map(({ score, examples, ...tag }) => tag),
+            recommendedTags: tags.slice(0, effectiveLimit).map(tag => ({
+                tag: tag.tag,
+                usageCount: tag.usageCount,
+                example: tag.example,
+                reason: tag.reason,
+                lifecycleTypes: tag.lifecycleTypes,
+                isTemporaryOnly: tag.isTemporaryOnly,
+            })),
             totalTags: tags.length,
             totalNotes: entries.length,
             vaultsSearched,