@raviolelabs/engram-mcp 0.4.5 → 0.5.1

package/dist/memory/public/tools.js

@@ -8,12 +8,12 @@ import { extractWikilinks } from '../core/wikilinks.js';
 const log = createLogger('public-tools');
 // ── Per-type weights for OSS recall calibration ───────────────────────────────
 const TYPE_WEIGHTS = {
-    notes: 1.00, // user-curated, high signal
+    notes: 1.0, // user-curated, high signal
     conversations: 0.95, // recent, dialog context
-    drive: 0.90, // structured documents
-    notion: 0.90,
+    drive: 0.9, // structured documents
+    notion: 0.9,
     obsidian: 0.95, // user notes, high signal
-    audio: 0.80, // transcripts can be noisy
+    audio: 0.8, // transcripts can be noisy
     youtube: 0.75, // longer, lower signal density
 };
 // Recency boost (exp decay, half-life ~180 days)
@@ -87,8 +87,7 @@ export function buildPublicTools(store, config) {
                 }
                 const contentBytes = Buffer.byteLength(content, 'utf-8');
                 if (contentBytes > MAX_CONTENT_BYTES) {
-                    throw new Error(`content too large (${Math.round(contentBytes / 1024)} KB) — max ${MAX_CONTENT_BYTES / 1024} KB. ` +
-                        `Split into multiple remember() calls or use ingest() for large files.`);
+                    throw new Error(`content too large (${Math.round(contentBytes / 1024)} KB) — max ${MAX_CONTENT_BYTES / 1024} KB. ` + `Split into multiple remember() calls or use ingest() for large files.`);
                 }
                 const contentHash = createHash('sha256').update(content).digest('hex');
                 // Idempotency: check for existing memory with same content_hash + type
@@ -352,7 +351,7 @@ export function buildPublicTools(store, config) {
                 'WHEN: "what else is connected to this?", building a memory graph, or exploring a topic cluster.',
                 'Use recall instead of relate when starting from a query string.',
                 'ANTI-LOOP: if returns empty, this memory has no semantic neighbors above the threshold — DO NOT retry.',
-                'Try recall with the memory\'s tags instead.',
+                "Try recall with the memory's tags instead.",
                 'RETURNS: array of { id, type, score, snippet, title }.',
             ].join(' '),
             inputSchema: {
@@ -670,7 +669,12 @@ export function buildPublicTools(store, config) {
                             config: { mimeType: meta.mimeType },
                         });
                         if (driveAlreadyExists) {
-                            return { watched: true, already_watching: true, source_id: sourceId, display_name: meta.name };
+                            return {
+                                watched: true,
+                                already_watching: true,
+                                source_id: sourceId,
+                                display_name: meta.name,
+                            };
                         }
                         const content = await downloadFileContent(targetId, meta.mimeType, config);
                         if (content) {
@@ -690,7 +694,12 @@ export function buildPublicTools(store, config) {
                             display_name: meta.title,
                         });
                         if (notionAlreadyExists) {
-                            return { watched: true, already_watching: true, source_id: sourceId, display_name: meta.title };
+                            return {
+                                watched: true,
+                                already_watching: true,
+                                source_id: sourceId,
+                                display_name: meta.title,
+                            };
                         }
                         const content = await fetchPageText(meta.id);
                         const item = buildNotionItem({ metadata: meta, content, embeddingModel });
@@ -710,7 +719,12 @@ export function buildPublicTools(store, config) {
                         });
                         if (ytAlreadyExists) {
                             const existingSource = sourceRegistry.get(sourceId);
-                            return { watched: true, already_watching: true, source_id: sourceId, display_name: existingSource?.display_name ?? channelName };
+                            return {
+                                watched: true,
+                                already_watching: true,
+                                source_id: sourceId,
+                                display_name: existingSource?.display_name ?? channelName,
+                            };
                         }
                         return { watched: true, source_id: sourceId, display_name: channelName };
                     }
