memoir-cli 3.11.3 → 3.14.0

package/evals/retrieval-performance.mjs

@@ -0,0 +1,99 @@
+// Synthetic filesystem benchmark. No models, network, or real user memories.
+// Run unchanged against a prior checkout with --repo to compare implementations.
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { performance } from 'node:perf_hooks';
+import { execFileSync } from 'node:child_process';
+
+const args = process.argv.slice(2);
+const option = (key, fallback) => { const i = args.indexOf('--' + key); return i < 0 ? fallback : args[i + 1]; };
+const repo = path.resolve(option('repo', fileURLToPath(new URL('..', import.meta.url))));
+const sizes = option('sizes', '1000,10000').split(',').map(Number);
+const samples = Number(option('samples', '120'));
+const kinds = option('kinds', 'adapter,canonical').split(',');
+if (!sizes.every(n => Number.isInteger(n) && n > 0 && n <= 50000) || !Number.isInteger(samples) || samples < 2 || samples > 1000 || !kinds.every(k => ['adapter', 'canonical'].includes(k))) throw new Error('Invalid benchmark options');
+const scratch = await fs.mkdtemp(path.join(os.tmpdir(), 'memoir-retrieval-bench-'));
+const realHomedir = os.homedir;
+// Only this process sees the fixture home; no system environment is repurposed.
+os.homedir = () => scratch;
+process.env.DO_NOT_TRACK = '1';
+globalThis.fetch = async () => { throw new Error('Network prohibited in evaluation'); };
+const fixtureVersion = 'coding-retrieval-v1';
+const prose = [
+  'The migration must create the new table before updating the reader. Keep the old reader available until the verification passes.',
+  'The rejected approach used a timer to hide the race. A transaction with an idempotency key prevents duplicate work.',
+  'The last session tested rollback against a disposable local database. That result describes the saved checkout, not every later commit.',
+  'An unsuccessful retry reused the old session token. Fetch the current token and confirm the request belongs to this project.',
+  'Record evidence from the test output and keep the pending check separate from a verified result.',
+  'Résumé: vérifier la migration et conserver les preuves. 数据库迁移需要验证。認証の更新を確認する。',
+].join('\n');
+const queries = [
+  'amberkingfisher recovery', 'migration reader', 'transaction idempotency', 'rejected timer',
+  'rollback disposable', 'session token', 'verification evidence', 'migration vérifi',
+  '数据库迁移', '認証', 'zzunknownnothing', 'component42',
+];
+const results = [];
+try {
+  const { adapters } = await import(pathToFileURL(path.join(repo, 'src/adapters/index.js')));
+  const { searchMemories, clearSearchCache } = await import(pathToFileURL(path.join(repo, 'src/memory/search.js')));
+  const { projectIdentity } = await import(pathToFileURL(path.join(repo, 'src/memory/scope.js')));
+  const { memoryRoot } = await import(pathToFileURL(path.join(repo, 'src/memory/store.js')));
+  const project = path.join(scratch, 'project');
+  await fs.mkdir(project);
+  const projectId = projectIdentity(project);
+  const source = path.join(scratch, 'adapter');
+  for (const kind of kinds) for (const count of sizes) {
+    await fs.rm(source, { recursive: true, force: true });
+    await fs.rm(memoryRoot, { recursive: true, force: true });
+    const dest = kind === 'canonical' ? memoryRoot : source;
+    await fs.mkdir(dest, { recursive: true });
+    adapters.splice(0, adapters.length, ...(kind === 'adapter' ? [{ name: 'Benchmark', source, filter: () => true }] : []));
+    const digest = crypto.createHash('sha256');
+    let bytes = 0;
+    for (let offset = 0; offset < count; offset += 32) {
+      const writes = [];
+      for (let i = offset; i < Math.min(count, offset + 32); i++) {
+        const id = crypto.createHash('sha256').update('record-' + i).digest('hex');
+        const filename = kind === 'canonical' ? id + '.md' : 'record-' + i + '.md';
+        const content = ['---', 'id: ' + id, 'name: component' + i, 'project: ' + projectId, 'type: decision', 'description: Component migration and recovery constraints', '---', '# Component ' + i, prose, i === count - 1 ? 'amberkingfisher recovery uses the verified snapshot.' : 'Routine component operations require a current smoke check.'].join('\n');
+        // Exclude machine-specific project IDs from the portable fixture hash.
+        digest.update(filename + '\0' + content.replace(projectId, '<project>'));
+        bytes += Buffer.byteLength(content);
+        writes.push(fs.writeFile(path.join(dest, filename), content));
+      }
+      await Promise.all(writes);
+    }
+    clearSearchCache();
+    const all = [];
+    for (let i = 0; i <= samples; i++) {
+      const query = i === 0 ? queries[0] : queries[(i - 1) % queries.length];
+      const start = performance.now();
+      const r = await searchMemories(query, { root: project, project, limit: 5, budget: 1800 });
+      const ms = performance.now() - start;
+      if (query === queries[0] && !r.results.some(x => x.passage.includes('verified snapshot'))) throw new Error('Required result missing');
+      if (query === 'zzunknownnothing' && r.results.length) throw new Error('No-evidence query returned a result');
+      all.push({ query, ms, total: r.total, results: r.results.length });
+    }
+    const warm = all.slice(1).map(r => r.ms).sort((a, b) => a - b);
+    const row = { kind, records: count, bytes, fixture_sha256: digest.digest('hex'), cold_ms: all[0].ms, warm_samples: samples, warm_median_ms: warm[Math.floor(warm.length / 2)], warm_p95_ms: warm[Math.ceil(warm.length * .95) - 1], rss_bytes: process.memoryUsage().rss, queries: all };
+    results.push(row);
+    console.error(JSON.stringify({ kind, count, cold_ms: row.cold_ms, median_ms: row.warm_median_ms, p95_ms: row.warm_p95_ms }));
+  }
+  let commit = null;
+  try { commit = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8' }).trim(); } catch {}
+  const sourceFiles = {};
+  for (const relative of ['src/memory/search.js', 'src/memory/scope.js', 'src/memory/lexical-index.js', 'src/security/files.js']) {
+    try { sourceFiles[relative] = crypto.createHash('sha256').update(await fs.readFile(path.join(repo, relative))).digest('hex'); }
+    catch (err) { if (err.code !== 'ENOENT') throw err; sourceFiles[relative] = null; }
+  }
+  const report = { label: 'Synthetic retrieval latency; not a coding utility or SOTA evaluation', fixture_version: fixtureVersion, harness_sha256: crypto.createHash('sha256').update(await fs.readFile(fileURLToPath(import.meta.url))).digest('hex'), source_commit: commit, source_file_sha256: sourceFiles, measured_at: new Date().toISOString(), node: process.version, platform: process.platform, arch: process.arch, cpu: os.cpus()[0]?.model, protocol: 'In-process public search API, including filesystem discovery/validation, parsing, ranking, and passage generation. One cold query then a fixed mixed query cycle. OS file cache is not flushed. RSS is process-wide. Sources are synthetic. File hashes identify the measured implementation even if the checkout has uncommitted edits.', results };
+  const json = JSON.stringify(report, null, 2) + '\n';
+  if (option('output', null)) await fs.writeFile(path.resolve(option('output')), json);
+  else console.log(json);
+} finally {
+  os.homedir = realHomedir;
+  await fs.rm(scratch, { recursive: true, force: true });
+}

package/evals/run.mjs

@@ -0,0 +1,87 @@
+// Development regression evaluation, not a held-out SOTA benchmark.
+// All storage is synthetic; no model/network calls or user memory are used.
+import fs from 'fs-extra';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { fileURLToPath } from 'node:url';
+
+const fixturePath = fileURLToPath(new URL('./cases.json', import.meta.url));
+const fixtureRaw = await fs.readFile(fixturePath);
+const fixture = JSON.parse(fixtureRaw);
+const scratch = await fs.mkdtemp(path.join(os.tmpdir(), 'memoir-evaluation-'));
+process.env.HOME = scratch;
+process.env.USERPROFILE = scratch;
+process.env.APPDATA = path.join(scratch, 'AppData', 'Roaming');
+process.env.DO_NOT_TRACK = '1';
+process.env.CI = '1';
+process.env.GIT_CONFIG_NOSYSTEM = '1';
+process.env.GIT_CONFIG_GLOBAL = path.join(scratch, 'gitconfig');
+globalThis.fetch = async () => { throw new Error('Network prohibited during evaluation'); };
+try {
+  const projects = { alpha: path.join(scratch, 'alpha'), beta: path.join(scratch, 'beta') };
+  await Promise.all(Object.values(projects).map(dir => fs.ensureDir(dir)));
+  process.env.MEMOIR_PROJECT_ROOT = projects.alpha;
+  const { rememberMemory, readStoredMemories } = await import('../src/memory/store.js');
+  const { searchMemories } = await import('../src/memory/search.js');
+  const ids = new Map();
+  for (const record of fixture.records) {
+    const metadata = { ...(record.metadata || {}), name: record.key };
+    const content = ['---', ...Object.entries(metadata).map(([key, value]) => key + ': ' + JSON.stringify(value)), '---', record.text].join('\n');
+    const saved = await rememberMemory({
+      filename: record.key + '.md', content,
+      project: projects[record.project || 'alpha'],
+      scope: record.project === 'shared' ? 'shared' : 'project',
+      aliases: record.aliases || [],
+    });
+    ids.set(saved.id, record.key);
+  }
+  const raw = await readStoredMemories();
+  const rows = [];
+  for (const test of fixture.cases) {
+    const started = performance.now();
+    const output = await searchMemories(test.query, { project: projects[test.project || 'alpha'], limit: 5, budget: 1800 });
+    const milliseconds = performance.now() - started;
+    const reference = await searchMemories(test.query, { project: projects[test.project || 'alpha'], limit: 5, budget: 1800, engine: 'scan' });
+    const retrieved = output.results.map(r => ids.get(r.id)).filter(Boolean);
+    const substring = raw.filter(doc => test.query.trim() && doc.content.toLowerCase().includes(test.query.toLowerCase()))
+      .slice(0, 5).map(doc => ids.get(path.basename(doc.path, '.md')));
+    rows.push({ name: test.name, expected: test.expected, forbidden: test.forbidden || [], retrieved, substring, milliseconds,
+      scan_reference: reference.results.map(r => ids.get(r.id)).filter(Boolean),
+      matches_scan_output: JSON.stringify(output) === JSON.stringify(reference),
+      passage_characters: output.results.reduce((sum, r) => sum + r.passage.length, 0) });
+  }
+  const metrics = field => {
+    const positive = rows.filter(r => r.expected.length);
+    const hits = positive.map(r => r.expected.filter(id => r[field].includes(id)).length / r.expected.length);
+    const rr = positive.map(r => { const rank = r[field].findIndex(id => r.expected.includes(id)); return rank < 0 ? 0 : 1 / (rank + 1); });
+    const negatives = rows.filter(r => !r.expected.length);
+    return {
+      recall_at_5: hits.reduce((a,b) => a+b, 0) / positive.length,
+      mean_reciprocal_rank: rr.reduce((a,b) => a+b, 0) / positive.length,
+      correct_abstentions: negatives.filter(r => r[field].length === 0).length,
+      abstention_cases: negatives.length,
+      forbidden_results: rows.reduce((sum, r) => sum + r[field].filter(id => r.forbidden.includes(id)).length, 0),
+    };
+  };
+  const latencies = rows.map(r => r.milliseconds).sort((a,b) => a-b);
+  const report = {
+    label: 'Development fixture evaluation; created after implementation, not held out',
+    fixture_sha256: crypto.createHash('sha256').update(fixtureRaw).digest('hex'),
+    runtime: process.version, platform: process.platform, architecture: process.arch,
+    records: fixture.records.length, cases: rows.length,
+    memoir: metrics('retrieved'),
+    scoped_scan_reference: metrics('scan_reference'),
+    indexed_scan_agreement_cases: rows.filter(r => r.matches_scan_output).length,
+    scan_reference_limit: 'Exhaustive scoring using the same source reader, visibility rules, and ranking formula. Measures index equivalence, not competitive quality. Use retrieval-performance.mjs for latency.',
+    unscoped_substring_control: metrics('substring'),
+    control_limit: 'Simple substring control, not the previous released ranking engine or a competing product',
+    latency_ms: { median: latencies[Math.floor(latencies.length / 2)], p95: latencies[Math.ceil(latencies.length * .95)-1] },
+    rows,
+  };
+  const json = JSON.stringify(report, null, 2) + '\n';
+  if (process.argv[2]) await fs.outputFile(path.resolve(process.argv[2]), json);
+  console.log(json);
+  if (report.memoir.forbidden_results || report.memoir.recall_at_5 < 1 || report.memoir.correct_abstentions !== report.memoir.abstention_cases || report.indexed_scan_agreement_cases !== rows.length) process.exitCode = 1;
+} finally { await fs.remove(scratch); }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "memoir-cli",
-  "version": "3.11.3",
+  "version": "3.14.0",
   "mcpName": "io.github.camgitt/memoir",
-  "description": "Private, portable AI memory: synced across every coding tool and machine, end-to-end encrypted, free. One memory for Claude Code, Cursor, Copilot, Gemini + more — MCP-native, zero-knowledge, open source.",
+  "description": "Portable, project-scoped memory and session handoffs for coding agents. Readable files, MCP recall, and optional user-passphrase encrypted backups.",
   "main": "src/index.js",
   "type": "module",
   "bin": {
@@ -14,7 +14,10 @@
     "bin/",
     "src/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "docs/",
+    "supabase/migrations/",
+    "evals/"
   ],
   "engines": {
     "node": ">=18"
@@ -32,7 +35,10 @@
     "test": "node run-tests.mjs",
     "test:legacy": "bash test-local.sh",
     "prepublishOnly": "node scripts/check-clean-for-publish.mjs && npm test",
-    "postinstall": "node -e \"try{const c='\\x1b[36m',r='\\x1b[0m',g='\\x1b[90m';console.log('\\n  '+c+'memoir'+r+' installed.\\n  Run '+c+'memoir activate'+r+' in any project to give your AI long-term memory.\\n  '+g+'https://memoir.sh'+r+'\\n')}catch{}\""
+    "version": "node -e \"const f=require('fs');const p=require('./package.json');const s=JSON.parse(f.readFileSync('server.json','utf8'));s.version=p.version;s.packages.forEach(x=>x.version=p.version);f.writeFileSync('server.json',JSON.stringify(s,null,2)+'\\n')\" && git add server.json",
+    "eval": "node evals/run.mjs",
+    "bench:retrieval": "node evals/retrieval-performance.mjs",
+    "test:packed": "node scripts/test-packed.mjs"
   },
   "keywords": [
     "mcp",
@@ -81,6 +87,8 @@
     "fs-extra": "^11.2.0",
     "gradient-string": "^3.0.0",
     "inquirer": "^9.2.15",
-    "ora": "^7.0.1"
+    "ora": "^7.0.1",
+    "smol-toml": "^1.8.0",
+    "zod": "4.5.4"
   }
 }

