@lotargo/memory_plugin 1.5.3 → 1.6.1

package/mcp-server/cli_boot.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+// ── CLI Boot Guard ──────────────────────────────────────────────────────────
+// Same version check as boot.js — see that file for the rationale.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const MIN_MAJOR = 22;
+const MIN_MINOR = 5;
+
+const [major, minor] = process.versions.node.split(".").map(Number);
+
+if (major < MIN_MAJOR || (major === MIN_MAJOR && minor < MIN_MINOR)) {
+  process.stderr.write(
+    `\n` +
+    `  ╔══════════════════════════════════════════════════════════════════╗\n` +
+    `  ║  @lotargo/memory_plugin requires Node.js >= 22.5.0             ║\n` +
+    `  ║                                                                ║\n` +
+    `  ║  Detected: Node.js ${process.versions.node.padEnd(44)}║\n` +
+    `  ║                                                                ║\n` +
+    `  ║  The built-in node:sqlite module used by this plugin was       ║\n` +
+    `  ║  introduced in Node.js 22.5.0.  Please upgrade your           ║\n` +
+    `  ║  Node.js installation:                                        ║\n` +
+    `  ║                                                                ║\n` +
+    `  ║    nvm install 22   # or: brew install node@22                 ║\n` +
+    `  ║                                                                ║\n` +
+    `  ╚══════════════════════════════════════════════════════════════════╝\n` +
+    `\n`
+  );
+  process.exit(1);
+}
+
+// Version is OK — hand off to the real CLI.
+import("./cli.js").then(m => {
+  if (process.argv[1] && process.argv[1].includes("cli_boot.js")) {
+    m.runCli().catch((err) => console.error("CLI error:", err));
+  }
+});

package/mcp-server/config/auth_store.js

@@ -57,14 +57,17 @@ function getMachineId() {
   return _cachedMachineId;
 }
 
