@knowall-ai/reverie 0.5.2 → 0.5.4

package/README.md

@@ -1,6 +1,8 @@
 # Reverie — graph memory that dreams
 
-**Reverie** is KnowAll AI's Neo4j knowledge-graph memory for AI agents, served over MCP. Until `@knowall-ai/reverie` is published to npm, install the legacy package `@knowall-ai/mcp-neo4j-agent-memory` (0.2.x). The GitHub repository is now `knowall-ai/mcp-reverie`, and old URLs redirect.
+[![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/knowall-ai/mcp-reverie?label=CodeRabbit+Reviews&labelColor=171717&color=FF570A)](https://coderabbit.ai)
+
+**Reverie** is KnowAll AI's Neo4j knowledge-graph memory for AI agents, served over MCP. It is published on npm as [`@knowall-ai/reverie`](https://www.npmjs.com/package/@knowall-ai/reverie) (successor to the legacy package `@knowall-ai/mcp-neo4j-agent-memory`). The GitHub repository is now `knowall-ai/mcp-reverie`, and old URLs redirect.
 
 ![Reverie — graph memory that dreams](./images/reverie-banner.png)
 
@@ -9,7 +11,7 @@ Reverie turns an agent's memory from a pile of facts into a **map of the entitie
 ## Why Reverie
 
 - **A typed entity graph, not a fact store.** People, organisations, projects, places, concepts, meetings and decisions are nodes with typed relationships. "Who at the Irish FA have we talked to about Winnie?" is a graph walk, not a similarity search.
-- **Search that finds "Ben" when you say "Benjamin".** Hybrid keyword + semantic search, with local embeddings by default (no API key) and OpenAI, Azure OpenAI, Ollama or Voyage a config switch away.
+- **Search that finds "Ben" when you say "Benjamin".** Hybrid keyword + semantic + fuzzy name search, with local embeddings by default (no API key) and OpenAI, Azure OpenAI, Ollama or Voyage a config switch away.
 - **It dreams.** A `dream` tool merges duplicates safely, canonicalises labels, re-embeds, counts orphans and flags nodes that have become property dumps, so a nightly job can keep the graph clean.
 - **One graph, any agent.** KnowAll runs Sallie (OpenClaw) and Poppie (Hermes) against the same conventions; Reverie is how they share what they know.
 - **LLM-driven, transparent tools.** Simple atomic operations; the model does the entity recognition and conflict resolution, and every action is explicit.
@@ -20,7 +22,7 @@ Reverie turns an agent's memory from a pile of facts into a **map of the entitie
 You can run this MCP server directly using npx:
 
 ```bash
-npx @knowall-ai/mcp-neo4j-agent-memory   # becomes `npx @knowall-ai/reverie` once 0.4.0 is published
+npx -y @knowall-ai/reverie
 ```
 
 Or add it to your Claude Desktop configuration:
@@ -28,9 +30,9 @@ Or add it to your Claude Desktop configuration:
 ```json
 {
   "mcpServers": {
-    "neo4j-memory": {
+    "reverie": {
       "command": "npx",
-      "args": ["@knowall-ai/mcp-neo4j-agent-memory"],
+      "args": ["-y", "@knowall-ai/reverie"],
       "env": {
         "NEO4J_URI": "bolt://localhost:7687",
         "NEO4J_USERNAME": "neo4j",
@@ -64,22 +66,23 @@ Unlike traditional approaches that embed complex logic in tools, this server pro
 - **Transparent operations**: Every action is explicit and predictable
 - **Maximum flexibility**: The LLM can implement any strategy without tool limitations
 
-### Search Behavior
-`search_memories` is hybrid: keyword hits (any word of the query as a substring of any searchable content property) rank first, then semantic matches above a similarity threshold. See **Search** below.
+### Search Behaviour
+`search_memories` is hybrid: each result ranks by its best keyword, semantic or fuzzy name signal. See **Search** below.
 
 This approach makes the system more powerful and adaptable, as improvements in LLM capabilities directly translate to better memory management.
 
 ## Search
 
-`search_memories` now supports three modes:
-- `hybrid` (default): keyword hits score `1`, then semantic matches add close variants such as `Benjamin Weeks` for `Ben Weeks`
+`search_memories` supports four matching signals — keyword, semantic, fuzzy and exact — through these modes:
+- `hybrid` (default): rank by the best signal — keyword share of query words, semantic cosine or fuzzy name similarity
 - `keyword`: any word of the query as a substring of any searchable content property (timestamps, `status` and embedding fields are never matched)
-- `semantic`: uses embeddings only when available, with graceful fallback to keyword behavior if embeddings are unavailable
+- `semantic`: embeddings only; if embeddings are unavailable it falls back to keyword matching (and `hybrid` keeps its keyword and fuzzy signals)
+- `fuzzy`: match misspelled or misheard names and aliases using spelling, prefixes and phonetics; "Ben Wicks" can find "Benjamin Weeks" without embeddings
 - `exact`: case-insensitive equality on `name`, `aliases` or `email`; the precise lookup to run before creating a memory, so "ben weeks" finds exactly "Ben Weeks" and nothing else
 
 Archived memories (`status = 'archived'`) are left out of results and of `list_memory_labels` unless `include_archived: true` is passed. Returned relationships carry `_start` and `_end` node ids, so a connection's direction is always recoverable.
 
-Use `similarity_threshold` (default `0.4`; must be between `0` and `1`, other values are rejected) to control how strict semantic matches are. Results include `_score` and `_match` on each returned `memory` object so callers can explain why a memory was returned.
+Use `similarity_threshold` (default `0.4`; must be between `0` and `1`, other values are rejected) to control how strict semantic matches are. Use `fuzzy_threshold` (default `0.85`, range `0`–`1`) for fuzzy strictness. Results include `_score`, `_match` and, for fuzzy hits, `_matched` (the stored name or alias). Confirm differing names with the user; nicknames such as Bill/William need `aliases`.
 
 ### Neo4j Enterprise Support
 
@@ -88,10 +91,10 @@ This server now supports connecting to specific databases in Neo4j Enterprise Ed
 ### Memory Tools
 
 - `search_memories`: Search and retrieve memories from the knowledge graph
-  - **Hybrid search**: Blend keyword and semantic search; `Ben Weeks` can also find `Benjamin Weeks`
-  - Choose `search_mode` = `hybrid`, `keyword`, or `semantic`
-  - Tune semantic strictness with `similarity_threshold` (default `0.4`)
-  - Returned memories include `_score` and `_match` metadata
+  - **Hybrid search**: Blend keyword, semantic and fuzzy name search; `Ben Wicks` can find `Benjamin Weeks`
+  - Choose `search_mode` = `hybrid`, `keyword`, `semantic`, `fuzzy` or `exact`
+  - Tune `similarity_threshold` (default `0.4`) and `fuzzy_threshold` (default `0.85`)
+  - Returned memories include `_score`, `_match` and `_matched` for fuzzy hits
   - Filter by memory type (case-insensitive, so `person` and `Person` both work), date, depth, result limit, and sort order
 
 - `create_memory`: Create a new memory in the knowledge graph
@@ -168,7 +171,7 @@ Reverie is listed in the [MCP Registry](https://registry.modelcontextprotocol.io
 ### Installing via Smithery
 
 
-To install Reverie for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@knowall-ai/mcp-neo4j-agent-memory):
+To install Reverie for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@knowall-ai/mcp-neo4j-agent-memory) (currently indexed under its legacy package name):
 
 ```bash
 npx -y @smithery/cli install @knowall-ai/mcp-neo4j-agent-memory --client claude
@@ -218,7 +221,7 @@ Set `REVERIE_EMBEDDINGS` to choose the embedding provider used by hybrid and sem
 
 Use `REVERIE_EMBEDDING_MODEL` to override the model name for any provider. Remote providers batch up to 64 texts per request, time out after `REVERIE_EMBED_TIMEOUT_MS` (default 30000, max 120000), and must be reached over https; plain http is only accepted for localhost.
 
-The `local` provider downloads its model (about 23 MB) from Hugging Face on first use and caches it. If that download fails, or any provider errors, search degrades to keyword matching for that call and the error is logged to stderr. Set `REVERIE_EMBEDDINGS=none` to turn embeddings off entirely.
+The `local` provider downloads its model (about 23 MB) from Hugging Face on first use and caches it. If that download fails, or any provider errors, semantic search falls back to keyword matching and hybrid retains keyword + fuzzy matching for that call and the error is logged to stderr. Set `REVERIE_EMBEDDINGS=none` to turn embeddings off entirely.
 
 Each node stores two vectors: `embedding` (label, name and every text property) and `name_embedding` (label, name and aliases only), plus `embedding_model` and `embedded_at`. A semantic score is the better of the two, so a short query like `Ben Weeks` still matches a richly described `Benjamin Weeks`. None of these fields are ever returned by the tools.
 
@@ -372,7 +375,7 @@ I found several people matching your search:
 The most likely match appears to be Ben Weeks, the Software Engineer.
 ```
 
-Note: The search finds ANY word from your query, allowing the LLM to present all potentially relevant results and identify the best match based on context.
+Keyword matching finds ANY word from your query and scores the fraction found. Hybrid search also considers semantic and fuzzy name matches, ranking each result by its best signal.
 
 #### Recent Memories (Last 7 Days)
 ```
@@ -506,6 +509,12 @@ CI runs the same suite against a Neo4j service container on every pull request a
 build if coverage drops below the gate. The first semantic search downloads the local embedding
 model (about 23 MB); CI caches it.
 
+A second CI check, `Version bumped with src/` (`scripts/check-version.mjs`), keeps the version
+honest: `server.json`'s `version` and each `packages[].version` must equal `package.json`'s, and a
+pull request that changes `src/` must raise `package.json`'s version above the base branch's
+(SemVer). To fix it, run `npm version patch --no-git-tag-version` and set the same version in both
+places in `server.json`.
+
 ### Interactive Testing with MCP Inspector
 
 For interactive testing and debugging, use the MCP Inspector:

package/build/fuzzy.js

@@ -0,0 +1,103 @@
+import { doubleMetaphone } from 'double-metaphone';
+/** Default cut-off for a fuzzy name match, calibrated so Wicks≈Weeks and Grimsby≈Grimshaw match but Jones≠James. */
+export const FUZZY_DEFAULT_THRESHOLD = 0.85;
+/** Phonetic codes by token; cleared when it reaches 50,000 entries. */
+const phoneticCache = new Map();
+/** Lower-case name tokens with diacritics stripped: "Zoë-Smith" → ["zoe", "smith"]. */
+export function nameTokens(value) {
+    return value.normalize('NFD').replace(/\p{M}/gu, '').toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+}
+/** Jaro-Winkler similarity (0..1), favouring strings that share a prefix; good for short names. */
+export function jaroWinkler(a, b) {
+    if (a === b)
+        return 1;
+    if (!a || !b)
+        return 0;
+    const window = Math.max(0, Math.floor(Math.max(a.length, b.length) / 2) - 1);
+    const aMatches = new Array(a.length).fill(false);
+    const bMatches = new Array(b.length).fill(false);
+    let matches = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        for (let j = Math.max(0, i - window); j < Math.min(b.length, i + window + 1); j += 1) {
+            if (!bMatches[j] && a[i] === b[j]) {
+                aMatches[i] = true;
+                bMatches[j] = true;
+                matches += 1;
+                break;
+            }
+        }
+    }
+    if (!matches)
+        return 0;
+    let differences = 0;
+    let j = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        if (!aMatches[i])
+            continue;
+        while (!bMatches[j])
+            j += 1;
+        if (a[i] !== b[j])
+            differences += 1;
+        j += 1;
+    }
+    const jaro = (matches / a.length + matches / b.length + (matches - differences / 2) / matches) / 3;
+    let prefix = 0;
+    while (prefix < Math.min(4, a.length, b.length) && a[prefix] === b[prefix])
+        prefix += 1;
+    return jaro > 0.7 ? jaro + prefix * 0.1 * (1 - jaro) : jaro;
+}
+/** Double Metaphone codes for a token (memoised); sound-alikes such as Wicks and Weeks share a code. */
+export function phoneticCodes(token) {
+    const cached = phoneticCache.get(token);
+    if (cached)
+        return cached;
+    const codes = [...new Set(doubleMetaphone(token))].filter((code) => code.length >= 2);
+    if (phoneticCache.size >= 50_000)
+        phoneticCache.clear();
+    phoneticCache.set(token, codes);
+    return codes;
+}
+/**
+ * Similarity of two normalised tokens: 1 when equal, at least 0.9 for a prefix (ben → benjamin) or shared phonetic
+ * code, otherwise Jaro-Winkler. Tokens under three characters only match exactly.
+ */
+export function tokenSimilarity(query, candidate) {
+    if (query === candidate)
+        return 1;
+    if (query.length < 3 || candidate.length < 3)
+        return 0;
+    const jw = jaroWinkler(query, candidate);
+    if (query.startsWith(candidate) || candidate.startsWith(query))
+        return Math.max(0.9, jw);
+    const candidateCodes = phoneticCodes(candidate);
+    if (phoneticCodes(query).some((code) => candidateCodes.includes(code)))
+        return Math.max(0.9, jw);
+    return jw;
+}
+/**
+ * Best fuzzy match of a query against name/alias values: the mean over query tokens of each token's best similarity
+ * (tokens below the threshold count as 0). Returns the score and matched value, or null below the threshold.
+ */
+export function fuzzyNameScore(query, values, threshold) {
+    const queryTokens = nameTokens(query);
+    if (!queryTokens.length)
+        return null;
+    let best = null;
+    for (const value of values) {
+        const tokens = nameTokens(value);
+        if (!tokens.length)
+            continue;
+        let total = 0;
+        for (const queryToken of queryTokens) {
+            let tokenScore = 0;
+            for (const token of tokens)
+                tokenScore = Math.max(tokenScore, tokenSimilarity(queryToken, token));
+            if (tokenScore >= threshold)
+                total += tokenScore;
+        }
+        const score = total / queryTokens.length;
+        if (score >= threshold && (!best || score > best.score))
+            best = { score, matched: value };
+    }
+    return best;
+}

