@j0hanz/memory-mcp 1.5.0 → 1.7.0

package/dist/db/index.js

@@ -7,6 +7,10 @@ const TARGET_SCHEMA_VERSION = 2;
 const FTS5_CHECK_SQL = 'CREATE VIRTUAL TABLE IF NOT EXISTS __fts5_check USING fts5(x); DROP TABLE __fts5_check;';
 const FTS5_REQUIRED_MESSAGE = 'SQLite FTS5 extension is not available. memory-mcp requires a SQLite build with FTS5 support.';
 const DEFENSIVE_PRAGMA_SQL = 'PRAGMA defensive = ON';
+const RELATIONSHIP_INDEX_SQL = [
+    'CREATE INDEX IF NOT EXISTS idx_relationships_from ON relationships(from_hash)',
+    'CREATE INDEX IF NOT EXISTS idx_relationships_to ON relationships(to_hash)',
+];
 const RELATIONSHIPS_TABLE_SQL = `CREATE TABLE IF NOT EXISTS relationships (
     from_hash TEXT NOT NULL REFERENCES memories(hash) ON DELETE CASCADE ON UPDATE CASCADE,
     to_hash TEXT NOT NULL REFERENCES memories(hash) ON DELETE CASCADE ON UPDATE CASCADE,
@@ -57,12 +61,17 @@ const SCHEMA_SQL = `
   CREATE INDEX IF NOT EXISTS idx_memories_created
     ON memories(created_at DESC);
 
-  CREATE INDEX IF NOT EXISTS idx_relationships_from
-    ON relationships(from_hash);
-
-  CREATE INDEX IF NOT EXISTS idx_relationships_to
-    ON relationships(to_hash);
+  ${RELATIONSHIP_INDEX_SQL.join(';\n\n  ')};
 `;
+const RELATIONSHIP_EDGE_COLUMNS = new Set(['from_hash', 'to_hash']);
+function isMemoryRelationshipForeignKey(row) {
+    return row.table === 'memories' && RELATIONSHIP_EDGE_COLUMNS.has(row.from);
+}
+function ensureRelationshipIndexes(db) {
+    for (const statement of RELATIONSHIP_INDEX_SQL) {
+        db.exec(statement);
+    }
+}
 function runImmediateTransaction(db, action) {
     db.exec('BEGIN IMMEDIATE');
     try {
@@ -101,13 +110,8 @@ function needsRelationshipsCascadeUpdateMigration(db) {
     const rows = db
         .prepare("PRAGMA foreign_key_list('relationships')")
         .all();
-    if (rows.length === 0) {
-        return false;
-    }
     for (const row of rows) {
-        const isMemoryEdge = row.table === 'memories' &&
-            (row.from === 'from_hash' || row.from === 'to_hash');
-        if (!isMemoryEdge) {
+        if (!isMemoryRelationshipForeignKey(row)) {
             continue;
         }
         if (row.on_update.toUpperCase() !== 'CASCADE') {
@@ -126,8 +130,7 @@ function migrateRelationshipsCascadeUpdate(db) {
       FROM relationships_old
     `);
         db.exec('DROP TABLE relationships_old');
-        db.exec('CREATE INDEX IF NOT EXISTS idx_relationships_from ON relationships(from_hash)');
-        db.exec('CREATE INDEX IF NOT EXISTS idx_relationships_to ON relationships(to_hash)');
+        ensureRelationshipIndexes(db);
     });
 }
 function applyMigrations(db) {

package/dist/lib/errors.d.ts

@@ -8,3 +8,7 @@ export declare const E_UNKNOWN = "E_UNKNOWN";
 export declare function getErrorMessage(err: unknown): string;
 export declare function isMcpError(err: unknown): err is McpError;
 export declare function rethrowMcpError(err: unknown): void;
+export declare class CancelledError extends Error {
+    constructor();
+}
+export declare function throwIfAborted(signal?: AbortSignal): void;

package/dist/lib/errors.js

@@ -20,3 +20,14 @@ export function rethrowMcpError(err) {
     if (isMcpError(err))
         throw err;
 }
+export class CancelledError extends Error {
+    constructor() {
+        super(E_CANCELLED);
+        this.name = 'CancelledError';
+    }
+}
+export function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw new CancelledError();
+    }
+}

package/dist/lib/graph-traversal.d.ts

