@j0hanz/memory-mcp 1.5.0 → 1.7.0

package/dist/lib/tool-execution.js

@@ -0,0 +1,51 @@
+import { McpError } from '@modelcontextprotocol/sdk/types.js';
+import { CancelledError, E_CANCELLED, E_UNKNOWN, getErrorMessage, rethrowMcpError, } from './errors.js';
+import { createErrorResponse } from './tool-response.js';
+export async function executeToolSafely(work) {
+    try {
+        return await work();
+    }
+    catch (err) {
+        rethrowMcpError(err);
+        return createErrorResponse(E_UNKNOWN, getErrorMessage(err));
+    }
+}
+export function summarizeBatch(items, isMatched) {
+    let succeeded = 0;
+    let matched = 0;
+    for (const item of items) {
+        if (item.ok) {
+            succeeded += 1;
+        }
+        if (isMatched(item)) {
+            matched += 1;
+        }
+    }
+    return {
+        succeeded,
+        failed: items.length - succeeded,
+        matched,
+    };
+}
+export async function executeLongRunningToolSafely(work, onFinally) {
+    let result;
+    let thrownError;
+    try {
+        result = await work();
+    }
+    catch (err) {
+        if (err instanceof CancelledError) {
+            result = createErrorResponse(E_CANCELLED, 'Request cancelled');
+        }
+        else if (err instanceof McpError) {
+            thrownError = err;
+        }
+        else {
+            result = createErrorResponse(E_UNKNOWN, getErrorMessage(err));
+        }
+    }
+    if (onFinally) {
+        await onFinally();
+    }
+    return result ?? createErrorResponse(E_UNKNOWN, getErrorMessage(thrownError));
+}

package/dist/prompts/index.js

@@ -1,5 +1,10 @@
 import { loadInstructions } from '../lib/instructions.js';
 const INSTRUCTIONS_CONTENT = loadInstructions();
