memorix 1.6.2 → 1.7.0

package/src/project/launch-root.ts

@@ -0,0 +1,115 @@
+/**
+ * Launch-root guards for HTTP/stdio/background.
+ *
+ * LaunchAgents and Cursor stdio often start with cwd=$HOME. Binding that path
+ * treats the home directory as a project and can create a decoy ~/memorix.db
+ * while the real store lives in ~/.memorix/data/memorix.db.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const LAST_PROJECT_ROOT_FILENAME = 'last-project-root';
+
+/**
+ * Resolve the home directory used by Memorix boundary guards.
+ *
+ * Node's os.homedir() is intentionally stable on Windows and does not always
+ * follow a process-level HOME/USERPROFILE override. The CLI and test harnesses
+ * use those environment variables as the configured home, so all guards need
+ * one shared resolution rule instead of mixing the two sources.
+ */
+export function effectiveHomeDirectory(): string {
+  const configuredHome = process.platform === 'win32'
+    ? process.env.USERPROFILE?.trim() || process.env.HOME?.trim()
+    : process.env.HOME?.trim() || process.env.USERPROFILE?.trim();
+  return path.resolve(configuredHome || os.homedir());
+}
+
+export function isHomeDirectory(candidate: string, homeDir: string = effectiveHomeDirectory()): boolean {
+  try {
+    return path.resolve(candidate) === path.resolve(homeDir);
+  } catch {
+    return false;
+  }
+}
+
+export function lastProjectRootPath(homeDir: string = effectiveHomeDirectory()): string {
+  return path.join(homeDir, '.memorix', LAST_PROJECT_ROOT_FILENAME);
+}
+
+export function readLastProjectRoot(homeDir: string = effectiveHomeDirectory()): string | null {
+  try {
+    const raw = readFileSync(lastProjectRootPath(homeDir), 'utf8').trim();
+    if (!raw) return null;
+    const resolved = path.resolve(raw);
+    if (isHomeDirectory(resolved, homeDir)) return null;
+    if (!existsSync(resolved)) return null;
+    return resolved;
+  } catch {
+    return null;
+  }
+}
+
+export function writeLastProjectRoot(projectRoot: string, homeDir?: string): void {
+  // Tests pass an explicit homeDir. Default writes are skipped under Vitest so
+  // unit tests do not mutate the developer's ~/.memorix/last-project-root.
+  if (process.env.VITEST && homeDir === undefined) return;
+  const resolvedHome = homeDir ?? effectiveHomeDirectory();
+  const resolved = path.resolve(projectRoot);
+  if (isHomeDirectory(resolved, resolvedHome)) return;
+  if (!existsSync(resolved)) return;
+  const memorixDir = path.join(resolvedHome, '.memorix');
+  mkdirSync(memorixDir, { recursive: true });
+  writeFileSync(lastProjectRootPath(resolvedHome), `${resolved}\n`, 'utf8');
+}
+
+export function homeProjectRootError(candidate: string): string {
+  return (
+    `Refusing to bind $HOME as a project root (${candidate}). ` +
+    'Pass a git project via --cwd, MEMORIX_PROJECT_ROOT, or memorix_session_start({ projectRoot }). ' +
+    'Memorix will not create ~/memorix.db.'
+  );
+}
+
+/**
+ * When the launcher cwd is $HOME, inherit the last git project or an explicit
+ * MEMORIX_PROJECT_ROOT. System directories stay fail-closed (no restore).
+ */
+export function inheritProjectRootFromHome(options: {
+  homeDir: string;
+  envProjectRoot?: string;
+  readLastRoot?: () => string | null;
+}): string | null {
+  const envRoot = options.envProjectRoot?.trim();
+  if (envRoot && !isHomeDirectory(envRoot, options.homeDir) && existsSync(envRoot)) {
+    return path.resolve(envRoot);
+  }
+  const lastRoot = (options.readLastRoot ?? (() => readLastProjectRoot(options.homeDir)))();
+  if (lastRoot && !isHomeDirectory(lastRoot, options.homeDir) && existsSync(lastRoot)) {
+    return lastRoot;
+  }
+  return null;
+}
+
+/**
+ * Shared SQLite must never be opened at $HOME — that creates a decoy ~/memorix.db.
+ */
+export function resolveControlPlaneDataDir(options: {
+  requestedDataDir?: string;
+  homeDir?: string;
+  globalDataDir: string;
+}): string {
+  const homeDir = options.homeDir ?? effectiveHomeDirectory();
+  if (options.requestedDataDir && !isHomeDirectory(options.requestedDataDir, homeDir)) {
+    return options.requestedDataDir;
+  }
+  return options.globalDataDir;
+}
+
+export function assertNotHomeDataDir(dataDir: string, homeDir: string = effectiveHomeDirectory()): void {
+  if (isHomeDirectory(dataDir, homeDir)) {
+    throw new Error(homeProjectRootError(dataDir));
+  }
+}