@@ -0,0 +1,12 @@
+import type { TypedDb } from '../db/typed.js';
+import type { MemoryRow, RelationshipEdge } from './types.js';
+export type ProgressNotifier = (hop: number, total: number) => void;
+export declare const MAX_EDGE_ROWS: number;
+export declare const MAX_VISITED_NODES: number;
+export interface TraverseGraphResult {
+    edges: RelationshipEdge[];
+    visited: Set<string>;
+    depthReached: number;
+    aborted: boolean;
+}
+export declare function traverseGraph(db: TypedDb, seeds: MemoryRow[], depth: number, signal?: AbortSignal, onHop?: ProgressNotifier): Promise<TraverseGraphResult>;

package/dist/lib/graph-traversal.js

@@ -0,0 +1,145 @@
+import process from 'node:process';
+import { throwIfAborted } from './errors.js';
+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);
+export const MAX_EDGE_ROWS = parseEnvInt('RECALL_MAX_EDGE_ROWS', 5000, 100, 50000);
+export 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 ?`;
+function initializeTraversalState(seeds) {
+    const visited = new Set();
+    const frontier = [];
+    for (const seed of seeds) {
+        visited.add(seed.hash);
+        frontier.push(seed.hash);
+    }
+    return {
+        visited,
+        frontier,
+        edges: [],
+        seenEdges: new Set(),
+        depthReached: 0,
+        aborted: false,
+    };
+}
+function capFrontier(state) {
+    if (state.frontier.length <= MAX_FRONTIER_SIZE) {
+        return;
+    }
+    state.frontier.length = MAX_FRONTIER_SIZE;
+    state.aborted = true;
+}
+function getRemainingBudget(state) {
+    return {
+        edges: MAX_EDGE_ROWS - state.edges.length,
+        nodes: MAX_VISITED_NODES - state.visited.size,
+    };
+}
+function hasExhaustedBudget(budget) {
+    return budget.edges <= 0 || budget.nodes <= 0;
+}
+function loadEdgeRows(edgeStmt, frontier, edgeLimit) {
+    const frontierJson = JSON.stringify(frontier);
+    return edgeStmt.all(frontierJson, frontierJson, edgeLimit + 1);
+}
+function toRowsToProcessCount(edgeRowsLength, remainingEdgeBudget) {
+    return edgeRowsLength > remainingEdgeBudget
+        ? remainingEdgeBudget
+        : edgeRowsLength;
+}
+function toEdgeKey(edge) {
+    return `${edge.from_hash}|${edge.to_hash}|${edge.relation_type}`;
+}
+function appendEdgeIfNew(state, edge) {
+    const edgeKey = toEdgeKey(edge);
+    if (state.seenEdges.has(edgeKey)) {
+        return;
+    }
+    state.seenEdges.add(edgeKey);
+    state.edges.push({
+        from_hash: edge.from_hash,
+        to_hash: edge.to_hash,
+        relation_type: edge.relation_type,
+    });
+}
+function createVisitedQueue(state, nextHashes) {
+    return (hash) => {
+        if (state.visited.has(hash)) {
+            return;
+        }
+        if (state.visited.size >= MAX_VISITED_NODES) {
+            state.aborted = true;
+            return;
+        }
+        state.visited.add(hash);
+        if (nextHashes.length < MAX_FRONTIER_SIZE) {
+            nextHashes.push(hash);
+            return;
+        }
+        state.aborted = true;
+    };
+}
+function shouldStopEdgeProcessing(state) {
+    return (state.aborted &&
+        (state.edges.length >= MAX_EDGE_ROWS ||
+            state.visited.size >= MAX_VISITED_NODES));
+}
+function processEdgeRows(state, edgeRows, rowsToProcess) {
+    const nextHashes = [];
+    const queueVisitedHash = createVisitedQueue(state, nextHashes);
+    for (let i = 0; i < rowsToProcess; i += 1) {
+        const edge = edgeRows[i];
+        if (!edge) {
+            break;
+        }
+        appendEdgeIfNew(state, edge);
+        queueVisitedHash(edge.from_hash);
+        queueVisitedHash(edge.to_hash);
+        if (shouldStopEdgeProcessing(state)) {
+            break;
+        }
+    }
+    state.frontier.length = 0;
+    state.frontier.push(...nextHashes);
+}
+export async function traverseGraph(db, seeds, depth, signal, onHop) {
+    const state = initializeTraversalState(seeds);
+    const edgeStmt = db.prepareOnce(EDGE_QUERY_SQL);
+    for (let hop = 0; hop < depth && state.frontier.length > 0; hop += 1) {
+        await yieldToEventLoop();
+        throwIfAborted(signal);
+        state.depthReached = hop + 1;
+        onHop?.(hop, depth);
+        capFrontier(state);
+        const budget = getRemainingBudget(state);
+        if (hasExhaustedBudget(budget)) {
+            state.aborted = true;
+            break;
+        }
+        const edgeRows = loadEdgeRows(edgeStmt, state.frontier, budget.edges);
+        const rowsToProcess = toRowsToProcessCount(edgeRows.length, budget.edges);
+        if (edgeRows.length > budget.edges) {
+            state.aborted = true;
+        }
+        processEdgeRows(state, edgeRows, rowsToProcess);
+    }
+    return {
+        edges: state.edges,
+        visited: state.visited,
+        depthReached: state.depthReached,
+        aborted: state.aborted,
+    };
+}

package/dist/lib/json-schema.d.ts

@@ -1,3 +1,8 @@
 import { z } from 'zod/v4';
 export type JsonSchemaObject = Record<string, unknown>;
 export declare function extractJsonSchema(schema: z.ZodType): JsonSchemaObject;
+export interface SchemaMeta {
+    properties: Record<string, JsonSchemaObject>;
+    requiredFields: Set<string>;
+}
+export declare function getSchemaMeta(schema: z.ZodType): SchemaMeta;

package/dist/lib/json-schema.js

@@ -1,9 +1,27 @@
 import { z } from 'zod/v4';
+const JsonSchemaPayloadSchema = z
+    .object({
+    properties: z
+        .record(z.string(), z.record(z.string(), z.unknown()))
+        .optional(),
+    required: z.array(z.string()).optional(),
+})
+    .catchall(z.unknown());
 export function extractJsonSchema(schema) {
     try {
-        return z.toJSONSchema(schema);
+        const raw = z.toJSONSchema(schema);
+        return raw;
     }
     catch {
         return {};
     }
 }
+export function getSchemaMeta(schema) {
+    const jsonSchema = extractJsonSchema(schema);
+    const parsed = JsonSchemaPayloadSchema.safeParse(jsonSchema);
+    const data = parsed.success ? parsed.data : {};
+    return {
+        properties: data.properties ?? {},
+        requiredFields: new Set(data.required ?? []),
+    };
+}

package/dist/lib/pagination.d.ts

@@ -2,6 +2,4 @@ export interface PageSlice<T> {
     page: T[];
     hasMore: boolean;
 }
-export declare function encodeCursor(offset: number): string;
-export declare function decodeCursor(cursor: string): number;
 export declare function splitPage<T>(rows: readonly T[], limit: number): PageSlice<T>;

package/dist/lib/pagination.js

@@ -1,46 +1,3 @@
-import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { E_INVALID_CURSOR } from './errors.js';
-const CURSOR_ENCODING = 'base64url';
-const INVALID_CURSOR_STRUCTURE_MESSAGE = 'Invalid cursor structure';
-function isRecord(value) {
-    return typeof value === 'object' && value !== null;
-}
-function isNonNegativeInteger(value) {
-    return (typeof value === 'number' &&
-        Number.isInteger(value) &&
-        Number.isFinite(value) &&
-        value >= 0);
-}
-function isCursorPayload(value) {
-    if (!isRecord(value)) {
-        return false;
-    }
-    const { offset } = value;
-    return isNonNegativeInteger(offset);
-}
-function parseCursorPayload(cursor) {
-    const json = Buffer.from(cursor, CURSOR_ENCODING).toString();
-    const parsed = JSON.parse(json);
-    if (!isCursorPayload(parsed)) {
-        throw new Error(INVALID_CURSOR_STRUCTURE_MESSAGE);
-    }
-    return parsed;
-}
-function invalidCursor() {
-    return new McpError(ErrorCode.InvalidParams, `${E_INVALID_CURSOR}: malformed cursor`);
-}
-export function encodeCursor(offset) {
-    const payload = { offset };
-    return Buffer.from(JSON.stringify(payload)).toString(CURSOR_ENCODING);
-}
-export function decodeCursor(cursor) {
-    try {
-        return parseCursorPayload(cursor).offset;
-    }
-    catch {
-        throw invalidCursor();
-    }
-}
 export function splitPage(rows, limit) {
     if (rows.length > limit) {
         return { page: rows.slice(0, limit), hasMore: true };

package/dist/lib/search.js

@@ -12,6 +12,9 @@ export function sanitizeFtsQuery(query) {
     }
     return tokens.map((token) => `"${token}"`).join(' ');
 }
+function isOffsetCursor(cursor) {
+    return cursor == null || cursor.mode === 'offset';
+}
 const FILTER_RULES = [
     { key: 'min_importance', clause: 'm.importance >= ?' },
     { key: 'max_importance', clause: 'm.importance <= ?' },
@@ -35,15 +38,18 @@ export function buildAndWhereClause(clauses) {
     }
     return ` AND ${clauses.join(' AND ')}`;
 }
+function buildBaseSearchWhere(whereExtra) {
+    return `${BASE_RANKED_SEARCH_SQL}
+         WHERE memories_fts MATCH ?${whereExtra}`;
+}
 function buildRankedSearchSql(whereExtra, cursor) {
-    if (!cursor || cursor.mode === 'offset') {
-        return `${BASE_RANKED_SEARCH_SQL}
-         WHERE memories_fts MATCH ?${whereExtra}
+    const whereSql = buildBaseSearchWhere(whereExtra);
+    if (isOffsetCursor(cursor)) {
+        return `${whereSql}
          ORDER BY memories_fts.rank, m.hash
          LIMIT ? OFFSET ?`;
     }