-// Generate a deterministic hardware + system fingerprint (stable across reboots,
-// network changes and user sessions on the same machine).
+// OWASP 2023 recommendation for PBKDF2-HMAC-SHA256.
+const PBKDF2_ITERATIONS = 600000;
+const LEGACY_PBKDF2_ITERATIONS = 10000;
+
+// Generate a deterministic hardware fingerprint. Only STABLE components are used:
+// hostname and username are volatile (renaming the machine or the account would
+// permanently lock the user out of their own secrets), so they are excluded.
 function getSystemFingerprint() {
   if (_cachedFingerprint !== null && _cachedFingerprint !== undefined) return _cachedFingerprint;
   const parts = [
     getMachineId() || "no-machine-id",
-    os.hostname() || "localhost",
-    os.userInfo()?.username || "default_user",
     os.platform() || "unknown",
     os.arch() || "unknown",
   ];
@@ -72,16 +75,38 @@ function getSystemFingerprint() {
   return _cachedFingerprint;
 }
 
+// Fingerprint used by <= 1.5.3 (included volatile hostname/username).
+function getLegacyFingerprint() {
+  return [
+    getMachineId() || "no-machine-id",
+    os.hostname() || "localhost",
+    os.userInfo()?.username || "default_user",
+    os.platform() || "unknown",
+    os.arch() || "unknown",
+  ].join("|");
+}
+
+function deriveKey(fingerprint, iterations) {
+  const salt = crypto.createHash("sha256").update(fingerprint).digest();
+  return crypto.pbkdf2Sync(fingerprint, salt, iterations, 32, "sha256");
+}
+
 // Derive a 256-bit (32 bytes) key using PBKDF2 with salt derived from fingerprint
 function deriveEncryptionKey() {
   if (_cachedEncryptionKey) return _cachedEncryptionKey;
-  const fingerprint = getSystemFingerprint();
-  const salt = crypto.createHash("sha256").update(fingerprint).digest();
-  // PBKDF2 with 10,000 iterations to derive a secure 32-byte key
-  _cachedEncryptionKey = crypto.pbkdf2Sync(fingerprint, salt, 10000, 32, "sha256");
+  _cachedEncryptionKey = deriveKey(getSystemFingerprint(), PBKDF2_ITERATIONS);
   return _cachedEncryptionKey;
 }
 
+// Keys accepted for DECRYPTION only, so secrets written by older versions keep
+// working; they are transparently re-encrypted with the current key on read.
+function legacyDecryptionKeys() {
+  return [
+    deriveKey(getLegacyFingerprint(), LEGACY_PBKDF2_ITERATIONS),
+    deriveKey(getSystemFingerprint(), LEGACY_PBKDF2_ITERATIONS),
+  ];
+}
+
 // Encrypt data using AES-256-GCM
 export function encryptData(plainText) {
   const key = deriveEncryptionKey();
@@ -105,19 +130,35 @@ export function decryptData(encryptedStr) {
   }
 
   const [ivHex, authTagHex, encryptedHex] = parts;
-  const key = deriveEncryptionKey();
   const iv = Buffer.from(ivHex, "hex");
   const authTag = Buffer.from(authTagHex, "hex");
 
-  const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
-  decipher.setAuthTag(authTag);
-
-  let decrypted = decipher.update(encryptedHex, "hex", "utf8");
-  decrypted += decipher.final("utf8");
+  const tryKey = (key) => {
+    const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(authTag);
+    let decrypted = decipher.update(encryptedHex, "hex", "utf8");
+    decrypted += decipher.final("utf8");
+    return decrypted;
+  };
 
-  return decrypted;
+  try {
+    return tryKey(deriveEncryptionKey());
+  } catch (err) {
+    for (const legacyKey of legacyDecryptionKeys()) {
+      try {
+        const plain = tryKey(legacyKey);
+        _needsReEncrypt = true;
+        return plain;
+      } catch {}
+    }
+    throw err;
+  }
 }
 
+// Set when a secret was decrypted with a legacy key so it can be rewritten
+// under the current derivation parameters.
+let _needsReEncrypt = false;
+
 // Load a KEY=VALUE .env file from MEMORY_DIR (global environment override for
 // headless / Docker / CI deployments). Values may optionally be quoted.
 function loadEnvFile() {
@@ -194,7 +235,15 @@ function readStoredSecrets() {
   try {
     const encrypted = fs.readFileSync(SECRETS_FILE, "utf-8").trim();
     if (!encrypted) { _cachedSecrets = null; return null; }
+    _needsReEncrypt = false;
     _cachedSecrets = JSON.parse(decryptData(encrypted));
+    if (_needsReEncrypt) {
+      _needsReEncrypt = false;
+      try {
+        writeSecretsFile(encryptData(JSON.stringify(_cachedSecrets)));
+        _cachedSecretsMtime = fs.statSync(SECRETS_FILE).mtimeMs;
+      } catch {}
+    }
     return _cachedSecrets;
   } catch (err) {
     console.error(
@@ -221,11 +270,20 @@ export function getSecretsSource() {
 }
 
 // Save secrets securely
+// Write the secrets file with owner-only permissions (0600). On Linux/macOS a
+// default 0644 would let any other local user read auth_secrets.enc.
+function writeSecretsFile(encrypted) {
+  fs.writeFileSync(SECRETS_FILE, encrypted, { encoding: "utf-8", mode: 0o600 });
+  try {
+    fs.chmodSync(SECRETS_FILE, 0o600);
+  } catch {}
+}
+
 export function saveSecrets(secrets) {
   ensureDirSync();
   const plainText = JSON.stringify(secrets);
   const encrypted = encryptData(plainText);
-  fs.writeFileSync(SECRETS_FILE, encrypted, "utf-8");
+  writeSecretsFile(encrypted);
   _cachedSecrets = undefined;  // invalidate so readStoredSecrets re-reads
   _cachedSecretsMtime = 0;
   if (typeof _onSecretsChanged === "function") _onSecretsChanged();

package/mcp-server/config/config_manager.js

@@ -8,9 +8,11 @@ export const DEFAULT_CONFIG = {
   fusionAlgorithm: "rsf", // "rsf" | "rrf" | "semantic_only" | "lexical_only"
   alpha: 0.5,             // Weight for vector similarity in RSF [0.0 - 1.0] (50/50 balance)
   embeddingModel: "Xenova/multilingual-e5-small",
+  vectorDimension: 0,     // Fixed embedding dimension (0 = auto-detect from model output)
   rerankerModel: "none",   // "none" | "Xenova/bge-reranker-base" | custom HF model
   rerankerEnabled: false,
   batchSize: 12,           // Ingestion vector batch size [1 - 256] (default 12)
+  vectorScanLimit: 50000,  // Max micro-chunks scanned per vector query (0 = unlimited)
   gpuAttentionBudget: 2000000, // GPU micro-batch attention budget [1M - 16M] (default 2.0M ~1.5GB VRAM)
   onnxThreads: 0,          // ONNX WASM threads: 0 = auto-detect CPU cores, or 1-16
   executionDevice: "cpu",  // "cpu" | "webgpu"
@@ -21,6 +23,8 @@ export const DEFAULT_CONFIG = {
   failoverUrl: "",        // Failover connection endpoint URL (Fly.io + LiteFS)
   authorized: false,      // True once the user completed cloud login (token stored encrypted)
   username: "",           // Account username from the Turso OAuth profile
+  ingestAllowedPaths: [], // Extra directories ingest_document(type:"file") may read from
+  ingestAllowAnyPath: false, // Escape hatch: allow reading ANY path from disk (unsafe)
 };
 
 let cachedConfig = null;

package/mcp-server/db/database.js

@@ -34,19 +34,19 @@ class DatabaseWrapper {
 
     while (attempts < maxAttempts) {
       attempts++;
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+      // A plain timer is enough here; an AbortController per attempt leaked its
+      // "abort" listener because it was never removed.
+      let timeoutId = null;
+      const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(
+          () => reject(new Error(`Database operation timed out after ${timeoutMs / 1000} seconds`)),
+          timeoutMs
+        );
+      });
 
       try {
         const client = (this.usingFailover && this.failoverClient) ? this.failoverClient : this.cloudClient;
-        const result = await Promise.race([
-          fn(client),
-          new Promise((_, reject) => {
-            controller.signal.addEventListener("abort", () => {
-              reject(new Error("Database operation timed out after 10 seconds"));
-            });
-          })
-        ]);
+        const result = await Promise.race([fn(client), timeoutPromise]);
         clearTimeout(timeoutId);
         // Successful operation, reset consecutive failures
         this.consecutiveFailures = 0;
@@ -156,6 +156,9 @@ async function openDatabase(customPath, mode) {
     localDb = new DatabaseSync(dbPath);
     localDb.exec("PRAGMA foreign_keys = ON;");
     localDb.exec("PRAGMA journal_mode = WAL;");
+    // Default busy_timeout is 0 => an immediate SQLITE_BUSY ("database is
+    // locked") whenever background sync, ingestion and MCP calls overlap.
+    localDb.exec("PRAGMA busy_timeout = 5000;");
   }
 
   let cloudClient = null;
@@ -179,10 +182,16 @@ async function openDatabase(customPath, mode) {
           authToken: token || undefined,
         });
       }
-      // In hybrid-sync mode, ensure remote schema is also fully migrated and up to date
+      // In hybrid-sync mode, ensure remote schema is also fully migrated and up to date.
+      // Use a dedicated short-lived client so closing it doesn't kill the shared one.
       if (mode === "hybrid-sync") {
-        const cloudDbWrapper = new DatabaseWrapper(null, cloudClient, "only-cloud", failoverClient);
+        const remoteClient = createClient({
+          url: tursoUrl,
+          authToken: token || undefined,
+        });
+        const cloudDbWrapper = new DatabaseWrapper(null, remoteClient, "only-cloud", null);
         await runMigrations(cloudDbWrapper);
+        cloudDbWrapper.close();
       }
     } else if (mode === "only-cloud") {
       throw new Error("Turso URL is required for only-cloud mode. Please login first.");
@@ -195,6 +204,13 @@ async function openDatabase(customPath, mode) {
   await runMigrations(wrappedDb);
 
   if (!customPath) {
+    // Closing the previous instance before replacing it: otherwise a mode switch
+    // leaked the old DatabaseSync handle and Turso client.
+    if (dbInstance && dbInstance !== wrappedDb) {
+      try {
+        dbInstance.close();
+      } catch {}
+    }
     dbInstance = wrappedDb;
   }
 
@@ -209,8 +225,11 @@ export async function getDatabase(customPath = null, forceMode = null) {
     if (dbInstance && dbInstance.mode === mode) {
       return dbInstance;
     }
-    // After a failed init, wait before retrying to avoid hammering cloud auth
-    if (!dbInitPromise && dbLastFailAt && (Date.now() - dbLastFailAt) < DB_FAIL_COOLDOWN_MS) {
+    // After a failed init, wait before retrying to avoid hammering cloud auth.
+    // Only cloud modes are throttled — reopening a local SQLite file is cheap
+    // and must never be blocked by an unrelated cloud failure.
+    const isCloudMode = mode === "only-cloud" || mode === "hybrid-sync";
+    if (isCloudMode && !dbInitPromise && dbLastFailAt && (Date.now() - dbLastFailAt) < DB_FAIL_COOLDOWN_MS) {
       throw new Error("Database initialization failed recently. Retrying in a few seconds...");
     }
     // Deduplicate concurrent default-DB initialization so migrations never run

package/mcp-server/db/sync_queue.js

@@ -1,6 +1,7 @@
 import { readFile, readdir } from "fs/promises";
-import { join, basename } from "path";
-import { MEMORY_DIR, GLOBAL_KEY, buildMemoryContent, extractFacts, writeMemoryFile, storeFilePath, memoryFileName } from "../memory.js";
+import { join } from "path";
+import { MEMORY_DIR, GLOBAL_KEY, buildMemoryContent, extractFacts, writeMemoryFile } from "../memory.js";
+import { toVectorBytes } from "../retrieval/retriever.js";
 
 let isSyncing = false;
 
@@ -104,18 +105,12 @@ async function processSyncTask(db, task) {
     // 5. Insert micro_chunks & FTS
     if (Array.isArray(data.micro_chunks)) {
       for (const mc of data.micro_chunks) {
-        let vecBuf = Buffer.alloc(0);
-        if (mc.vector) {
-          if (Buffer.isBuffer(mc.vector)) {
-            vecBuf = mc.vector;
-          } else if (typeof mc.vector === "string") {
-            vecBuf = Buffer.from(mc.vector, "base64");
-          } else if (mc.vector.type === "Buffer" && Array.isArray(mc.vector.data)) {
-            vecBuf = Buffer.from(mc.vector.data);
-          } else if (Array.isArray(mc.vector)) {
-            vecBuf = Buffer.from(mc.vector);
-          }
-        }
+        // node:sqlite hands back Uint8Array, which matched none of the old
+        // branches — hybrid-sync silently pushed EMPTY vectors to the cloud.
+        const vecBytes = toVectorBytes(mc.vector);
+        const vecBuf = vecBytes
+          ? Buffer.from(vecBytes.buffer, vecBytes.byteOffset, vecBytes.byteLength)
+          : Buffer.alloc(0);
         await db.cloudClient.execute({
           sql: "INSERT INTO micro_chunks (id, section_id, doc_id, content, vector, token_count, medium_id) VALUES (?, ?, ?, ?, ?, ?, ?);",
           args: [mc.id, mc.section_id, doc.id, mc.content, vecBuf, mc.token_count, mc.medium_id || null],
@@ -172,11 +167,6 @@ export async function enqueueSyncTask(action, keyOrId, payload = null) {
   });
 }
 
-// Map a store key to its local file path, mirroring memory.js naming.
-function localFilePath(key) {
-  return join(MEMORY_DIR, memoryFileName(key));
-}
-
 // Enumerate local store files as { key, path }.
 async function enumerateLocalStores() {
   const files = await readdir(MEMORY_DIR).catch(() => []);

package/mcp-server/index.js

@@ -1,42 +1,112 @@
-#!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { ensureDir, MEMORY_DIR } from "./memory.js";
-import { registerAllTools } from "./tools/index.js";
-
-const cliArgs = process.argv.slice(2);
-
-if (cliArgs.includes("setup") || cliArgs.includes("install") || cliArgs.includes("--setup") || cliArgs.includes("-s")) {
-  const { runSetup } = await import("./setup.js");
-  await runSetup();
-  process.exit(0);
-}
-
-if (
-  cliArgs.includes("cli") ||
-  cliArgs.includes("config") ||
-  cliArgs.includes("--cli") ||
-  cliArgs.includes("-c") ||
-  cliArgs.includes("login") ||
-  cliArgs.includes("logout") ||
-  cliArgs.includes("auth-status") ||
-  cliArgs.includes("auth_status") ||
-  cliArgs.includes("auth")
-) {
-  const { runCli } = await import("./cli.js");
-  await runCli();
-  process.exit(0);
-}
-
-await ensureDir();
-
-const server = new McpServer({
-  name: "memory-agent",
-  version: "1.5.2",
-});
-
-registerAllTools(server);
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
-console.error(`memory-agent MCP server running, data dir: ${MEMORY_DIR}`);
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ensureDir, MEMORY_DIR } from "./memory.js";
+import { registerAllTools } from "./tools/index.js";
+import { closeDatabase } from "./db/database.js";
+import { readFileSync } from "node:fs";
+
+function readPackageVersion() {
+  try {
+    const pkgUrl = new URL("../package.json", import.meta.url);
+    return JSON.parse(readFileSync(pkgUrl, "utf8")).version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+const cliArgs = process.argv.slice(2);
+
+// Every command handled by cli.js/direct_commands.js must be routed here too,
+// otherwise `memory_plugin link` etc. would fall through and start an MCP
+// server that silently blocks on stdin.
+const CLI_COMMANDS = new Set([
+  "cli",
+  "config",
+  "--cli",
+  "-c",
+  "login",
+  "logout",
+  "auth-status",
+  "auth_status",
+  "auth",
+  "link",
+  "unlink",
+  "relink",
+  "identity",
+  "migrate_titles",
+  "enable-prompt",
+  "disable-prompt",
+]);
+
+function printUsage() {
+  console.log(`memory_plugin v${readPackageVersion()} — hybrid RAG memory for AI coding agents
+
+Usage:
+  memory_plugin                      Start the MCP server on stdio (default)
+  memory_plugin setup [--opencode|--claude|--codex|--antigravity] [--mode <MODE>]
+  memory_plugin cli                  Interactive terminal UI
+  memory_plugin login [--from-env|--api-token|--db-url <URL>]
+  memory_plugin logout [--api-key]
+  memory_plugin auth-status
+  memory_plugin link|unlink|relink|identity [--dir <path>] [--remote <url>]
+  memory_plugin migrate_titles [--key <key>]
+  memory_plugin enable-prompt | disable-prompt
+
+Options:
+  -h, --help                         Show this help text
+  -v, --version                      Print the package version
+
+Secrets: prefer TURSO_API_TOKEN / TURSO_DB_URL / TURSO_DB_TOKEN environment
+variables over command-line flags — argv is visible to other local processes.
+Data directory: ${MEMORY_DIR}`);
+}
+
+if (cliArgs.includes("--help") || cliArgs.includes("-h") || cliArgs[0] === "help") {
+  printUsage();
+  process.exit(0);
+}
+
+if (cliArgs.includes("--version") || cliArgs.includes("-v")) {
+  console.log(readPackageVersion());
+  process.exit(0);
+}
+
+if (cliArgs.includes("setup") || cliArgs.includes("install") || cliArgs.includes("--setup") || cliArgs.includes("-s")) {
+  const { runSetup } = await import("./setup.js");
+  await runSetup();
+  process.exit(0);
+}
+
+if (cliArgs.some((a) => CLI_COMMANDS.has(a))) {
+  const { runCli } = await import("./cli.js");
+  await runCli();
+  process.exit(0);
+}
+
+await ensureDir();
+
+process.on("exit", () => {
+  try {
+    closeDatabase();
+  } catch {}
+});
+for (const sig of ["SIGINT", "SIGTERM"]) {
+  process.on(sig, () => {
+    try {
+      closeDatabase();
+    } catch {}
+    process.exit(0);
+  });
+}
+
+const server = new McpServer({
+  name: "memory-agent",
+  version: readPackageVersion(),
+});
+
+registerAllTools(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`memory-agent MCP server running, data dir: ${MEMORY_DIR}`);

package/mcp-server/ingest/normalizer.js

@@ -1,4 +1,6 @@
 import { basename, extname } from "node:path";
+import { isIP } from "node:net";
+import { lookup } from "node:dns/promises";
 import { PDFParse } from "pdf-parse";
 import mammoth from "mammoth";
 import xlsx from "xlsx";
@@ -45,46 +47,131 @@ export function validateUrlForSsrf(urlStr) {
     throw new Error(`Unsupported URL scheme '${parsed.protocol}'. Only http/https are allowed.`);
   }
 
-  const hostname = parsed.hostname.toLowerCase();
-
-  const isBlocked =
-    hostname === "localhost" ||
-    hostname === "127.0.0.1" ||
-    hostname === "::1" ||
-    hostname === "169.254.169.254" ||
-    hostname === "metadata.google.internal" ||
-    /^127\./.test(hostname) ||
-    /^10\./.test(hostname) ||
-    /^192\.168\./.test(hostname) ||
-    /^172\.(1[6-9]|2[0-9]|3[0-1])\./.test(hostname) ||
-    /^169\.254\./.test(hostname) ||
-    /^0\./.test(hostname);
-
-  if (isBlocked) {
+  const hostname = normalizeHostname(parsed.hostname);
+
+  if (isBlockedHost(hostname)) {
     throw new Error(`Ingestion blocked: URL '${urlStr}' targets a private/local IP address or metadata service.`);
   }
 
   return parsed;
 }
 
+// URL.hostname keeps the brackets for IPv6 literals ("[::1]"), which broke the
+// plain string comparisons and allowed http://[::1]/ and IPv4-mapped forms through.
+export function normalizeHostname(rawHostname) {
+  let host = String(rawHostname || "").toLowerCase();
+  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
+  if (host.endsWith(".")) host = host.slice(0, -1);
+  return host;
+}
+
+function isPrivateIPv4(host) {
+  if (isIP(host) !== 4) return false;
+  const [a, b] = host.split(".").map(Number);
+  if (a === 127 || a === 0 || a === 10) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT 100.64.0.0/10
+  if (a >= 224) return true; // multicast + reserved
+  return false;
+}
+
+function isPrivateIPv6(host) {
+  if (isIP(host) !== 6) return false;
+  // IPv4-mapped / IPv4-compatible forms: ::ffff:127.0.0.1 and ::ffff:7f00:1
+  const mapped = extractMappedIPv4(host);
+  if (mapped) return isPrivateIPv4(mapped);
+
+  if (host === "::" || host === "::1") return true;
+  if (/^fe[89ab]/.test(host)) return true; // fe80::/10 link-local
+  if (/^f[cd]/.test(host)) return true;    // fc00::/7 unique-local
+  if (/^ff/.test(host)) return true;       // ff00::/8 multicast
+  if (/^0{0,4}:/.test(host) && !host.startsWith("::ffff:")) return true; // ::/8
+  return false;
+}
+
+function extractMappedIPv4(host) {
+  const dotted = host.match(/::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+  if (dotted) return dotted[1];
+  const hex = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (hex) {
+    const hi = parseInt(hex[1], 16);
+    const lo = parseInt(hex[2], 16);
+    return `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+  }
+  return null;
+}
+
+export function isBlockedHost(hostname) {
+  const host = normalizeHostname(hostname);
+  if (!host) return true;
+  if (host === "localhost" || host.endsWith(".localhost")) return true;
+  if (host === "metadata.google.internal" || host === "metadata") return true;
+  if (isPrivateIPv4(host)) return true;
+  if (isPrivateIPv6(host)) return true;
+  return false;
+}
+
+// Defence against DNS rebinding: resolve the hostname and re-check the actual
+// address before the request is issued.
+export async function assertResolvedHostAllowed(hostname) {
+  const host = normalizeHostname(hostname);
+  if (isIP(host)) return;
+  let addresses;
+  try {
+    addresses = await lookup(host, { all: true, verbatim: true });
+  } catch {
+    return; // fetch() will surface the resolution error itself
+  }
+  for (const { address } of addresses) {
+    if (isBlockedHost(address)) {
+      throw new Error(
+        `Ingestion blocked: host '${host}' resolves to a private/local address (${address}).`
+      );
+    }
+  }
+}
+
 // Fetch a web page and convert it to Markdown/text. Used by the 'url' ingestion type
 // so the RAG store gets the page CONTENT, not just the URL string.
 export async function fetchUrlContent(url) {
   const parsed = validateUrlForSsrf(url);
-  const targetUrl = parsed.toString();
-  let res;
-  try {
-    res = await fetch(targetUrl, {
-      headers: {
-        "User-Agent": "memory-agent-rag/1.0",
-        Accept: "text/html,application/xhtml+xml,application/json,text/plain,*/*",
-      },
-      redirect: "follow",
-      signal: AbortSignal.timeout(15000),
-    });
-  } catch (err) {
-    throw new Error(`Failed to fetch URL '${url}': ${err.message}`);
+  await assertResolvedHostAllowed(parsed.hostname);
+  let currentUrl = parsed.toString();
+
+  const fetchOnce = async (targetUrl) => {
+    try {
+      return await fetch(targetUrl, {
+        headers: {
+          "User-Agent": "memory-agent-rag/1.0",
+          Accept: "text/html,application/xhtml+xml,application/json,text/plain,*/*",
+        },
+        redirect: "manual",
+        signal: AbortSignal.timeout(15000),
+      });
+    } catch (err) {
+      throw new Error(`Failed to fetch URL '${url}': ${err.message}`);
+    }
+  };
+
+  // Follow up to 3 redirect hops manually, re-validating each target against SSRF rules.
+  let res = await fetchOnce(currentUrl);
+  for (let hop = 0; hop < 3 && res.status >= 300 && res.status < 400; hop++) {
+    const location = res.headers.get("location");
+    if (!location) break;
+    let redirectUrl;
+    try {
+      redirectUrl = new URL(location, currentUrl);
+    } catch {
+      throw new Error(`URL '${url}' redirected to an invalid location`);
+    }
+    validateUrlForSsrf(redirectUrl.toString());
+    await assertResolvedHostAllowed(redirectUrl.hostname);
+    currentUrl = redirectUrl.toString();
+    res = await fetchOnce(currentUrl);
   }
+
   if (!res.ok) {
     throw new Error(`Failed to fetch URL '${url}': HTTP ${res.status} ${res.statusText}`);
   }