+const GET_HELP_PROMPT = {
+    name: 'get-help',
+    title: 'Get Help',
+    description: 'Return full usage instructions.',
+};
 function createHelpMessages(instructions) {
     return [
         {
@@ -19,13 +24,12 @@ function createHelpMessages(instructions) {
     ];
 }
 const HELP_MESSAGES = createHelpMessages(INSTRUCTIONS_CONTENT);
-const GET_HELP_PROMPT_NAME = 'get-help';
-const GET_HELP_PROMPT_CONFIG = {
-    title: 'Get Help',
-    description: 'Return full usage instructions.',
-};
+function createGetHelpPromptResult() {
+    return { messages: HELP_MESSAGES };
+}
 export function registerAllPrompts(server) {
-    server.registerPrompt(GET_HELP_PROMPT_NAME, GET_HELP_PROMPT_CONFIG, () => ({
-        messages: HELP_MESSAGES,
-    }));
+    server.registerPrompt(GET_HELP_PROMPT.name, {
+        title: GET_HELP_PROMPT.title,
+        description: GET_HELP_PROMPT.description,
+    }, createGetHelpPromptResult);
 }

package/dist/resources/index.js

@@ -44,6 +44,13 @@ function createResourceAnnotations(audience, priority) {
 function getSingleVariable(value) {
     return Array.isArray(value) ? value[0] : value;
 }
+function requireValidMemoryHash(variables) {
+    const hash = getSingleVariable(variables['hash']);
+    if (!hash || !HASH_REGEX.test(hash)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid hash: must be a 64-character hex string');
+    }
+    return hash;
+}
 function requireSingleVariable(variables, key, errorMessage) {
     const value = getSingleVariable(variables[key]);
     if (!value) {
@@ -51,6 +58,13 @@ function requireSingleVariable(variables, key, errorMessage) {
     }
     return value;
 }
+function requireKnownToolInfo(toolName) {
+    const info = getToolInfo(toolName);
+    if (!info) {
+        throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${toolName}`);
+    }
+    return info;
+}
 function registerStaticMarkdownResource(server, config) {
     server.registerResource(config.name, config.uri, {
         title: config.title,
@@ -90,70 +104,75 @@ const INSTRUCTIONS_CONTENT = loadInstructions();
 const TOOL_CATALOG_CONTENT = buildToolCatalog();
 const WORKFLOW_GUIDE_CONTENT = buildWorkflowGuide();
 const SERVER_CONFIG_CONTENT = buildServerConfig();
-// --- Registration ---
-export function registerAllResources(server, db) {
-    // internal://instructions
-    registerStaticMarkdownResource(server, {
+const STATIC_CONTENT_BY_KEY = {
+    instructions: INSTRUCTIONS_CONTENT,
+    toolCatalog: TOOL_CATALOG_CONTENT,
+    workflows: WORKFLOW_GUIDE_CONTENT,
+    serverConfig: SERVER_CONFIG_CONTENT,
+};
+const STATIC_RESOURCE_SEEDS = [
+    {
         name: 'instructions',
         uri: INSTRUCTIONS_URI,
         title: 'Memory Instructions',
         description: 'Complete usage guide: tool inventory, routing decisions, error codes, data model, and workflow patterns. Read this first.',
         audience: ['assistant'],
         priority: 0.9,
-        content: INSTRUCTIONS_CONTENT,
-    });
-    // internal://tool-catalog
-    registerStaticMarkdownResource(server, {
+        contentKey: 'instructions',
+    },
+    {
         name: 'tool-catalog',
         uri: TOOL_CATALOG_URI,
         title: 'Tool Catalog',
         description: 'Tool reference table, optional parameter matrix, and cross-tool data flow.',
         audience: ['assistant'],
         priority: 0.7,
-        content: TOOL_CATALOG_CONTENT,
-    });
-    // internal://tool-info/{toolName}
-    server.registerResource('tool-info', new ResourceTemplate(TOOL_INFO_URI_TEMPLATE, {
-        list: () => listToolInfoResources(),
-        complete: {
-            toolName: (value) => TOOL_NAMES.filter((n) => n.startsWith(value)),
-        },
-    }), {
-        title: 'Tool Info',
-        description: 'Per-tool detail: parameters, behavior, and output shape. Supports toolName auto-completion.',
-        mimeType: 'text/markdown',
-        annotations: createResourceAnnotations(['assistant'], 0.6),
-    }, (uri, variables) => {
-        const toolName = requireSingleVariable(variables, 'toolName', 'Missing toolName parameter');
-        const info = getToolInfo(toolName);
-        if (!info) {
-            throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${toolName}`);
-        }
-        return {
-            contents: [createMarkdownContent(uri.href, info)],
-        };
-    });
-    // internal://workflows
-    registerStaticMarkdownResource(server, {
+        contentKey: 'toolCatalog',
+    },
+    {
         name: 'workflows',
         uri: WORKFLOWS_URI,
         title: 'Workflow Guide',
         description: 'Recommended multi-step workflow sequences with guardrails and tool reference.',
         audience: ['assistant'],
         priority: 0.7,
-        content: WORKFLOW_GUIDE_CONTENT,
-    });
-    // internal://server-config
-    registerStaticMarkdownResource(server, {
+        contentKey: 'workflows',
+    },
+    {
         name: 'server-config',
         uri: SERVER_CONFIG_URI,
         title: 'Server Configuration',
         description: 'Runtime configuration, environment variables, capabilities, and data limits.',
         audience: ['user', 'assistant'],
         priority: 0.5,
-        content: SERVER_CONFIG_CONTENT,
+        contentKey: 'serverConfig',
+    },
+];
+function getStaticMarkdownResources() {
+    return STATIC_RESOURCE_SEEDS.map((seed) => ({
+        ...seed,
+        content: STATIC_CONTENT_BY_KEY[seed.contentKey],
+    }));
+}
+function completeToolName(value) {
+    return TOOL_NAMES.filter((toolName) => toolName.startsWith(value));
+}
+function registerToolInfoResource(server) {
+    server.registerResource('tool-info', new ResourceTemplate(TOOL_INFO_URI_TEMPLATE, {
+        list: listToolInfoResources,
+        complete: { toolName: completeToolName },
+    }), {
+        title: 'Tool Info',
+        description: 'Per-tool detail: parameters, behavior, and output shape. Supports toolName auto-completion.',
+        mimeType: 'text/markdown',
+        annotations: createResourceAnnotations(['assistant'], 0.6),
+    }, (uri, variables) => {
+        const toolName = requireSingleVariable(variables, 'toolName', 'Missing toolName parameter');
+        const info = requireKnownToolInfo(toolName);
+        return { contents: [createMarkdownContent(uri.href, info)] };
     });
-    // memory://memories/{hash}
+}
+function registerMemoryResource(server, db) {
     const hashCompletion = createHashCompletionCallback(db);
     server.registerResource('memory', new ResourceTemplate(MEMORY_RESOURCE_URI_TEMPLATE, {
         list: () => listMemoryResources(db),
@@ -164,10 +183,7 @@ export function registerAllResources(server, db) {
         mimeType: 'application/json',
         annotations: createResourceAnnotations(['assistant'], 0.7),
     }, (uri, variables) => {
-        const hash = getSingleVariable(variables['hash']);
-        if (!hash || !HASH_REGEX.test(hash)) {
-            throw new McpError(ErrorCode.InvalidParams, 'Invalid hash: must be a 64-character hex string');
-        }
+        const hash = requireValidMemoryHash(variables);
         const row = readMemoryByHash(db, hash);
         if (!row) {
             return createErrorResourceContents(uri.href, 'Not found', hash);
@@ -177,3 +193,11 @@ export function registerAllResources(server, db) {
         };
     });
 }
+// --- Registration ---
+export function registerAllResources(server, db) {
+    for (const config of getStaticMarkdownResources()) {
+        registerStaticMarkdownResource(server, config);
+    }
+    registerToolInfoResource(server);
+    registerMemoryResource(server, db);
+}

package/dist/resources/instructions.js

@@ -63,42 +63,49 @@ function renderSharedConstraints() {
         .map((c) => `- ${c}`)
         .join('\n');
 }
-export function buildServerInstructions() {
+function renderTaggedSection(section) {
+    return [`<${section.tag}>`, section.content, `</${section.tag}>`].join('\n');
+}
+function buildTaggedSections() {
     return [
-        '<role>',
-        'Memory MCP: Persistent memory storage, full-text retrieval, and relationship graph traversal.',
-        '</role>',
-        '',
-        '<capabilities>',
-        buildToolRouting(),
-        '</capabilities>',
-        '',
-        '<constraints>',
-        renderSharedConstraints(),
-        '</constraints>',
-        '',
-        '<error_codes>',
-        ERROR_CODES.join('\n'),
-        '</error_codes>',
-        '',
-        '<error_result_conventions>',
-        ERROR_RESULT_CONVENTIONS.join('\n'),
-        '</error_result_conventions>',
-        '',
-        '<data_model>',
-        DATA_MODEL,
-        '</data_model>',
-        '',
-        '<workflows>',
-        WORKFLOWS,
-        '</workflows>',
-        '',
-        '<prompts>',
-        PROMPTS_INVENTORY.join('\n'),
-        '</prompts>',
-        '',
-        '<resources>',
-        RESOURCES_INVENTORY.join('\n'),
-        '</resources>',
-    ].join('\n');
+        {
+            tag: 'role',
+            content: 'Memory MCP: Persistent memory storage, full-text retrieval, and relationship graph traversal.',
+        },
+        {
+            tag: 'capabilities',
+            content: buildToolRouting(),
+        },
+        {
+            tag: 'constraints',
+            content: renderSharedConstraints(),
+        },
+        {
+            tag: 'error_codes',
+            content: ERROR_CODES.join('\n'),
+        },
+        {
+            tag: 'error_result_conventions',
+            content: ERROR_RESULT_CONVENTIONS.join('\n'),
+        },
+        {
+            tag: 'data_model',
+            content: DATA_MODEL,
+        },
+        {
+            tag: 'workflows',
+            content: WORKFLOWS,
+        },
+        {
+            tag: 'prompts',
+            content: PROMPTS_INVENTORY.join('\n'),
+        },
+        {
+            tag: 'resources',
+            content: RESOURCES_INVENTORY.join('\n'),
+        },
+    ];
+}
+export function buildServerInstructions() {
+    return buildTaggedSections().map(renderTaggedSection).join('\n\n');
 }

package/dist/resources/server-config.js

@@ -46,32 +46,43 @@ const CAPABILITIES = [
 function toEnvVarRow(v) {
     return `| \`${v.name}\` | ${v.default} | ${v.range} | ${v.purpose} |`;
 }
-function toRangeRow(label, range) {
-    return `| ${label} | ${range} |`;
+function toTwoColumnRow(label, value) {
+    return `| ${label} | ${value} |`;
 }
-export function buildServerConfig() {
-    const envRows = ENV_VARS.map(toEnvVarRow);
-    const limitRows = DATA_LIMITS.map((l) => toRangeRow(l.dimension, l.range));
-    const capRows = CAPABILITIES.map((c) => toRangeRow(c.capability, c.status));
+function renderTableSection(section) {
     return [
-        '# Server Configuration',
-        '',
-        '## Environment Variables',
-        '',
-        '| Variable | Default | Range | Purpose |',
-        '|----------|---------|-------|---------|',
-        ...envRows,
-        '',
-        '## Capabilities',
+        `## ${section.title}`,
         '',
-        '| Capability | Status |',
-        '|------------|--------|',
-        ...capRows,
+        section.header,
+        section.separator,
+        ...section.rows,
         '',
-        '## Data Limits',
+    ];
+}
+export function buildServerConfig() {
+    const sections = [
+        {
+            title: 'Environment Variables',
+            header: '| Variable | Default | Range | Purpose |',
+            separator: '|----------|---------|-------|---------|',
+            rows: ENV_VARS.map(toEnvVarRow),
+        },
+        {
+            title: 'Capabilities',
+            header: '| Capability | Status |',
+            separator: '|------------|--------|',
+            rows: CAPABILITIES.map((c) => toTwoColumnRow(c.capability, c.status)),
+        },
+        {
+            title: 'Data Limits',
+            header: '| Dimension | Range |',
+            separator: '|-----------|-------|',
+            rows: DATA_LIMITS.map((l) => toTwoColumnRow(l.dimension, l.range)),
+        },
+    ];
+    return [
+        '# Server Configuration',
         '',
-        '| Dimension | Range |',
-        '|-----------|-------|',
-        ...limitRows,
+        ...sections.flatMap(renderTableSection),
     ].join('\n');
 }

package/dist/resources/tool-catalog.js

@@ -1,12 +1,8 @@
-import { extractJsonSchema, } from '../lib/json-schema.js';
+import { getSchemaMeta } from '../lib/json-schema.js';
 import { getToolContracts } from '../lib/tool-contracts.js';
 import { buildCoreContextPack } from './tool-info.js';
 function extractOptionalParams(toolName, schema) {
-    const jsonSchema = extractJsonSchema(schema);
-    const properties = (jsonSchema['properties'] ?? {});
-    const requiredFields = new Set(Array.isArray(jsonSchema['required'])
-        ? jsonSchema['required']
-        : []);
+    const { properties, requiredFields } = getSchemaMeta(schema);
     const rows = [];
     for (const [name, prop] of Object.entries(properties).sort(([a], [b]) => a.localeCompare(b))) {
         if (requiredFields.has(name))

package/dist/resources/tool-info.js

@@ -1,4 +1,4 @@
-import { extractJsonSchema, } from '../lib/json-schema.js';
+import { extractJsonSchema, getSchemaMeta, } from '../lib/json-schema.js';
 import { getToolContracts } from '../lib/tool-contracts.js';
 // --- Shared Constraints (Single Source of Truth) ---
 const SHARED_CONSTRAINTS = [
@@ -61,6 +61,12 @@ function formatParamConstraints(prop) {
         parts.push(`enum: ${prop['enum'].join(' | ')}`);
     return parts.length > 0 ? `; ${parts.join(', ')}` : '';
 }
+function getSortedSchemaProperties(properties) {
+    return Object.entries(properties).sort(([a], [b]) => a.localeCompare(b));
+}
+function formatParamLines(meta) {
+    return getSortedSchemaProperties(meta.properties).map(([pName, pSchema]) => formatParam(pName, pSchema, meta.requiredFields.has(pName)));
+}
 function formatParam(name, prop, required) {
     const type = typeof prop['type'] === 'string' ? prop['type'] : 'unknown';
     const desc = typeof prop['description'] === 'string' ? prop['description'] : '';
@@ -87,14 +93,8 @@ export function getToolInfo(name) {
     const contract = getToolContracts().find((c) => c.name === name);
     if (!contract)
         return undefined;
-    const inputSchema = extractJsonSchema(contract.inputSchema);
-    const properties = (inputSchema['properties'] ?? {});
-    const requiredFields = new Set(Array.isArray(inputSchema['required'])
-        ? inputSchema['required']
-        : []);
-    const paramLines = Object.entries(properties)
-        .sort(([a], [b]) => a.localeCompare(b))
-        .map(([pName, pSchema]) => formatParam(pName, pSchema, requiredFields.has(pName)));
+    const inputMeta = getSchemaMeta(contract.inputSchema);
+    const paramLines = formatParamLines(inputMeta);
     const behaviorLine = formatBehavior(contract.annotations);
     const outputShape = formatOutputShape(contract.outputSchema);
     return [

package/dist/resources/workflows.js

@@ -1,53 +1,82 @@
 import { getSharedConstraints } from './tool-info.js';
-const WORKFLOW_TRACKS = `## Workflow A: Store and Link
-
-1. \`store_memories({ items: [...] })\` → \`{ items[].hash, succeeded, failed }\`
-2. \`create_relationship({ from_hash, to_hash, relation_type })\` × N
-
-> Constraint: Both endpoint memories must exist before creating a relationship.
-
-## Workflow B: Search and Read
-
-1. \`search_memories({ query, limit })\` → \`{ memories[], nextCursor }\`
-2. \`get_memory({ hash })\` for full detail on a specific result
-
-> Or use \`recall({ query, depth: 1 })\` → \`{ memories[], graph[] }\` to follow relationships.
-
-## Workflow C: Fill Context Window
-
-1. \`retrieve_context({ query, token_budget: 4000, strategy: 'relevance' })\` → \`{ memories[], estimated_tokens, truncated }\`
-
-> Use \`strategy\` to control sort: \`relevance\` (FTS rank), \`importance\` (highest first), or \`recency\` (newest first).
-
-## Workflow D: Update a Memory
-
-1. \`update_memory({ hash, content })\` → \`{ old_hash, new_hash }\`
-
-> Existing relationships auto-update to new_hash via CASCADE.
-> Returns E_CONFLICT if the new content+tags already maps to an existing hash.
-
-## Workflow E: Batch Delete
-
-1. \`delete_memories({ hashes: [...] })\` → \`{ items[].{ hash, deleted }, succeeded, failed }\`
-
-> \`deleted: false\` means hash not found — not an error, the batch still succeeds.
-
-## Workflow F: Explore Graph
-
-1. \`recall({ query, depth: 2 })\` → \`{ memories[], graph[], depth_reached, aborted }\`
-2. \`get_relationships({ hash, direction: 'both' })\` for a specific memory's edges
-
-> BFS traversal emits progress per hop. Use \`depth: 0\` to skip traversal.`;
+const WORKFLOW_TRACKS = [
+    {
+        title: 'Workflow A: Store and Link',
+        steps: [
+            '`store_memories({ items: [...] })` → `{ items[].hash, succeeded, failed }`',
+            '`create_relationship({ from_hash, to_hash, relation_type })` × N',
+        ],
+        notes: [
+            'Constraint: Both endpoint memories must exist before creating a relationship.',
+        ],
+    },
+    {
+        title: 'Workflow B: Search and Read',
+        steps: [
+            '`search_memories({ query, limit })` → `{ memories[], nextCursor }`',
+            '`get_memory({ hash })` for full detail on a specific result',
+        ],
+        notes: [
+            'Or use `recall({ query, depth: 1 })` → `{ memories[], graph[] }` to follow relationships.',
+        ],
+    },
+    {
+        title: 'Workflow C: Fill Context Window',
+        steps: [
+            "`retrieve_context({ query, token_budget: 4000, strategy: 'relevance' })` → `{ memories[], estimated_tokens, truncated }`",
+        ],
+        notes: [
+            'Use `strategy` to control sort: `relevance` (FTS rank), `importance` (highest first), or `recency` (newest first).',
+        ],
+    },
+    {
+        title: 'Workflow D: Update a Memory',
+        steps: ['`update_memory({ hash, content })` → `{ old_hash, new_hash }`'],
+        notes: [
+            'Existing relationships auto-update to new_hash via CASCADE.',
+            'Returns E_CONFLICT if the new content+tags already maps to an existing hash.',
+        ],
+    },
+    {
+        title: 'Workflow E: Batch Delete',
+        steps: [
+            '`delete_memories({ hashes: [...] })` → `{ items[].{ hash, deleted }, succeeded, failed }`',
+        ],
+        notes: [
+            '`deleted: false` means hash not found - not an error, the batch still succeeds.',
+        ],
+    },
+    {
+        title: 'Workflow F: Explore Graph',
+        steps: [
+            '`recall({ query, depth: 2 })` → `{ memories[], graph[], depth_reached, aborted }`',
+            "`get_relationships({ hash, direction: 'both' })` for a specific memory's edges",
+        ],
+        notes: [
+            'BFS traversal emits progress per hop. Use `depth: 0` to skip traversal.',
+        ],
+    },
+];
 function renderSharedConstraintsSection() {
     return getSharedConstraints()
         .map((c) => `- ${c}`)
         .join('\n');
 }
+function renderWorkflowTrack(track) {
+    const stepLines = track.steps
+        .map((step, idx) => `${idx + 1}. ${step}`)
+        .join('\n');
+    const noteLines = track.notes.map((note) => `> ${note}`).join('\n');
+    return [`## ${track.title}`, '', stepLines, '', noteLines].join('\n');
+}
+function renderWorkflowTracks() {
+    return WORKFLOW_TRACKS.map(renderWorkflowTrack).join('\n\n');
+}
 export function buildWorkflowGuide() {
     return [
         '# Workflow Reference',
         '',
-        WORKFLOW_TRACKS,
+        renderWorkflowTracks(),
         '',
         '## Shared Constraints',
         renderSharedConstraintsSection(),

package/dist/schemas/inputs.d.ts

@@ -63,7 +63,7 @@ export declare const GetMemoryInputSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const UpdateMemoryInputSchema: z.ZodObject<{
     hash: z.ZodString;
-    content: z.ZodString;
+    content: z.ZodOptional<z.ZodString>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export declare const DeleteMemoryInputSchema: z.ZodObject<{
@@ -77,7 +77,7 @@ export declare const SearchMemoriesInputSchema: z.ZodObject<{
     max_importance: z.ZodOptional<z.ZodNumber>;
     memory_type: z.ZodOptional<typeof MEMORY_TYPE_SCHEMA>;
     query: z.ZodString;
-    limit: z.ZodPrefault<z.ZodOptional<z.ZodInt>>;
+    limit: z.ZodPrefault<z.ZodOptional<z.ZodNumber>>;
     cursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const RecallInputSchema: z.ZodObject<{
@@ -85,13 +85,16 @@ export declare const RecallInputSchema: z.ZodObject<{
     max_importance: z.ZodOptional<z.ZodNumber>;
     memory_type: z.ZodOptional<typeof MEMORY_TYPE_SCHEMA>;
     query: z.ZodString;
-    depth: z.ZodPrefault<z.ZodOptional<z.ZodInt>>;
-    limit: z.ZodPrefault<z.ZodOptional<z.ZodInt>>;
+    depth: z.ZodPrefault<z.ZodOptional<z.ZodNumber>>;
+    limit: z.ZodPrefault<z.ZodOptional<z.ZodNumber>>;
     cursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const RetrieveContextInputSchema: z.ZodObject<{
+    min_importance: z.ZodOptional<z.ZodNumber>;
+    max_importance: z.ZodOptional<z.ZodNumber>;
+    memory_type: z.ZodOptional<typeof MEMORY_TYPE_SCHEMA>;
     query: z.ZodString;
-    token_budget: z.ZodPrefault<z.ZodOptional<z.ZodInt>>;
+    token_budget: z.ZodPrefault<z.ZodOptional<z.ZodNumber>>;
     strategy: z.ZodPrefault<z.ZodOptional<z.ZodEnum<{
         importance: "importance";
         recency: "recency";