-    return `${BASE_RANKED_SEARCH_SQL}
-       WHERE memories_fts MATCH ?${whereExtra}
+    return `${whereSql}
          AND (
            memories_fts.rank > ?
            OR (memories_fts.rank = ? AND m.hash > ?)
@@ -51,28 +57,43 @@ function buildRankedSearchSql(whereExtra, cursor) {
        ORDER BY memories_fts.rank, m.hash
        LIMIT ?`;
 }
-export function loadRankedSearchRows(db, query, limit, cursor, filters) {
-    const ftsQuery = sanitizeFtsQuery(query);
-    const filter = buildFilterClauses(filters);
-    const whereExtra = buildAndWhereClause(filter.clauses);
-    const sql = buildRankedSearchSql(whereExtra, cursor);
-    const stmt = db.prepareOnce(sql);
-    if (!cursor || cursor.mode === 'offset') {
+function buildBaseSearchParams(ftsQuery, filterParams) {
+    return [ftsQuery, ...filterParams];
+}
+function buildOffsetParams(baseParams, limit, offset) {
+    return [...baseParams, limit + 1, offset];
+}
+function buildKeysetParams(baseParams, limit, cursor) {
+    return [...baseParams, cursor.rank, cursor.rank, cursor.hash, limit + 1];
+}
+function buildRankedSearchParams(ftsQuery, filterParams, limit, cursor) {
+    const baseParams = buildBaseSearchParams(ftsQuery, filterParams);
+    if (isOffsetCursor(cursor)) {
         const offset = cursor?.offset ?? 0;
-        return stmt.all(ftsQuery, ...filter.params, limit + 1, offset);
+        return buildOffsetParams(baseParams, limit, offset);
     }
-    return stmt.all(ftsQuery, ...filter.params, cursor.rank, cursor.rank, cursor.hash, limit + 1);
+    return buildKeysetParams(baseParams, limit, cursor);
+}
+function buildSearchPlan(query, limit, cursor, filters) {
+    const filter = buildFilterClauses(filters);
+    const sql = buildRankedSearchSql(buildAndWhereClause(filter.clauses), cursor);
+    const params = buildRankedSearchParams(query, filter.params, limit, cursor);
+    return { sql, params };
+}
+export function loadRankedSearchRows(db, query, limit, cursor, filters) {
+    const ftsQuery = sanitizeFtsQuery(query);
+    const plan = buildSearchPlan(ftsQuery, limit, cursor, filters);
+    return db.prepareOnce(plan.sql).all(...plan.params);
 }
 export function toMemoryFilters(params) {
     const filters = {};
-    if (params.min_importance != null) {
-        filters.min_importance = params.min_importance;
-    }
-    if (params.max_importance != null) {
-        filters.max_importance = params.max_importance;
-    }
-    if (params.memory_type != null) {
-        filters.memory_type = params.memory_type;
-    }
+    const addFilter = (key, value) => {
+        if (value != null) {
+            filters[key] = value;
+        }
+    };
+    addFilter('min_importance', params.min_importance);
+    addFilter('max_importance', params.max_importance);
+    addFilter('memory_type', params.memory_type);
     return filters;
 }

package/dist/lib/tool-contracts.js

@@ -1,19 +1,46 @@
 import {} from 'zod/v4';
 import { CreateRelationshipInputSchema, DeleteMemoriesInputSchema, DeleteMemoryInputSchema, DeleteRelationshipInputSchema, GetMemoryInputSchema, GetRelationshipsInputSchema, MemoryStatsInputSchema, RecallInputSchema, RetrieveContextInputSchema, SearchMemoriesInputSchema, StoreMemoriesInputSchema, StoreMemoryInputSchema, UpdateMemoryInputSchema, } from '../schemas/inputs.js';
 import { BatchResultSchema, CreateRelationshipResultSchema, DeleteRelationshipResultSchema, DeleteResultSchema, MemoryResultSchema, RecallResultSchema, RelationshipResultSchema, RetrieveContextResultSchema, SearchResultSchema, StatsResultSchema, StoreResultSchema, UpdateResultSchema, } from '../schemas/outputs.js';
-export const TOOL_CONTRACTS = [
+const DEFAULT_ANNOTATIONS = {
+    readOnlyHint: false,
+    idempotentHint: false,
+    destructiveHint: false,
+    openWorldHint: false,
+};
+const READ_ONLY_ANNOTATIONS = {
+    readOnlyHint: true,
+};
+const IDEMPOTENT_ANNOTATIONS = {
+    idempotentHint: true,
+};
+const DESTRUCTIVE_ANNOTATIONS = {
+    destructiveHint: true,
+};
+function createToolContract(definition) {
+    const { annotations, ...rest } = definition;
+    return {
+        ...rest,
+        annotations: {
+            ...DEFAULT_ANNOTATIONS,
+            ...annotations,
+        },
+    };
+}
+function combineAnnotations(...annotations) {
+    const merged = {};
+    for (const annotation of annotations) {
+        Object.assign(merged, annotation);
+    }
+    return merged;
+}
+const TOOL_DEFINITIONS = [
     {
         name: 'store_memory',
         title: 'Store Memory',
         description: 'Store single memory. Returns hash. Idempotent (created: false if exists). Prefer store_memories.',
         inputSchema: StoreMemoryInputSchema,
         outputSchema: StoreResultSchema,
-        annotations: {
-            readOnlyHint: false,
-            idempotentHint: true,
-            destructiveHint: false,
-            openWorldHint: false,
-        },
+        annotations: IDEMPOTENT_ANNOTATIONS,
     },
     {
         name: 'store_memories',
@@ -21,12 +48,7 @@ export const TOOL_CONTRACTS = [
         description: 'Store 1-50 memories atomically. Idempotent. Rolls back on error.',
         inputSchema: StoreMemoriesInputSchema,
         outputSchema: BatchResultSchema,
-        annotations: {
-            readOnlyHint: false,
-            idempotentHint: true,
-            destructiveHint: false,
-            openWorldHint: false,
-        },
+        annotations: IDEMPOTENT_ANNOTATIONS,
     },
     {
         name: 'get_memory',
@@ -34,11 +56,7 @@ export const TOOL_CONTRACTS = [
         description: 'Retrieve memory by SHA-256 hash. Returns E_NOT_FOUND if missing.',
         inputSchema: GetMemoryInputSchema,
         outputSchema: MemoryResultSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            openWorldHint: false,
-        },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'search_memories',
@@ -46,23 +64,15 @@ export const TOOL_CONTRACTS = [
         description: 'Full-text search (content+tags). Ranked, paginated. Alphanumeric/underscore only. Implicit AND.',
         inputSchema: SearchMemoriesInputSchema,
         outputSchema: SearchResultSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            openWorldHint: false,
-        },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'retrieve_context',
         title: 'Retrieve Context',
-        description: 'FTS search within token budget. Sorts by relevance/importance/recency. Returns truncated: true if limit hit.',
+        description: 'FTS search within token budget. Sorts by relevance/importance/recency. Supports importance and type filters. Returns truncated: true if limit hit.',
         inputSchema: RetrieveContextInputSchema,
         outputSchema: RetrieveContextResultSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            openWorldHint: false,
-        },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'recall',
@@ -70,23 +80,15 @@ export const TOOL_CONTRACTS = [
         description: 'FTS search + BFS traversal (depth hops). Returns memories+edges. Emits progress. Aborts on limit.',
         inputSchema: RecallInputSchema,
         outputSchema: RecallResultSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            openWorldHint: false,
-        },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'update_memory',
         title: 'Update Memory',
-        description: 'Update content/tags. Returns old+new hash. Cascade updates relationships.',
+        description: 'Update content and/or tags (at least one required). Returns old+new hash. Cascade updates relationships.',
         inputSchema: UpdateMemoryInputSchema,
         outputSchema: UpdateResultSchema,
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: true,
-            openWorldHint: false,
-        },
+        annotations: DESTRUCTIVE_ANNOTATIONS,
     },
     {
         name: 'delete_memory',
@@ -94,12 +96,7 @@ export const TOOL_CONTRACTS = [
         description: 'Delete memory by hash. Cascade deletes relationships. Idempotent.',
         inputSchema: DeleteMemoryInputSchema,
         outputSchema: DeleteResultSchema,
-        annotations: {
-            readOnlyHint: false,
-            idempotentHint: true,
-            destructiveHint: true,
-            openWorldHint: false,
-        },
+        annotations: combineAnnotations(DESTRUCTIVE_ANNOTATIONS, IDEMPOTENT_ANNOTATIONS),
     },
     {
         name: 'delete_memories',
@@ -107,11 +104,7 @@ export const TOOL_CONTRACTS = [
         description: 'Delete 1-50 memories atomically. Cascade deletes. Rolls back on error.',
         inputSchema: DeleteMemoriesInputSchema,
         outputSchema: BatchResultSchema,
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: true,
-            openWorldHint: false,
-        },
+        annotations: DESTRUCTIVE_ANNOTATIONS,
     },
     {
         name: 'create_relationship',
@@ -119,24 +112,15 @@ export const TOOL_CONTRACTS = [
         description: 'Create directed edge. Idempotent. Errors if endpoints missing.',
         inputSchema: CreateRelationshipInputSchema,
         outputSchema: CreateRelationshipResultSchema,
-        annotations: {
-            readOnlyHint: false,
-            idempotentHint: true,
-            destructiveHint: false,
-            openWorldHint: false,
-        },
+        annotations: IDEMPOTENT_ANNOTATIONS,
     },
     {
         name: 'delete_relationship',
         title: 'Delete Relationship',
-        description: 'Delete edge. Exact match required. Errors if missing.',
+        description: 'Delete edge. Exact match required. Idempotent (deleted: false if missing).',
         inputSchema: DeleteRelationshipInputSchema,
         outputSchema: DeleteRelationshipResultSchema,
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: true,
-            openWorldHint: false,
-        },
+        annotations: combineAnnotations(DESTRUCTIVE_ANNOTATIONS, IDEMPOTENT_ANNOTATIONS),
     },
     {
         name: 'get_relationships',
@@ -144,11 +128,7 @@ export const TOOL_CONTRACTS = [
         description: 'Get relationships for memory. Filter direction. Inlines related memory.',
         inputSchema: GetRelationshipsInputSchema,
         outputSchema: RelationshipResultSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            openWorldHint: false,
-        },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'memory_stats',
@@ -156,13 +136,10 @@ export const TOOL_CONTRACTS = [
         description: 'Get global stats: counts, timestamps, importance.',
         inputSchema: MemoryStatsInputSchema,
         outputSchema: StatsResultSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            openWorldHint: false,
-        },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
 ];
+export const TOOL_CONTRACTS = TOOL_DEFINITIONS.map(createToolContract);
 const TOOL_CONTRACTS_BY_NAME = new Map(TOOL_CONTRACTS.map((contract) => [contract.name, contract]));
 export function getToolContracts() {
     return TOOL_CONTRACTS;

package/dist/lib/tool-execution.d.ts

@@ -0,0 +1,13 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+interface BatchSummary {
+    succeeded: number;
+    failed: number;
+    matched: number;
+}
+interface BatchItemLike {
+    ok: boolean;
+}
+export declare function executeToolSafely(work: () => Promise<CallToolResult> | CallToolResult): Promise<CallToolResult>;
+export declare function summarizeBatch<T extends BatchItemLike>(items: readonly T[], isMatched: (item: T) => boolean): BatchSummary;
+export declare function executeLongRunningToolSafely(work: () => Promise<CallToolResult> | CallToolResult, onFinally?: () => Promise<void>): Promise<CallToolResult>;
+export {};