total-recall-brain 3.18.3 → 3.19.0

package/src/core/clarity-rewriter.mjs

@@ -567,24 +567,42 @@ export async function runCutoffAudit({ vaultDir, queueDir, runtimeConfig }) {
   return { audited: batch.length, flagged, critical };
 }
 
+/** Resolve vault dir from node file path (…/memory-vault/category/slug.md). */
+function vaultDirFromNodeFile(filePath) {
+  if (!filePath) return null;
+  let cur = path.dirname(filePath);
+  while (cur && cur !== path.dirname(cur)) {
+    if (path.basename(cur) === 'memory-vault') return cur;
+    cur = path.dirname(cur);
+  }
+  // Fallback: parent of category dir
+  return path.dirname(path.dirname(filePath));
+}
+
+function nodeFilePath(node) {
+  return node?._filepath || node?._filePath || null;
+}
+
 async function stampVerified(node) {
-  if (!node._filepath) return;
+  const fp = nodeFilePath(node);
+  if (!fp) return;
   try {
-    const raw = fs.readFileSync(node._filepath, 'utf8');
+    const raw = fs.readFileSync(fp, 'utf8');
     const { data, content } = matter(raw);
     data.x_cutoff_verified_at = new Date().toISOString();
     data.x_cutoff_risk = 'none';
-    atomicWrite(node._filepath, safeStringify(content, data));
-    invalidate(path.dirname(node._filepath));
+    atomicWrite(fp, safeStringify(content, data));
+    invalidate(vaultDirFromNodeFile(fp));
   } catch (err) {
     logger.debug('clarity-rewriter: stampCutoffRiskNone failed', { err: err.message });
   }
 }
 
 async function stampCutoffRisk(node, riskLevel, claimCount) {
-  if (!node._filepath) return;
+  const fp = nodeFilePath(node);
+  if (!fp) return;
   try {
-    const raw = fs.readFileSync(node._filepath, 'utf8');
+    const raw = fs.readFileSync(fp, 'utf8');
     const { data, content } = matter(raw);
     data.x_cutoff_risk = riskLevel;
     data.x_cutoff_claim_count = claimCount;
@@ -592,8 +610,8 @@ async function stampCutoffRisk(node, riskLevel, claimCount) {
     // Lower confidence to reflect that claims are unverified
     const confidencePenalty = riskLevel === 'critical' ? 0.3 : riskLevel === 'high' ? 0.2 : 0.1;
     data.confidence = Math.max(0.1, (data.confidence || 0.5) - confidencePenalty);
-    atomicWrite(node._filepath, safeStringify(content, data));
-    invalidate(path.dirname(node._filepath));
+    atomicWrite(fp, safeStringify(content, data));
+    invalidate(vaultDirFromNodeFile(fp));
   } catch (err) {
     logger.debug('clarity-rewriter: stampCutoffRisk failed', { err: err.message });
   }
@@ -756,9 +774,10 @@ export async function writeCorrection(originalSlug, researchEvidence, { vaultDir
 }
 
 async function stampNodeForCorrection(node, correctionSlug, disposition) {
-  if (!node._filepath) return;
+  const fp = nodeFilePath(node);
+  if (!fp) return;
   try {
-    const raw = fs.readFileSync(node._filepath, 'utf8');
+    const raw = fs.readFileSync(fp, 'utf8');
     const { data, content } = matter(raw);
     data.status = disposition === 'deleted' ? 'archived' : 'superseded';
     data.superseded_by = correctionSlug;
@@ -766,8 +785,8 @@ async function stampNodeForCorrection(node, correctionSlug, disposition) {
     // Lower confidence significantly — this fact has been proven wrong
     data.confidence = Math.max(0.05, (data.confidence || 0.5) * 0.3);
     data.updated = new Date().toISOString();
-    atomicWrite(node._filepath, safeStringify(content, data));
-    invalidate(path.dirname(node._filepath));
+    atomicWrite(fp, safeStringify(content, data));
+    invalidate(vaultDirFromNodeFile(fp));
   } catch (err) {
     logger.debug('clarity-rewriter: stampNodeForCorrection failed', { err: err.message });
   }

package/src/core/config.mjs

@@ -48,6 +48,7 @@ const configSchema = z.object({
   cliModel: z.string().optional(),
   cliTimeout: z.preprocess((val) => val === undefined || val === '' ? 300 : parseInt(String(val), 10), z.number().int().default(300)),
   googleApiKey: z.string().optional(),
+  openRouterApiKey: z.string().optional(),
   embedModel: z.string().default('gemini-embedding-2'),
   searxngBaseUrl: z.string().optional(),
   braveApiKey: z.string().optional(),
@@ -151,10 +152,13 @@ try {
         const isConfigPath = p.includes(path.join('config', 'secrets.enc'));
         const brainDir = isConfigPath ? path.dirname(path.dirname(p)) : path.dirname(p);
         const parsed = loadSecretsSync(brainDir);
-        if (Object.keys(parsed).length > 0) {
-          secrets = parsed;
-          break; // Found valid secrets!
-        }
+        // Merge (don't stop at the first non-empty file): an earlier, sparser
+        // store (e.g. the global ~/.agent/secrets.enc root) was previously
+        // short-circuiting the search and silently hiding real secrets that
+        // only existed in a later, richer store (e.g. the total-recall
+        // skill's own config/secrets.enc). Earlier candidates still win on
+        // key collisions — this only fills in keys the earlier ones lack.
+        secrets = { ...parsed, ...secrets };
       } catch {}
     }
   }
@@ -178,6 +182,7 @@ const rawConfig = {
   cliModel: process.env.TR_CLI_MODEL,
   cliTimeout: process.env.TR_CLI_TIMEOUT,
   googleApiKey: process.env.GOOGLE_API_KEY || secrets.google_api_key,
+  openRouterApiKey: process.env.OPENROUTER_API_KEY || secrets.openrouter_api_key || secrets.OPENROUTER_API_KEY,
   embedModel: process.env.TR_EMBED_MODEL,
   searxngBaseUrl: process.env.SEARXNG_BASE_URL,
   braveApiKey: process.env.BRAVE_SEARCH_API_KEY || process.env.BRAVE_API_KEY || secrets.brave_api_key,
@@ -225,6 +230,7 @@ export const {
   cliModel,
   cliTimeout,
   googleApiKey,
+  openRouterApiKey,
   embedModel,
   searxngBaseUrl,
   braveApiKey,

package/src/core/daemon-loop.mjs

@@ -31,7 +31,8 @@ const DERIVED_DIR = path.join(BRAIN_DIR, 'memory-derived');
 const CONFLICTS_DIR = path.join(BRAIN_DIR, 'memory-inbox', 'conflicts');
 const SESSIONS_DIR = path.join(BRAIN_DIR, 'sessions');
 const QUEUE_DIR = path.join(BRAIN_DIR, 'scheduler', 'queue');
-const INSTRUCTIONS_FILE = path.join(BRAIN_DIR, 'INSTRUCTIONS.md');
+// Surface shims resolve from the agent root (.agent/), not brainDir (…/skills/total-recall/)
+const INSTRUCTIONS_FILE = path.join(AGENT_DIR, 'INSTRUCTIONS.md');
 
 // How often to recompile surfaces (every N task ticks)
 const RECOMPILE_EVERY_N_TASKS = 20;

package/src/core/embeddings.mjs

@@ -20,7 +20,7 @@ import {
   getVssLoadablePath,
 } from 'sqlite-vss';
 
-import { googleApiKey, embedModel, brainDir as defaultBrainDir } from './config.mjs';
+import { googleApiKey, openRouterApiKey, embedModel, brainDir as defaultBrainDir } from './config.mjs';
 import { logger } from './logger.mjs';
 
 const DEFAULT_EMBED_MODEL = embedModel;
@@ -34,6 +34,10 @@ function resolveOpenAiApiKey() {
   return process.env.OPENAI_API_KEY || null;
 }
 
+function resolveOpenRouterApiKey() {
+  return openRouterApiKey || process.env.OPENROUTER_API_KEY || null;
+}
+
 let dbInstance = null;
 let currentDbPath = null;
 /** @type {WeakMap<object, boolean>} */
@@ -227,6 +231,37 @@ async function getGoogleEmbedding(text, model) {
   return data.embedding.values;
 }
 
+async function getOpenRouterEmbedding(text, model = 'openai/text-embedding-3-small') {
+  const openRouterKey = resolveOpenRouterApiKey();
+  if (!openRouterKey) {
+    throw new Error('OPENROUTER_API_KEY not set. Cannot generate embeddings.');
+  }
+
+  const res = await throttledFetch('https://openrouter.ai/api/v1/embeddings', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${openRouterKey}`,
+    },
+    // Request 768 dims to match the existing vault vss0(embedding(768)) schema
+    // and stay comparable against previously-stored Google embeddings.
+    body: JSON.stringify({ model, input: text, dimensions: 768 }),
+    signal: AbortSignal.timeout(30000),
+  }, 20000);
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`OpenRouter embedding API error ${res.status}: ${body || 'no response body'}`);
+  }
+
+  const data = await res.json();
+  if (!data.data?.[0]?.embedding) {
+    throw new Error('OpenRouter returned no embedding vector');
+  }
+
+  return data.data[0].embedding;
+}
+
 async function getOpenAIEmbedding(text, model = 'text-embedding-3-small') {
   const openaiKey = resolveOpenAiApiKey();
   if (!openaiKey) {
@@ -258,11 +293,24 @@ async function getOpenAIEmbedding(text, model = 'text-embedding-3-small') {
 
 export async function getEmbedding(text, _unused, model = DEFAULT_EMBED_MODEL) {
   const input = String(text).slice(0, 8000);
+  const openRouterKey = resolveOpenRouterApiKey();
   const googleKey = resolveGoogleApiKey();
   const openaiKey = resolveOpenAiApiKey();
 
   let embedding;
-  if (googleKey) {
+
+  // OpenRouter first: standing preference (Gemini's budget is exhausted, so
+  // Google is a near-guaranteed slow failure right now — trying it first just
+  // taxes every call with a ~15-20s timeout before falling through).
+  if (openRouterKey) {
+    try {
+      embedding = await getOpenRouterEmbedding(input);
+    } catch (err) {
+      logger.debug('embeddings: OpenRouter failed, trying Google fallback', { err: err.message });
+    }
+  }
+
+  if (!embedding && googleKey) {
     try {
       embedding = await getGoogleEmbedding(input, model);
     } catch (err) {
@@ -280,7 +328,7 @@ export async function getEmbedding(text, _unused, model = DEFAULT_EMBED_MODEL) {
   }
 
   if (!embedding) {
-    throw new Error('No embedding provider available. Set GOOGLE_API_KEY or OPENAI_API_KEY.');
+    throw new Error('No embedding provider available. Set OPENROUTER_API_KEY, GOOGLE_API_KEY, or OPENAI_API_KEY.');
   }
 
   return embedding;

package/src/core/memory-title.mjs

@@ -0,0 +1,70 @@
+/**
+ * Memory title helpers — provenance belongs in source/tags, not a title prefix.
+ */
+
+const SELF_CAPTURED_PREFIX_RE = /^Self-captured memory:\s*/i;
+
+/**
+ * Strip legacy auto-title prefix if present.
+ * @param {string} title
+ * @returns {string}
+ */
+export function stripSelfCapturedTitlePrefix(title) {
+  return String(title || '').replace(SELF_CAPTURED_PREFIX_RE, '').trim();
+}
+
+/**
+ * True when title is the old auto-generated echo of the body.
+ * @param {string} title
+ * @param {string} [body]
+ */
+export function isSelfCapturedEchoTitle(title, body = '') {
+  const raw = String(title || '').trim();
+  if (SELF_CAPTURED_PREFIX_RE.test(raw)) return true;
+  const stripped = stripSelfCapturedTitlePrefix(raw);
+  const text = String(body || '').replace(/\s+/g, ' ').trim();
+  if (!stripped || !text) return false;
+  const head = stripped.replace(/\.\.\.$/, '').trim().toLowerCase();
+  if (head.length < 12) return false;
+  return text.toLowerCase().startsWith(head.slice(0, Math.min(40, head.length)));
+}
+
+/**
+ * Build a short human title from body content (no provenance prefix).
+ * Uses first sentence when reasonable, else first ~100 chars.
+ * @param {string} body
+ * @returns {string}
+ */
+export function defaultTitleFromBody(body) {
+  const oneLine = String(body || '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!oneLine) return 'Untitled memory';
+
+  // Prefer first sentence
+  const m = oneLine.match(/^(.{12,}?[.!?])(\s|$)/);
+  let candidate = m ? m[1].trim() : oneLine;
+
+  // Avoid absurdly long single-sentence titles
+  if (candidate.length > 100) {
+    candidate = candidate.slice(0, 97).replace(/\s+\S*$/, '').trim() + '...';
+  }
+  return candidate || oneLine.slice(0, 100);
+}
+
+/**
+ * Normalize an existing title that may carry the legacy prefix.
+ * If after strip the title is empty or still an echo of body, rebuild from body.
+ * @param {string} title
+ * @param {string} body
+ * @returns {string}
+ */
+export function normalizeMemoryTitle(title, body) {
+  const stripped = stripSelfCapturedTitlePrefix(title);
+  if (!stripped) return defaultTitleFromBody(body);
+  if (isSelfCapturedEchoTitle(title, body) || isSelfCapturedEchoTitle(stripped, body)) {
+    // Prefer full first sentence from body over truncated echo
+    return defaultTitleFromBody(body);
+  }
+  return stripped;
+}

package/src/core/runtime.mjs

@@ -139,12 +139,22 @@ export function loadRuntimeConfig(_configPath) {
   }
 
   // Tier D: Check SSSS Compiled Memory Preference Surface
+  // Surfaces live at agent root / repo root — not under brainDir (…/skills/total-recall/)
   if (!preferredAgent) {
     try {
       const checkPaths = [
+        path.join(agentDir, 'INSTRUCTIONS.md'),
+        path.join(agentDir, 'AGENTS.md'),
+        path.join(agentDir, 'GEMINI.md'),
+        path.join(path.dirname(agentDir), 'INSTRUCTIONS.md'),
+        path.join(path.dirname(agentDir), 'AGENTS.md'),
+        path.join(process.cwd(), 'INSTRUCTIONS.md'),
+        path.join(process.cwd(), 'AGENTS.md'),
+        path.join(process.cwd(), 'Claude.md'),
+        // legacy mistaken brainDir locations (kept as last resort)
         path.join(brainDir, 'INSTRUCTIONS.md'),
         path.join(brainDir, 'GEMINI.md'),
-        path.join(brainDir, 'AGENTS.md')
+        path.join(brainDir, 'AGENTS.md'),
       ];
       for (const p of checkPaths) {
         if (fs.existsSync(p)) {

package/src/core/secrets-store.mjs

@@ -760,7 +760,13 @@ export async function setSecret(brainDir, key, value, opts = {}) {
   });
 
   // First-time set only: optionally queue product-level API research (not raw key-name scraping).
-  if (!prev.created_at && opts.skip_integration_research !== true) {
+  // Skip under Vitest / NODE_ENV=test — enqueue can hang on network and blow 5s timeouts.
+  // Force research in tests with skip_integration_research: false.
+  const inTest = process.env.VITEST === 'true' || process.env.NODE_ENV === 'test';
+  const skipResearch =
+    opts.skip_integration_research === true ||
+    (inTest && opts.skip_integration_research !== false);
+  if (!prev.created_at && !skipResearch) {
     try {
       const { maybeEnqueueIntegrationResearch } = await import('./secret-integration-research.mjs');
       const result = await maybeEnqueueIntegrationResearch(brainDir, key, {

package/src/core/skills-registry.mjs

@@ -552,6 +552,18 @@ export function isRepoScopedSkill(brainDir, skillId) {
     entry?.source_path,
     ...registry.installs.filter((install) => install.skill_id === skillId).map((install) => install.path),
   ].filter(Boolean);
+  // Also examine copies not yet tracked in the registry. collectSkillLocations()
+  // (what syncSkillTwoWay actually acts on) additionally scans every known repo
+  // for live-but-undiscovered copies of this skill id. Without doing the same
+  // here, the very first sync that ever touches a newly-known repo only sees
+  // the catalog source as a candidate, never notices that repo's same-named
+  // skill diverges, and lets an unrelated same-named skill silently clobber it
+  // before either copy is ever registered.
+  for (const repo of loadKnownRepoRoots(brainDir)) {
+    for (const hit of discoverSkillsInRepo(repo)) {
+      if (hit.id === skillId) candidates.push(hit.path);
+    }
+  }
   const seen = new Set();
   const liveRepos = new Set();
   const liveHashes = new Set();

package/src/core/surface.mjs

@@ -186,16 +186,16 @@ function modalityMarker(node) {
  */
 export function heuristicCompact(node) {
   const rawTitle = (node.title || '').trim();
+  // Legacy prefix only — provenance is source.type / tags, not title text
   const title = rawTitle.replace(/^Self-captured memory:\s*/i, '').trim();
   const text = (node.body || node.content || '').trim();
   const marker = modalityMarker(node);
   const prefix = marker ? `${marker} ` : '';
 
   // Determine the best display text, avoiding title/body duplication.
-  // When title is auto-generated ("Self-captured memory: ...") it echoes the body —
-  // use the body directly to avoid doubling the same content.
-  const titleIsEcho = rawTitle.startsWith('Self-captured memory:') ||
-    (text && title.length > 20 && text.toLowerCase().startsWith(title.toLowerCase().slice(0, 20)));
+  // Echo titles (legacy "Self-captured…" or title that is just a body prefix) use body only.
+  const titleIsEcho = /^Self-captured memory:/i.test(rawTitle) ||
+    (text && title.length > 20 && text.toLowerCase().startsWith(title.toLowerCase().replace(/\.\.\.$/, '').slice(0, 20)));
 
   if (node.category && ['invariants', 'preferences', 'anti-patterns'].includes(node.category)) {
     if (text) {

package/src/core/throttled-fetch.mjs

@@ -140,6 +140,9 @@ export async function loadFirewallPolicy(brainDir) {
       policyWatcher = fs.watch(policyPath, (eventType) => {
         if (eventType === 'change') applyPolicy();
       });
+      // Unref so this watcher does not prevent one-shot CLI commands (e.g.
+      // `recall`) from exiting cleanly once their work is done.
+      policyWatcher.unref();
     }
 
     // Also watch the parent directory so we pick up the policy file being
@@ -153,8 +156,10 @@ export async function loadFirewallPolicy(brainDir) {
           policyWatcher = fs.watch(policyPath, (evt) => {
             if (evt === 'change') applyPolicy();
           });
+          policyWatcher.unref();
         }
       });
+      parentWatcher.unref();
     }
   } catch (err) {
     logger.error('throttled-fetch', `Failed to load network policy: ${err.message}`);

package/src/core/vault.mjs

@@ -76,7 +76,13 @@ export function loadNodes(vaultDir) {
       const raw = fs.readFileSync(file, 'utf8');
       const { data, content } = matter(raw);
       if (data.type === 'memory') {
-        nodes.push({ ...data, body: content.trim() });
+        // Attach absolute path for stampers/rewriters (both spellings used in codebase)
+        nodes.push({
+          ...data,
+          body: content.trim(),
+          _filePath: file,
+          _filepath: file,
+        });
       }
     } catch (err) {
       logger.warn('vault', `Failed to parse ${file}`, { err: err.message });

package/src/server/index.mjs

@@ -43,6 +43,51 @@ const PACKAGE_VERSION = (() => {
   }
 })();
 
+// ─── PID Lock ───────────────────────────────────────────────────────────────────
+// A second instance that loses the listen() race for PORT has historically kept
+// running indefinitely (no bound port, no work, never exiting) because nothing
+// handled the EADDRINUSE 'error' event. Fail fast instead, mirroring the daemon
+// loop's acquirePidLock/releasePidLock pattern.
+const SERVER_PID_FILE = path.join(configBrainDir, 'server.pid');
+
+function acquireServerPidLock() {
+  try {
+    if (fs.existsSync(SERVER_PID_FILE)) {
+      const existingPid = parseInt(fs.readFileSync(SERVER_PID_FILE, 'utf8').trim(), 10);
+      if (existingPid && !isNaN(existingPid)) {
+        try {
+          process.kill(existingPid, 0); // signal 0 = liveness check only
+          logger.error('server', `Another server instance is already running (PID: ${existingPid}). Exiting.`);
+          process.exit(1);
+        } catch {
+          logger.info('server', `Stale server PID file found (PID: ${existingPid} is dead). Overwriting.`);
+        }
+      }
+    }
+  } catch {
+    // PID file unreadable — proceed
+  }
+  try {
+    fs.mkdirSync(path.dirname(SERVER_PID_FILE), { recursive: true });
+    fs.writeFileSync(SERVER_PID_FILE, String(process.pid), { mode: 0o644 });
+  } catch (err) {
+    logger.warn('server', `Could not write server PID lockfile: ${err.message}`);
+  }
+}
+
+function releaseServerPidLock() {
+  try {
+    if (fs.existsSync(SERVER_PID_FILE)) {
+      const storedPid = parseInt(fs.readFileSync(SERVER_PID_FILE, 'utf8').trim(), 10);
+      if (storedPid === process.pid) fs.unlinkSync(SERVER_PID_FILE);
+    }
+  } catch {
+    // best-effort cleanup
+  }
+}
+
+acquireServerPidLock();
+
 // ─── Watchdog ───────────────────────────────────────────────────────────────────
 // Attach circuit-breaker log monitor before any subsystem can emit events.
 import { attachLogMonitor } from '../core/watchdog.mjs';
@@ -699,6 +744,11 @@ const server = app.listen(PORT, HOST, () => {
   }
   logger.info("server", `Total Recall Brain v3.0.0 is listening on http://${HOST}:${PORT}`);
 });
+server.on('error', (err) => {
+  logger.error('server', `Failed to bind ${HOST}:${PORT}: ${err.message}. Exiting.`);
+  releaseServerPidLock();
+  process.exit(1);
+});
 
 // If bound to a mesh IP, also bind to 127.0.0.1 so local CLI/Dashboard works
 if (HOST !== '127.0.0.1' && HOST !== '0.0.0.0') {
@@ -706,6 +756,11 @@ if (HOST !== '127.0.0.1' && HOST !== '0.0.0.0') {
     setupUpgradeHandler(localServer);
     logger.info("server", `Total Recall Brain v3.0.0 is ALSO listening on http://127.0.0.1:${PORT}`);
   });
+  localServer.on('error', (err) => {
+    logger.error('server', `Failed to bind 127.0.0.1:${PORT}: ${err.message}. Exiting.`);
+    releaseServerPidLock();
+    process.exit(1);
+  });
 }
 
   logger.info("server", "┌─────────────────────────────────────────────┐");
@@ -940,6 +995,7 @@ async function handleShutdown(signal) {
     }
 
     clearTimeout(forceExitTimeout);
+    releaseServerPidLock();
     logger.info('server', 'Graceful shutdown complete. Exiting.');
     process.exit(0);
   });

package/src/server/route-manifest.json

@@ -415,6 +415,10 @@
     "method": "PATCH",
     "path": "/api/secrets/:key"
   },
+  {
+    "method": "POST",
+    "path": "/api/secrets/:key/account-sync"
+  },
   {
     "method": "POST",
     "path": "/api/secrets/:key/reveal"
@@ -423,6 +427,10 @@
     "method": "POST",
     "path": "/api/secrets/:key/rotate"
   },
+  {
+    "method": "POST",
+    "path": "/api/secrets/account-sync"
+  },
   {
     "method": "GET",
     "path": "/api/secrets/checksum"
@@ -467,6 +475,10 @@
     "method": "GET",
     "path": "/api/secrets/scan-env"
   },
+  {
+    "method": "GET",
+    "path": "/api/secrets/shared-values"
+  },
   {
     "method": "GET",
     "path": "/api/secrets/sync"
@@ -483,6 +495,10 @@
     "method": "POST",
     "path": "/api/secrets/sync/trigger-pull"
   },
+  {
+    "method": "GET",
+    "path": "/api/secrets/tracking-health"
+  },
   {
     "method": "GET",
     "path": "/api/secrets/usage"

package/src/server/routes/_shared.mjs

@@ -113,6 +113,29 @@ export function resolveAllVaultsFromQuery(req) {
   return uniqueVaults.length > 0 ? uniqueVaults : [VAULT_DIR];
 }
 
+/**
+ * Derive brain-local paths from a vault directory.
+ * vaultDir is always `…/<brain>/memory-vault`.
+ * Ensures project brains use their own derived indexes / surfaces, not global.
+ *
+ * @param {string} vaultDir
+ * @returns {{ brainDir: string, derivedDir: string, skillsDir: string, instructionsFile: string, sessionsDir: string, inboxDir: string }}
+ */
+export function pathsForVault(vaultDir) {
+  const brainDir = path.dirname(vaultDir);
+  // brainDir = …/.agent/skills/total-recall → agentDir = …/.agent
+  const skillsParent = path.dirname(brainDir); // …/skills
+  const agentDir = path.dirname(skillsParent); // …/.agent
+  return {
+    brainDir,
+    derivedDir: path.join(brainDir, 'memory-derived'),
+    skillsDir: path.join(agentDir, 'skills'),
+    instructionsFile: path.join(agentDir, 'INSTRUCTIONS.md'),
+    sessionsDir: path.join(brainDir, 'sessions'),
+    inboxDir: path.join(brainDir, 'memory-inbox'),
+  };
+}
+
 export function notFound(res, msg) {
   return res.status(404).json({ error: msg || 'Not found' });
 }
@@ -127,6 +150,15 @@ export function serverError(res, err) {
 }
 
 /** Strip the internal `body` field from a vault node into `content`. */
-export function sanitizeNode({ body, ...rest }) {
+export function sanitizeNode(node) {
+  if (!node || typeof node !== 'object') return node;
+  // Strip internal fields — never expose absolute paths or vault internals over the API
+  const {
+    body,
+    _filePath,
+    _filepath,
+    _layer,
+    ...rest
+  } = node;
   return { ...rest, content: body };
 }

package/src/server/routes/context.mjs

@@ -1,10 +1,11 @@
 import { Router } from 'express';
-import fs from 'node:fs';
-import path from 'node:path';
-import crypto from 'node:crypto';
 import { requireAuth, requireScope } from '../auth.mjs';
-import { serverError, ROOT, BRAIN_DIR, VAULT_DIR, SKILLS_DIR, INSTRUCTIONS, DERIVED_DIR, badRequest } from './_shared.mjs';
-import { logger } from '../../core/logger.mjs';
+import {
+  serverError,
+  badRequest,
+  resolveVaultFromQuery,
+  pathsForVault,
+} from './_shared.mjs';
 
 const router = Router();
 
@@ -12,10 +13,12 @@ router.post('/api/context', requireAuth, requireScope('memory:read'), async (req
   try {
     const { compileContext } = await import('../../core/context-compiler.mjs');
     const { query, budget, momentum_slugs } = req.body || {};
+    const vaultDir = resolveVaultFromQuery(req);
+    const { derivedDir } = pathsForVault(vaultDir);
     const result = await compileContext({
       query: query || '',
-      vaultDir: VAULT_DIR,
-      derivedDir: DERIVED_DIR,
+      vaultDir,
+      derivedDir,
       budget: budget || {},
       consumer: 'api',
       momentumSlugs: momentum_slugs || [],
@@ -29,7 +32,8 @@ router.post('/api/context', requireAuth, requireScope('memory:read'), async (req
 router.get('/api/context/preview', requireAuth, requireScope('memory:read'), async (req, res) => {
   try {
     const { previewContext } = await import('../../core/context-compiler.mjs');
-    const result = previewContext({ vaultDir: VAULT_DIR });
+    const vaultDir = resolveVaultFromQuery(req);
+    const result = previewContext({ vaultDir });
     res.json(result);
   } catch (err) {
     serverError(res, err);
@@ -41,9 +45,10 @@ router.post('/api/context/stream', requireAuth, requireScope('memory:read'), asy
     const { streamParallelContext } = await import('../../core/parallel-context.mjs');
     const { query, budget_tokens, batch_size, concurrency, min_score } = req.body || {};
     if (!query) return badRequest(res, 'query is required');
+    const vaultDir = resolveVaultFromQuery(req);
     const result = await streamParallelContext({
       query,
-      vaultDir: VAULT_DIR,
+      vaultDir,
       budgetTokens: budget_tokens,
       batchSize: batch_size,
       concurrency,