@@ -726,7 +740,12 @@ export function buildPublicTools(store, config) {
                             config: { vault_path: vaultPath },
                         });
                         if (obsidianAlreadyExists) {
-                            return { watched: true, already_watching: true, source_id: sourceId, display_name: path.default.basename(vaultPath) };
+                            return {
+                                watched: true,
+                                already_watching: true,
+                                source_id: sourceId,
+                                display_name: path.default.basename(vaultPath),
+                            };
                         }
                         const files = await readVault(vaultPath);
                         for (const file of files) {
@@ -735,7 +754,12 @@ export function buildPublicTools(store, config) {
                             await store.insert(item);
                         }
                         sourceRegistry.recordSync(sourceId, new Date().toISOString());
-                        return { watched: true, source_id: sourceId, display_name: path.default.basename(vaultPath), files_indexed: files.length };
+                        return {
+                            watched: true,
+                            source_id: sourceId,
+                            display_name: path.default.basename(vaultPath),
+                            files_indexed: files.length,
+                        };
                     }
                     default:
                         throw new Error(`Unknown source_type: ${sourceType}`);
@@ -903,7 +927,11 @@ export function buildPublicTools(store, config) {
                         flow.waitForCallback.then(() => ({ connected: true })),
                         new Promise((resolve) => setTimeout(() => resolve({ timeout: true }), 300_000)),
                     ]);
