@199-bio/engram 0.8.0 → 0.10.0

package/src/retrieval/hybrid.ts

@@ -4,7 +4,7 @@
  * Enhanced with temporal decay and salience scoring
  */
 
-import { EngramDatabase, Memory } from "../storage/database.js";
+import { EngramDatabase, Memory, Digest } from "../storage/database.js";
 import { KnowledgeGraph } from "../graph/knowledge-graph.js";
 import { ColBERTRetriever, SimpleRetriever, SearchResult, Document } from "./colbert.js";
 
@@ -20,8 +20,15 @@ export interface HybridSearchResult {
   };
 }
 
+export interface DigestSearchResult {
+  digest: Digest;
+  score: number;
+  key_memories: Memory[];  // 2-3 source memories that best support this digest
+}
+
 export interface HybridSearchResponse {
   results: HybridSearchResult[];
+  digests: DigestSearchResult[];  // Relevant synthesized context
   recall_id: string;  // For LLM feedback
   connected_memories: Array<{
     memory: Memory;
@@ -179,11 +186,15 @@ export class HybridSearch {
     if (allCandidateIds.size === 0) {
       return {
         results: [],
+        digests: [],
         recall_id: recallId,
         connected_memories: [],
       };
     }
 
+    // Search digests via BM25 (top 3 relevant digests)
+    const digestResults = this.searchDigests(query, 3);
+
     // Create rankings for RRF
     const rankings: Map<string, { bm25?: number; semantic?: number; graph?: number; connected?: number }> = new Map();
 
@@ -327,17 +338,70 @@ export class HybridSearch {
     // Log this retrieval for deferred learning
     try {
       this.db.createRetrievalLog(this.sessionId, recallId, query, allResultIds);
-    } catch {
-      // Ignore duplicate recall_id errors (can happen with rapid queries)
+    } catch (error) {
+      // Only ignore duplicate recall_id errors (UNIQUE constraint), log all others
+      const msg = error instanceof Error ? error.message : String(error);
+      if (!msg.includes("UNIQUE constraint")) {
+        console.error(`[Engram] Failed to create retrieval log: ${msg}`);
+      }
+    }
+
+    // TOKEN EFFICIENCY: If digests are returned, reduce memory count
+    // Digest provides context (synthesis), memories provide evidence (specifics)
+    // Return fewer memories when we have good digest coverage
+    let finalResults = results;
+    if (digestResults.length > 0) {
+      // Get IDs of memories already covered by digests as key_memories
+      const coveredByDigests = new Set<string>();
+      digestResults.forEach(d => d.key_memories.forEach(m => coveredByDigests.add(m.id)));
+
+      // Keep memories not already shown as key_memories in digests
+      // Also limit to fewer since digests provide the context
+      const maxMemoriesWithDigests = Math.max(2, Math.floor(limit / 2));
+      finalResults = results
+        .filter(r => !coveredByDigests.has(r.memory.id))
+        .slice(0, maxMemoriesWithDigests);
     }
 
     return {
-      results,
+      results: finalResults,
+      digests: digestResults,
       recall_id: recallId,
       connected_memories: connectedMemories,
     };
   }
 
+  /**
+   * Search digests via BM25 and return with key source memories
+   * Returns top N digests with 2-3 representative source memories each
+   */
+  private searchDigests(query: string, limit: number): DigestSearchResult[] {
+    try {
+      const digestHits = this.db.searchDigestsBM25(query, limit);
+
+      return digestHits.map(hit => {
+        // Get source memories for this digest, take top 3 most relevant
+        const sources = this.db.getDigestSources(hit.id);
+        // Sort by importance and recency, take best 3
+        const keyMemories = sources
+          .sort((a, b) => {
+            const scoreA = (a.importance || 0.5) + (a.access_count || 0) * 0.1;
+            const scoreB = (b.importance || 0.5) + (b.access_count || 0) * 0.1;
+            return scoreB - scoreA;
+          })
+          .slice(0, 3);
+
+        return {
+          digest: hit,
+          score: Math.abs(hit.score),  // BM25 returns negative scores
+          key_memories: keyMemories,
+        };
+      });
+    } catch {
+      return [];
+    }
+  }
+
   /**
    * Expanded search when LLM needs more memories
    * Relaxes constraints and follows weaker connections
@@ -351,7 +415,7 @@ export class HybridSearch {
     // Get the original retrieval log
     const log = this.db.getRetrievalLog(recallId);
     if (!log) {
-      return { results: [], recall_id: recallId, connected_memories: [] };
+      return { results: [], digests: [], recall_id: recallId, connected_memories: [] };
     }
 
     // Search again with relaxed parameters

package/src/storage/database.ts

@@ -119,6 +119,37 @@ export interface RetrievalLog {
   processed: boolean;      // Has this been used for learning?
 }
 
+/**
+ * Consolidation checkpoint for safe backlog processing
+ * Enables resume capability and progress tracking
+ */
+export interface ConsolidationCheckpoint {
+  id: string;
+  run_id: string;              // Unique ID for this consolidation run
+  phase: "episodes" | "memories" | "decay" | "cleanup" | "complete";
+  batches_completed: number;
+  batches_total: number;
+  memories_processed: number;
+  episodes_processed: number;
+  digests_created: number;
+  contradictions_found: number;
+  tokens_used: number;
+  estimated_cost_usd: number;
+  started_at: Date;
+  updated_at: Date;
+  completed_at: Date | null;
+  error: string | null;
+}
+
+/**
+ * Consolidation configuration for budget and rate limits
+ */
+export interface ConsolidationConfig {
+  key: string;
+  value: string;
+  updated_at: Date;
+}
+
 export class EngramDatabase {
   private db: Database.Database;
   private stmtCache: Map<string, Database.Statement> = new Map();
@@ -284,6 +315,34 @@ export class EngramDatabase {
       CREATE INDEX IF NOT EXISTS idx_digest_sources_memory ON digest_sources(memory_id);
     `);
 
+    // FTS5 for digest BM25 search
+    this.db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS digests_fts USING fts5(
+        content,
+        topic,
+        content='digests',
+        content_rowid='rowid'
+      );
+
+      -- Triggers to keep FTS in sync
+      CREATE TRIGGER IF NOT EXISTS digests_ai AFTER INSERT ON digests BEGIN
+        INSERT INTO digests_fts(rowid, content, topic) VALUES (NEW.rowid, NEW.content, COALESCE(NEW.topic, ''));
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS digests_ad AFTER DELETE ON digests BEGIN
+        INSERT INTO digests_fts(digests_fts, rowid, content, topic) VALUES('delete', OLD.rowid, OLD.content, COALESCE(OLD.topic, ''));
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS digests_au AFTER UPDATE ON digests BEGIN
+        INSERT INTO digests_fts(digests_fts, rowid, content, topic) VALUES('delete', OLD.rowid, OLD.content, COALESCE(OLD.topic, ''));
+        INSERT INTO digests_fts(rowid, content, topic) VALUES (NEW.rowid, NEW.content, COALESCE(NEW.topic, ''));
+      END;
+    `);
+
+    // Rebuild FTS5 index to sync with content table (necessary for existing databases)
+    // This is idempotent and fast for small tables
+    this.db.exec(`INSERT INTO digests_fts(digests_fts) VALUES('rebuild');`);
+
     // Contradictions table (detected conflicts)
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS contradictions (
@@ -340,6 +399,48 @@ export class EngramDatabase {
       CREATE INDEX IF NOT EXISTS idx_retrieval_logs_recall ON retrieval_logs(recall_id);
       CREATE INDEX IF NOT EXISTS idx_retrieval_logs_processed ON retrieval_logs(processed);
     `);
+
+    // Consolidation checkpoints for safe backlog processing
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS consolidation_checkpoints (
+        id TEXT PRIMARY KEY,
+        run_id TEXT NOT NULL UNIQUE,
+        phase TEXT NOT NULL CHECK(phase IN ('episodes', 'memories', 'decay', 'cleanup', 'complete')),
+        batches_completed INTEGER DEFAULT 0,
+        batches_total INTEGER DEFAULT 0,
+        memories_processed INTEGER DEFAULT 0,
+        episodes_processed INTEGER DEFAULT 0,
+        digests_created INTEGER DEFAULT 0,
+        contradictions_found INTEGER DEFAULT 0,
+        tokens_used INTEGER DEFAULT 0,
+        estimated_cost_usd REAL DEFAULT 0,
+        started_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        completed_at DATETIME,
+        error TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_checkpoints_run ON consolidation_checkpoints(run_id);
+      CREATE INDEX IF NOT EXISTS idx_checkpoints_phase ON consolidation_checkpoints(phase);
+    `);
+
+    // Consolidation configuration for budget and rate limits
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS consolidation_config (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      );
+
+      -- Default configuration values
+      INSERT OR IGNORE INTO consolidation_config (key, value) VALUES
+        ('daily_budget_usd', '5.0'),
+        ('max_batches_per_run', '5'),
+        ('delay_between_calls_ms', '2000'),
+        ('recovery_mode_threshold', '100'),
+        ('error_rate_threshold', '0.3'),
+        ('empty_digest_threshold', '0.2');
+    `);
   }
 
   /**
@@ -568,6 +669,23 @@ export class EngramDatabase {
     }));
   }
 
+  searchDigestsBM25(query: string, limit: number = 10): Array<Digest & { score: number }> {
+    const escapedQuery = this.escapeFTS5Query(query);
+    const rows = this.stmt(`
+      SELECT d.*, bm25(digests_fts) as score
+      FROM digests_fts fts
+      JOIN digests d ON fts.rowid = d.rowid
+      WHERE digests_fts MATCH ?
+      ORDER BY score
+      LIMIT ?
+    `).all(escapedQuery, limit) as Array<Record<string, unknown>>;
+
+    return rows.map((row) => ({
+      ...this.rowToDigest(row),
+      score: row.score as number,
+    }));
+  }
+
   private escapeFTS5Query(query: string): string {
     // Simple tokenization - split on whitespace, escape special chars
     const tokens = query
@@ -1183,59 +1301,72 @@ export class EngramDatabase {
 
   /**
    * Record that memories were retrieved together (co-retrieval)
+   * Uses cached statement and transaction for O(n²) efficiency
    */
   recordCoRetrieval(memoryIds: string[]): void {
     if (memoryIds.length < 2) return;
 
-    // Update all pairs
-    for (let i = 0; i < memoryIds.length; i++) {
-      for (let j = i + 1; j < memoryIds.length; j++) {
-        const [a, b] = memoryIds[i] < memoryIds[j]
-          ? [memoryIds[i], memoryIds[j]]
-          : [memoryIds[j], memoryIds[i]];
-
-        this.db.prepare(`
-          INSERT INTO memory_connections (id, memory_a, memory_b, co_retrievals, last_fired)
-          VALUES (?, ?, ?, 1, CURRENT_TIMESTAMP)
-          ON CONFLICT(memory_a, memory_b) DO UPDATE SET
-            co_retrievals = co_retrievals + 1,
-            last_fired = CURRENT_TIMESTAMP
-        `).run(randomUUID(), a, b);
+    // Cache statement once (not per iteration)
+    const upsertStmt = this.stmt(`
+      INSERT INTO memory_connections (id, memory_a, memory_b, co_retrievals, last_fired)
+      VALUES (?, ?, ?, 1, CURRENT_TIMESTAMP)
+      ON CONFLICT(memory_a, memory_b) DO UPDATE SET
+        co_retrievals = co_retrievals + 1,
+        last_fired = CURRENT_TIMESTAMP
+    `);
+
+    // Wrap in transaction for batch efficiency
+    this.db.transaction(() => {
+      for (let i = 0; i < memoryIds.length; i++) {
+        for (let j = i + 1; j < memoryIds.length; j++) {
+          const [a, b] = memoryIds[i] < memoryIds[j]
+            ? [memoryIds[i], memoryIds[j]]
+            : [memoryIds[j], memoryIds[i]];
+
+          upsertStmt.run(randomUUID(), a, b);
+        }
       }
-    }
+    })();
   }
 
   /**
    * Record that memories were useful together (from LLM feedback)
    * This is what actually strengthens connections
+   * Uses cached statement and transaction for O(n²) efficiency
    */
   recordCoUseful(memoryIds: string[]): void {
     if (memoryIds.length < 2) return;
 
-    for (let i = 0; i < memoryIds.length; i++) {
-      for (let j = i + 1; j < memoryIds.length; j++) {
-        const [a, b] = memoryIds[i] < memoryIds[j]
-          ? [memoryIds[i], memoryIds[j]]
-          : [memoryIds[j], memoryIds[i]];
-
-        // Get current stats to calculate new strength
-        const conn = this.getOrCreateConnection(a, b);
-        const newCoUseful = conn.co_useful + 1;
-        const newCoRetrievals = Math.max(conn.co_retrievals, newCoUseful);
-
-        // Calculate strength with diminishing returns
-        const usefulRatio = newCoUseful / Math.max(1, newCoRetrievals);
-        const diminished = Math.sqrt(usefulRatio);
-        const confidence = Math.min(1, newCoUseful / 3); // Require 3+ co-useful for strong connection
-        const newStrength = diminished * confidence;
-
-        this.db.prepare(`
-          UPDATE memory_connections
-          SET co_useful = ?, strength = ?, last_fired = CURRENT_TIMESTAMP
-          WHERE memory_a = ? AND memory_b = ?
-        `).run(newCoUseful, newStrength, a, b);
+    // Cache statement once (not per iteration)
+    const updateStmt = this.stmt(`
+      UPDATE memory_connections
+      SET co_useful = ?, strength = ?, last_fired = CURRENT_TIMESTAMP
+      WHERE memory_a = ? AND memory_b = ?
+    `);
+
+    // Wrap in transaction for batch efficiency
+    this.db.transaction(() => {
+      for (let i = 0; i < memoryIds.length; i++) {
+        for (let j = i + 1; j < memoryIds.length; j++) {
+          const [a, b] = memoryIds[i] < memoryIds[j]
+            ? [memoryIds[i], memoryIds[j]]
+            : [memoryIds[j], memoryIds[i]];
+
+          // Get current stats to calculate new strength
+          const conn = this.getOrCreateConnection(a, b);
+          const newCoUseful = conn.co_useful + 1;
+          const newCoRetrievals = Math.max(conn.co_retrievals, newCoUseful);
+
+          // Calculate strength with diminishing returns
+          const usefulRatio = newCoUseful / Math.max(1, newCoRetrievals);
+          const diminished = Math.sqrt(usefulRatio);
+          const confidence = Math.min(1, newCoUseful / 3); // Require 3+ co-useful for strong connection
+          const newStrength = diminished * confidence;
+
+          updateStmt.run(newCoUseful, newStrength, a, b);
+        }
       }
-    }
+    })();
   }
 
   /**
@@ -1328,6 +1459,195 @@ export class EngramDatabase {
     return result.changes;
   }
 
+  // ============ Consolidation Checkpoints ============
+
+  /**
+   * Create a new consolidation checkpoint
+   */
+  createCheckpoint(runId: string, phase: ConsolidationCheckpoint["phase"], batchesTotal: number): ConsolidationCheckpoint {
+    const id = randomUUID();
+    this.db.prepare(`
+      INSERT INTO consolidation_checkpoints (id, run_id, phase, batches_total)
+      VALUES (?, ?, ?, ?)
+    `).run(id, runId, phase, batchesTotal);
+    return this.getCheckpoint(runId)!;
+  }
+
+  /**
+   * Get checkpoint by run_id
+   */
+  getCheckpoint(runId: string): ConsolidationCheckpoint | null {
+    const row = this.stmt("SELECT * FROM consolidation_checkpoints WHERE run_id = ?").get(runId) as Record<string, unknown> | undefined;
+    return row ? this.rowToCheckpoint(row) : null;
+  }
+
+  /**
+   * Get the latest incomplete checkpoint (for resume)
+   */
+  getIncompleteCheckpoint(): ConsolidationCheckpoint | null {
+    const row = this.stmt(`
+      SELECT * FROM consolidation_checkpoints
+      WHERE completed_at IS NULL AND error IS NULL
+      ORDER BY started_at DESC LIMIT 1
+    `).get() as Record<string, unknown> | undefined;
+    return row ? this.rowToCheckpoint(row) : null;
+  }
+
+  /**
+   * Update checkpoint progress
+   */
+  updateCheckpoint(
+    runId: string,
+    updates: Partial<Pick<ConsolidationCheckpoint,
+      "phase" | "batches_completed" | "batches_total" | "memories_processed" |
+      "episodes_processed" | "digests_created" | "contradictions_found" |
+      "tokens_used" | "estimated_cost_usd" | "error"
+    >>
+  ): ConsolidationCheckpoint | null {
+    const sets: string[] = ["updated_at = CURRENT_TIMESTAMP"];
+    const values: unknown[] = [];
+
+    if (updates.phase !== undefined) {
+      sets.push("phase = ?");
+      values.push(updates.phase);
+    }
+    if (updates.batches_completed !== undefined) {
+      sets.push("batches_completed = ?");
+      values.push(updates.batches_completed);
+    }
+    if (updates.batches_total !== undefined) {
+      sets.push("batches_total = ?");
+      values.push(updates.batches_total);
+    }
+    if (updates.memories_processed !== undefined) {
+      sets.push("memories_processed = ?");
+      values.push(updates.memories_processed);
+    }
+    if (updates.episodes_processed !== undefined) {
+      sets.push("episodes_processed = ?");
+      values.push(updates.episodes_processed);
+    }
+    if (updates.digests_created !== undefined) {
+      sets.push("digests_created = ?");
+      values.push(updates.digests_created);
+    }
+    if (updates.contradictions_found !== undefined) {
+      sets.push("contradictions_found = ?");
+      values.push(updates.contradictions_found);
+    }
+    if (updates.tokens_used !== undefined) {
+      sets.push("tokens_used = ?");
+      values.push(updates.tokens_used);
+    }
+    if (updates.estimated_cost_usd !== undefined) {
+      sets.push("estimated_cost_usd = ?");
+      values.push(updates.estimated_cost_usd);
+    }
+    if (updates.error !== undefined) {
+      sets.push("error = ?");
+      values.push(updates.error);
+    }
+
+    values.push(runId);
+    this.db.prepare(`UPDATE consolidation_checkpoints SET ${sets.join(", ")} WHERE run_id = ?`).run(...values);
+    return this.getCheckpoint(runId);
+  }
+
+  /**
+   * Mark checkpoint as complete
+   */
+  completeCheckpoint(runId: string): void {
+    this.db.prepare(`
+      UPDATE consolidation_checkpoints
+      SET phase = 'complete', completed_at = CURRENT_TIMESTAMP, updated_at = CURRENT_TIMESTAMP
+      WHERE run_id = ?
+    `).run(runId);
+  }
+
+  /**
+   * Get recent checkpoints for reporting
+   */
+  getRecentCheckpoints(limit: number = 10): ConsolidationCheckpoint[] {
+    const rows = this.stmt(`
+      SELECT * FROM consolidation_checkpoints
+      ORDER BY started_at DESC LIMIT ?
+    `).all(limit) as Record<string, unknown>[];
+    return rows.map(r => this.rowToCheckpoint(r));
+  }
+
+  /**
+   * Get total spending in the last 24 hours
+   */
+  getDailySpending(): number {
+    const row = this.stmt(`
+      SELECT COALESCE(SUM(estimated_cost_usd), 0) as total
+      FROM consolidation_checkpoints
+      WHERE started_at >= datetime('now', '-1 day')
+    `).get() as { total: number };
+    return row.total;
+  }
+
+  // ============ Consolidation Config ============
+
+  /**
+   * Get a config value
+   */
+  getConfig(key: string): string | null {
+    const row = this.stmt("SELECT value FROM consolidation_config WHERE key = ?").get(key) as { value: string } | undefined;
+    return row?.value ?? null;
+  }
+
+  /**
+   * Get a config value as number
+   */
+  getConfigNumber(key: string, defaultValue: number): number {
+    const value = this.getConfig(key);
+    return value ? parseFloat(value) : defaultValue;
+  }
+
+  /**
+   * Set a config value
+   */
+  setConfig(key: string, value: string): void {
+    this.db.prepare(`
+      INSERT INTO consolidation_config (key, value, updated_at)
+      VALUES (?, ?, CURRENT_TIMESTAMP)
+      ON CONFLICT(key) DO UPDATE SET value = ?, updated_at = CURRENT_TIMESTAMP
+    `).run(key, value, value);
+  }
+
+  /**
+   * Get all config values
+   */
+  getAllConfig(): Record<string, string> {
+    const rows = this.stmt("SELECT key, value FROM consolidation_config").all() as Array<{ key: string; value: string }>;
+    const config: Record<string, string> = {};
+    for (const row of rows) {
+      config[row.key] = row.value;
+    }
+    return config;
+  }
+
+  private rowToCheckpoint(row: Record<string, unknown>): ConsolidationCheckpoint {
+    return {
+      id: row.id as string,
+      run_id: row.run_id as string,
+      phase: row.phase as ConsolidationCheckpoint["phase"],
+      batches_completed: row.batches_completed as number,
+      batches_total: row.batches_total as number,
+      memories_processed: row.memories_processed as number,
+      episodes_processed: row.episodes_processed as number,
+      digests_created: row.digests_created as number,
+      contradictions_found: row.contradictions_found as number,
+      tokens_used: row.tokens_used as number,
+      estimated_cost_usd: row.estimated_cost_usd as number,
+      started_at: new Date(row.started_at as string),
+      updated_at: new Date(row.updated_at as string),
+      completed_at: row.completed_at ? new Date(row.completed_at as string) : null,
+      error: row.error as string | null,
+    };
+  }
+
   // ============ Statistics ============
 
   getStats(): {

package/src/transport/http.ts

@@ -0,0 +1,111 @@
+/**
+ * HTTP Transport for Engram MCP Server
+ * Uses StreamableHTTPServerTransport in stateless mode for Railway deployment
+ */
+
+import http from "http";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+
+interface HttpServerOptions {
+  port: number;
+  server: Server;
+}
+
+/**
+ * Start HTTP server with MCP transport
+ * Returns a promise that resolves when server is listening
+ */
+export async function startHttpServer(options: HttpServerOptions): Promise<http.Server> {
+  const { port, server } = options;
+
+  // Create stateless transport (sessionIdGenerator: undefined)
+  // Stateless mode is perfect for Railway - no session management needed
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+  });
+
+  // Connect MCP server to transport
+  await server.connect(transport);
+
+  // Create HTTP server
+  const httpServer = http.createServer(async (req, res) => {
+    // CORS headers for remote clients (ElevenLabs, etc.)
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, mcp-session-id");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    const url = new URL(req.url || "/", `http://localhost:${port}`);
+
+    // Health check endpoint (Railway uses this)
+    if (url.pathname === "/health" && req.method === "GET") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({
+        status: "ok",
+        transport: "http",
+        version: "0.10.0"
+      }));
+      return;
+    }
+
+    // Root endpoint - service info
+    if (url.pathname === "/" && req.method === "GET") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({
+        name: "engram",
+        description: "MCP memory server with hybrid search",
+        version: "0.10.0",
+        transport: "streamable-http",
+        endpoints: {
+          mcp: "/mcp",
+          health: "/health",
+        },
+      }));
+      return;
+    }
+
+    // MCP endpoint - handles both POST (messages) and GET (SSE stream)
+    if (url.pathname === "/mcp") {
+      try {
+        await transport.handleRequest(req, res);
+      } catch (error) {
+        console.error("[Engram HTTP] Error handling MCP request:", error);
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "Internal server error" }));
+        }
+      }
+      return;
+    }
+
+    // SSE alias (for clients expecting /sse endpoint)
+    if (url.pathname === "/sse") {
+      // Redirect to /mcp which handles SSE via GET
+      res.writeHead(307, { "Location": "/mcp" });
+      res.end();
+      return;
+    }
+
+    // 404 for unknown paths
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Not found" }));
+  });
+
+  // Start listening
+  return new Promise((resolve, reject) => {
+    httpServer.once("error", reject);
+    httpServer.listen(port, () => {
+      console.error(`[Engram] MCP HTTP server running on port ${port}`);
+      console.error(`[Engram] Endpoints:`);
+      console.error(`[Engram]   POST http://localhost:${port}/mcp - MCP protocol`);
+      console.error(`[Engram]   GET  http://localhost:${port}/health - Health check`);
+      resolve(httpServer);
+    });
+  });
+}