package/src/runtime/isolated-maintenance.ts

@@ -1,5 +1,6 @@
 import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { existsSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -52,6 +53,16 @@ function childError(prefix: string, detail: string): Error {
   return new Error(cleaned ? `${prefix}: ${cleaned}` : prefix);
 }
 
+/**
+ * Isolated jobs already receive an absolute projectRoot on stdin. Using that
+ * directory as spawn cwd keeps the folder locked on Windows (EBUSY on rmdir)
+ * for the life of the child. Park the process in a disposable temp dir instead.
+ */
+export function isolatedMaintenanceCwd(): string {
+  const tmp = os.tmpdir();
+  return existsSync(tmp) ? tmp : process.cwd();
+}
+
 /**
  * Resolve the runner beside the compiled package entry. The CLI bundle lives
  * in dist/cli while the library entry lives directly in dist.
@@ -148,7 +159,7 @@ export async function runMaintenanceInChildProcess(
     let child: ChildProcessWithoutNullStreams;
     try {
       child = spawn(process.execPath, [runnerPath], {
-        cwd: request.projectRoot,
+        cwd: isolatedMaintenanceCwd(),
         env,
         stdio: ['pipe', 'pipe', 'pipe'],
         windowsHide: true,

package/src/server.ts

@@ -33,6 +33,7 @@ import { canManageObservation, canReadObservation, filterReadableObservations, r
 import { compactSearch, compactTimeline, compactDetail } from './compact/engine.js';
 import { buildGraphContextPacket, formatGraphContextPrompt } from './memory/graph-context.js';
 import { detectProject } from './project/detector.js';
+import { homeProjectRootError, isHomeDirectory, writeLastProjectRoot } from './project/launch-root.js';
 import { registerAlias, initAliasRegistry, resolveAliases, autoMergeByBaseName } from './project/aliases.js';
 import { getProjectDataDir } from './store/persistence.js';
 import type { ObservationType, RuleSource, AgentTarget, MCPServerEntry, ObservationReader } from './types.js';
@@ -45,7 +46,8 @@ import {
   type ToolProfile,
 } from './server/tool-profile.js';
 import { initLLM, isLLMEnabled, getLLMConfig } from './llm/provider.js';
-import { compactOnWrite, deduplicateMemory } from './llm/memory-manager.js';
+import { compactOnWrite } from './llm/memory-manager.js';
+import { applyDeduplicationPlan, planMemoryDeduplication } from './memory/deduplication.js';
 import type { ExistingMemory } from './llm/memory-manager.js';
 import { runFormation, getMetricsSummary, getBeforeAfterMetrics } from './memory/formation/index.js';
 import type { FormationConfig, SearchHit, FormedMemory, FormationStage, FormationStageEvent } from './memory/formation/types.js';
@@ -228,6 +230,7 @@ export const BOOTSTRAP_SAFE_TOOL_NAMES = new Set([
   'memorix_codegraph_status',
   'memorix_graph_context',
   'memorix_context_pack',
+  'memorix_session_start',
 ]);
 
 const AUTOPILOT_RETRIEVAL_BOUNDARY_TTL_MS = 2 * 60 * 1000;
@@ -265,7 +268,10 @@ export async function createMemorixServer(
   });
   const teamFeaturesEnabled = isToolInProfile('team_manage', toolProfile);
   const projectBinding = options.projectBinding ?? createProjectBindingController(cwd ?? process.cwd());
-  const detectedProject = detectProject(cwd);
+  const detectedProjectRaw = detectProject(cwd);
+  const detectedProject = detectedProjectRaw && !isHomeDirectory(detectedProjectRaw.rootPath)
+    ? detectedProjectRaw
+    : null;
   let rawProject: import('./types.js').ProjectInfo;
   let projectResolved = true;
   let projectResolutionError: string | null = null;
@@ -316,6 +322,7 @@ export async function createMemorixServer(
   }
   if (projectResolved) {
     projectBinding.recordResolvedProject(project.id, project.rootPath);
+    writeLastProjectRoot(project.rootPath);
   }
 
   const registerMaintenanceTarget = async (): Promise<void> => {
@@ -362,6 +369,7 @@ export async function createMemorixServer(
 
   const lightweightUnresolvedSession = !projectResolved && deferProjectInitUntilBound;
   let projectRuntimeInitPromise: Promise<void> | null = null;
+  let runtimeHydratedForDir: string | null = null;
 
   const initializeProjectRuntime = async (logPrefix: 'startup' | 'switch'): Promise<void> => {
     await initObservationStore(projectDir);
@@ -430,14 +438,20 @@ export async function createMemorixServer(
   } catch { /* migration is optional */ }
 
   await initializeProjectRuntime('startup');