-                    return { auth_url: flow.authUrl, instructions: 'Open auth_url in your browser and authorize. Then confirm here.', ...result };
+                    return {
+                        auth_url: flow.authUrl,
+                        instructions: 'Open auth_url in your browser and authorize. Then confirm here.',
+                        ...result,
+                    };
                 }
                 catch (e) {
                     const msg = e instanceof Error ? e.message : String(e);
@@ -929,8 +957,15 @@ export function buildPublicTools(store, config) {
             inputSchema: {
                 type: 'object',
                 properties: {
-                    query: { type: 'string', description: 'Google Drive search query (e.g. "name contains \'report\'".' },
-                    limit: { type: 'number', default: 25, description: 'Max files to return (default 25, max 100).' },
+                    query: {
+                        type: 'string',
+                        description: 'Google Drive search query (e.g. "name contains \'report\'".',
+                    },
+                    limit: {
+                        type: 'number',
+                        default: 25,
+                        description: 'Max files to return (default 25, max 100).',
+                    },
                 },
             },
             handler: async (args) => {
@@ -994,10 +1029,17 @@ export function buildPublicTools(store, config) {
                 try {
                     const flow = await startNotionOAuthFlow(config);
                     const result = await Promise.race([
-                        flow.waitForCallback.then((t) => ({ connected: true, workspace: t.workspace_name })),
+                        flow.waitForCallback.then((t) => ({
+                            connected: true,
+                            workspace: t.workspace_name,
+                        })),
                         new Promise((resolve) => setTimeout(() => resolve({ timeout: true }), 300_000)),
                     ]);
-                    return { auth_url: flow.authUrl, instructions: 'Open auth_url in your browser and authorize. Then confirm here.', ...result };
+                    return {
+                        auth_url: flow.authUrl,
+                        instructions: 'Open auth_url in your browser and authorize. Then confirm here.',
+                        ...result,
+                    };
                 }
                 catch (e) {
                     const msg = e instanceof Error ? e.message : String(e);
@@ -1031,7 +1073,11 @@ export function buildPublicTools(store, config) {
                 const { searchPages } = await import('../modules/notion/connector.js');
                 const { isNotionConnected } = await import('../modules/notion/oauth.js');
                 if (!isNotionConnected())
-                    return { error: 'notion_not_connected', message: 'Notion is not connected.', hint: 'Call connect_notion first to authenticate with Notion.' };
+                    return {
+                        error: 'notion_not_connected',
+                        message: 'Notion is not connected.',
+                        hint: 'Call connect_notion first to authenticate with Notion.',
+                    };
                 return await searchPages(args.query ?? '', args.limit ?? 25);
             },
         },
@@ -1041,7 +1087,7 @@ export function buildPublicTools(store, config) {
             description: [
                 'Bulk-import a YouTube playlist (public URL). Imports all videos as memory items.',
                 'SLOW: can take 1-30 minutes depending on playlist size.',
-                'ANTI-LOOP: DO NOT call twice for the same playlist — duplicates are deduped but the API hammering wastes the user\'s YouTube quota.',
+                "ANTI-LOOP: DO NOT call twice for the same playlist — duplicates are deduped but the API hammering wastes the user's YouTube quota.",
                 'For individual YouTube videos, use ingest(youtube_url) instead.',
                 'Poll get_ingest_status(job_id) to track progress.',
                 'RETURNS: { job_id?, status, imported?, errors? } — large playlists run as async job.',
@@ -1118,7 +1164,10 @@ export function buildPublicTools(store, config) {
                         return [];
                     }
                 }));
-                let candidates = allResults.flat().sort((a, b) => b.score - a.score).slice(0, limit);
+                let candidates = allResults
+                    .flat()
+                    .sort((a, b) => b.score - a.score)
+                    .slice(0, limit);
                 // Apply lookback filter if specified
                 if (lookbackDays !== undefined) {
                     const cutoff = Date.now() - lookbackDays * 24 * 60 * 60 * 1000;
@@ -1326,7 +1375,10 @@ export function buildPublicTools(store, config) {
                         return [];
                     }
                 }));
-                let candidates = allResults.flat().sort((a, b) => b.score - a.score).slice(0, 50);
+                let candidates = allResults
+                    .flat()
+                    .sort((a, b) => b.score - a.score)
+                    .slice(0, 50);
                 // Apply lookback filter
                 candidates = candidates.filter((c) => Date.parse(c.memory.properties.created_at) >= cutoff);
                 if (candidates.length === 0) {
@@ -1438,6 +1490,206 @@ export function buildPublicTools(store, config) {
                 return { deleted: typeName };
             },
         },
+        // ── skip / unskip / pin / unpin / set_importance ─────────────────────────
+        // Recall-signal tools. Cheap writes to the memories table — no embedding,
+        // no chunking, no vector index touch. Used by users (via dashboard) and by
+        // agents to teach the system what to surface vs hide vs preserve forever.
+        {
+            name: 'skip',
+            description: [
+                'Mark a memory as "not useful right now" — multiplies its skip_penalty by 0.2.',
+                "WHEN: a recall result is genuinely irrelevant and the agent shouldn't surface it again on similar queries.",
+                'NOT for deletion — the memory stays in storage and unskip() restores full rank.',
+                'IDEMPOTENT: calling twice multiplies penalty again (0.2 → 0.04). Use sparingly.',
+                'RETURNS: { id, skip_penalty: <new value> }.',
+            ].join(' '),
+            inputSchema: {
+                type: 'object',
+                properties: { id: { type: 'string' } },
+                required: ['id'],
+            },
+            handler: async (args) => {
+                const id = args.id;
+                const { getDb } = await import('../../db/index.js');
+                const db = getDb();
+                const result = db
+                    .prepare(`UPDATE memories SET skip_penalty = MAX(0.001, skip_penalty * 0.2) WHERE id = ?`)
+                    .run(id);
+                if (result.changes === 0)
+                    return { error: 'not_found', id };
+                const row = db.prepare(`SELECT skip_penalty FROM memories WHERE id = ?`).get(id);
+                return { id, skip_penalty: row?.skip_penalty };
+            },
+        },
+        {
+            name: 'unskip',
+            description: [
+                'Restore a previously skipped memory to full recall rank (skip_penalty = 1.0).',
+                'WHEN: the user corrects a wrongly skipped item, or you realise a "not useful" call was a mistake.',
+                'IDEMPOTENT: returns success even if the memory was never skipped.',
+                'RETURNS: { id, skip_penalty: 1.0 }.',
+            ].join(' '),
+            inputSchema: {
+                type: 'object',
+                properties: { id: { type: 'string' } },
+                required: ['id'],
+            },
+            handler: async (args) => {
+                const id = args.id;
+                const { getDb } = await import('../../db/index.js');
+                const r = getDb().prepare(`UPDATE memories SET skip_penalty = 1.0 WHERE id = ?`).run(id);
+                if (r.changes === 0)
+                    return { error: 'not_found', id };
+                return { id, skip_penalty: 1.0 };
+            },
+        },
+        {
+            name: 'pin',
+            description: [
+                'Pin a memory — exempts it from time-decay forever (until unpinned).',
+                'WHEN: critical preference, identity fact, or a piece of context that must never fade.',
+                'Pinned memories ignore the importance × half-life decay curve.',
+                'IDEMPOTENT: returns {pinned: true} regardless of prior state.',
+                'RETURNS: { id, pinned: true }.',
+            ].join(' '),
+            inputSchema: {
+                type: 'object',
+                properties: { id: { type: 'string' } },
+                required: ['id'],
+            },
+            handler: async (args) => {
+                const id = args.id;
+                const { getDb } = await import('../../db/index.js');
+                const r = getDb().prepare(`UPDATE memories SET pinned = 1 WHERE id = ?`).run(id);
+                if (r.changes === 0)
+                    return { error: 'not_found', id };
+                return { id, pinned: true };
+            },
+        },
+        {
+            name: 'unpin',
+            description: [
+                'Remove the pin from a memory — it resumes normal time-decay based on its importance.',
+                'IDEMPOTENT: returns {pinned: false} regardless of prior state.',
+                'RETURNS: { id, pinned: false }.',
+            ].join(' '),
+            inputSchema: {
+                type: 'object',
+                properties: { id: { type: 'string' } },
+                required: ['id'],
+            },
+            handler: async (args) => {
+                const id = args.id;
+                const { getDb } = await import('../../db/index.js');
+                const r = getDb().prepare(`UPDATE memories SET pinned = 0 WHERE id = ?`).run(id);
+                if (r.changes === 0)
+                    return { error: 'not_found', id };
+                return { id, pinned: false };
+            },
+        },
+        {
+            name: 'set_importance',
+            description: [
+                "Set a memory's importance level — affects decay half-life (high=90d, medium=30d, low=14d) and recall ranking.",
+                'WHEN: user marks something as critical, or the agent decides a memory deserves more/less prominence.',
+                'Default importance is set automatically at remember() time based on intent classification (preferences + corrections → high).',
+                'IDEMPOTENT.',
+                'RETURNS: { id, importance }.',
+            ].join(' '),
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    id: { type: 'string' },
+                    level: { type: 'string', enum: ['high', 'medium', 'low'] },
+                },
+                required: ['id', 'level'],
+            },
+            handler: async (args) => {
+                const id = args.id;
+                const level = args.level;
+                if (!['high', 'medium', 'low'].includes(level)) {
+                    return { error: 'invalid_level', message: 'level must be high|medium|low' };
+                }
+                const { getDb } = await import('../../db/index.js');
+                const r = getDb().prepare(`UPDATE memories SET importance = ? WHERE id = ?`).run(level, id);
+                if (r.changes === 0)
+                    return { error: 'not_found', id };
+                return { id, importance: level };
+            },
+        },
+        // ── recall_chain ────────────────────────────────────────────────────────
+        // Graph traversal over wikilinks + related_ids — our answer to Neo4j-backed
+        // graph memory features in competing products. No external graph DB needed
+        // because we already store the edges in the memory row's related_ids array.
+        {
+            name: 'recall_chain',
+            description: [
+                'Traverse the memory graph from a starting memory id, following wikilinks + related_ids up to `depth` hops.',
+                'WHEN: "show me the chain of reasoning that led here", "what memories are connected to this decision?".',
+                'Returns memories grouped by hop distance — direct neighbors at depth 1, their neighbors at depth 2, etc.',
+                'ANTI-LOOP: depth is capped at 4 (silently). Memories are deduplicated across hops.',
+                'RETURNS: { root: id, chain: [{ depth, memories: [{ id, type, title, score }] }] }.',
+            ].join(' '),
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    id: { type: 'string', description: 'Starting memory id.' },
+                    depth: { type: 'number', default: 2, description: 'Max hop distance (capped at 4).' },
+                    limit_per_hop: { type: 'number', default: 10 },
+                },
+                required: ['id'],
+            },
+            handler: async (args) => {
+                const rootId = args.id;
+                const maxDepth = Math.min(4, Math.max(1, args.depth ?? 2));
+                const limitPerHop = Math.max(1, args.limit_per_hop ?? 10);
+                const root = store.getById(rootId);
+                if (!root)
+                    return { error: 'not_found', id: rootId };
+                const visited = new Set([rootId]);
+                const chain = [];
+                let frontier = [rootId];
+                for (let d = 1; d <= maxDepth; d++) {
+                    const nextFrontier = [];
+                    for (const fid of frontier) {
+                        const m = store.getById(fid);
+                        if (!m)
+                            continue;
+                        for (const wl of m.wikilinks ?? []) {
+                            const targetId = wl;
+                            if (!visited.has(targetId)) {
+                                visited.add(targetId);
+                                nextFrontier.push({ id: targetId, via: 'wikilink' });
+                            }
+                        }
+                        for (const rid of m.related_ids ?? []) {
+                            if (!visited.has(rid)) {
+                                visited.add(rid);
+                                nextFrontier.push({ id: rid, via: 'related' });
+                            }
+                        }
+                    }
+                    if (nextFrontier.length === 0)
+                        break;
+                    const hopMemories = [];
+                    for (const f of nextFrontier.slice(0, limitPerHop)) {
+                        const m = store.getById(f.id);
+                        if (!m)
+                            continue;
+                        hopMemories.push({ id: m.id, type: m.type, title: m.properties.title, via: f.via });
+                    }
+                    if (hopMemories.length === 0)
+                        break;
+                    chain.push({ depth: d, memories: hopMemories });
+                    frontier = hopMemories.map((m) => m.id);
+                }
+                return {
+                    root: { id: root.id, type: root.type, title: root.properties.title },
+                    total_reached: visited.size - 1,
+                    chain,
+                };
+            },
+        },
     ];
 }
 // ── Heavy-op detection ────────────────────────────────────────────────────────
