@j0hanz/memory-mcp 1.0.0 → 1.1.0

package/dist/lib/instructions.js

@@ -0,0 +1,96 @@
+import { getToolContracts } from './tool-contracts.js';
+const SHARED_CONSTRAINTS = [
+    'Idempotence: `store_memory` and `store_memories` return `created: false` if content+tags already exist.',
+    'Atomic Transactions: `store_memories` and `delete_memories` roll back entirely on unexpected errors.',
+    'Hash Changes: `update_memory` changes the hash when content or tags change. Relationships survive via CASCADE.',
+    'FTS Search Limits: Query terms matched individually (all-OR logic). Phrase operators and negation not supported.',
+    'Recall Limits: BFS traversal is bounded by env vars (RECALL_MAX_FRONTIER_SIZE, RECALL_MAX_EDGE_ROWS, RECALL_MAX_VISITED_NODES). Returns `aborted: true` with partial results when limits are hit.',
+];
+const ERROR_CODES = [
+    '| Code | Meaning |',
+    '| --- | --- |',
+    '| `E_NOT_FOUND` | Hash or relationship does not exist |',
+    '| `E_CONFLICT` | `update_memory` target content+tags already maps to an existing hash |',
+    '| `E_CANCELLED` | Request was cancelled |',
+    '| `E_UNKNOWN` | Unexpected internal error — retry once |',
+];
+const DATA_MODEL = `
+### Memory
+- \`hash\` — SHA-256 of \`(content + sorted tags)\`; deterministic; changes when content or tags change
+- \`content\` — Text; 1–100,000 chars
+- \`tags\` — Array; 1–100 tags; each 1–50 chars, no whitespace; minimum 1 required
+- \`memory_type\` — \`general\` | \`fact\` | \`plan\` | \`decision\` | \`reflection\` | \`lesson\` | \`error\` | \`gradient\` (default \`general\`)
+- \`importance\` — Integer 0–10 (default 0; 10 = critical)
+- \`created_at\`, \`updated_at\` — ISO 8601 timestamps
+
+### Relationship
+- Directed edge: \`from_hash -[relation_type]-> to_hash\`
+- \`relation_type\` — Free-form string, 1–50 chars, no whitespace
+- Suggested types: \`related_to\`, \`causes\`, \`depends_on\`, \`parent_of\`, \`child_of\`, \`supersedes\`, \`contradicts\`, \`supports\`, \`references\`
+- Both endpoints must exist before creating a relationship
+- Cascade-deleted when either endpoint memory is deleted
+- Cascade-updated when either endpoint hash changes (ON UPDATE CASCADE)
+`;
+const WORKFLOWS = `
+### Store and Link
+\`\`\`
+store_memories({ items: [...] })         → { items[].hash, succeeded, failed }
+create_relationship({ from_hash, to_hash, relation_type })  × N
+\`\`\`
+
+### Search and Read
+\`\`\`
+search_memories({ query, limit })        → { memories[], nextCursor }
+# or, for relationship navigation:
+recall({ query, depth: 1 })             → { memories[], graph[] }
+\`\`\`
+
+### Fill Context Window
+\`\`\`
+retrieve_context({ query, token_budget: 4000, strategy: 'relevance' })
+  → { memories[], estimated_tokens, truncated }
+\`\`\`
+
+### Update a Memory
+\`\`\`
+update_memory({ hash, content })         → { old_hash, new_hash }
+# Existing relationships auto-update to new_hash via CASCADE
+\`\`\`
+
+### Batch Delete
+\`\`\`
+delete_memories({ hashes: [...] })       → { items[].{ hash, deleted }, succeeded, failed }
+# deleted: false means hash not found — not an error
+\`\`\`
+`;
+let cachedInstructions;
+export function loadInstructions() {
+    if (cachedInstructions !== undefined) {
+        return cachedInstructions;
+    }
+    const contracts = getToolContracts();
+    const toolRows = contracts.map((c) => {
+        return `| \`${c.name}\` | ${c.description.split('.')[0] ?? ''} |`;
+    });
+    cachedInstructions = [
+        '# Memory MCP — Usage Guide',
+        '## Tool Routing',
+        '| Tool | Purpose |',
+        '| --- | --- |',
+        ...toolRows,
+        '',
+        '## Shared Constraints',
+        SHARED_CONSTRAINTS.map((c) => `- ${c}`).join('\n'),
+        '## Error Codes',
+        ERROR_CODES.join('\n'),
+        '## Data Model',
+        DATA_MODEL,
+        '## Common Workflows',
+        WORKFLOWS,
+        '## Resources',
+        '- `internal://instructions` — This document. Read for tool routing, error codes, and workflows.',
+        '- `memory://memories/{hash}` — Fetch a single memory by URI with hash auto-completion.',
+    ].join('\n\n');
+    return cachedInstructions;
+}
+//# sourceMappingURL=instructions.js.map