package/src/adapters/index.js

@@ -1,3 +1,6 @@
+import { projectIdentity } from '../memory/scope.js';
+import { readSafeFile, writeSafeFile } from '../security/files.js';
+import { stageMemories } from '../memory/store.js';
 import fs from 'fs-extra';
 import nodeFs from 'node:fs';
 import path from 'path';
@@ -80,7 +83,7 @@ export const adapters = [
       if (src === codexDir) return true;
       const basename = path.basename(src);
       // Only sync config files
-      const allowed = ['config.json', 'settings.json', 'instructions.md'];
+      const allowed = ['config.toml', 'config.json', 'settings.json', 'instructions.md', 'AGENTS.md'];
       return allowed.includes(basename) && !rel.includes(path.sep);
     }
   },
@@ -241,7 +244,7 @@ function formatSize(bytes) {
 }
 
 export async function extractMemories(stagingDir, spinner, onlyFilter = null) {
-  let foundAny = false;
+  let foundAny = (await stageMemories(stagingDir)) > 0;
   const results = [];
 
   for (const adapter of adapters) {
@@ -264,7 +267,7 @@ export async function extractMemories(stagingDir, spinner, onlyFilter = null) {
             await fs.ensureDir(dest);
             foundFile = true;
           }
-          await fs.copy(filePath, path.join(dest, file));
+          await writeSafeFile(dest, file, await readSafeFile(adapter.source, file));
           fileCount++;
         }
       }