@@ -1514,7 +1766,7 @@ async function handleAsyncIngest(uri, forceType, titleOverride, tagsOverride, st
     return { job_id: jobId, status: 'pending', estimated_ms: estimatedMs };
 }
 // ── Ingest routing helper ─────────────────────────────────────────────────────
-async function routeIngest(uri, forceType, titleOverride, tagsOverride, store, config) {
+export async function routeIngest(uri, forceType, titleOverride, tagsOverride, store, config) {
     const embeddingModel = `${config.embeddings.provider}/${config.embeddings.model}`;
     // Normalise: bare absolute paths → file:// URI
     let normalUri = uri;
@@ -1549,7 +1801,9 @@ async function routeIngest(uri, forceType, titleOverride, tagsOverride, store, c
         const { buildYoutubeItem } = await import('../modules/youtube/ingest.js');
         const transcript = await fetchTranscript(normalUri, config.youtube);
         // Fail fast if transcript is empty — do not create an empty memory
-        if (!transcript.full_text || transcript.full_text.trim() === '' || transcript.segments.length === 0) {
+        if (!transcript.full_text ||
+            transcript.full_text.trim() === '' ||
+            transcript.segments.length === 0) {
             throw new Error(`Could not fetch transcript — video may have no captions or yt-dlp is unavailable (video_id: ${transcript.video_id})`);
         }
         const item = buildYoutubeItem({ transcript, embeddingModel });
@@ -1683,10 +1937,11 @@ async function routeIngest(uri, forceType, titleOverride, tagsOverride, store, c
             let extractionError;
             try {
                 const buffer = await readFile(filePath);
-                const { PDFParse } = await import('pdf-parse');
+                const { PDFParse } = (await import('pdf-parse'));
                 const parser = new PDFParse({ data: buffer, verbosity: 0 });
                 const result = await parser.getText();
-                content = result.text.trim() || `[PDF] ${title} — no extractable text (possibly scanned image PDF)`;
+                content =
+                    result.text.trim() || `[PDF] ${title} — no extractable text (possibly scanned image PDF)`;
             }
             catch (e) {
                 extractionFailed = true;
@@ -1703,11 +1958,16 @@ async function routeIngest(uri, forceType, titleOverride, tagsOverride, store, c
                 content_hash: createHash('sha256').update(content).digest('hex'),
                 properties: {
                     title,
-                    tags: extractionFailed ? [...(tagsOverride ?? []), 'pdf_extraction_failed'] : tagsOverride,
+                    tags: extractionFailed
+                        ? [...(tagsOverride ?? []), 'pdf_extraction_failed']
+                        : tagsOverride,
                     created_at: now,
                     ingested_at: now,
                     source_url: normalUri,
-                    custom: { pdf_path: filePath, extraction_status: extractionFailed ? 'failed' : 'complete' },
+                    custom: {
+                        pdf_path: filePath,
+                        extraction_status: extractionFailed ? 'failed' : 'complete',
+                    },
                 },
                 wikilinks,
                 related_ids: [],
@@ -1790,7 +2050,10 @@ async function routeIngest(uri, forceType, titleOverride, tagsOverride, store, c
             if (titleMatch)
                 autoTitle = titleMatch[1].trim();
             // Naive text extraction: strip tags
-            content = html.replace(/<[^>]+>/g, ' ').replace(/\s{2,}/g, ' ').slice(0, 5000);
+            content = html
+                .replace(/<[^>]+>/g, ' ')
+                .replace(/\s{2,}/g, ' ')
+                .slice(0, 5000);
         }
         catch {
             // fetch failed — just store URL as note