package/dist/lib/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/lib/instructions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,kBAAkB,GAAG;IACzB,yGAAyG;IACzG,sGAAsG;IACtG,gHAAgH;IAChH,kHAAkH;IAClH,mMAAmM;CACpM,CAAC;AAEF,MAAM,WAAW,GAAG;IAClB,oBAAoB;IACpB,eAAe;IACf,yDAAyD;IACzD,yFAAyF;IACzF,2CAA2C;IAC3C,0DAA0D;CAC3D,CAAC;AAEF,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;CAgBlB,CAAC;AAEF,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BjB,CAAC;AAEF,IAAI,kBAAsC,CAAC;AAE3C,MAAM,UAAU,gBAAgB;IAC9B,IAAI,kBAAkB,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IAED,MAAM,SAAS,GAAG,gBAAgB,EAAE,CAAC;IACrC,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACnC,OAAO,OAAO,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC;IACpE,CAAC,CAAC,CAAC;IAEH,kBAAkB,GAAG;QACnB,4BAA4B;QAC5B,iBAAiB;QACjB,oBAAoB;QACpB,eAAe;QACf,GAAG,QAAQ;QACX,EAAE;QACF,uBAAuB;QACvB,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAClD,gBAAgB;QAChB,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;QACtB,eAAe;QACf,UAAU;QACV,qBAAqB;QACrB,SAAS;QACT,cAAc;QACd,iGAAiG;QACjG,wFAAwF;KACzF,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAEf,OAAO,kBAAkB,CAAC;AAC5B,CAAC"}

package/dist/lib/mcp-utils.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error';
+export declare function logToolEvent(server: McpServer, logger: string, data: unknown, level?: LogLevel): Promise<void>;
+export declare function notifyMemoryResourceUpdated(server: McpServer, hash: string): Promise<void>;
+export {};
+//# sourceMappingURL=mcp-utils.d.ts.map

package/dist/lib/mcp-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-utils.d.ts","sourceRoot":"","sources":["../../src/lib/mcp-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,KAAK,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAElE,wBAAsB,YAAY,CAChC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,KAAK,GAAE,QAAiB,GACvB,OAAO,CAAC,IAAI,CAAC,CAUf;AAID,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/lib/mcp-utils.js

@@ -0,0 +1,26 @@
+export async function logToolEvent(server, logger, data, level = 'info') {
+    if (!server.isConnected()) {
+        return;
+    }
+    try {
+        await server.server.sendLoggingMessage({ level, logger, data });
+    }
+    catch {
+        // best-effort logging
+    }
+}
+const MEMORY_RESOURCE_URI_PREFIX = 'memory://memories/';
+export async function notifyMemoryResourceUpdated(server, hash) {
+    if (!server.isConnected()) {
+        return;
+    }
+    try {
+        await server.server.sendResourceUpdated({
+            uri: `${MEMORY_RESOURCE_URI_PREFIX}${hash}`,
+        });
+    }
+    catch {
+        // best-effort notification
+    }
+}
+//# sourceMappingURL=mcp-utils.js.map

package/dist/lib/mcp-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-utils.js","sourceRoot":"","sources":["../../src/lib/mcp-utils.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAiB,EACjB,MAAc,EACd,IAAa,EACb,QAAkB,MAAM;IAExB,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC;QAC1B,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,sBAAsB;IACxB,CAAC;AACH,CAAC;AAED,MAAM,0BAA0B,GAAG,oBAAoB,CAAC;AAExD,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,MAAiB,EACjB,IAAY;IAEZ,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC;QAC1B,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC;YACtC,GAAG,EAAE,GAAG,0BAA0B,GAAG,IAAI,EAAE;SAC5C,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,2BAA2B;IAC7B,CAAC;AACH,CAAC"}

