@remnic/core 1.1.31 → 9.3.516

package/src/review/index.ts

@@ -79,6 +79,44 @@ interface ReviewFileMatch {
 
 const DEFAULT_CONFIDENCE_THRESHOLD = 0.7;
 
+function realMemoryRoot(memoryDir: string): string | null {
+  try {
+    const stat = fs.lstatSync(memoryDir);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) return null;
+    return fs.realpathSync(memoryDir);
+  } catch {
+    return null;
+  }
+}
+
+function isPathInside(rootReal: string, candidateReal: string): boolean {
+  const relative = path.relative(rootReal, candidateReal);
+  return relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function isSafeDirectory(rootReal: string, dir: string): boolean {
+  try {
+    const stat = fs.lstatSync(dir);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) return false;
+    return isPathInside(rootReal, fs.realpathSync(dir));
+  } catch {
+    return false;
+  }
+}
+
+function ensureSafeDirectory(rootReal: string, dir: string): void {
+  if (fs.existsSync(dir)) {
+    if (!isSafeDirectory(rootReal, dir)) {
+      throw new Error(`Refusing to write through unsafe review path: ${dir}`);
+    }
+    return;
+  }
+  fs.mkdirSync(dir, { recursive: true });
+  if (!isSafeDirectory(rootReal, dir)) {
+    throw new Error(`Refusing to write through unsafe review path: ${dir}`);
+  }
+}
+
 // ── Main functions ───────────────────────────────────────────────────────────
 
 /**
@@ -92,23 +130,29 @@ export function listReviewItems(options: ReviewOptions): ReviewListResult {
     limit = 50,
     confidenceThreshold = DEFAULT_CONFIDENCE_THRESHOLD,
   } = options;
+  const maxItems = Math.max(0, limit);
+  const rootReal = realMemoryRoot(memoryDir);
+  if (!rootReal || maxItems === 0) {
+    return { items: [], total: 0, durationMs: Date.now() - startTime };
+  }
 
   const items: ReviewItem[] = [];
+  const isLimitReached = (): boolean => items.length >= maxItems;
   const addItem = (item: ReviewItem): void => {
-    if (items.length >= limit) return;
+    if (isLimitReached()) return;
     if (filterReason && item.reviewReason !== filterReason) return;
     items.push(item);
   };
 
   // Check suggestions directory
   const suggestionsDir = path.join(memoryDir, "suggestions");
-  if (fs.existsSync(suggestionsDir)) {
-    walkMd(suggestionsDir, (filePath, content) => {
-      if (items.length >= limit) return;
+  if (!isLimitReached() && fs.existsSync(suggestionsDir) && isSafeDirectory(rootReal, suggestionsDir)) {
+    walkMd(rootReal, suggestionsDir, (filePath, content) => {
+      if (isLimitReached()) return true;
 
       const fm = parseFrontmatter(content);
       const body = extractBody(content);
-      if (!fm?.id) return;
+      if (!fm?.id) return false;
 
       addItem({
         id: fm.id as string,
@@ -121,18 +165,19 @@ export function listReviewItems(options: ReviewOptions): ReviewListResult {
         created: (fm.created as string) ?? new Date().toISOString(),
         reviewReason: "suggestion",
       });
+      return isLimitReached();
     });
   }
 
   // Check review directory
   const reviewDir = path.join(memoryDir, "review");
-  if (fs.existsSync(reviewDir)) {
-    walkMd(reviewDir, (filePath, content) => {
-      if (items.length >= limit) return;
+  if (!isLimitReached() && fs.existsSync(reviewDir) && isSafeDirectory(rootReal, reviewDir)) {
+    walkMd(rootReal, reviewDir, (filePath, content) => {
+      if (isLimitReached()) return true;
 
       const fm = parseFrontmatter(content);
       const body = extractBody(content);
-      if (!fm?.id) return;
+      if (!fm?.id) return false;
 
       addItem({
         id: fm.id as string,
@@ -146,30 +191,31 @@ export function listReviewItems(options: ReviewOptions): ReviewListResult {
         reviewReason: (fm.reviewReason as ReviewItem["reviewReason"]) ?? "low_confidence",
         context: fm.context as string | undefined,
       });
+      return isLimitReached();
     });
   }
 
   // Scan all categories for low-confidence items
   const categories = ALL_CATEGORY_DIRS;
   for (const category of categories) {
-    if (items.length >= limit) break;
+    if (isLimitReached()) break;
 
     const dir = path.join(memoryDir, category);
-    if (!fs.existsSync(dir)) continue;
+    if (!fs.existsSync(dir) || !isSafeDirectory(rootReal, dir)) continue;
 
-    walkMd(dir, (filePath, content) => {
-      if (items.length >= limit) return;
+    walkMd(rootReal, dir, (filePath, content) => {
+      if (isLimitReached()) return true;
 
       const fm = parseFrontmatter(content);
       const body = extractBody(content);
-      if (!fm?.id) return;
+      if (!fm?.id) return false;
 
       const confidence = parseConfidence(fm.confidence, 1);
-      if (confidence >= confidenceThreshold) return;
-      if (parseBoolean(fm.reviewDismissed)) return;
+      if (confidence >= confidenceThreshold) return false;
+      if (parseBoolean(fm.reviewDismissed)) return false;
 
       // Skip if already in items
-      if (items.some((i) => i.id === fm.id)) return;
+      if (items.some((i) => i.id === fm.id)) return false;
 
       addItem({
         id: fm.id as string,
@@ -182,6 +228,7 @@ export function listReviewItems(options: ReviewOptions): ReviewListResult {
         created: (fm.created as string) ?? new Date().toISOString(),
         reviewReason: "low_confidence",
       });
+      return isLimitReached();
     });
   }
 
@@ -218,6 +265,8 @@ function approveItem(
   itemId: string,
   options: ReviewActionOptions,
 ): ReviewResult {
+  const rootReal = realMemoryRoot(memoryDir);
+  if (!rootReal) return { itemId, action: "approve", message: "Item not found" };
   const found = findReviewFileById(memoryDir, itemId, options);
   if (!found) {
     return { itemId, action: "approve", message: "Item not found" };
@@ -247,9 +296,10 @@ function approveItem(
   const category = (fm.category as string) ?? "fact";
   const targetDir = getCategoryDir(memoryDir, category);
   const dateDir = new Date().toISOString().split("T")[0];
+  ensureSafeDirectory(rootReal, targetDir);
   const outputPath = path.join(targetDir, dateDir, path.basename(found.filePath));
 
-  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  ensureSafeDirectory(rootReal, path.dirname(outputPath));
   const promotedPath = writeFileWithoutClobber(outputPath, updatedContent, itemId);
 
   // Remove from review
@@ -326,19 +376,21 @@ function findReviewFileById(
   id: string,
   options: ReviewActionOptions = {},
 ): ReviewFileMatch | null {
+  const rootReal = realMemoryRoot(memoryDir);
+  if (!rootReal) return null;
   for (const loc of ["suggestions", "review"]) {
     const dir = path.join(memoryDir, loc);
-    if (!fs.existsSync(dir)) continue;
+    if (!fs.existsSync(dir) || !isSafeDirectory(rootReal, dir)) continue;
 
-    const found = findFileById(dir, id);
+    const found = findFileById(rootReal, dir, id);
     if (found) return { filePath: found, location: "queue" };
   }
 
   for (const category of ALL_CATEGORY_DIRS) {
     const dir = path.join(memoryDir, category);
-    if (!fs.existsSync(dir)) continue;
+    if (!fs.existsSync(dir) || !isSafeDirectory(rootReal, dir)) continue;
 
-    const found = findFileById(dir, id, (fm) => isLowConfidenceReviewCandidate(fm, options));
+    const found = findFileById(rootReal, dir, id, (fm) => isLowConfidenceReviewCandidate(fm, options));
     if (found) return { filePath: found, location: "category" };
   }
 
@@ -346,11 +398,12 @@ function findReviewFileById(
 }
 
 function findFileById(
+  rootReal: string,
   dir: string,
   id: string,
   include?: (frontmatter: Record<string, unknown>) => boolean,
 ): string | null {
-  const files = walkMdPaths(dir);
+  const files = walkMdPaths(rootReal, dir);
   for (const filePath of files) {
     const content = readFileSafe(filePath);
     if (!content) continue;
@@ -510,25 +563,30 @@ function extractBody(content: string): string {
   return match ? match[1].trim() : content.trim();
 }
 
-function walkMd(dir: string, callback: (filePath: string, content: string) => void): void {
+function walkMd(rootReal: string, dir: string, callback: (filePath: string, content: string) => boolean | void): boolean {
+  if (!isSafeDirectory(rootReal, dir)) return false;
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const fullPath = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) continue;
     if (entry.isDirectory()) {
-      walkMd(fullPath, callback);
-    } else if (entry.name.endsWith(".md")) {
+      if (walkMd(rootReal, fullPath, callback)) return true;
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
       const content = readFileSafe(fullPath);
-      if (content) callback(fullPath, content);
+      if (content && callback(fullPath, content) === true) return true;
     }
   }
+  return false;
 }
 
-function walkMdPaths(dir: string): string[] {
+function walkMdPaths(rootReal: string, dir: string): string[] {
   const results: string[] = [];
+  if (!isSafeDirectory(rootReal, dir)) return results;
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const fullPath = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) continue;
     if (entry.isDirectory()) {
-      results.push(...walkMdPaths(fullPath));
-    } else if (entry.name.endsWith(".md")) {
+      results.push(...walkMdPaths(rootReal, fullPath));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
       results.push(fullPath);
     }
   }

package/src/routing/store.ts

@@ -1,6 +1,6 @@
-import { lstat, mkdir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, realpath, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { log } from "../logger.js";
 import { validateRouteTarget, type RouteRule, type RoutingEngineOptions } from "./engine.js";
 
@@ -41,7 +41,6 @@ function resolveStatePath(memoryDir: string, stateFile: string): string {
 
 function normalizeRule(rule: RouteRule, options?: RoutingEngineOptions): RouteRule | null {
   if (!rule || typeof rule !== "object") return null;
-  if (rule.enabled === false) return null;
   if (rule.patternType !== "keyword" && rule.patternType !== "regex") return null;
   if (typeof rule.pattern !== "string" || rule.pattern.trim().length === 0) return null;
   if (typeof rule.priority !== "number" || !Number.isFinite(rule.priority)) return null;
@@ -65,7 +64,7 @@ function normalizeRule(rule: RouteRule, options?: RoutingEngineOptions): RouteRu
     pattern: rule.pattern.trim(),
     priority: normalizedPriority,
     target: normalizedTarget,
-    enabled: true,
+    enabled: rule.enabled === false ? false : true,
   };
 }
 
@@ -233,9 +232,15 @@ export class RoutingRulesStore {
     while (Date.now() - start < timeoutMs) {
       try {
         await mkdir(this.lockPath);
+        const ownerPath = path.join(this.lockPath, "owner");
+        const ownerToken = `${process.pid}:${randomUUID()}`;
+        await writeFile(ownerPath, ownerToken, "utf-8");
         return async () => {
           try {
-            await rm(this.lockPath, { recursive: true, force: true });
+            const currentOwner = await readFile(ownerPath, "utf-8").catch(() => "");
+            if (currentOwner === ownerToken) {
+              await rm(this.lockPath, { recursive: true, force: true });
+            }
           } catch {
             // Fail-open: lock cleanup should not fail writes.
           }
@@ -249,7 +254,7 @@ export class RoutingRulesStore {
         try {
           const lockStat = await stat(this.lockPath);
           if (Date.now() - lockStat.mtimeMs > staleMs) {
-            await rm(this.lockPath, { recursive: true, force: true });
+            await this.removeStaleLock(lockStat);
             continue;
           }
         } catch {
@@ -265,6 +270,31 @@ export class RoutingRulesStore {
     throw new Error(`routing rules lock acquisition timed out after ${timeoutMs}ms`);
   }
 
+  private async removeStaleLock(observedStat: Awaited<ReturnType<typeof stat>>): Promise<void> {
+    const currentStat = await stat(this.lockPath);
+    if (!this.sameLockStat(observedStat, currentStat)) return;
+
+    try {
+      await rmdir(this.lockPath);
+      return;
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code !== "ENOTEMPTY" && code !== "EEXIST") {
+        throw err;
+      }
+    }
+
+    const quarantinePath = `${this.lockPath}.stale-${process.pid}-${Date.now()}-${randomUUID()}`;
+    await rename(this.lockPath, quarantinePath);
+    await rm(quarantinePath, { recursive: true, force: true });
+  }
+
+  private sameLockStat(left: Awaited<ReturnType<typeof stat>>, right: Awaited<ReturnType<typeof stat>>): boolean {
+    if (left.mtimeMs !== right.mtimeMs || left.size !== right.size) return false;
+    if (left.ino && right.ino && left.ino !== right.ino) return false;
+    return true;
+  }
+
   private async assertStatePathScoped(): Promise<void> {
     await mkdir(this.memoryRoot, { recursive: true });
     const canonicalRoot = await realpath(this.memoryRoot);

package/src/runtime/env.test.ts

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { readEnvVar } from "./env.js";
+
+test("readEnvVar prefers REMNIC values over ENGRAM values for paired names", () => {
+  const previousRemnic = process.env.REMNIC_MEMORY_DIR;
+  const previousEngram = process.env.ENGRAM_MEMORY_DIR;
+  try {
+    process.env.REMNIC_MEMORY_DIR = "/new";
+    process.env.ENGRAM_MEMORY_DIR = "/old";
+
+    assert.equal(readEnvVar("REMNIC_MEMORY_DIR"), "/new");
+    assert.equal(readEnvVar("ENGRAM_MEMORY_DIR"), "/new");
+  } finally {
+    if (previousRemnic === undefined) {
+      delete process.env.REMNIC_MEMORY_DIR;
+    } else {
+      process.env.REMNIC_MEMORY_DIR = previousRemnic;
+    }
+    if (previousEngram === undefined) {
+      delete process.env.ENGRAM_MEMORY_DIR;
+    } else {
+      process.env.ENGRAM_MEMORY_DIR = previousEngram;
+    }
+  }
+});
+
+test("readEnvVar falls back to ENGRAM values when REMNIC values are absent", () => {
+  const previousRemnic = process.env.REMNIC_MEMORY_DIR;
+  const previousEngram = process.env.ENGRAM_MEMORY_DIR;
+  try {
+    delete process.env.REMNIC_MEMORY_DIR;
+    process.env.ENGRAM_MEMORY_DIR = "/old";
+
+    assert.equal(readEnvVar("REMNIC_MEMORY_DIR"), "/old");
+    assert.equal(readEnvVar("ENGRAM_MEMORY_DIR"), "/old");
+  } finally {
+    if (previousRemnic === undefined) {
+      delete process.env.REMNIC_MEMORY_DIR;
+    } else {
+      process.env.REMNIC_MEMORY_DIR = previousRemnic;
+    }
+    if (previousEngram === undefined) {
+      delete process.env.ENGRAM_MEMORY_DIR;
+    } else {
+      process.env.ENGRAM_MEMORY_DIR = previousEngram;
+    }
+  }
+});
+
+test("readEnvVar falls back to ENGRAM values when REMNIC values are empty", () => {
+  const previousRemnic = process.env.REMNIC_MEMORY_DIR;
+  const previousEngram = process.env.ENGRAM_MEMORY_DIR;
+  try {
+    process.env.REMNIC_MEMORY_DIR = "";
+    process.env.ENGRAM_MEMORY_DIR = "/old";
+
+    assert.equal(readEnvVar("REMNIC_MEMORY_DIR"), "/old");
+    assert.equal(readEnvVar("ENGRAM_MEMORY_DIR"), "/old");
+  } finally {
+    if (previousRemnic === undefined) {
+      delete process.env.REMNIC_MEMORY_DIR;
+    } else {
+      process.env.REMNIC_MEMORY_DIR = previousRemnic;
+    }
+    if (previousEngram === undefined) {
+      delete process.env.ENGRAM_MEMORY_DIR;
+    } else {
+      process.env.ENGRAM_MEMORY_DIR = previousEngram;
+    }
+  }
+});

package/src/runtime/env.ts

@@ -1,10 +1,6 @@
 import os from "node:os";
 
 type EnvMap = Record<string, string | undefined>;
-const REMNIC_ENGRAM_PREFIX_PAIRS: Array<[string, string]> = [
-  ["REMNIC_", "ENGRAM_"],
-  ["ENGRAM_", "REMNIC_"],
-];
 
 function getEnvMap(): EnvMap | undefined {
   const runtimeProcess = globalThis.process as { env?: EnvMap } | undefined;
@@ -12,20 +8,20 @@ function getEnvMap(): EnvMap | undefined {
 }
 
 function legacyEnvCandidates(name: string): string[] {
-  const candidates = [name];
-  for (const [primary, legacy] of REMNIC_ENGRAM_PREFIX_PAIRS) {
-    if (name.startsWith(primary)) {
-      candidates.push(`${legacy}${name.slice(primary.length)}`);
-    }
+  if (name.startsWith("REMNIC_")) {
+    return [name, `ENGRAM_${name.slice("REMNIC_".length)}`];
   }
-  return candidates;
+  if (name.startsWith("ENGRAM_")) {
+    return [`REMNIC_${name.slice("ENGRAM_".length)}`, name];
+  }
+  return [name];
 }
 
 export function readEnvVar(name: string): string | undefined {
   const env = getEnvMap();
   for (const candidate of legacyEnvCandidates(name)) {
     const value = env?.[candidate];
-    if (typeof value === "string") return value;
+    if (typeof value === "string" && value.length > 0) return value;
   }
   return undefined;
 }

package/src/schemas.ts

@@ -159,6 +159,22 @@ export const ExtractedFactSchema = z.object({
     .describe(
       'For category "reasoning_trace" only: a stored solution chain with ordered steps, a final answer, and an optional observed outcome. Require at least two steps.',
     ),
+}).superRefine((value, ctx) => {
+  if (value.category === "procedure" && (!Array.isArray(value.procedureSteps) || value.procedureSteps.length < 2)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["procedureSteps"],
+      message: "procedure facts require at least two procedureSteps",
+    });
+  }
+
+  if (value.category === "reasoning_trace" && value.reasoningTrace == null) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["reasoningTrace"],
+      message: "reasoning_trace facts require reasoningTrace",
+    });
+  }
 });
 
 export const EntityMentionSchema = z.object({
@@ -446,4 +462,3 @@ export type ConsolidationItemParsed = z.infer<typeof ConsolidationItemSchema>;
 export type ConsolidationResultParsed = z.infer<
   typeof ConsolidationResultSchema
 >;
-

package/src/search/abort.ts

@@ -0,0 +1,18 @@
+import { throwIfAborted } from "../abort-error.js";
+import type { SearchExecutionOptions } from "./port.js";
+
+export function isSearchAborted(execution?: SearchExecutionOptions): boolean {
+  return execution?.signal?.aborted === true;
+}
+
+export function throwIfSearchAborted(
+  execution?: SearchExecutionOptions,
+  message = "search operation aborted",
+): void {
+  throwIfAborted(execution?.signal, message);
+}
+
+export function withTimeoutSignal(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal {
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  return signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+}

package/src/search/document-scanner.test.ts

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { scanMemoryDir } from "./document-scanner.js";
+
+test("scanMemoryDir rejects symlinked category roots", async (t) => {
+  if (process.platform === "win32") {
+    t.skip("directory symlink setup is platform-specific");
+    return;
+  }
+
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-scan-root-"));
+  const outsideDir = await mkdtemp(path.join(os.tmpdir(), "remnic-scan-outside-"));
+  try {
+    await writeFile(
+      path.join(outsideDir, "outside.md"),
+      [
+        "---",
+        "id: outside",
+        "---",
+        "Outside memory should not be indexed.",
+      ].join("\n"),
+      "utf8",
+    );
+    await symlink(outsideDir, path.join(memoryDir, "facts"), "dir");
+
+    await assert.rejects(
+      () => scanMemoryDir(memoryDir),
+      /symlinked memory category directory/,
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+    await rm(outsideDir, { recursive: true, force: true });
+  }
+});
+
+test("scanMemoryDir skips nested symlink entries", async (t) => {
+  if (process.platform === "win32") {
+    t.skip("directory symlink setup is platform-specific");
+    return;
+  }
+
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-scan-nested-"));
+  const outsideDir = await mkdtemp(path.join(os.tmpdir(), "remnic-scan-nested-outside-"));
+  try {
+    const factsDir = path.join(memoryDir, "facts");
+    await mkdir(factsDir, { recursive: true });
+    await writeFile(
+      path.join(factsDir, "inside.md"),
+      [
+        "---",
+        "id: inside",
+        "---",
+        "Inside memory should be indexed.",
+      ].join("\n"),
+      "utf8",
+    );
+    await writeFile(
+      path.join(outsideDir, "outside.md"),
+      [
+        "---",
+        "id: outside",
+        "---",
+        "Outside memory should not be indexed.",
+      ].join("\n"),
+      "utf8",
+    );
+    await symlink(outsideDir, path.join(factsDir, "outside"), "dir");
+
+    const docs = await scanMemoryDir(memoryDir);
+
+    assert.deepEqual(docs.map((doc) => doc.docid), ["inside"]);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+    await rm(outsideDir, { recursive: true, force: true });
+  }
+});

package/src/search/document-scanner.ts

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { readdir, readFile } from "node:fs/promises";
+import { lstat, readdir, readFile, realpath } from "node:fs/promises";
 
 export interface IndexableDocument {
   /** Memory ID from frontmatter or filename stem */