+    runtimeHydratedForDir = projectDir;
   } else {
     // Intentionally silent — serve-http.ts deferred logging handles session lifecycle visibility.
     // Noisy per-probe 'awaiting binding' log was removed to reduce terminal spam.
   }
 
   const ensureProjectRuntimeInitialized = async (): Promise<void> => {
-    if (lightweightUnresolvedSession || !deferProjectRuntimeInit) return;
+    if (!projectResolved) return;
+    if (runtimeHydratedForDir === projectDir) {
+      if (projectRuntimeInitPromise) await projectRuntimeInitPromise;
+      return;
+    }
     if (!projectRuntimeInitPromise) {
+      const targetDir = projectDir;
       projectRuntimeInitPromise = (async () => {
         // Auto-merge obvious alias groups by scanning observed projectIds in data.
         try {
@@ -470,7 +484,8 @@ export async function createMemorixServer(
           }
         } catch { /* migration is optional */ }
 
-        await initializeProjectRuntime('startup');
+        await initializeProjectRuntime(runtimeHydratedForDir ? 'switch' : 'startup');
+        runtimeHydratedForDir = targetDir;
       })().catch((err) => {
         projectRuntimeInitPromise = null;
         throw err;
@@ -2489,66 +2504,31 @@ export async function createMemorixServer(
         return { content: [{ type: 'text' as const, text: 'Not enough memories in scope to deduplicate.' }] };
       }
 
-      // Group by entity for focused dedup
-      const byEntity = new Map<string, typeof candidates>();
-      for (const obs of candidates) {
-        const list = byEntity.get(obs.entityName) ?? [];
-        list.push(obs);
-        byEntity.set(obs.entityName, list);
-      }
-
-      const actions: string[] = [];
-      const toResolve: number[] = [];
-
-      for (const [entity, group] of byEntity) {
-        if (group.length < 2) continue;
-
-        // Compare each pair within entity group
-        for (let i = 0; i < group.length; i++) {
-          for (let j = i + 1; j < group.length; j++) {
-            const newer = group[j];
-            const older = group[i];
-            try {
-              const decision = await deduplicateMemory(
-                { title: newer.title, narrative: newer.narrative, facts: newer.facts },
-                [{ id: older.id, title: older.title, narrative: older.narrative, facts: older.facts.join('\n') }],
-              );
-              if (decision && decision.action === 'UPDATE' && decision.targetId) {
-                actions.push(`[UPDATED] #${older.id} "${older.title}" → superseded by #${newer.id} (${decision.reason})${decision.usedLLM ? ' [LLM]' : ' [heuristic]'}`);
-                toResolve.push(older.id);
-              } else if (decision && decision.action === 'NONE') {
-                actions.push(`[DELETE] #${newer.id} "${newer.title}" → redundant (${decision.reason})${decision.usedLLM ? ' [LLM]' : ' [heuristic]'}`);
-                toResolve.push(newer.id);
-              } else if (decision && decision.action === 'DELETE') {
-                actions.push(`[ERROR] #${decision.targetId ?? older.id} → outdated (${decision.reason})${decision.usedLLM ? ' [LLM]' : ' [heuristic]'}`);
-                toResolve.push(decision.targetId ?? older.id);
-              }
-            } catch (dedupErr) { actions.push(`[WARN] comparison failed: ${(dedupErr as Error)?.message ?? dedupErr}`); }
-          }
-        }
-      }
+      const manageableCandidates = candidates.filter((observation) => canManageObservation(observation, reader));
+      const plan = await planMemoryDeduplication(manageableCandidates);
+      const actionLines = plan.actions.map((item) =>
+        `Resolve #${item.resolveId} "${item.resolveTitle}"; keep #${item.keepId} "${item.keepTitle}" (${item.reason})${item.usedLLM ? ' [LLM]' : ' [heuristic]'}`,
+      );
 
-      if (actions.length === 0) {
-        return { content: [{ type: 'text' as const, text: `[OK] Scanned ${candidates.length} memories across ${byEntity.size} entities — no duplicates found.` }] };
+      if (actionLines.length === 0) {
+        return { content: [{ type: 'text' as const, text: `[OK] Scanned ${plan.scanned} memories across ${plan.entities} entities — no duplicates found.` }] };
       }
 
       if (dryRun) {
         return {
           content: [{
             type: 'text' as const,
-            text: `[SEARCH] DRY RUN — ${actions.length} action(s) found:\n\n${actions.join('\n')}\n\nRun with dryRun=false to apply.`,
+            text: `[SEARCH] DRY RUN — ${actionLines.length} action(s) found:\n\n${actionLines.join('\n')}\n\nRun with dryRun=false to apply.`,
           }],
         };
       }
 
-      // Apply resolutions
-      const unique = [...new Set(toResolve)];
-      await resolveObservations(unique, 'resolved');
+      const result = await applyDeduplicationPlan(getObservationStore(), project.id, plan.resolveIds, reader);
 
       return {
         content: [{
           type: 'text' as const,
-          text: `[CLEANUP] Deduplicated: resolved ${unique.length} memory(ies)\n\n${actions.join('\n')}`,
+          text: `[CLEANUP] Deduplicated: resolved ${result.resolved.length} memory(ies)\n\n${actionLines.join('\n')}`,
         }],
       };
     },
@@ -3846,6 +3826,15 @@ export async function createMemorixServer(
       // BEFORE checking whether the project is resolved. This is the primary
       // mechanism for HTTP/control-plane multi-project support.
       if (explicitRoot && typeof explicitRoot === 'string') {
+        if (isHomeDirectory(explicitRoot)) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: homeProjectRootError(explicitRoot),
+            }],
+            isError: true as const,
+          };
+        }
         let bound = await switchProject(explicitRoot, 'explicit-project-root');
         // switchProject returns false for both "same project, no-op" and "no git repo".
         // Only scan subdirectories when explicitRoot is not itself a git repo; otherwise
@@ -5503,8 +5492,12 @@ export async function createMemorixServer(
   ): Promise<boolean> => {
     if (source === 'mcp-roots' && projectBinding.isExplicit()) return false;
     const { detectProjectWithDiagnostics } = await import('./project/detector.js');
+    if (isHomeDirectory(newCwd)) {
+      console.error(`[memorix] Refusing to bind $HOME as a project root: ${newCwd}`);
+      return false;
+    }
     const result = detectProjectWithDiagnostics(newCwd);
-    if (!result.project) {
+    if (!result.project || isHomeDirectory(result.project.rootPath)) {
       if (result.failure) {
         console.error(`[memorix] Project detection failed for "${newCwd}": [${result.failure.reason}] ${result.failure.detail}`);
       }
@@ -5523,6 +5516,7 @@ export async function createMemorixServer(
       else if (source === 'mcp-roots') projectBinding.bindFromRoots(newDetected.rootPath);
       else projectBinding.bindStartup(newDetected.rootPath);
       projectBinding.recordResolvedProject(project.id, project.rootPath);
+      writeLastProjectRoot(project.rootPath);
       return false; // same project, no-op
     }
 
@@ -5580,7 +5574,12 @@ export async function createMemorixServer(
       }
     } catch { /* best-effort - coordination features degrade gracefully */ }
 
-    await initializeProjectRuntime('switch');
+    writeLastProjectRoot(project.rootPath);
+    runtimeHydratedForDir = null;
+    projectRuntimeInitPromise = null;
+    void ensureProjectRuntimeInitialized().catch((err) => {
+      console.error(`[memorix] Background project runtime init failed: ${err instanceof Error ? err.message : err}`);
+    });
     try {
       await startProjectMaintenanceWorker();
     } catch {

package/src/store/obs-store.ts

@@ -59,7 +59,7 @@ export interface ObservationStore {
   /** Load one project's observations without scanning the shared flat store. */
   loadByProject(
     projectId: string,
-    options?: { status?: string; limit?: number; offset?: number; afterId?: number },
+    options?: { status?: string; limit?: number; offset?: number; afterId?: number; newestFirst?: boolean },
   ): Promise<Observation[]>;
 
   /** Count one project's observations without materializing the rows. */
@@ -231,7 +231,7 @@ export class DegradedBackend implements ObservationStore {
     return [];
   }
 
-  async loadByProject(_projectId: string, _options?: { status?: string; limit?: number; offset?: number; afterId?: number }): Promise<Observation[]> {
+  async loadByProject(_projectId: string, _options?: { status?: string; limit?: number; offset?: number; afterId?: number; newestFirst?: boolean }): Promise<Observation[]> {
     return [];
   }
 

package/src/store/sqlite-db.ts

@@ -16,6 +16,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import fs from 'node:fs';
 import { createDatabase, loadSqlite } from './bun-sqlite-compat.js';
+import { assertNotHomeDataDir } from '../project/launch-root.js';
 
 // Dynamic require for SQLite (better-sqlite3, node:sqlite, or bun:sqlite)
 let BetterSqlite3: any;
@@ -998,6 +999,7 @@ const _dbCache = new Map<string, any>();
  */
 export function getDatabase(dataDir: string): any {
   const normalized = path.resolve(dataDir);
+  assertNotHomeDataDir(normalized);
   const existing = _dbCache.get(normalized);
   if (existing) return existing;
 

package/src/store/sqlite-store.ts

@@ -122,6 +122,8 @@ export class SqliteBackend implements ObservationStore {
   private stmtSelectByProjectStatus: any = null;
   private stmtSelectByProjectAfterId: any = null;
   private stmtSelectByProjectStatusAfterId: any = null;
+  private stmtSelectByProjectNewest: any = null;
+  private stmtSelectByProjectStatusNewest: any = null;
   private stmtCountByProject: any = null;
   private stmtCountByProjectStatus: any = null;
   private stmtSelectByTopicKey: any = null;
@@ -175,6 +177,14 @@ export class SqliteBackend implements ObservationStore {
       SELECT * FROM observations WHERE projectId = ? AND status = ? AND id > ?
       ORDER BY id ASC LIMIT ?
     `);
+    this.stmtSelectByProjectNewest = this.db.prepare(`
+      SELECT * FROM observations WHERE projectId = ?
+      ORDER BY createdAt DESC, id DESC LIMIT ? OFFSET ?
+    `);
+    this.stmtSelectByProjectStatusNewest = this.db.prepare(`
+      SELECT * FROM observations WHERE projectId = ? AND status = ?
+      ORDER BY createdAt DESC, id DESC LIMIT ? OFFSET ?
+    `);
     this.stmtCountByProject = this.db.prepare(
       `SELECT COUNT(*) AS count FROM observations WHERE projectId = ?`,
     );
@@ -288,15 +298,20 @@ export class SqliteBackend implements ObservationStore {
 
   async loadByProject(
     projectId: string,
-    options: { status?: string; limit?: number; offset?: number; afterId?: number } = {},
+    options: { status?: string; limit?: number; offset?: number; afterId?: number; newestFirst?: boolean } = {},
   ): Promise<Observation[]> {
     const limit = options.limit == null ? -1 : Math.max(1, Math.floor(options.limit));
     const offset = options.offset == null ? 0 : Math.max(0, Math.floor(options.offset));
     const afterId = options.afterId == null ? null : Math.max(0, Math.floor(options.afterId));
+    const newestFirst = options.newestFirst === true && afterId === null;
     const rows = afterId === null
-      ? (options.status
-        ? this.stmtSelectByProjectStatus.all(projectId, options.status, limit, offset)
-        : this.stmtSelectByProject.all(projectId, limit, offset))
+      ? (newestFirst
+        ? (options.status
+          ? this.stmtSelectByProjectStatusNewest.all(projectId, options.status, limit, offset)
+          : this.stmtSelectByProjectNewest.all(projectId, limit, offset))
+        : (options.status
+          ? this.stmtSelectByProjectStatus.all(projectId, options.status, limit, offset)
+          : this.stmtSelectByProject.all(projectId, limit, offset)))
       : (options.status
         ? this.stmtSelectByProjectStatusAfterId.all(projectId, options.status, afterId, limit)
         : this.stmtSelectByProjectAfterId.all(projectId, afterId, limit));