package/dist/lib/pagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/lib/pagination.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,OAAO,EAAE,OAAO,CAAC;CAClB;AAwBD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CASnD;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAM5E"}
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/lib/pagination.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,OAAO,EAAE,OAAO,CAAC;CAClB;AAiCD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CASnD;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAM5E"}

package/dist/lib/pagination.js

@@ -1,21 +1,28 @@
 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 (typeof value !== 'object' || value === null) {
+    if (!isRecord(value)) {
         return false;
     }
     const { offset } = value;
-    return (typeof offset === 'number' &&
-        Number.isInteger(offset) &&
-        Number.isFinite(offset) &&
-        offset >= 0);
+    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');
+        throw new Error(INVALID_CURSOR_STRUCTURE_MESSAGE);
     }
     return parsed;
 }
@@ -35,6 +42,6 @@ export function splitPage(rows, limit) {
     if (rows.length > limit) {
         return { page: rows.slice(0, limit), hasMore: true };
     }
-    return { page: [...rows], hasMore: false };
+    return { page: rows.slice(), hasMore: false };
 }
 //# sourceMappingURL=pagination.js.map

package/dist/lib/pagination.js.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/lib/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,eAAe,GAAG,WAAW,CAAC;AAWpC,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,EAAE,MAAM,EAAE,GAAG,KAAgC,CAAC;IACpD,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC;QACxB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;QACvB,MAAM,IAAI,CAAC,CACZ,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAc;IACxC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC7D,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,OAAO,GAAkB,EAAE,MAAM,EAAE,CAAC;IAC1C,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,IAAI,CAAC;QACH,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,QAAQ,CAChB,SAAS,CAAC,aAAa,EACvB,GAAG,gBAAgB,oBAAoB,CACxC,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAI,IAAkB,EAAE,KAAa;IAC5D,IAAI,IAAI,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC;QACxB,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACvD,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/lib/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,eAAe,GAAG,WAAW,CAAC;AAUpC,MAAM,gCAAgC,GAAG,0BAA0B,CAAC;AAEpE,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAc;IAC1C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;QACvB,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QACtB,KAAK,IAAI,CAAC,CACX,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACzB,OAAO,oBAAoB,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAc;IACxC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC7D,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,OAAO,GAAkB,EAAE,MAAM,EAAE,CAAC;IAC1C,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,IAAI,CAAC;QACH,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,QAAQ,CAChB,SAAS,CAAC,aAAa,EACvB,GAAG,gBAAgB,oBAAoB,CACxC,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAI,IAAkB,EAAE,KAAa;IAC5D,IAAI,IAAI,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC;QACxB,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACvD,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAChD,CAAC"}

package/dist/lib/search-cursor.d.ts

@@ -0,0 +1,13 @@
+import type { MemoryFilters } from './search.js';
+export type DecodedSearchCursor = {
+    mode: 'keyset';
+    rank: number;
+    hash: string;
+} | {
+    mode: 'offset';
+    offset: number;
+};
+export declare function buildSearchCursorScope(query: string, filters: MemoryFilters): string;
+export declare function encodeSearchCursor(scope: string, rank: number, hash: string): string;
+export declare function decodeSearchCursor(cursor: string, expectedScope: string): DecodedSearchCursor;
+//# sourceMappingURL=search-cursor.d.ts.map

package/dist/lib/search-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-cursor.d.ts","sourceRoot":"","sources":["../../src/lib/search-cursor.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAmBjD,MAAM,MAAM,mBAAmB,GAC3B;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AA+DN,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,GACrB,MAAM,CAKR;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,MAAM,CASR;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,mBAAmB,CAuBrB"}

package/dist/lib/search-cursor.js

