@j0hanz/memory-mcp 1.5.0 → 1.7.0

package/dist/tools/progress.d.ts

@@ -26,9 +26,15 @@ interface WrappedHandlerOptions<TArgs> {
     completionMessage?: (args: TArgs, result: CallToolResult) => string;
     progressMessage: (args: TArgs) => string;
 }
+interface CompletionRunOptions {
+    reporter: Pick<ProgressReporter, 'flush'>;
+    completionCurrent: number | (() => number);
+    completionMessage: (result: CallToolResult) => string;
+}
 type ToolHandler<TArgs> = (args: TArgs, extra: ProgressContext) => Promise<CallToolResult> | CallToolResult;
 export declare function notifyProgress(extra: ProgressContext, progress: ProgressUpdate): Promise<void>;
 export declare function createProgressReporter(extra: ProgressContext, options?: ProgressReporterOptions): ProgressReporter;
 export declare function progressWithMessage(reporter: ProgressReporter, getMessage: (progress: ProgressSnapshot) => string): ProgressReporter<ProgressSnapshot>;
 export declare function wrapToolHandler<TArgs>(handler: ToolHandler<TArgs>, options: WrappedHandlerOptions<TArgs>): ToolHandler<TArgs>;
+export declare function runWithProgressCompletion(extra: ProgressContext, run: () => CallToolResult | Promise<CallToolResult>, options: CompletionRunOptions): Promise<CallToolResult>;
 export {};

package/dist/tools/progress.js

@@ -1,6 +1,15 @@
-import { E_CANCELLED } from '../lib/errors.js';
+import { McpError } from '@modelcontextprotocol/sdk/types.js';
+import { CancelledError, E_CANCELLED, E_UNKNOWN, getErrorMessage, rethrowMcpError, } from '../lib/errors.js';
+import { createErrorResponse } from '../lib/tool-response.js';
 import { getToolResultText } from './result.js';
+function resolveCompletionCurrent(value) {
+    return typeof value === 'function' ? value() : value;
+}
 const DEFAULT_PROGRESS_INTERVAL_MS = 250;