@@ -40,17 +40,31 @@ function parseFrontmatter(raw: string): { data: Record<string, string>; body: st
 /**
  * Recursively scan a directory for `.md` files and return IndexableDocuments.
  */
-async function scanDir(dir: string): Promise<IndexableDocument[]> {
+async function scanDir(dir: string, memoryRootReal: string): Promise<IndexableDocument[]> {
   const docs: IndexableDocument[] = [];
   try {
+    const dirStat = await lstat(dir);
+    if (dirStat.isSymbolicLink()) {
+      throw new Error(`Refusing to scan symlinked memory category directory: ${dir}`);
+    }
+    if (!dirStat.isDirectory()) {
+      const error = new Error(`Memory category path is not a directory: ${dir}`) as NodeJS.ErrnoException;
+      error.code = "ENOTDIR";
+      throw error;
+    }
+    assertPathInsideRoot(memoryRootReal, await realpath(dir), dir);
+
     const entries = await readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
       const fullPath = path.join(dir, entry.name);
       if (entry.isDirectory()) {
-        const sub = await scanDir(fullPath);
+        assertPathInsideRoot(memoryRootReal, await realpath(fullPath), fullPath);
+        const sub = await scanDir(fullPath, memoryRootReal);
         docs.push(...sub);
       } else if (entry.name.endsWith(".md")) {
         try {
+          assertPathInsideRoot(memoryRootReal, await realpath(fullPath), fullPath);
           const raw = await readFile(fullPath, "utf-8");
           const parsed = parseFrontmatter(raw);
           const body = parsed ? parsed.body : raw.trim();
@@ -66,12 +80,31 @@ async function scanDir(dir: string): Promise<IndexableDocument[]> {
         }
       }
     }
-  } catch {
-    // Directory doesn't exist yet — not an error
+  } catch (err) {
+    if (isNodeError(err) && err.code === "ENOENT") {
+      // Optional category directories may not exist yet.
+      return docs;
+    }
+    throw err;
   }
   return docs;
 }
 
+function isNodeError(err: unknown): err is NodeJS.ErrnoException {
+  return typeof err === "object" && err !== null && "code" in err;
+}
+
+function pathIsInside(parent: string, child: string): boolean {
+  const relative = path.relative(parent, child);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function assertPathInsideRoot(rootReal: string, candidateReal: string, originalPath: string): void {
+  if (!pathIsInside(rootReal, candidateReal)) {
+    throw new Error(`Refusing to scan memory path outside memoryDir: ${originalPath}`);
+  }
+}
+
 /**
  * Scan `facts/`, `corrections/`, `procedures/`, and `reasoning-traces/`
  * subdirs of memoryDir for indexable markdown documents.
@@ -82,15 +115,24 @@ async function scanDir(dir: string): Promise<IndexableDocument[]> {
  * or those backends silently stop seeing the new memories.
  */
 export async function scanMemoryDir(memoryDir: string): Promise<IndexableDocument[]> {
+  let memoryRootReal: string;
+  try {
+    memoryRootReal = await realpath(memoryDir);
+  } catch (err) {
+    if (isNodeError(err) && err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
   const factsDir = path.join(memoryDir, "facts");
   const correctionsDir = path.join(memoryDir, "corrections");
   const proceduresDir = path.join(memoryDir, "procedures");
   const reasoningTracesDir = path.join(memoryDir, "reasoning-traces");
   const [facts, corrections, procedures, reasoningTraces] = await Promise.all([
-    scanDir(factsDir),
-    scanDir(correctionsDir),
-    scanDir(proceduresDir),
-    scanDir(reasoningTracesDir),
+    scanDir(factsDir, memoryRootReal),
+    scanDir(correctionsDir, memoryRootReal),
+    scanDir(proceduresDir, memoryRootReal),
+    scanDir(reasoningTracesDir, memoryRootReal),
   ]);
   return [...facts, ...corrections, ...procedures, ...reasoningTraces];
 }