@@ -0,0 +1,89 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { createHash } from 'node:crypto';
+import { E_INVALID_CURSOR } from './errors.js';
+const CURSOR_ENCODING = 'base64url';
+const CURSOR_VERSION = 2;
+const CURSOR_KIND = 'fts-keyset';
+const CURSOR_SCOPE_HASH_LENGTH = 24;
+function invalidCursor(reason) {
+    return new McpError(ErrorCode.InvalidParams, `${E_INVALID_CURSOR}: ${reason}`);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isKeysetCursorPayload(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (value['v'] === CURSOR_VERSION &&
+        value['kind'] === CURSOR_KIND &&
+        typeof value['scope'] === 'string' &&
+        typeof value['rank'] === 'number' &&
+        Number.isFinite(value['rank']) &&
+        typeof value['hash'] === 'string' &&
+        /^[a-f0-9]{64}$/.test(value['hash']));
+}
+function isLegacyOffsetCursorPayload(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const { offset } = value;
+    return (typeof offset === 'number' &&
+        Number.isInteger(offset) &&
+        Number.isFinite(offset) &&
+        offset >= 0);
+}
+function parseCursorPayload(cursor) {
+    try {
+        const json = Buffer.from(cursor, CURSOR_ENCODING).toString();
+        return JSON.parse(json);
+    }
+    catch {
+        throw invalidCursor('malformed cursor');
+    }
+}
+function toScopeInput(query, filters) {
+    return JSON.stringify({
+        query,
+        min_importance: filters.min_importance ?? null,
+        max_importance: filters.max_importance ?? null,
+        memory_type: filters.memory_type ?? null,
+    });
+}
+export function buildSearchCursorScope(query, filters) {
+    return createHash('sha256')
+        .update(toScopeInput(query, filters))
+        .digest('hex')
+        .slice(0, CURSOR_SCOPE_HASH_LENGTH);
+}
+export function encodeSearchCursor(scope, rank, hash) {
+    const payload = {
+        v: CURSOR_VERSION,
+        kind: CURSOR_KIND,
+        scope,
+        rank,
+        hash,
+    };
+    return Buffer.from(JSON.stringify(payload)).toString(CURSOR_ENCODING);
+}
+export function decodeSearchCursor(cursor, expectedScope) {
+    const payload = parseCursorPayload(cursor);
+    if (isKeysetCursorPayload(payload)) {
+        if (payload.scope !== expectedScope) {
+            throw invalidCursor('cursor does not match current query or filters');
+        }
+        return {
+            mode: 'keyset',
+            rank: payload.rank,
+            hash: payload.hash,
+        };
+    }
+    if (isLegacyOffsetCursorPayload(payload)) {
+        return {
+            mode: 'offset',
+            offset: payload.offset,
+        };
+    }
+    throw invalidCursor('malformed cursor');
+}
+//# sourceMappingURL=search-cursor.js.map

package/dist/lib/search-cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-cursor.js","sourceRoot":"","sources":["../../src/lib/search-cursor.ts"],"names":[],"mappings":"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"}

package/dist/lib/search.d.ts

@@ -1,4 +1,6 @@
 import type { SQLInputValue } from 'node:sqlite';
+import type { TypedDb } from '../db/typed.js';
+import type { MemoryRow } from './types.js';
 export declare function sanitizeFtsQuery(query: string): string;
 export interface MemoryFilters {
     min_importance?: number;
@@ -9,6 +11,20 @@ export interface FilterClauses {
     clauses: string[];
     params: SQLInputValue[];
 }
+export type SearchCursorState = {
+    mode: 'offset';
+    offset: number;
+} | {
+    mode: 'keyset';
+    rank: number;
+    hash: string;
+};
 export declare function buildFilterClauses(filters: MemoryFilters): FilterClauses;
 export declare function buildAndWhereClause(clauses: readonly string[]): string;
+export declare function loadRankedSearchRows(db: TypedDb, query: string, limit: number, cursor: SearchCursorState | undefined, filters: MemoryFilters): MemoryRow[];
+export declare function toMemoryFilters(params: {
+    min_importance?: number | undefined;
+    max_importance?: number | undefined;
+    memory_type?: string | undefined;
+}): MemoryFilters;
 //# sourceMappingURL=search.d.ts.map

package/dist/lib/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/lib/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AASjD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAgBxE;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAMtE"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/lib/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAW5C,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAWN,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAaxE;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAMtE;AAuBD,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,OAAO,EACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,iBAAiB,GAAG,SAAS,EACrC,OAAO,EAAE,aAAa,GACrB,SAAS,EAAE,CAoBb;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACtC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,GAAG,aAAa,CAUhB"}

package/dist/lib/search.js

@@ -1,5 +1,7 @@
 const FTS_SAFE_TOKEN_REGEX = /[A-Za-z0-9_]+/g;
 const FTS_EMPTY_QUERY_FALLBACK = '"__mcp_no_results__"';
+const BASE_RANKED_SEARCH_SQL = `SELECT m.*, memories_fts.rank AS rank FROM memories m
+         JOIN memories_fts ON memories_fts.rowid = m.rowid`;
 function tokenizeQuery(query) {
     return query.match(FTS_SAFE_TOKEN_REGEX) ?? [];
 }
@@ -10,20 +12,20 @@ export function sanitizeFtsQuery(query) {
     }
     return tokens.map((token) => `"${token}"`).join(' ');
 }