package/build/handlers/index.js

@@ -1,6 +1,7 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import neo4j from 'neo4j-driver';
 import { embedNodes, scrub } from '../embeddings.js';
+import { FUZZY_DEFAULT_THRESHOLD } from '../fuzzy.js';
 import { readOnlyViolation } from '../cypher-guard.js';
 import { emit } from '../events.js';
 import { bloatHint, contentKeys, factLikeKeys, lazyEmbedBatch, maxProperties } from '../hygiene.js';
@@ -41,6 +42,7 @@ export async function handleToolCall(name, args, neo4jClient, embedder) {
                 const query = args.query ?? '';
                 const requestedMode = args.search_mode ?? 'hybrid';
                 const similarityThreshold = args.similarity_threshold ?? 0.4;
+                const fuzzyThreshold = args.fuzzy_threshold ?? FUZZY_DEFAULT_THRESHOLD;
                 let orderBy = 'memory.created_at DESC';
                 let hasCustomOrder = false;
                 if (args.order_by) {
@@ -67,8 +69,8 @@ export async function handleToolCall(name, args, neo4jClient, embedder) {
                 if (conditions.length > 0) {
                     baseQuery += ` WHERE ${conditions.join(' AND ')}`;
                 }
-                // Keyword mode never needs the stored vectors, so leave them out of the wire payload.
-                const propsProjection = requestedMode === 'keyword' || requestedMode === 'exact'
+                // Keyword, exact and fuzzy modes never need the stored vectors, so leave them out of the wire payload.
+                const propsProjection = requestedMode === 'keyword' || requestedMode === 'exact' || requestedMode === 'fuzzy'
                     ? 'memory {.*, embedding: null, name_embedding: null}'
                     : 'properties(memory)';
                 baseQuery += ` RETURN id(memory) AS id, labels(memory)[0] AS label, ${propsProjection} AS props ORDER BY id(memory)`;
@@ -78,7 +80,7 @@ export async function handleToolCall(name, args, neo4jClient, embedder) {
                     label: candidate.label || 'Memory',
                     props: candidate.props || {}
                 }));
-                const ranking = await rankCandidates(neo4jClient, candidates, query, requestedMode, similarityThreshold, embedder);
+                const ranking = await rankCandidates(neo4jClient, candidates, query, requestedMode, similarityThreshold, fuzzyThreshold, embedder);
                 const topRanked = ranking.slice(0, limit);
                 const rankedIds = topRanked.map((item) => item.id);
                 if (rankedIds.length === 0) {
@@ -86,7 +88,7 @@ export async function handleToolCall(name, args, neo4jClient, embedder) {
                     return jsonResult([]);
                 }
                 const result = await fetchMemories(neo4jClient, rankedIds, depth, orderBy, limit, Boolean(args.include_archived));
-                const scoring = new Map(topRanked.map((item) => [item.id, { score: Number(item.score.toFixed(2)), match: item.match }]));
+                const scoring = new Map(topRanked.map((item) => [item.id, { score: Number(item.score.toFixed(2)), match: item.match, matched: item.matched }]));
                 for (const row of result) {
                     const memoryId = row?.memory?._id;
                     if (typeof memoryId !== 'number') {
@@ -96,6 +98,8 @@ export async function handleToolCall(name, args, neo4jClient, embedder) {
                     if (meta) {
                         row.memory._score = meta.score;
                         row.memory._match = meta.match;
+                        if (meta.matched !== undefined)
+                            row.memory._matched = meta.matched;
                     }
                 }
                 const orderedResult = hasCustomOrder
@@ -454,13 +458,13 @@ export async function handleToolCall(name, args, neo4jClient, embedder) {
         };
     }
 }
-async function rankCandidates(neo4jClient, candidates, query, requestedMode, threshold, embedder) {
+async function rankCandidates(neo4jClient, candidates, query, requestedMode, threshold, fuzzyThreshold, embedder) {
     const trimmedQuery = query.trim();
     let effectiveMode = requestedMode;
     let queryEmbedding;
-    if (trimmedQuery && requestedMode !== 'keyword' && requestedMode !== 'exact') {
+    if (trimmedQuery && (requestedMode === 'hybrid' || requestedMode === 'semantic')) {
         if (!embedder) {
-            effectiveMode = 'keyword';
+            effectiveMode = requestedMode === 'semantic' ? 'keyword' : 'hybrid';
         }
         else {
             try {
@@ -477,7 +481,7 @@ async function rankCandidates(neo4jClient, candidates, query, requestedMode, thr
             }
             catch (error) {
                 console.error('Embedding unavailable for search_memories:', error);
-                effectiveMode = 'keyword';
+                effectiveMode = requestedMode === 'semantic' ? 'keyword' : 'hybrid';
                 queryEmbedding = undefined;
             }
         }
@@ -487,6 +491,7 @@ async function rankCandidates(neo4jClient, candidates, query, requestedMode, thr
         mode: effectiveMode,
         queryEmbedding,
         threshold,
+        fuzzyThreshold,
         modelId: embedder?.id
     });
 }

package/build/search.js

@@ -1,4 +1,5 @@
 import { cosine } from './embeddings.js';
+import { FUZZY_DEFAULT_THRESHOLD, fuzzyNameScore } from './fuzzy.js';
 import { contentKeys } from './hygiene.js';
 /** Case-insensitive equality on name, aliases or email: the lookup to run before creating a memory. */
 export function exactMatches(query, props) {
@@ -8,12 +9,18 @@ export function exactMatches(query, props) {
     const values = [props.name, props.email, ...(Array.isArray(props.aliases) ? props.aliases : [])];
     return values.some((v) => typeof v === 'string' && v.trim().toLowerCase() === wanted);
 }
+/** True when any query word is a substring of a content property; an empty query matches everything. */
 export function keywordMatches(query, props) {
+    return !query.trim() || keywordScore(query, props) > 0;
+}
+/** Share of query words (0..1) found as substrings of any content property; timestamps, status and vectors never match. */
+export function keywordScore(query, props) {
     const trimmedQuery = query.trim().toLowerCase();
     if (!trimmedQuery) {
-        return true;
+        return 0;
     }
     const words = trimmedQuery.split(/\s+/);
+    const found = new Set();
     // Only user content is searchable: timestamps, status and embedding fields never match.
     for (const key of contentKeys(props)) {
         const value = props[key];
@@ -23,12 +30,17 @@ export function keywordMatches(query, props) {
         const haystack = Array.isArray(value)
             ? value.map((item) => item?.toString() || '').join(' ').toLowerCase()
             : value.toString().toLowerCase();
-        if (words.some((word) => haystack.includes(word))) {
-            return true;
-        }
+        words.forEach((word, index) => {
+            if (haystack.includes(word))
+                found.add(index);
+        });
     }
-    return false;
+    return found.size / words.length;
 }
+/**
+ * Rank candidates for a query. `exact` keeps only equality hits; every other mode scores each candidate by its
+ * best allowed signal (exact in hybrid, keyword share, semantic cosine, fuzzy name similarity).
+ */
 export function rank(candidates, opts) {
     const trimmedQuery = opts.query.trim();
     if (!trimmedQuery) {
@@ -37,7 +49,6 @@ export function rank(candidates, opts) {
             .sort(compareRankedBy(candidates));
     }
     const results = [];
-    const seen = new Set();
     if (opts.mode === 'exact') {
         for (const candidate of candidates) {
             if (exactMatches(trimmedQuery, candidate.props)) {
@@ -46,33 +57,44 @@ export function rank(candidates, opts) {
         }
         return results.sort(compareRankedBy(candidates));
     }
-    if (opts.mode === 'hybrid' || opts.mode === 'keyword') {
-        for (const candidate of candidates) {
-            if (keywordMatches(trimmedQuery, candidate.props)) {
-                results.push({ id: candidate.id, score: 1, match: 'keyword' });
-                seen.add(candidate.id);
-            }
+    for (const candidate of candidates) {
+        // In hybrid, an exact name, alias or email hit is the strongest signal there is.
+        if (opts.mode === 'hybrid' && exactMatches(trimmedQuery, candidate.props)) {
+            results.push({ id: candidate.id, score: 1, match: 'exact' });
+            continue;
         }
-    }
-    if ((opts.mode === 'hybrid' || opts.mode === 'semantic') && opts.queryEmbedding && opts.modelId) {
-        for (const candidate of candidates) {
-            if (seen.has(candidate.id)) {
-                continue;
-            }
-            if (candidate.props.embedding_model !== opts.modelId) {
-                continue;
-            }
+        let best;
+        // Strictly greater comparisons preserve keyword > semantic > fuzzy on ties.
+        if (opts.mode === 'hybrid' || opts.mode === 'keyword') {
+            const score = keywordScore(trimmedQuery, candidate.props);
+            if (score > 0)
+                best = { id: candidate.id, score, match: 'keyword' };
+        }
+        if ((opts.mode === 'hybrid' || opts.mode === 'semantic') && opts.queryEmbedding && opts.modelId &&
+            candidate.props.embedding_model === opts.modelId) {
             const score = Math.max(similarity(opts.queryEmbedding, candidate.props.embedding), similarity(opts.queryEmbedding, candidate.props.name_embedding));
-            if (score >= opts.threshold) {
-                results.push({ id: candidate.id, score, match: 'semantic' });
+            if (score >= opts.threshold && (!best || score > best.score)) {
+                best = { id: candidate.id, score, match: 'semantic' };
             }
         }
+        if (opts.mode === 'hybrid' || opts.mode === 'fuzzy') {
+            const values = [candidate.props.name, ...(Array.isArray(candidate.props.aliases) ? candidate.props.aliases : [])]
+                .filter((value) => typeof value === 'string');
+            const fuzzy = fuzzyNameScore(trimmedQuery, values, opts.fuzzyThreshold ?? FUZZY_DEFAULT_THRESHOLD);
+            if (fuzzy && (!best || fuzzy.score > best.score)) {
+                best = { id: candidate.id, score: fuzzy.score, match: 'fuzzy', matched: fuzzy.matched };
+            }
+        }
+        if (best)
+            results.push(best);
     }
     return results.sort(compareRankedBy(candidates));
 }
 function similarity(query, vector) {
     return Array.isArray(vector) ? cosine(query, vector.map((item) => Number(item))) : 0;
 }
+/** On equal scores, the more precise signal ranks first. */
+const MATCH_PRIORITY = { exact: 0, keyword: 1, semantic: 2, fuzzy: 3 };
 function compareRankedBy(candidates) {
     const createdAt = new Map(candidates.map((candidate) => [
         candidate.id,
@@ -82,6 +104,9 @@ function compareRankedBy(candidates) {
         if (right.score !== left.score) {
             return right.score - left.score;
         }
+        if (left.match !== right.match) {
+            return MATCH_PRIORITY[left.match] - MATCH_PRIORITY[right.match];
+        }
         const leftCreatedAt = createdAt.get(left.id) ?? '';
         const rightCreatedAt = createdAt.get(right.id) ?? '';
         if (rightCreatedAt !== leftCreatedAt) {

package/build/server.js

@@ -5,6 +5,8 @@ import { createEmbedder } from './embeddings.js';
 import { handleToolCall } from './handlers/index.js';
 import { Neo4jClient } from './neo4j-client.js';
 import { tools } from './tools/definitions.js';
+import { VERSION } from './version.js';
+export { VERSION };
 /** A misconfigured provider (missing key, http endpoint…) must not stop the server; search degrades to keyword. */
 export function safeCreateEmbedder() {
     try {
@@ -15,7 +17,6 @@ export function safeCreateEmbedder() {
         return null;
     }
 }
-export const VERSION = '0.5.0';
 /** The MCP protocol server with Reverie's tools, bound to a (possibly absent) Neo4j client and embedder. */
 export function createMcpServer(neo4j, embedder) {
     const server = new Server({ name: 'reverie', version: VERSION }, { capabilities: { tools: {} } });

package/build/tools/definitions.js

@@ -8,7 +8,7 @@ import { guidanceTool } from './guidance-tool.js';
 export const tools = [
     {
         name: 'search_memories',
-        description: 'Hybrid keyword + semantic search across the knowledge graph. "Ben Weeks" can also find "Benjamin Weeks" and each result includes _score and _match.',
+        description: 'Hybrid keyword + semantic + fuzzy name search across the knowledge graph. "Ben Wicks" can find "Benjamin Weeks". Each result\'s memory carries _score (0-1: exact = 1, keyword = share of query words found, semantic = cosine similarity, fuzzy = name similarity), _match (exact | keyword | semantic | fuzzy) and, for fuzzy hits, _matched (the stored name or alias that matched: "did you mean <_matched>?"). A semantic-only hit below about 0.5 is weak and often unrelated.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -42,8 +42,15 @@ export const tools = [
                 },
                 search_mode: {
                     type: 'string',
-                    enum: ['hybrid', 'keyword', 'semantic', 'exact'],
-                    description: 'Search mode: hybrid (default), keyword-only, semantic-only, or exact (case-insensitive equality on name/aliases/email: use before creating a memory).',
+                    enum: ['hybrid', 'keyword', 'semantic', 'exact', 'fuzzy'],
+                    description: 'Search mode: hybrid (default), keyword-only, semantic-only, fuzzy name matching, or exact (case-insensitive equality on name/aliases/email: use before creating a memory).',
+                },
+                fuzzy_threshold: {
+                    type: 'number',
+                    minimum: 0,
+                    maximum: 1,
+                    default: 0.85,
+                    description: 'Fuzzy name-match cut-off for misspelled or misheard names',
                 },
                 similarity_threshold: {
                     type: 'number',

package/build/tools/guidance-tool.js

@@ -149,12 +149,17 @@ Use UPPERCASE for relationship types:
 
 **Searching**
 - Empty query string returns all memories
-- Use search_mode: "hybrid" (the default) to return keyword matches first, then semantic matches above the threshold
+- Use search_mode: "hybrid" (the default) to rank every result by its best signal: keyword share of query words, semantic cosine, or fuzzy name similarity
 - Use search_mode: "keyword" to match any word of the query as a substring of any searchable content property (not timestamps, status or embedding fields), or search_mode: "semantic" for meaning-first recall
+- Use search_mode: "fuzzy" for name lookups when spelling may be wrong (for example speech-to-text: "Ben Wicks" can find "Benjamin Weeks")
+- Tune fuzzy_threshold (default 0.85, range 0..1) for misspelled or misheard names
+- When _match is fuzzy and the name differs, confirm with the user ("Did you mean Grimshaw?") rather than silently swapping
+- First-name nicknames that do not sound alike (Bill/William) need aliases; store full-name aliases such as "Bill Weeks" for full-name queries
 - Use search_mode: "exact" before creating: it matches only a memory whose name, alias or email equals the query, case-insensitively
 - Archived memories are excluded unless include_archived: true
 - Lower similarity_threshold (for example 0.35) to widen semantic matches, or raise it (for example 0.7) to be stricter
-- Results include _score and _match so you can explain why something was returned
+- Each result's memory carries _score (0..1) and _match (exact | keyword | semantic | fuzzy), plus _matched (the stored name or alias) for fuzzy hits, so you can explain why something was returned
+- Reading _score: exact is 1; keyword is the share of query words found; semantic is the cosine similarity; fuzzy is the name similarity (at least fuzzy_threshold). A semantic-only hit below about 0.5 is weak and often unrelated, so do not present it as a match
 - Use label parameter to filter by type
 - Increase depth to include more relationships (depth=2 or 3 for rich context)
 - Default limit is 10, max is 200

package/build/types.js

@@ -28,7 +28,7 @@ export function isCreateMemoryArgs(args) {
         isIdentifier(args.label) &&
         isPlainObject(args.properties);
 }
-const SEARCH_KEYS = ['query', 'label', 'depth', 'order_by', 'limit', 'since_date', 'search_mode', 'similarity_threshold', 'include_archived'];
+const SEARCH_KEYS = ['query', 'label', 'depth', 'order_by', 'limit', 'since_date', 'search_mode', 'similarity_threshold', 'fuzzy_threshold', 'include_archived'];
 export function isSearchMemoriesArgs(args) {
     if (!isPlainObject(args) || !hasOnlyKeys(args, SEARCH_KEYS))
         return false;
@@ -45,7 +45,7 @@ export function isSearchMemoriesArgs(args) {
         return false;
     if (searchArgs.since_date !== undefined && typeof searchArgs.since_date !== 'string')
         return false;
-    if (searchArgs.search_mode !== undefined && !['hybrid', 'keyword', 'semantic', 'exact'].includes(searchArgs.search_mode))
+    if (searchArgs.search_mode !== undefined && !['hybrid', 'keyword', 'semantic', 'exact', 'fuzzy'].includes(searchArgs.search_mode))
         return false;
     if (searchArgs.include_archived !== undefined && typeof searchArgs.include_archived !== 'boolean')
         return false;
@@ -54,6 +54,11 @@ export function isSearchMemoriesArgs(args) {
         if (typeof threshold !== 'number' || !Number.isFinite(threshold) || threshold < 0 || threshold > 1)
             return false;
     }
+    if (searchArgs.fuzzy_threshold !== undefined) {
+        const threshold = searchArgs.fuzzy_threshold;
+        if (typeof threshold !== 'number' || !Number.isFinite(threshold) || threshold < 0 || threshold > 1)
+            return false;
+    }
     return true;
 }
 export function isCreateConnectionArgs(args) {

package/build/version.js

@@ -0,0 +1,17 @@
+import { createRequire } from 'node:module';
+/**
+ * The package version, read from package.json at run time (build/version.js → ../package.json), so the
+ * serverInfo a client sees can never drift from the release again: until 0.5.4 it was hard-coded as 0.5.0.
+ * npm always ships package.json and the Docker image copies it; anything else reports "unknown" rather
+ * than a wrong number.
+ */
+export function readVersion() {
+    try {
+        const pkg = createRequire(import.meta.url)('../package.json');
+        return typeof pkg.version === 'string' && pkg.version ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export const VERSION = readVersion();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowall-ai/reverie",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Reverie — graph memory that dreams. Graph-based memory system for AI agents. Store people, places, organizations as nodes. Build semantic relationships (KNOWS, WORKS_AT, CREATED). Hybrid keyword + semantic search finds partial matches and close variants. Filter by date, traverse relationships, maintain temporal context. Simple tools, LLM handles complexity. 12 tools for complete memory management.",
   "mcpName": "ai.knowall/reverie",
   "type": "module",
@@ -27,6 +27,7 @@
     "@huggingface/transformers": "^3.8.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "dotenv": "^17.2.0",
+    "double-metaphone": "^2.0.1",
     "neo4j-driver": "^5.27.0",
     "uuid": "^11.0.4",
     "zod": "^3.25.76"