@onenomad/engram-mcp 1.1.0 → 2.0.0

package/dist/server.js

@@ -23,6 +23,9 @@ import { syncBridge, loadBridgeFile } from './procedural-bridge.js';
 import { writeHandoff, readHandoff, listHandoffs } from './handoff.js';
 import { assessPressure } from './context-pressure.js';
 import { listRecentTraces, gcOldTraces } from './retrieval-trace.js';
+import { hostname } from 'node:os';
+import { startDeviceCode, pollDeviceCode, credentialsFromApproval, } from './auth/login.js';
+import { readCredentials, writeCredentials, deleteCredentials, credentialsPath, credentialsStat, } from './auth/credentials.js';
 // ── Config & Storage ────────────────────────────────────────────────
 const config = loadConfig();
 let _storage = null;
@@ -42,17 +45,17 @@ const server = new McpServer({ name: 'engram', version: '2.4.0' }, {
     instructions: [
         'Engram is your long-term memory.',
         '',
-        'Save what matters: memory_ingest for facts/preferences/decisions, memory_kg_add for relationships, memory_diary_write at session end.',
-        'Before answering about prior conversations: memory_search first.',
+        'Save what matters: engram-ingest for facts/preferences/decisions, engram-kg-add for relationships, engram-diary-write at session end.',
+        'Before answering about prior conversations: engram-search first.',
         '',
         '## Handoff protocol (MANDATORY)',
         'Context compaction can fail if the window fills completely. When that happens, the user has to abandon the chat. Never let this happen.',
         '',
-        '1. Save memories continuously with memory_ingest — never batch.',
-        '2. At session start, call memory_handoff_read to resume where the prior session left off. If the user references a specific past session (by name or topic), call memory_handoff_list first and load the matching named checkpoint with memory_handoff_read({ name }).',
-        '3. When context feels heavy (long tool outputs, many file reads, extended work) call memory_context_pressure with your honest level assessment. Follow the returned actionPlan.',
-        '4. At NATURAL PHASE BOUNDARIES (task done, pivoting focus, finishing a subsystem, user says "ok next let\'s…") call memory_context_pressure with phaseBoundary=true and compact. Pivots thrash the cache anyway — compacting at the boundary is a free lunch, carrying verbose tool output from the old phase into the new one is not.',
-        '5. BEFORE invoking /compact — or before session end, or when the user asks to "save this session" / "checkpoint this" — call memory_handoff_write with a full "where we left off" snapshot: currentTask, completed, nextSteps, openQuestions, fileRefs (path:line), decisions, notes. Pass `name` for a user-friendly checkpoint label so the user can resume it explicitly later.',
+        '1. Save memories continuously with engram-ingest — never batch.',
+        '2. At session start, call engram-handoff-read to resume where the prior session left off. If the user references a specific past session (by name or topic), call engram-handoff-list first and load the matching named checkpoint with engram-handoff-read({ name }).',
+        '3. When context feels heavy (long tool outputs, many file reads, extended work) call engram-context-pressure with your honest level assessment. Follow the returned actionPlan.',
+        '4. At NATURAL PHASE BOUNDARIES (task done, pivoting focus, finishing a subsystem, user says "ok next let\'s…") call engram-context-pressure with phaseBoundary=true and compact. Pivots thrash the cache anyway — compacting at the boundary is a free lunch, carrying verbose tool output from the old phase into the new one is not.',
+        '5. BEFORE invoking /compact — or before session end, or when the user asks to "save this session" / "checkpoint this" — call engram-handoff-write with a full "where we left off" snapshot: currentTask, completed, nextSteps, openQuestions, fileRefs (path:line), decisions, notes. Pass `name` for a user-friendly checkpoint label so the user can resume it explicitly later.',
         '6. Do not wait for the system to auto-compact. Compact early, while there is still headroom for the handoff.',
         '',
         'If persona MCP available: call persona_signal on user reactions (correction, approval, frustration, praise, etc).',
@@ -61,7 +64,7 @@ const server = new McpServer({ name: 'engram', version: '2.4.0' }, {
 // ─────────────────────────────────────────────────────────────────────
 // CORE MEMORY TOOLS
 // ─────────────────────────────────────────────────────────────────────
-server.registerTool('memory_search', {
+server.registerTool('engram-search', {
     title: 'Search Memories',
     description: 'Search long-term memories. Returns relevant facts, preferences, decisions, and rules. Set format=true to get pre-formatted output for prompt injection.',
     inputSchema: z.object({
@@ -110,7 +113,7 @@ server.registerTool('memory_search', {
             .sort((a, b) => b.chunk.importance - a.chunk.importance)
             .slice(0, 3);
     }
-    // Formatted output mode (replaces old memory_format tool)
+    // Formatted output mode (replaces old engram-format tool)
     if (formatOutput) {
         const memText = formatRecalledMemories(selected);
         const rules = await formatRulesForPrompt(storage);
@@ -135,13 +138,13 @@ server.registerTool('memory_search', {
         })),
     });
 });
-server.registerTool('memory_budget', {
+server.registerTool('engram-budget', {
     title: 'Search Memories Within a Token Budget',
     description: [
-        'Like memory_search, but returns memories that fit within a TOKEN BUDGET instead of a count limit.',
+        'Like engram-search, but returns memories that fit within a TOKEN BUDGET instead of a count limit.',
         'Greedy fill from highest-relevance memories: candidates ranked by score × importance, included until the next entry would exceed the budget.',
         'Used by Pyre\'s Context Budget Engine: the persona/memories slot allocates N tokens, and Engram returns "the most useful subset that fits."',
-        'Returns the same memory shape as memory_search plus { budgetTokens, usedTokens, includedCount, candidateCount } so callers can see how the budget got spent.',
+        'Returns the same memory shape as engram-search plus { budgetTokens, usedTokens, includedCount, candidateCount } so callers can see how the budget got spent.',
     ].join(' '),
     inputSchema: z.object({
         query: z.string().describe('Natural language search query.'),
@@ -207,7 +210,7 @@ server.registerTool('memory_budget', {
         })),
     });
 });
-server.registerTool('memory_ingest', {
+server.registerTool('engram-ingest', {
     title: 'Save Memory',
     description: 'Save a fact, preference, decision, correction, or context to long-term memory. Auto-classifies type/tags if omitted. Auto-checks for duplicates before saving unless skipDedupe=true.',
     inputSchema: z.object({
@@ -225,13 +228,13 @@ server.registerTool('memory_ingest', {
         origin: z.enum(['user', 'derived', 'extracted', 'imported']).optional().describe('Provenance. Default "user" — explicit ingest is treated as user-asserted and protected from auto-merge / archive. Set "derived" when the caller is a downstream pipeline writing inferences.'),
         tier: z.enum(['scratch', 'short-term']).optional().describe('Memory tier. "scratch" = session-only, never promoted by consolidation, auto-purged after 24h. Use for exploratory notes you may want to discard. Default short-term.'),
         createdAt: z.string().optional().describe('ISO 8601 timestamp override. Default: ingest time (now). Use this when ingesting memories that ORIGINALLY happened at a different time — meeting notes from yesterday, chat history from last week, dated documents from years ago. The timestamp flows into the contextual prefix embedded with the content, giving the retrieval pipeline a temporal signal it would otherwise lose. Critical for benchmarks (LoCoMo) and real workloads that backfill historical context (Cortex ingest of dated docs, importing chat history from Slack/Discord).'),
-        skipKgExtraction: z.boolean().optional().describe('Skip the per-chunk knowledge-graph triple extraction. Production users should leave this off — KG extraction powers memory_dossier, memory_kg_query, and graph-aware reranking. Benchmark harnesses comparing apples-to-apples vs the standalone locomo bench (which bypasses wal.ts entirely) should set this to true so they measure the same code path.'),
-        skipDailyEntry: z.boolean().optional().describe('Skip the post-batch daily-entry append. Production users should leave this off — daily entries power memory_diary_read and cross-session summaries. Benchmark harnesses set this true alongside skipKgExtraction to match the standalone bench setup.'),
-        awaitSideEffects: z.boolean().optional().describe('When false, KG extraction + daily-entry append run in the BACKGROUND after the chunks land on disk; memory_ingest returns ~5-30x faster. Default true (caller awaits everything). Right for production paths where the agent doesn\'t immediately query the just-written content (chat WAL, vault → Engram bridge). Sync mode (true) is right when the caller WILL query within the same turn — bench harnesses, test fixtures, multi-step extraction pipelines.'),
+        skipKgExtraction: z.boolean().optional().describe('Skip the per-chunk knowledge-graph triple extraction. Production users should leave this off — KG extraction powers engram-dossier, engram-kg-query, and graph-aware reranking. Benchmark harnesses comparing apples-to-apples vs the standalone locomo bench (which bypasses wal.ts entirely) should set this to true so they measure the same code path.'),
+        skipDailyEntry: z.boolean().optional().describe('Skip the post-batch daily-entry append. Production users should leave this off — daily entries power engram-diary-read and cross-session summaries. Benchmark harnesses set this true alongside skipKgExtraction to match the standalone bench setup.'),
+        awaitSideEffects: z.boolean().optional().describe('When false, KG extraction + daily-entry append run in the BACKGROUND after the chunks land on disk; engram-ingest returns ~5-30x faster. Default true (caller awaits everything). Right for production paths where the agent doesn\'t immediately query the just-written content (chat WAL, vault → Engram bridge). Sync mode (true) is right when the caller WILL query within the same turn — bench harnesses, test fixtures, multi-step extraction pipelines.'),
     }),
 }, async ({ content, type, importance, tags, source, domain, topic, sentiment, emotionalValence, emotionalArousal, skipDedupe, origin, tier, createdAt, skipKgExtraction, skipDailyEntry, awaitSideEffects }) => {
     const storage = await ensureStorage();
-    // Auto duplicate check (replaces old memory_check_duplicate tool). Callers
+    // Auto duplicate check (replaces old engram-check-duplicate tool). Callers
     // writing intentional refinements can bypass via skipDedupe=true.
     if (!skipDedupe) {
         const dupeResults = await search(config, storage, content, 5);
@@ -278,7 +281,7 @@ server.registerTool('memory_ingest', {
         } : null,
     });
 });
-// memory_update_metadata — patch metadata-shape fields on an existing
+// engram-update-metadata — patch metadata-shape fields on an existing
 // memory by id. Closes a gap that callers (e.g. cortex's workspace
 // backfill) hit when they need to correct stamps without re-ingesting
 // (which either dupes or relies on similarity dedupe to overwrite —
@@ -295,7 +298,7 @@ server.registerTool('memory_ingest', {
 // (`embedding`, `embeddingVersion`) are rejected — those are either
 // immutable identity or computed from content. Callers wanting to
 // re-embed should re-ingest with skipDedupe.
-server.registerTool('memory_update_metadata', {
+server.registerTool('engram-update-metadata', {
     title: 'Update Memory Metadata',
     description: 'Patch metadata-shape fields on an existing memory by id. Use to correct mis-stamped tags/source/domain/topic without re-ingesting (which would either duplicate or rely on similarity dedupe to overwrite). Mode "merge" (default) only updates specified fields; "replace" wipes unset fields to defaults — footgun-y, used sparingly. Rejects mutations of id, createdAt, embedding (re-embedding requires re-ingest with skipDedupe).',
     inputSchema: z.object({
@@ -325,7 +328,7 @@ server.registerTool('memory_update_metadata', {
     // immutable fields (id, createdAt, embedding) stay locked.
     const patch = buildUpdateMetadataPatch(metadata, effectiveMode);
     if (effectiveMode === 'replace') {
-        process.stderr.write(`[engram] memory_update_metadata mode=replace id=${id} — caller wiped unset metadata fields to defaults\n`);
+        process.stderr.write(`[engram] engram-update-metadata mode=replace id=${id} — caller wiped unset metadata fields to defaults\n`);
     }
     // Compute a lightweight diff for the audit line (existing vs patch),
     // limited to the keys the patch actually touches so we don't log the
@@ -335,7 +338,7 @@ server.registerTool('memory_update_metadata', {
         const before = existing[key];
         diff[key] = { from: before, to: value };
     }
-    process.stderr.write(`[engram] memory_update_metadata id=${id} mode=${effectiveMode} diff=${JSON.stringify(diff)}\n`);
+    process.stderr.write(`[engram] engram-update-metadata id=${id} mode=${effectiveMode} diff=${JSON.stringify(diff)}\n`);
     await storage.updateChunk(id, patch);
     const updated = await storage.getChunk(id);
     if (!updated) {
@@ -356,7 +359,7 @@ server.registerTool('memory_update_metadata', {
         },
     });
 });
-server.registerTool('memory_scratch_promote', {
+server.registerTool('engram-scratch-promote', {
     title: 'Promote Scratch Memory',
     description: 'Graduate a scratch-tier memory to short-term so it survives the 24h auto-purge and enters the normal consolidation lifecycle. Use after deciding an exploratory note is worth keeping.',
     inputSchema: z.object({
@@ -373,7 +376,7 @@ server.registerTool('memory_scratch_promote', {
     await storage.updateChunk(id, { tier: 'short-term' });
     return json({ promoted: true, id, from: 'scratch', to: 'short-term' });
 });
-server.registerTool('memory_extract', {
+server.registerTool('engram-extract', {
     title: 'Extract Memories',
     description: 'Extract memories from a conversation. Uses LLM or heuristic fallback. Set rulesOnly=true to extract procedural rules only.',
     inputSchema: z.object({
@@ -385,7 +388,7 @@ server.registerTool('memory_extract', {
     const storage = await ensureStorage();
     const parsed = JSON.parse(messages);
     const convId = conversationId ?? `mcp-${Date.now()}`;
-    // Rules-only mode (replaces old memory_extract_rules tool)
+    // Rules-only mode (replaces old engram-extract-rules tool)
     if (rulesOnly) {
         await extractRules(config, storage, parsed);
         const rules = await formatRulesForPrompt(storage);
@@ -409,7 +412,7 @@ server.registerTool('memory_extract', {
     }
     return json({ extracted: allChunks.length, memories: allChunks });
 });
-server.registerTool('memory_maintain', {
+server.registerTool('engram-maintain', {
     title: 'Consolidate',
     description: 'Run memory consolidation: decay, promote/demote tiers, link related, merge duplicates, self-organize, and sync Persona bridge.',
     inputSchema: z.object({}),
@@ -426,7 +429,7 @@ server.registerTool('memory_maintain', {
     }
     return json({ action: 'consolidation', ...stats, bridge: bridgeSync });
 });
-server.registerTool('memory_rules', {
+server.registerTool('engram-rules', {
     title: 'Procedural Rules',
     description: 'Show active procedural rules learned from corrections and preferences.',
     inputSchema: z.object({}),
@@ -435,7 +438,7 @@ server.registerTool('memory_rules', {
     const t = await formatRulesForPrompt(storage);
     return text(t || 'No active procedural rules.');
 });
-server.registerTool('memory_outcome', {
+server.registerTool('engram-outcome', {
     title: 'Recall Outcome',
     description: 'Record whether recalled memories were helpful, corrected, or irrelevant. Adjusts importance.',
     inputSchema: z.object({
@@ -448,7 +451,7 @@ server.registerTool('memory_outcome', {
     await recordRecallOutcome(config, storage, ids, outcome, `mcp-${Date.now()}`);
     return text(`Recorded ${outcome} outcome for ${ids.length} chunk(s).`);
 });
-server.registerTool('memory_session', {
+server.registerTool('engram-session', {
     title: 'Session State',
     description: 'Manage session state (hot RAM). Actions: show, task, context, decision, action, clear.',
     inputSchema: z.object({
@@ -478,7 +481,7 @@ server.registerTool('memory_session', {
             return text(`Unknown action: ${action}`);
     }
 });
-server.registerTool('memory_stats', {
+server.registerTool('engram-stats', {
     title: 'Stats',
     description: 'Memory system stats: chunks by tier/layer/type, rules, knowledge graph, bridge status, and taxonomy.',
     inputSchema: z.object({}),
@@ -497,7 +500,7 @@ server.registerTool('memory_stats', {
     const kgStats = await getGraphStats(storage);
     const state = readSessionState(config.dataDir);
     const diaryDates = listDiaryDates(config.dataDir);
-    // Taxonomy (folded in from old memory_taxonomy tool)
+    // Taxonomy (folded in from old engram-taxonomy tool)
     const tree = await storage.getTaxonomy();
     // Bridge status (new observability)
     let bridge = { status: 'no bridge file' };
@@ -527,7 +530,7 @@ server.registerTool('memory_stats', {
         sessionTask: state.currentTask || null,
     });
 });
-server.registerTool('memory_govern', {
+server.registerTool('engram-govern', {
     title: 'Governance Check',
     description: 'Advisory checks: "check" (contradictions), "drift" (semantic drift), "poison" (injection scan), "full" (all).',
     inputSchema: z.object({
@@ -562,7 +565,7 @@ server.registerTool('memory_govern', {
 // ─────────────────────────────────────────────────────────────────────
 // KNOWLEDGE GRAPH TOOLS
 // ─────────────────────────────────────────────────────────────────────
-server.registerTool('memory_kg_add', {
+server.registerTool('engram-kg-add', {
     title: 'KG Add',
     description: 'Add a subject-predicate-object triple. Use replace=true to auto-invalidate conflicting facts.',
     inputSchema: z.object({
@@ -578,7 +581,7 @@ server.registerTool('memory_kg_add', {
     const triple = await fn(storage, subject, predicate, object, `mcp-${Date.now()}`, confidence);
     return json({ added: true, triple: { id: triple.id, subject: triple.subject, predicate: triple.predicate, object: triple.object } });
 });
-server.registerTool('memory_kg_query', {
+server.registerTool('engram-kg-query', {
     title: 'KG Query',
     description: 'Query knowledge graph triples. Filter by subject, predicate, and/or object.',
     inputSchema: z.object({
@@ -601,7 +604,7 @@ server.registerTool('memory_kg_query', {
         })),
     });
 });
-server.registerTool('memory_kg_invalidate', {
+server.registerTool('engram-kg-invalidate', {
     title: 'KG Invalidate',
     description: 'Mark a fact as no longer valid. Stays in history.',
     inputSchema: z.object({
@@ -612,7 +615,7 @@ server.registerTool('memory_kg_invalidate', {
     await invalidateTriple(storage, tripleId);
     return text(`Triple ${tripleId} invalidated.`);
 });
-server.registerTool('memory_kg_timeline', {
+server.registerTool('engram-kg-timeline', {
     title: 'KG Timeline',
     description: 'Chronological history of all facts about an entity.',
     inputSchema: z.object({
@@ -629,7 +632,7 @@ server.registerTool('memory_kg_timeline', {
         })),
     });
 });
-server.registerTool('memory_dossier', {
+server.registerTool('engram-dossier', {
     title: 'Entity Dossier',
     description: [
         'Aggregate everything Engram knows about an entity (person, project, concept) into a structured snapshot.',
@@ -713,7 +716,7 @@ server.registerTool('memory_dossier', {
     // Optional token-budget enforcement. Splits budget evenly across
     // the 5 categories (facts / preferences / decisions / corrections
     // / recent) and greedy-fills each within its share. Same 4
-    // chars/token + 30 wrapper estimate as memory_budget.
+    // chars/token + 30 wrapper estimate as engram-budget.
     let usedTokens = 0;
     if (typeof budgetTokens === 'number' && budgetTokens > 0) {
         const perCategoryBudget = Math.floor(budgetTokens / 5);
@@ -772,7 +775,7 @@ server.registerTool('memory_dossier', {
 // ─────────────────────────────────────────────────────────────────────
 // DIARY TOOLS
 // ─────────────────────────────────────────────────────────────────────
-server.registerTool('memory_diary_write', {
+server.registerTool('engram-diary-write', {
     title: 'Write Diary',
     description: 'Write a session diary entry. Record what happened, what was decided, what matters next.',
     inputSchema: z.object({
@@ -783,7 +786,7 @@ server.registerTool('memory_diary_write', {
     const entry = writeDiaryEntry(config.dataDir, content, agent);
     return json({ written: true, date: entry.date, time: entry.time, agent: entry.agent });
 });
-server.registerTool('memory_diary_read', {
+server.registerTool('engram-diary-read', {
     title: 'Read Diary',
     description: 'Read diary entries from recent days or a specific date.',
     inputSchema: z.object({
@@ -798,7 +801,7 @@ server.registerTool('memory_diary_read', {
 // ─────────────────────────────────────────────────────────────────────
 // HANDOFF TOOLS — cross-session "where we left off" lifeline
 // ─────────────────────────────────────────────────────────────────────
-server.registerTool('memory_handoff_write', {
+server.registerTool('engram-handoff-write', {
     title: 'Write Handoff Note',
     description: 'Write a structured "where we left off" snapshot (a.k.a. session checkpoint). Call BEFORE /compact, before session end, when context_pressure returns hot/critical, or when the user asks to "save this session." Pass an optional `name` (e.g. "engram-named-checkpoints") so the user can later list-and-pick rather than scanning timestamps. This is the lifeline if the context window fills before compaction runs.',
     inputSchema: z.object({
@@ -835,13 +838,13 @@ server.registerTool('memory_handoff_write', {
         summary: note.currentTask,
     });
 });
-server.registerTool('memory_handoff_read', {
+server.registerTool('engram-handoff-read', {
     title: 'Read Handoff Note',
-    description: 'Read a saved handoff/checkpoint. With no arg, returns the most recent. Pass `name` to load a named checkpoint, or `stamp` to load a specific timestamp. Set `list=true` to get recent checkpoints (deprecated — prefer memory_handoff_list).',
+    description: 'Read a saved handoff/checkpoint. With no arg, returns the most recent. Pass `name` to load a named checkpoint, or `stamp` to load a specific timestamp. Set `list=true` to get recent checkpoints (deprecated — prefer engram-handoff-list).',
     inputSchema: z.object({
         name: z.string().optional().describe('Named checkpoint to load (e.g. "engram-named-checkpoints"). Takes precedence over stamp if both are provided.'),
         stamp: z.string().optional().describe('Handoff stamp to load (e.g. "2026-04-20_14-32-05"). If omitted and no name, returns the latest.'),
-        list: z.boolean().optional().describe('Deprecated — use memory_handoff_list. If true, lists recent checkpoints.'),
+        list: z.boolean().optional().describe('Deprecated — use engram-handoff-list. If true, lists recent checkpoints.'),
         limit: z.number().min(1).max(50).optional().describe('For list mode: max entries to return (default 10).'),
     }),
 }, async ({ name, stamp, list, limit }) => {
@@ -854,22 +857,22 @@ server.registerTool('memory_handoff_read', {
         return json({
             found: false,
             message: identifier
-                ? `No handoff found matching "${identifier}". Use memory_handoff_list to see saved checkpoints.`
+                ? `No handoff found matching "${identifier}". Use engram-handoff-list to see saved checkpoints.`
                 : 'No handoff note available.',
         });
     }
     return json({ found: true, ...note });
 });
-server.registerTool('memory_handoff_list', {
+server.registerTool('engram-handoff-list', {
     title: 'List Handoff Checkpoints',
-    description: 'List recent saved handoffs/checkpoints, newest first. Each entry includes stamp, timestamp, reason, currentTask snippet, and (if set) the user-facing name. Call this when the user asks to "resume" or "pick up where we left off" so you can present options before loading one with memory_handoff_read.',
+    description: 'List recent saved handoffs/checkpoints, newest first. Each entry includes stamp, timestamp, reason, currentTask snippet, and (if set) the user-facing name. Call this when the user asks to "resume" or "pick up where we left off" so you can present options before loading one with engram-handoff-read.',
     inputSchema: z.object({
         limit: z.number().min(1).max(50).optional().describe('Max checkpoints to return (default 10, max 50).'),
     }),
 }, async ({ limit }) => {
     return json({ handoffs: listHandoffs(config.dataDir, limit ?? 10) });
 });
-server.registerTool('memory_context_pressure', {
+server.registerTool('engram-context-pressure', {
     title: 'Context Pressure Check',
     description: 'Self-assess context window pressure and get an action plan. Call periodically during long sessions — especially after big tool outputs, many file reads, or when responses feel sluggish. Levels: ok, warm, hot, critical. Also call with phaseBoundary=true at natural phase boundaries (task complete, pivoting focus, finishing a subsystem) — pivots thrash the cache anyway, so that is the RIGHT moment to compact. Returns an ordered actionPlan telling you exactly what to do (save memories, write handoff, compact).',
     inputSchema: z.object({
@@ -881,9 +884,161 @@ server.registerTool('memory_context_pressure', {
     return json(assessPressure(level, reason ?? '', phaseBoundary ?? false));
 });
 // ─────────────────────────────────────────────────────────────────────
+// CLOUD AUTH — device-code login + credentials file management
+// ─────────────────────────────────────────────────────────────────────
+// The MCP login flow is two-step because device-code pairing needs the
+// user to approve in a browser, which usually takes longer than a single
+// MCP tool call can wait. Tool 1 starts the pairing and returns the URL +
+// user code. Tool 2 polls for approval in chunks short enough to stay
+// under the MCP tool timeout. The caller re-invokes tool 2 if the user
+// is still finishing the browser flow.
+function sleepMs(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+// Cap a single resume call well under the MCP tool timeout. Leaves
+// headroom for the final pollDeviceCode round-trip after the loop's
+// "still pending" exit check.
+const RESUME_MAX_DURATION_MS = 45_000;
+server.registerTool('engram-login', {
+    title: 'Cloud Login (start device-code pairing)',
+    description: [
+        'Start a device-code login against a Pyre Cloud server (the same flow as the `engram-memory login` CLI command).',
+        'Returns the URL and user code the human must visit + enter in a browser. AFTER showing those to the user, call `engram-login-resume` with the returned `deviceCode` to poll for approval — it may need to be called more than once if the user is slow.',
+        'On approval the credentials file at `~/.pyre/credentials.json` (or $PYRE_CREDENTIALS_FILE) is written and Engram\'s cloud storage adapter starts using it on next server start.',
+    ].join(' '),
+    inputSchema: z.object({
+        serverUrl: z.string().describe('Pyre Cloud base URL (e.g. https://pyre.sh). No trailing slash needed.'),
+        label: z.string().optional().describe('Friendly device label to attach to the issued credential. Defaults to this machine\'s hostname.'),
+    }),
+}, async ({ serverUrl, label }) => {
+    const apiUrl = serverUrl.trim().replace(/\/+$/, '');
+    if (!apiUrl) {
+        return json({ ok: false, error: 'serverUrl is required (e.g. https://pyre.sh).' });
+    }
+    try {
+        const start = await startDeviceCode(fetch, apiUrl, label?.trim() || hostname(), sleepMs);
+        const expiresAt = Date.now() + start.expires_in * 1000;
+        return json({
+            ok: true,
+            serverUrl: apiUrl,
+            verificationUrl: start.verification_url,
+            userCode: start.user_code,
+            deviceCode: start.device_code,
+            intervalSeconds: start.interval,
+            expiresInSeconds: start.expires_in,
+            expiresAt,
+            instructions: `Show the user this URL and code, then call engram-login-resume({ serverUrl: "${apiUrl}", deviceCode: "${start.device_code}", intervalSeconds: ${start.interval}, expiresAt: ${expiresAt} }) to poll for approval. If it returns "pending", call it again.`,
+        });
+    }
+    catch (err) {
+        return json({ ok: false, error: `Could not reach ${apiUrl}: ${err.message}` });
+    }
+});
+server.registerTool('engram-login-resume', {
+    title: 'Cloud Login (resume / poll device-code)',
+    description: [
+        'Poll a device-code pairing started by `engram-login`. Polls for ~45s, then returns one of: approved, pending, denied, expired, error.',
+        'If "pending" is returned and `expiresAt` has not passed, call this tool again with the same arguments to keep waiting.',
+        'On "approved" the credentials file is written and the response includes the storage api_url assigned by the server.',
+    ].join(' '),
+    inputSchema: z.object({
+        serverUrl: z.string().describe('Pyre Cloud base URL — must match the one passed to engram-login.'),
+        deviceCode: z.string().describe('device_code returned by engram-login.'),
+        intervalSeconds: z.number().min(1).max(60).describe('Polling interval suggested by the server (returned by engram-login).'),
+        expiresAt: z.number().describe('Epoch ms after which the device code is expired (returned by engram-login).'),
+    }),
+}, async ({ serverUrl, deviceCode, intervalSeconds, expiresAt }) => {
+    const apiUrl = serverUrl.trim().replace(/\/+$/, '');
+    const intervalMs = Math.max(1, intervalSeconds) * 1000;
+    const stopAt = Math.min(Date.now() + RESUME_MAX_DURATION_MS, expiresAt);
+    while (Date.now() < stopAt) {
+        await sleepMs(intervalMs);
+        if (Date.now() >= stopAt)
+            break;
+        let body;
+        try {
+            body = await pollDeviceCode(fetch, apiUrl, deviceCode);
+        }
+        catch {
+            // Transient — keep polling until our window closes.
+            continue;
+        }
+        if (body.status === 'pending')
+            continue;
+        if (body.status === 'denied') {
+            return json({ ok: false, status: 'denied', error: 'Authorization denied.' });
+        }
+        if (body.status === 'expired') {
+            return json({ ok: false, status: 'expired', error: 'Pairing code expired. Call engram-login again.' });
+        }
+        if (body.status === 'approved') {
+            try {
+                const creds = credentialsFromApproval(body);
+                writeCredentials(creds);
+                return json({
+                    ok: true,
+                    status: 'approved',
+                    apiUrl: creds.api_url,
+                    label: creds.label,
+                    scopes: creds.scopes,
+                    credentialsPath: credentialsPath(),
+                    note: 'Credentials written. Restart the Engram MCP server (or your MCP client) for cloud storage to take effect.',
+                });
+            }
+            catch (err) {
+                return json({ ok: false, status: 'error', error: `Could not write credentials: ${err.message}` });
+            }
+        }
+    }
+    if (Date.now() >= expiresAt) {
+        return json({ ok: false, status: 'expired', error: 'Pairing code expired. Call engram-login again.' });
+    }
+    return json({
+        ok: true,
+        status: 'pending',
+        secondsUntilExpiry: Math.max(0, Math.floor((expiresAt - Date.now()) / 1000)),
+        note: 'Still waiting on browser approval. Call engram-login-resume again with the same arguments.',
+    });
+});
+server.registerTool('engram-login-status', {
+    title: 'Cloud Login Status',
+    description: 'Inspect the local Pyre Cloud credentials file. Returns whether the user is logged in, the api_url and label of the active credential, and the credentials file path. No network calls.',
+    inputSchema: z.object({}),
+}, async () => {
+    const path = credentialsPath();
+    const stat = credentialsStat();
+    const creds = readCredentials();
+    if (!creds) {
+        return json({ loggedIn: false, credentialsPath: path, fileExists: stat !== null });
+    }
+    return json({
+        loggedIn: true,
+        credentialsPath: path,
+        apiUrl: creds.api_url,
+        label: creds.label,
+        scopes: creds.scopes,
+        issuedAt: creds.issued_at,
+    });
+});
+server.registerTool('engram-logout', {
+    title: 'Cloud Logout',
+    description: 'Delete the local Pyre Cloud credentials file. Idempotent — succeeds whether or not the file existed. Engram falls back to local LanceDB on next server start.',
+    inputSchema: z.object({}),
+}, async () => {
+    const path = credentialsPath();
+    const removed = deleteCredentials();
+    return json({
+        ok: true,
+        loggedOut: removed,
+        alreadyLoggedOut: !removed,
+        credentialsPath: path,
+        note: removed ? 'Restart the Engram MCP server to fall back to local storage.' : undefined,
+    });
+});
+// ─────────────────────────────────────────────────────────────────────
 // DIAGNOSTIC RETRIEVAL TRACES
 // ─────────────────────────────────────────────────────────────────────
-server.registerTool('memory_trace_recent', {
+server.registerTool('engram-trace-recent', {
     title: 'Recent Retrieval Traces',
     description: [
         'List the most recent diagnostic retrieval traces. Each trace captures: query text, filters, per-stage candidate counts (corpus → vector above/below floor → keyword → final), result IDs, and total latency.',
@@ -912,7 +1067,7 @@ server.registerTool('memory_trace_recent', {
 // ─────────────────────────────────────────────────────────────────────
 // IMPORT
 // ─────────────────────────────────────────────────────────────────────
-server.registerTool('memory_import', {
+server.registerTool('engram-import', {
     title: 'Import',
     description: 'Bulk import from chat exports: claude-jsonl, chatgpt-json, or plain-text.',
     inputSchema: z.object({