+const FILTER_RULES = [
+    { key: 'min_importance', clause: 'm.importance >= ?' },
+    { key: 'max_importance', clause: 'm.importance <= ?' },
+    { key: 'memory_type', clause: 'm.memory_type = ?' },
+];
 export function buildFilterClauses(filters) {
     const clauses = [];
     const params = [];
-    if (filters.min_importance != null) {
-        clauses.push('m.importance >= ?');
-        params.push(filters.min_importance);
-    }
-    if (filters.max_importance != null) {
-        clauses.push('m.importance <= ?');
-        params.push(filters.max_importance);
-    }
-    if (filters.memory_type != null) {
-        clauses.push('m.memory_type = ?');
-        params.push(filters.memory_type);
+    for (const rule of FILTER_RULES) {
+        const value = filters[rule.key];
+        if (value != null) {
+            clauses.push(rule.clause);
+            params.push(value);
+        }
     }
     return { clauses, params };
 }
@@ -31,6 +33,45 @@ export function buildAndWhereClause(clauses) {
     if (clauses.length === 0) {
         return '';
     }
-    return ` ${clauses.map((clause) => `AND ${clause}`).join(' ')}`;
+    return clauses.map((clause) => ` AND ${clause}`).join('');
+}
+function buildRankedSearchSql(whereExtra, cursor) {
+    if (!cursor || cursor.mode === 'offset') {
+        return `${BASE_RANKED_SEARCH_SQL}
+         WHERE memories_fts MATCH ?${whereExtra}
+         ORDER BY memories_fts.rank, m.hash
+         LIMIT ? OFFSET ?`;
+    }
+    return `${BASE_RANKED_SEARCH_SQL}
+       WHERE memories_fts MATCH ?${whereExtra}
+         AND (
+           memories_fts.rank > ?
+           OR (memories_fts.rank = ? AND m.hash > ?)
+         )
+       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') {
+        const offset = cursor?.offset ?? 0;
+        return stmt.all(ftsQuery, ...filter.params, limit + 1, offset);
+    }
+    return stmt.all(ftsQuery, ...filter.params, cursor.rank, cursor.rank, cursor.hash, limit + 1);
+}
+export function toMemoryFilters(params) {
+    return {
+        ...(params.min_importance != null
+            ? { min_importance: params.min_importance }
+            : {}),
+        ...(params.max_importance != null
+            ? { max_importance: params.max_importance }
+            : {}),
+        ...(params.memory_type != null ? { memory_type: params.memory_type } : {}),
+    };
 }
 //# sourceMappingURL=search.js.map

package/dist/lib/search.js.map

@@ -1 +1 @@
-{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/lib/search.ts"],"names":[],"mappings":"AAEA,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAC9C,MAAM,wBAAwB,GAAG,sBAAsB,CAAC;AAExD,SAAS,aAAa,CAAC,KAAa;IAClC,OAAO,KAAK,CAAC,KAAK,CAAC,oBAAoB,CAAC,IAAI,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,wBAAwB,CAAC;IAClC,CAAC;IAED,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACvD,CAAC;AAaD,MAAM,UAAU,kBAAkB,CAAC,OAAsB;IACvD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,IAAI,OAAO,CAAC,cAAc,IAAI,IAAI,EAAE,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,OAAO,CAAC,cAAc,IAAI,IAAI,EAAE,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,OAAO,CAAC,WAAW,IAAI,IAAI,EAAE,CAAC;QAChC,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAA0B;IAC5D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AAClE,CAAC"}
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/lib/search.ts"],"names":[],"mappings":"AAKA,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAC9C,MAAM,wBAAwB,GAAG,sBAAsB,CAAC;AACxD,MAAM,sBAAsB,GAAG;2DAC4B,CAAC;AAE5D,SAAS,aAAa,CAAC,KAAa;IAClC,OAAO,KAAK,CAAC,KAAK,CAAC,oBAAoB,CAAC,IAAI,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,wBAAwB,CAAC;IAClC,CAAC;IAED,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACvD,CAAC;AAwBD,MAAM,YAAY,GAGZ;IACJ,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,EAAE,mBAAmB,EAAE;IACtD,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,EAAE,mBAAmB,EAAE;IACtD,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,mBAAmB,EAAE;CACpD,CAAC;AAEF,MAAM,UAAU,kBAAkB,CAAC,OAAsB;IACvD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAoB,EAAE,CAAC;IAEnC,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;YAClB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAA0B;IAC5D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,oBAAoB,CAC3B,UAAkB,EAClB,MAAqC;IAErC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,GAAG,sBAAsB;qCACC,UAAU;;0BAErB,CAAC;IACzB,CAAC;IAED,OAAO,GAAG,sBAAsB;mCACC,UAAU;;;;;;eAM9B,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,EAAW,EACX,KAAa,EACb,KAAa,EACb,MAAqC,EACrC,OAAsB;IAEtB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,UAAU,GAAG,mBAAmB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACvD,MAAM,GAAG,GAAG,oBAAoB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,EAAE,CAAC,WAAW,CAAY,GAAG,CAAC,CAAC;IAE5C,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,IAAI,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,CACb,QAAQ,EACR,GAAG,MAAM,CAAC,MAAM,EAChB,MAAM,CAAC,IAAI,EACX,MAAM,CAAC,IAAI,EACX,MAAM,CAAC,IAAI,EACX,KAAK,GAAG,CAAC,CACV,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAI/B;IACC,OAAO;QACL,GAAG,CAAC,MAAM,CAAC,cAAc,IAAI,IAAI;YAC/B,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE;YAC3C,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,MAAM,CAAC,cAAc,IAAI,IAAI;YAC/B,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE;YAC3C,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3E,CAAC;AACJ,CAAC"}

package/dist/lib/sql.d.ts

@@ -0,0 +1,17 @@
+/** Shared SQL statement constants. Centralised here to ensure all callers
+ *  cache the same string key via `prepareOnce`. */
+/** Insert or silently ignore a duplicate memory (content+tags hash is PK). */
+export declare const INSERT_MEMORY_SQL = "INSERT OR IGNORE INTO memories (hash, content, tags, memory_type, importance, created_at, updated_at)\n  VALUES (?, ?, ?, ?, ?, ?, ?)";
+/** Delete one memory row by hash. Relationships cascade via FK. */
+export declare const DELETE_MEMORY_SQL = "DELETE FROM memories WHERE hash = ?";
+/** Fetch a full memory row by hash. */
+export declare const SELECT_MEMORY_BY_HASH_SQL = "SELECT * FROM memories WHERE hash = ?";
+/** Check existence: returns only the hash column to minimise data transfer. */
+export declare const SELECT_MEMORY_HASH_SQL = "SELECT hash FROM memories WHERE hash = ?";
+/** Aggregate memory store stats in a single scan. */
+export declare const MEMORY_AGGREGATE_SQL = "SELECT COUNT(*) AS total, MIN(created_at) AS oldest, MAX(created_at) AS newest, AVG(importance) AS avg_importance FROM memories";
+/** Total relationship count. */
+export declare const RELATIONSHIP_COUNT_SQL = "SELECT COUNT(*) AS total FROM relationships";
+/** Per-type memory breakdown. */
+export declare const TYPE_COUNTS_SQL = "SELECT memory_type, COUNT(*) AS count FROM memories GROUP BY memory_type ORDER BY count DESC";
+//# sourceMappingURL=sql.d.ts.map

package/dist/lib/sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/lib/sql.ts"],"names":[],"mappings":"AAAA;mDACmD;AAEnD,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,0IACC,CAAC;AAEhC,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,wCAAwC,CAAC;AAEvE,uCAAuC;AACvC,eAAO,MAAM,yBAAyB,0CACG,CAAC;AAE1C,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,6CACS,CAAC;AAE7C,qDAAqD;AACrD,eAAO,MAAM,oBAAoB,oIACkG,CAAC;AAEpI,gCAAgC;AAChC,eAAO,MAAM,sBAAsB,gDACY,CAAC;AAEhD,iCAAiC;AACjC,eAAO,MAAM,eAAe,iGACoE,CAAC"}

package/dist/lib/sql.js

@@ -0,0 +1,18 @@
+/** Shared SQL statement constants. Centralised here to ensure all callers
+ *  cache the same string key via `prepareOnce`. */
+/** Insert or silently ignore a duplicate memory (content+tags hash is PK). */
+export const INSERT_MEMORY_SQL = `INSERT OR IGNORE INTO memories (hash, content, tags, memory_type, importance, created_at, updated_at)
+  VALUES (?, ?, ?, ?, ?, ?, ?)`;
+/** Delete one memory row by hash. Relationships cascade via FK. */
+export const DELETE_MEMORY_SQL = 'DELETE FROM memories WHERE hash = ?';
+/** Fetch a full memory row by hash. */
+export const SELECT_MEMORY_BY_HASH_SQL = 'SELECT * FROM memories WHERE hash = ?';
+/** Check existence: returns only the hash column to minimise data transfer. */
+export const SELECT_MEMORY_HASH_SQL = 'SELECT hash FROM memories WHERE hash = ?';
+/** Aggregate memory store stats in a single scan. */
+export const MEMORY_AGGREGATE_SQL = 'SELECT COUNT(*) AS total, MIN(created_at) AS oldest, MAX(created_at) AS newest, AVG(importance) AS avg_importance FROM memories';
+/** Total relationship count. */
+export const RELATIONSHIP_COUNT_SQL = 'SELECT COUNT(*) AS total FROM relationships';
+/** Per-type memory breakdown. */
+export const TYPE_COUNTS_SQL = 'SELECT memory_type, COUNT(*) AS count FROM memories GROUP BY memory_type ORDER BY count DESC';
+//# sourceMappingURL=sql.js.map

package/dist/lib/sql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.js","sourceRoot":"","sources":["../../src/lib/sql.ts"],"names":[],"mappings":"AAAA;mDACmD;AAEnD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,iBAAiB,GAAG;+BACF,CAAC;AAEhC,mEAAmE;AACnE,MAAM,CAAC,MAAM,iBAAiB,GAAG,qCAAqC,CAAC;AAEvE,uCAAuC;AACvC,MAAM,CAAC,MAAM,yBAAyB,GACpC,uCAAuC,CAAC;AAE1C,+EAA+E;AAC/E,MAAM,CAAC,MAAM,sBAAsB,GACjC,0CAA0C,CAAC;AAE7C,qDAAqD;AACrD,MAAM,CAAC,MAAM,oBAAoB,GAC/B,iIAAiI,CAAC;AAEpI,gCAAgC;AAChC,MAAM,CAAC,MAAM,sBAAsB,GACjC,6CAA6C,CAAC;AAEhD,iCAAiC;AACjC,MAAM,CAAC,MAAM,eAAe,GAC1B,8FAA8F,CAAC"}

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

@@ -0,0 +1,18 @@
+import { type z } from 'zod/v4';
+export interface ToolContract {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodType;
+    outputSchema: z.ZodType;
+    annotations: {
+        readOnlyHint?: boolean;
+        idempotentHint?: boolean;
+        destructiveHint?: boolean;
+        openWorldHint?: boolean;
+    };
+}
+export declare const TOOL_CONTRACTS: ToolContract[];
+export declare function getToolContracts(): ToolContract[];
+export declare function getToolContract(name: string): ToolContract;
+//# sourceMappingURL=tool-contracts.d.ts.map

package/dist/lib/tool-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-contracts.d.ts","sourceRoot":"","sources":["../../src/lib/tool-contracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,QAAQ,CAAC;AAgChC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC;IACvB,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC;IACxB,WAAW,EAAE;QACX,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;CACH;AAED,eAAO,MAAM,cAAc,EAAE,YAAY,EAsHxC,CAAC;AAEF,wBAAgB,gBAAgB,IAAI,YAAY,EAAE,CAEjD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAM1D"}