+const TOOL_HANDLER_PROGRESS_TOTAL = 1;
+function hasProgressTransport(extra, progressToken) {
+    return (progressToken !== undefined && typeof extra.sendNotification === 'function');
+}
 function toProgressToken(value) {
     if (typeof value === 'string' || typeof value === 'number') {
         return value;
@@ -20,6 +29,19 @@ function toNotificationParams(progressToken, progress) {
     }
     return params;
 }
+function toProgressNotification(progressToken, progress) {
+    return {
+        method: 'notifications/progress',
+        params: toNotificationParams(progressToken, progress),
+    };
+}
+function toProgressPayload(progress, current) {
+    return {
+        current,
+        ...(progress.total !== undefined ? { total: progress.total } : {}),
+        ...(progress.message !== undefined ? { message: progress.message } : {}),
+    };
+}
 function getResultOutcome(result) {
     if (result.isError) {
         const text = getToolResultText(result);
@@ -41,14 +63,11 @@ export async function notifyProgress(extra, progress) {
     if (progressToken === undefined) {
         return;
     }
-    if (typeof extra.sendNotification !== 'function') {
+    if (!hasProgressTransport(extra, progressToken)) {
         return;
     }
     try {
-        await extra.sendNotification({
-            method: 'notifications/progress',
-            params: toNotificationParams(progressToken, progress),
-        });
+        await extra.sendNotification(toProgressNotification(progressToken, progress));
     }
     catch {
         // best-effort progress
@@ -75,13 +94,7 @@ export function createProgressReporter(extra, options = {}) {
         lastReportedAt = now;
         isCompleted =
             progress.total !== undefined && monotonicCurrent >= progress.total;
-        const payload = { current: monotonicCurrent };
-        if (progress.total !== undefined) {
-            payload.total = progress.total;
-        }
-        if (progress.message !== undefined) {
-            payload.message = progress.message;
-        }
+        const payload = toProgressPayload(progress, monotonicCurrent);
         notificationChain = notificationChain.then(() => notifyProgress(extra, payload));
     });
     reporter.flush = async () => {
@@ -102,11 +115,18 @@ export function progressWithMessage(reporter, getMessage) {
     return wrapped;
 }
 export function wrapToolHandler(handler, options) {
+    const notifyTerminalProgress = async (extra, startMessage, outcome, completionMessage) => {
+        await notifyProgress(extra, {
+            current: TOOL_HANDLER_PROGRESS_TOTAL,
+            total: TOOL_HANDLER_PROGRESS_TOTAL,
+            message: completionMessage ?? `${startMessage} • ${outcome}`,
+        });
+    };
     return async (args, extra) => {
         const startMessage = options.progressMessage(args);
         await notifyProgress(extra, {
             current: 0,
-            total: 1,
+            total: TOOL_HANDLER_PROGRESS_TOTAL,
             message: startMessage,
         });
         let result;
@@ -114,21 +134,44 @@ export function wrapToolHandler(handler, options) {
             result = await handler(args, extra);
         }
         catch (error) {
-            const isCancelled = error instanceof Error && error.message === E_CANCELLED;
-            await notifyProgress(extra, {
-                current: 1,
-                total: 1,
-                message: `${startMessage} • ${isCancelled ? 'cancelled' : 'failed'}`,
-            });
+            const isCancelled = error instanceof CancelledError;
+            await notifyTerminalProgress(extra, startMessage, isCancelled ? 'cancelled' : 'failed');
             throw error;
         }
         const completionMessage = options.completionMessage?.(args, result) ??
             defaultCompletionMessage(startMessage, result);
-        await notifyProgress(extra, {
-            current: 1,
-            total: 1,
-            message: completionMessage,
-        });
+        await notifyTerminalProgress(extra, startMessage, 'completed', completionMessage);
         return result;
     };
 }
+export async function runWithProgressCompletion(extra, run, options) {
+    let result;
+    let thrownError;
+    try {
+        result = await run();
+    }
+    catch (error) {
+        if (error instanceof CancelledError) {
+            result = createErrorResponse(E_CANCELLED, 'Request cancelled');
+        }
+        else if (error instanceof McpError) {
+            thrownError = error;
+        }
+        else {
+            rethrowMcpError(error);
+            result = createErrorResponse(E_UNKNOWN, getErrorMessage(error));
+        }
+    }
+    await options.reporter.flush();
+    const completionResult = result ?? createErrorResponse(E_UNKNOWN, getErrorMessage(thrownError));
+    const completionCurrent = resolveCompletionCurrent(options.completionCurrent);
+    await notifyProgress(extra, {
+        current: completionCurrent,
+        total: completionCurrent,
+        message: options.completionMessage(completionResult),
+    });
+    if (thrownError) {
+        throw thrownError;
+    }
+    return completionResult;
+}

package/dist/tools/recall.js

@@ -1,121 +1,16 @@
-import { McpError, } from '@modelcontextprotocol/sdk/types.js';
-import process from 'node:process';
-import { E_CANCELLED, E_UNKNOWN, getErrorMessage, rethrowMcpError, } from '../lib/errors.js';
+import { throwIfAborted } from '../lib/errors.js';
+import { traverseGraph, } from '../lib/graph-traversal.js';
 import { logToolEvent } from '../lib/mcp-utils.js';
 import { splitPage } from '../lib/pagination.js';
 import { buildSearchCursorScope, decodeSearchCursor, encodeSearchCursor, } from '../lib/search-cursor.js';
 import { loadRankedSearchRows, toMemoryFilters } from '../lib/search.js';
-import { createErrorResponse, createToolResponse, } from '../lib/tool-response.js';
+import { createToolResponse } from '../lib/tool-response.js';
 import { parseMemoryRow } from '../lib/types.js';
-import { RecallInputSchema } from '../schemas/inputs.js';
-import { RecallResultSchema } from '../schemas/outputs.js';
-import { createProgressReporter, notifyProgress, progressWithMessage, } from './progress.js';
+import {} from '../schemas/inputs.js';
+import { createProgressReporter, notifyProgress, progressWithMessage, runWithProgressCompletion, } from './progress.js';
 import { registerToolWithContract } from './register-contract.js';
-import { countPayloadArrayItems, getToolResultPayload, getToolResultText, isOkStructuredToolResult, } from './result.js';
-function throwIfAborted(signal) {
-    if (!signal?.aborted) {
-        return;
-    }
-    throw new Error(E_CANCELLED);
-}
-function yieldToEventLoop() {
-    return new Promise((resolve) => setImmediate(resolve));
-}
-function parseEnvInt(name, fallback, min, max) {
-    const raw = process.env[name];
-    if (raw == null)
-        return fallback;
-    const parsed = parseInt(raw, 10);
-    if (Number.isNaN(parsed))
-        return fallback;
-    return Math.max(min, Math.min(max, parsed));
-}
-const MAX_FRONTIER_SIZE = parseEnvInt('RECALL_MAX_FRONTIER_SIZE', 1000, 100, 50000);
-const MAX_EDGE_ROWS = parseEnvInt('RECALL_MAX_EDGE_ROWS', 5000, 100, 50000);
-const MAX_VISITED_NODES = parseEnvInt('RECALL_MAX_VISITED_NODES', 5000, 100, 50000);
-const EDGE_QUERY_SQL = `SELECT from_hash, to_hash, relation_type FROM relationships
-         WHERE from_hash IN (SELECT value FROM json_each(?))
-            OR to_hash   IN (SELECT value FROM json_each(?))
-         LIMIT ?`;
+import { countPayloadArrayItems, formatToolCompletionMessage, } from './result.js';
 const MEMORIES_BY_HASH_SQL = 'SELECT * FROM memories WHERE hash IN (SELECT value FROM json_each(?))';
-async function traverseGraph(db, seeds, depth, signal, onHop) {
-    const visited = new Set();
-    const frontier = [];
-    for (const seed of seeds) {
-        visited.add(seed.hash);
-        frontier.push(seed.hash);
-    }
-    const edges = [];
-    const seenEdges = new Set();
-    let depthReached = 0;
-    let aborted = false;
-    const edgeStmt = db.prepareOnce(EDGE_QUERY_SQL);
-    for (let hop = 0; hop < depth && frontier.length > 0; hop += 1) {
-        // Yield to event loop to allow progress notifications and cancellation
-        await yieldToEventLoop();
-        throwIfAborted(signal);
-        depthReached = hop + 1;
-        onHop?.(hop, depth);
-        if (frontier.length > MAX_FRONTIER_SIZE) {
-            frontier.length = MAX_FRONTIER_SIZE;
-            aborted = true;
-        }
-        const remainingEdgeBudget = MAX_EDGE_ROWS - edges.length;
-        const remainingNodeBudget = MAX_VISITED_NODES - visited.size;
-        if (remainingEdgeBudget <= 0 || remainingNodeBudget <= 0) {
-            aborted = true;
-            break;
-        }
-        const frontierJson = JSON.stringify(frontier);
-        const edgeRows = edgeStmt.all(frontierJson, frontierJson, remainingEdgeBudget + 1);
-        const rowsToProcess = edgeRows.length > remainingEdgeBudget
-            ? remainingEdgeBudget
-            : edgeRows.length;
-        if (edgeRows.length > remainingEdgeBudget) {
-            aborted = true;
-        }
-        const nextHashes = [];
-        const queueVisitedHash = (hash) => {
-            if (visited.has(hash)) {
-                return;
-            }
-            if (visited.size >= MAX_VISITED_NODES) {
-                aborted = true;
-                return;
-            }
-            visited.add(hash);
-            if (nextHashes.length < MAX_FRONTIER_SIZE) {
-                nextHashes.push(hash);
-                return;
-            }
-            aborted = true;
-        };
-        for (let i = 0; i < rowsToProcess; i += 1) {
-            const edge = edgeRows[i];
-            if (edge === undefined) {
-                break;
-            }
-            const edgeKey = `${edge.from_hash}|${edge.to_hash}|${edge.relation_type}`;
-            if (!seenEdges.has(edgeKey)) {
-                seenEdges.add(edgeKey);
-                edges.push({
-                    from_hash: edge.from_hash,
-                    to_hash: edge.to_hash,
-                    relation_type: edge.relation_type,
-                });
-            }
-            queueVisitedHash(edge.from_hash);
-            queueVisitedHash(edge.to_hash);
-            if (aborted &&
-                (edges.length >= MAX_EDGE_ROWS || visited.size >= MAX_VISITED_NODES)) {
-                break;
-            }
-        }
-        frontier.length = 0;
-        frontier.push(...nextHashes);
-    }
-    return { edges, visited, depthReached, aborted };
-}
 function loadMemoriesByHashes(db, hashes) {
     if (hashes.length === 0) {
         return [];
@@ -125,29 +20,87 @@ function loadMemoriesByHashes(db, hashes) {
         .all(JSON.stringify(hashes));
 }
 function formatRecallCompletionMessage(query, result) {
-    const failedMessage = `⊙ recall: ${query} • failed`;
-    if (result.isError) {
-        const text = getToolResultText(result);
-        if (text.includes(E_CANCELLED)) {
-            return `⊙ recall: ${query} • cancelled`;
+    return formatToolCompletionMessage('recall', query, result, (payload) => {
+        const memoriesCount = countPayloadArrayItems(payload, 'memories');
+        const edgesCount = countPayloadArrayItems(payload, 'graph');
+        const aborted = 'aborted' in payload && payload.aborted === true;
+        return `${memoriesCount} memories, ${edgesCount} edges${aborted ? ' [aborted]' : ''}`;
+    });
+}
+function decodeCursorForRecall(cursor, scope) {
+    if (!cursor) {
+        return undefined;
+    }
+    return decodeSearchCursor(cursor, scope);
+}
+function buildSeedRelevanceMap(seeds) {
+    const seedRelevance = new Map();
+    for (const seed of seeds) {
+        if (seed.rank != null) {
+            seedRelevance.set(seed.hash, -seed.rank);
         }
-        return failedMessage;
     }
-    if (!isOkStructuredToolResult(result)) {
-        return failedMessage;
+    return seedRelevance;
+}
+function toMemoriesWithRelevance(rows, seedRelevance) {
+    return rows.map((row) => {
+        const memory = parseMemoryRow(row);
+        const relevance = seedRelevance.get(memory.hash);
+        if (relevance != null) {
+            memory.relevance = relevance;
+        }
+        return memory;
+    });
+}
+function buildNextCursor(hasMore, pageSeeds, scope) {
+    if (!hasMore || pageSeeds.length === 0) {
+        return undefined;
     }
-    const payload = getToolResultPayload(result);
-    if (!payload) {
-        return `⊙ recall: ${query} • completed`;
+    const lastSeed = pageSeeds[pageSeeds.length - 1];
+    if (!lastSeed) {
+        return undefined;
     }
-    const memoriesCount = countPayloadArrayItems(payload, 'memories');
-    const edgesCount = countPayloadArrayItems(payload, 'graph');
-    const aborted = 'aborted' in payload && payload.aborted === true;
-    return `⊙ recall: ${query} • ${memoriesCount} memories, ${edgesCount} edges${aborted ? ' [aborted]' : ''}`;
+    const rank = lastSeed.rank ?? 0;
+    return encodeSearchCursor(scope, rank, lastSeed.hash);
+}
+function createHopReporter(extra, query, completionCurrent) {
+    const reporter = progressWithMessage(createProgressReporter(extra), ({ current, total }) => `⊙ recall: ${query} [hop ${current}/${Math.max((total ?? current) - 1, current)}]`);
+    const onHop = (hop) => {
+        reporter({ current: hop + 1, total: completionCurrent });
+    };
+    return { reporter, onHop };
+}
+function toRecallResponse(computation) {
+    return createToolResponse({
+        memories: computation.memories,
+        graph: computation.edges,
+        depth_reached: computation.depthReached,
+        ...(computation.aborted ? { aborted: true } : {}),
+        ...(computation.nextCursor ? { nextCursor: computation.nextCursor } : {}),
+    });
+}
+async function computeRecall(db, params, scope, signal, onHop) {
+    const decodedCursor = decodeCursorForRecall(params.cursor, scope);
+    const seedRows = loadRankedSearchRows(db, params.query, params.limit, decodedCursor, toMemoryFilters(params));
+    const { page: pageSeeds, hasMore } = splitPage(seedRows, params.limit);
+    const traversal = await traverseGraph(db, pageSeeds, params.depth, signal, onHop);
+    const allHashes = Array.from(traversal.visited);
+    const seedRelevance = buildSeedRelevanceMap(pageSeeds);
+    const memoryRows = loadMemoriesByHashes(db, allHashes);
+    const nextCursor = buildNextCursor(hasMore, pageSeeds, scope);
+    return {
+        memories: toMemoriesWithRelevance(memoryRows, seedRelevance),
+        edges: traversal.edges,
+        depthReached: traversal.depthReached,
+        aborted: traversal.aborted,
+        ...(nextCursor ? { nextCursor } : {}),
+        seedCount: pageSeeds.length,
+        visitedCount: traversal.visited.size,
+    };
 }
 export function registerRecall(server, db) {
-    registerToolWithContract(server, 'recall', RecallInputSchema, RecallResultSchema, async (params, extra) => {
-        const { depth, limit, cursor } = params;
+    registerToolWithContract(server, 'recall', async (params, extra) => {
+        const { depth } = params;
         const filters = toMemoryFilters(params);
         const scope = buildSearchCursorScope(params.query, filters);
         const contextLabel = `⊙ recall: ${params.query} [depth ${depth}]`;
@@ -157,86 +110,24 @@ export function registerRecall(server, db) {
             total: completionCurrent,
             message: contextLabel,
         });
-        const hopReporter = progressWithMessage(createProgressReporter(extra), ({ current, total }) => `⊙ recall: ${params.query} [hop ${current}/${Math.max((total ?? current) - 1, current)}]`);
-        const onHop = (hop) => {
-            hopReporter({ current: hop + 1, total: completionCurrent });
-        };
-        let result;
-        let thrownError;
-        try {
+        const { reporter: hopReporter, onHop } = createHopReporter(extra, params.query, completionCurrent);
+        return runWithProgressCompletion(extra, async () => {
             throwIfAborted(extra.signal);
-            const decodedCursor = cursor
-                ? decodeSearchCursor(cursor, scope)
-                : undefined;
-            // Step 1: FTS seed search
-            const seedRows = loadRankedSearchRows(db, params.query, limit, decodedCursor, filters);
+            const computation = await computeRecall(db, params, scope, extra.signal, onHop);
             throwIfAborted(extra.signal);
-            const { page: pageSeeds, hasMore } = splitPage(seedRows, limit);
-            // Step 2: BFS traversal up to `depth` hops
-            const traversal = await traverseGraph(db, pageSeeds, depth, extra.signal, onHop);
-            throwIfAborted(extra.signal);
-            // Step 3: Load all discovered memory rows
-            const allHashes = Array.from(traversal.visited);
-            const seedRelevance = new Map();
-            for (const seed of pageSeeds) {
-                if (seed.rank != null)
-                    seedRelevance.set(seed.hash, -seed.rank);
-            }
-            const memoryRows = loadMemoriesByHashes(db, allHashes);
-            const memories = memoryRows.map((row) => {
-                const memory = parseMemoryRow(row);
-                const rel = seedRelevance.get(memory.hash);
-                if (rel != null) {
-                    memory.relevance = rel;
-                }
-                return memory;
-            });
-            let nextCursor;
-            if (hasMore && pageSeeds.length > 0) {
-                const lastSeed = pageSeeds[pageSeeds.length - 1];
-                if (lastSeed !== undefined) {
-                    const rank = lastSeed.rank ?? 0;
-                    nextCursor = encodeSearchCursor(scope, rank, lastSeed.hash);
-                }
-            }
             await logToolEvent(server, 'recall', {
                 depth,
-                depth_reached: traversal.depthReached,
-                seed_count: pageSeeds.length,
-                visited_nodes: traversal.visited.size,
-                edge_count: traversal.edges.length,
-                aborted: traversal.aborted,
+                depth_reached: computation.depthReached,
+                seed_count: computation.seedCount,
+                visited_nodes: computation.visitedCount,
+                edge_count: computation.edges.length,
+                aborted: computation.aborted,
             });
-            result = createToolResponse({
-                memories,
-                graph: traversal.edges,
-                depth_reached: traversal.depthReached,
-                ...(traversal.aborted ? { aborted: true } : {}),
-                ...(nextCursor ? { nextCursor } : {}),
-            });
-        }
-        catch (err) {
-            if (err instanceof Error && err.message === E_CANCELLED) {
-                result = createErrorResponse(E_CANCELLED, 'Request cancelled');
-            }
-            else if (err instanceof McpError) {
-                thrownError = err;
-            }
-            else {
-                rethrowMcpError(err);
-                result = createErrorResponse(E_UNKNOWN, getErrorMessage(err));
-            }
-        }
-        await hopReporter.flush();
-        const completionResult = result ?? createErrorResponse(E_UNKNOWN, getErrorMessage(thrownError));
-        await notifyProgress(extra, {
-            current: completionCurrent,
-            total: completionCurrent,
-            message: formatRecallCompletionMessage(params.query, completionResult),
+            return toRecallResponse(computation);
+        }, {
+            reporter: hopReporter,
+            completionCurrent,
+            completionMessage: (result) => formatRecallCompletionMessage(params.query, result),
         });
-        if (thrownError) {
-            throw thrownError;
-        }
-        return completionResult;
     });
 }

package/dist/tools/register-contract.d.ts

@@ -1,3 +1,2 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { z } from 'zod/v4';
-export declare function registerToolWithContract(server: McpServer, toolName: string, _inputSchema: z.ZodType, _outputSchema: z.ZodType, handler: unknown): void;
+export declare function registerToolWithContract(server: McpServer, toolName: string, handler: unknown): void;

package/dist/tools/register-contract.js

@@ -1,5 +1,5 @@
 import { getToolContract } from '../lib/tool-contracts.js';
-export function registerToolWithContract(server, toolName, _inputSchema, _outputSchema, handler) {
+export function registerToolWithContract(server, toolName, handler) {
     const contract = getToolContract(toolName);
     server.registerTool(contract.name, {
         title: contract.title,
@@ -7,5 +7,7 @@ export function registerToolWithContract(server, toolName, _inputSchema, _output
         inputSchema: contract.inputSchema,
         outputSchema: contract.outputSchema,
         annotations: contract.annotations,
-    }, handler);
+    }, 
+    // The handler is validated at runtime and tested via contract verification
+    handler);
 }

package/dist/tools/result.d.ts

@@ -5,3 +5,7 @@ export declare function getToolResultPayload(result: CallToolResult): ToolResult
 export declare function getToolResultText(result: CallToolResult): string;
 /** Count items in a named array field of a tool result payload. */
 export declare function countPayloadArrayItems(payload: Record<string, unknown>, key: string): number;
+/** Standardize format of tool completion messages. */
+export declare function formatToolCompletionMessage(toolName: string, query: string, result: CallToolResult, getSuccessMessage: (payload: ToolResultPayload) => string): string;
+export declare function formatHashPreview(hash: string, length?: number): string;
+export declare function formatRelationshipPreview(fromHash: string, toHash: string, length?: number): string;

package/dist/tools/result.js

@@ -1,3 +1,4 @@
+import { E_CANCELLED } from '../lib/errors.js';
 function isRecord(value) {
     return typeof value === 'object' && value !== null;
 }
@@ -20,3 +21,29 @@ export function countPayloadArrayItems(payload, key) {
     const value = payload[key];
     return Array.isArray(value) ? value.length : 0;
 }
+/** Standardize format of tool completion messages. */
+export function formatToolCompletionMessage(toolName, query, result, getSuccessMessage) {
+    const failedMessage = `⊙ ${toolName}: ${query} • failed`;
+    if (result.isError) {
+        const text = getToolResultText(result);
+        if (text.includes(E_CANCELLED)) {
+            return `⊙ ${toolName}: ${query} • cancelled`;
+        }
+        return failedMessage;
+    }
+    if (!isOkStructuredToolResult(result)) {
+        return failedMessage;
+    }
+    const payload = getToolResultPayload(result);
+    if (!payload) {
+        return `⊙ ${toolName}: ${query} • completed`;
+    }
+    const successSuffix = getSuccessMessage(payload);
+    return `⊙ ${toolName}: ${query} • ${successSuffix}`;
+}
+export function formatHashPreview(hash, length = 12) {
+    return `${hash.slice(0, length)}...`;
+}
+export function formatRelationshipPreview(fromHash, toHash, length = 8) {
+    return `${formatHashPreview(fromHash, length)} -> ${formatHashPreview(toHash, length)}`;
+}