@@ -278,7 +281,7 @@ export async function extractMemories(stagingDir, spinner, onlyFilter = null) {
       spinner.text = `${adapter.icon} Scanning ${chalk.cyan(adapter.name)}...`;
       const dest = path.join(stagingDir, adapter.name.toLowerCase().replace(/ /g, '-'));
       await fs.ensureDir(dest);
-      await fs.copy(adapter.source, dest, { filter: adapter.filter });
+      await fs.copy(adapter.source, dest, { filter: (src, dest) => !fs.lstatSync(src).isSymbolicLink() && adapter.filter(src, dest) });
 
       const fileCount = await countFiles(dest);
       const size = await dirSize(dest);
@@ -309,6 +312,7 @@ export async function extractMemories(stagingDir, spinner, onlyFilter = null) {
     let projectCount = 0;
     let projectFileCount = 0;
     const projectNames = [];
+    const projectManifest = {};
 
     // Walk home dir up to 3 levels deep looking for project markers
     const scanDir = async (dir, depth = 0) => {
@@ -329,7 +333,9 @@ export async function extractMemories(stagingDir, spinner, onlyFilter = null) {
 
       if (foundFiles.length > 0 && dir !== home && !shouldIgnoreProject(dir)) {
         // This is a project with AI configs
-        const projectName = path.basename(dir);
+        const identity = projectIdentity(dir);
+        const projectName = path.basename(dir) + '-' + identity.split(':')[1].slice(0, 12);
+        projectManifest[projectName] = { identity, name: path.basename(dir), relative_path: path.relative(home, dir).replace(/\\/g, '/') };
         const projectDestDir = path.join(projectsDest, projectName);
         await fs.ensureDir(projectDestDir);
 
@@ -337,7 +343,7 @@ export async function extractMemories(stagingDir, spinner, onlyFilter = null) {
           const src = path.join(dir, file);
           const dest = path.join(projectDestDir, file);
           await fs.ensureDir(path.dirname(dest));
-          await fs.copy(src, dest);
+          await writeSafeFile(projectDestDir, file, await readSafeFile(dir, file));
           projectFileCount++;
         }
 
@@ -357,6 +363,7 @@ export async function extractMemories(stagingDir, spinner, onlyFilter = null) {
     await scanDir(home);
 
     if (projectCount > 0) {
+      await writeSafeFile(stagingDir, 'projects.json', JSON.stringify(projectManifest, null, 2));
       const size = await dirSize(projectsDest);
       foundAny = true;
       results.push({

package/src/adapters/restore.js

@@ -1,3 +1,9 @@
+import { parseFrontmatter } from '../commands/validate.js';
+import { visibleMemory } from '../memory/scope.js';
+import { migrateSessionData } from '../session/migrations.js';
+import { readSafeFile, writeSafeFile, safePath, relativeFile, listSafeFiles } from '../security/files.js';
+import { projectIdentity } from '../memory/scope.js';
+import { restoreStoredMemories } from '../memory/store.js';
 import chalk from 'chalk';
 import fs from 'fs-extra';
 import path from 'path';
@@ -15,7 +21,7 @@ export function detectLocalHomeKey(adapterSource) {
 
   const entries = fs.readdirSync(localProjectsDir)
     .filter(e => !e.startsWith('.'))
-    .filter(e => fs.statSync(path.join(localProjectsDir, e)).isDirectory());
+    .filter(e => fs.lstatSync(path.join(localProjectsDir, e)).isDirectory());
   if (entries.length === 0) return null;
 
   // Prefer the key that matches this machine's homedir encoding.
@@ -65,7 +71,7 @@ function remapProjectPaths(backupDir, adapterSource) {
   if (!fs.existsSync(projectsDir)) return [];
 
   const backupEntries = fs.readdirSync(projectsDir)
-    .filter(e => fs.statSync(path.join(projectsDir, e)).isDirectory());
+    .filter(e => fs.lstatSync(path.join(projectsDir, e)).isDirectory());
   if (backupEntries.length === 0) return [];
 
   // Step 1: Detect the local home key from existing Claude dirs
@@ -221,11 +227,11 @@ async function mergeMemoryDirs(src, dest) {
         const srcStat = await fs.stat(srcPath);
         const destStat = await fs.stat(destPath);
         if (srcStat.mtimeMs > destStat.mtimeMs) {
-          await fs.copy(srcPath, destPath);
+          await writeSafeFile(dest, entry.name, await readSafeFile(src, entry.name));
         }
       } else {
         // File only exists on foreign machine — always copy it
-        await fs.copy(srcPath, destPath);
+        await writeSafeFile(dest, entry.name, await readSafeFile(src, entry.name));
       }
     }
   }
@@ -246,7 +252,7 @@ async function reconcileMemoryIndexes(claudeSource) {
     const memoryMdPath = path.join(memDir, 'MEMORY.md');
     let memoryMd = '';
     if (fs.existsSync(memoryMdPath)) {
-      memoryMd = fs.readFileSync(memoryMdPath, 'utf8');
+      memoryMd = (await readSafeFile(claudeSource, path.relative(claudeSource, memoryMdPath))).toString('utf8');
     }
 
     // Find all .md files in this memory dir
@@ -265,7 +271,8 @@ async function reconcileMemoryIndexes(claudeSource) {
     // Read each unreferenced file to get its name/description from frontmatter
     let additions = '\n\n## Synced from another machine\n';
     for (const file of unreferenced) {
-      const content = fs.readFileSync(path.join(memDir, file), 'utf8');
+      const content = (await readSafeFile(claudeSource, path.relative(claudeSource, path.join(memDir, file)))).toString('utf8');
+      if (!visibleMemory(parseFrontmatter(content).fields, { allProjects: true })) continue;
       // Try to extract name from frontmatter
       const nameMatch = content.match(/^name:\s*(.+)/m);
       const descMatch = content.match(/^description:\s*(.+)/m);
@@ -281,32 +288,36 @@ async function reconcileMemoryIndexes(claudeSource) {
     // Remove old "Synced from another machine" section if it exists, then re-add
     memoryMd = memoryMd.replace(/\n\n## Synced from another machine\n[\s\S]*$/, '');
     memoryMd = memoryMd.trimEnd() + additions;
-    fs.writeFileSync(memoryMdPath, memoryMd);
+    await writeSafeFile(claudeSource, path.relative(claudeSource, memoryMdPath), memoryMd);
   }
 }
 
-async function syncFiles(src, dest, changes) {
+async function syncFiles(src, dest, changes, adapter = null, base = dest) {
   const entries = await fs.readdir(src, { withFileTypes: true });
   for (const entry of entries) {
     const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
 
+    if (entry.isSymbolicLink()) throw new Error('Backup contains a symlink');
+    if (adapter && !adapter.filter(destPath)) throw new Error('Backup contains a file excluded by the adapter');
     if (entry.isDirectory()) {
-      await fs.ensureDir(destPath);
-      await syncFiles(srcPath, destPath, changes);
+      // Validate an eventual child before creating directories to reject
+      // symlink parents as well as symlink files.
+      await safePath(base, path.relative(base, destPath) + '/.memoir-check', { createParents: true });
+      await syncFiles(srcPath, destPath, changes, adapter, base);
     } else {
       if (await fs.pathExists(destPath)) {
         // Compare modification times — update if backup is newer
         const srcStat = await fs.stat(srcPath);
         const destStat = await fs.stat(destPath);
         if (srcStat.mtimeMs > destStat.mtimeMs) {
-          await fs.copy(srcPath, destPath);
+          await writeSafeFile(dest, entry.name, await readSafeFile(src, entry.name));
           changes.updated.push(destPath);
         } else {
           changes.skipped.push(destPath);
         }
       } else {
-        await fs.copy(srcPath, destPath);
+        await writeSafeFile(dest, entry.name, await readSafeFile(src, entry.name));
         changes.added.push(destPath);
       }
     }
@@ -314,7 +325,32 @@ async function syncFiles(src, dest, changes) {
 }
 
 export async function restoreMemories(sourceDir, spinner, onlyFilter = null, autoYes = false) {
-  let restoredAny = false;
+  if (await fs.pathExists(path.join(sourceDir, 'session.json'))) {
+    const raw = JSON.parse((await readSafeFile(sourceDir, 'session.json')).toString('utf8'));
+    if (migrateSessionData(raw).future) throw new Error('Backup uses a newer session schema. Upgrade Memoir first.');
+  }
+  for (const adapter of adapters) {
+    if (onlyFilter && !onlyFilter.some(f => adapter.name.toLowerCase().includes(f))) continue;
+    const dir = path.join(sourceDir, adapter.name.toLowerCase().replace(/ /g, '-'));
+    if (!await fs.pathExists(dir)) continue;
+    for (const rel of await listSafeFiles(dir)) {
+      const allowed = adapter.customExtract ? adapter.files.includes(rel) : adapter.filter(path.join(adapter.source, rel));
+      if (!allowed) throw new Error('Backup contains an excluded file for ' + adapter.name);
+      if (await fs.pathExists(adapter.source)) await safePath(adapter.source, rel);
+    }
+  }
+  const importedProjects = path.join(sourceDir, 'projects');
+  if (await fs.pathExists(importedProjects)) {
+    const allowed = new Set(['CLAUDE.md','GEMINI.md','CHATGPT.md','AGENTS.md','.cursorrules','.windsurfrules','.aider.conf.yml','.clinerules','.github/copilot-instructions.md']);
+    for (const rel of await listSafeFiles(importedProjects)) {
+      if (!allowed.has(rel.split('/').slice(1).join('/'))) throw new Error('Backup contains an unsupported project file');
+    }
+    if (await fs.pathExists(path.join(sourceDir, 'projects.json'))) {
+      const manifest = JSON.parse((await readSafeFile(sourceDir, 'projects.json')).toString());
+      for (const metadata of Object.values(manifest)) relativeFile(metadata.relative_path);
+    }
+  }
+  let restoredAny = (await restoreStoredMemories(sourceDir)) > 0;
   const allResults = [];
 
   for (const adapter of adapters) {
@@ -393,25 +429,26 @@ export async function restoreMemories(sourceDir, spinner, onlyFilter = null, aut
         if (adapter.customExtract) {
           const files = await fs.readdir(backupDir);
           for (const file of files) {
+            if (!adapter.files.includes(file)) throw new Error('Backup contains an excluded file');
             const destFile = path.join(adapter.source, file);
             if (await fs.pathExists(destFile)) {
               const srcStat = await fs.stat(path.join(backupDir, file));
               const destStat = await fs.stat(destFile);
               if (srcStat.mtimeMs > destStat.mtimeMs) {
-                await fs.copy(path.join(backupDir, file), destFile);
+                await writeSafeFile(adapter.source, file, await readSafeFile(backupDir, file));
                 changes.updated.push(destFile);
               } else {
                 changes.skipped.push(destFile);
               }
             } else {
-              await fs.copy(path.join(backupDir, file), destFile);
+              await writeSafeFile(adapter.source, file, await readSafeFile(backupDir, file));
               changes.added.push(destFile);
             }
           }
         } else {
           spinner.text = `Restoring ${chalk.cyan(adapter.name)} to ${adapter.source}...`;
           await fs.ensureDir(adapter.source);
-          await syncFiles(backupDir, adapter.source, changes);
+          await syncFiles(backupDir, adapter.source, changes, adapter);
         }
 
         // After syncing, reconcile MEMORY.md files
@@ -458,6 +495,8 @@ export async function restoreMemories(sourceDir, spinner, onlyFilter = null, aut
   const projectsDir = path.join(sourceDir, 'projects');
   if (await fs.pathExists(projectsDir)) {
     const projectEntries = await fs.readdir(projectsDir, { withFileTypes: true });
+    const manifestPath = path.join(sourceDir, 'projects.json');
+    const projectManifest = await fs.pathExists(manifestPath) ? JSON.parse((await readSafeFile(sourceDir, 'projects.json')).toString()) : {};
     const projectDirs = projectEntries.filter(e => e.isDirectory() && e.name !== '.git');
 
     if (projectDirs.length > 0) {
@@ -474,26 +513,29 @@ export async function restoreMemories(sourceDir, spinner, onlyFilter = null, aut
 
         // Search for project on local machine (up to 3 levels deep)
         let localProjDir = null;
-        const searchDirs = [home];
-        for (const searchDir of searchDirs) {
-          const candidate = path.join(searchDir, proj.name);
-          if (await fs.pathExists(candidate)) {
+        const metadata = projectManifest[proj.name];
+        if (metadata) {
+          const relative = relativeFile(metadata.relative_path);
+          const candidate = path.join(home, relative);
+          if (await fs.pathExists(candidate) && projectIdentity(candidate) === metadata.identity) {
+            await safePath(home, relative + '/.memoir-check');
             localProjDir = candidate;
-            break;
           }
-          // Check one level deeper
-          try {
-            const entries = await fs.readdir(searchDir, { withFileTypes: true });
-            for (const e of entries) {
-              if (!e.isDirectory() || e.name.startsWith('.')) continue;
-              const deeper = path.join(searchDir, e.name, proj.name);
-              if (await fs.pathExists(deeper)) {
-                localProjDir = deeper;
-                break;
-              }
-            }
-          } catch {}
-          if (localProjDir) break;
+        }
+        if (!metadata) {
+          const candidates = [];
+          const direct = path.join(home, proj.name);
+          if (await fs.pathExists(direct)) candidates.push(direct);
+          for (const e of await fs.readdir(home, { withFileTypes: true })) {
+            if (!e.isDirectory() || e.name.startsWith('.')) continue;
+            const deeper = path.join(home, e.name, proj.name);
+            if (await fs.pathExists(deeper)) candidates.push(deeper);
+          }
+          if (candidates.length === 1) {
+            await safePath(home, path.relative(home, candidates[0]) + '/.memoir-check');
+            localProjDir = candidates[0];
+          }
+          if (candidates.length > 1) console.log(chalk.yellow('  Ambiguous legacy project name; skipped ' + proj.name));
         }
 
         if (!localProjDir) {
@@ -517,6 +559,11 @@ export async function restoreMemories(sourceDir, spinner, onlyFilter = null, aut
         }
 
         if (confirm) {
+          const allowedProjectFiles = new Set(['CLAUDE.md','GEMINI.md','CHATGPT.md','AGENTS.md','.cursorrules','.windsurfrules','.aider.conf.yml','.clinerules','.github/copilot-instructions.md']);
+          for (const rel of await listSafeFiles(backupProjDir)) {
+            if (!allowedProjectFiles.has(rel)) throw new Error('Backup contains an unsupported project file');
+            await safePath(localProjDir, rel);
+          }
           for (const file of files) {
             const src = path.join(backupProjDir, file);
             const dest = path.join(localProjDir, file);
@@ -530,14 +577,14 @@ export async function restoreMemories(sourceDir, spinner, onlyFilter = null, aut
                 const srcStat = await fs.stat(src);
                 const destStat = await fs.stat(dest);
                 if (srcStat.mtimeMs > destStat.mtimeMs) {
-                  await fs.copy(src, dest);
+                  await writeSafeFile(localProjDir, file, await readSafeFile(backupProjDir, file));
                   console.log(chalk.yellow(`    ↻ ${file}`) + chalk.gray(` (updated)`));
                 } else {
                   console.log(chalk.gray(`    = ${file} (up to date)`));
                 }
               } else {
                 await fs.ensureDir(path.dirname(dest));
-                await fs.copy(src, dest);
+                await writeSafeFile(localProjDir, file, await readSafeFile(backupProjDir, file));
                 console.log(chalk.green(`    + ${file}`) + chalk.gray(` (new)`));
               }
               totalRestored++;

package/src/cloud/auth.js

@@ -22,16 +22,18 @@ async function supaFetch(endpoint, options = {}) {
   return res;
 }
 
+// GoTrue's REST API takes the post-email landing URL as a `redirect_to`
+// QUERY PARAM. `options.emailRedirectTo` / `options.redirectTo` in the JSON
+// body is supabase-js's client shape — sent raw it is silently ignored and
+// the email links fall back to the project's Site URL. Both URLs below must
+// also be on the Auth → URL Configuration → Redirect URLs allow-list.
+const CONFIRMED_URL = 'https://memoir.sh/confirmed';
+const RESET_URL = 'https://memoir.sh/reset-password';
+
 export async function signUp(email, password) {
-  const res = await supaFetch('/auth/v1/signup', {
+  const res = await supaFetch(`/auth/v1/signup?redirect_to=${encodeURIComponent(CONFIRMED_URL)}`, {
     method: 'POST',
-    body: JSON.stringify({
-      email,
-      password,
-      options: {
-        emailRedirectTo: 'https://memoir.sh/confirmed',
-      },
-    }),
+    body: JSON.stringify({ email, password }),
   });
   const data = await res.json();
   if (!res.ok) throw new Error(data.error_description || data.msg || 'Sign up failed');
@@ -116,14 +118,9 @@ export async function getSubscription(session) {
 }
 
 export async function resetPassword(email) {
-  const res = await supaFetch('/auth/v1/recover', {
+  const res = await supaFetch(`/auth/v1/recover?redirect_to=${encodeURIComponent(RESET_URL)}`, {
     method: 'POST',
-    body: JSON.stringify({
-      email,
-      options: {
-        redirectTo: 'https://memoir.sh/reset-password',
-      },
-    }),
+    body: JSON.stringify({ email }),
   });
   if (!res.ok) {
     const data = await res.json();

package/src/cloud/constants.js

@@ -1,5 +1,9 @@
 export const SUPABASE_URL = process.env.MEMOIR_SUPABASE_URL || 'https://oqrkxytbahfwjhcbyzrx.supabase.co';
 export const SUPABASE_ANON_KEY = process.env.MEMOIR_SUPABASE_ANON_KEY || 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Im9xcmt4eXRiYWhmd2poY2J5enJ4Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzMyMTQ4MzMsImV4cCI6MjA4ODc5MDgzM30.jOKOi73OJgIgi1zj0VOIQkGp0xqS3ee4gfCjpdqCnvM';
 export const STORAGE_BUCKET = 'memoir-backups';
-export const MAX_BACKUPS_FREE = 100;
-export const MAX_BACKUPS_PRO = 50;
+// Cloud backup retention (cleanupOldBackups prunes beyond these, oldest first).
+// Through 3.11 these were FREE=100 / PRO=50 — Pro pruned twice as aggressively
+// as free on a destructive path, while the upsell copy promised Pro more.
+// Free is a safety net; Pro is "full version history" (memoir.sh pricing).
+export const MAX_BACKUPS_FREE = 10;
+export const MAX_BACKUPS_PRO = 100;