@vodmal/vdx-cli 0.36.0 → 0.37.0

package/README.md

@@ -50,8 +50,11 @@ vdx push [project-path] [--dry-run]   # default: cwd
 
 # Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin; git hooks of the project; the GitHub token vdx asks with)
 vdx doctor [project-path] [--format=ansi|markdown|json]   # default: cwd
-vdx doctor --check [project-path]   # one line per hook declared but not running here — the plugin's SessionStart hook tells the agent
-vdx doctor --fix                    # write the profile's personal hooks (git.hooks) into ~/.gitconfig
+vdx doctor --check [project-path]   # one line per hook declared but not running here, and one when the memory is
+                                    # not inside — the plugin's SessionStart hook tells the agent
+vdx doctor --fix [project-path]     # write the profile's personal hooks (git.hooks) into ~/.gitconfig, and put
+                                    # the project's Claude Code memory inside it: .claude/memory/ (after a
+                                    # folder move, its path and conversations follow)
 
 # Start your agent in a project per your profile (~/.vdx-environment.yaml or $VDX_ENVIRONMENT)
 vdx ai[@host] [project-path] [--new | --conversation <id>] [--focused | --intercom] [--restart] [--detach] [--dry-run]   # default: cwd; @host: over ssh, in tmux there; --intercom: the project's mail session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "vdx — unified lifecycle interface (up/down/build/test/check/fix) + versioned maturity audit with drift detection. Pairs with the vdx Claude Code plugin.",
   "keywords": [
     "vdx",

package/rubric/vdx-rubric.yaml

@@ -11,7 +11,7 @@ schema_version: "0.3"
 
 metadata:
   name: vdx-rubric-vodmal
-  version: "1.6.1"
+  version: "1.7.0"
   description: "Personal maturity rubric for multi-stack projects (vodmal)"
   owner: vodmal
   homepage: "https://github.com/vodmal/vdx-rubric"

package/src/ai.ts

@@ -29,6 +29,7 @@ import {
   parseMachineReport,
   runsInProject,
 } from './conversations.ts';
+import { describeMemory, fixProjectMemory, memoryNeedsFix, memoryState } from './memory.ts';
 import { at, errorMessage, isStringList, str } from './narrow.ts';
 import { type Lag, sessionLag } from './session-versions.ts';
 
@@ -115,6 +116,8 @@ interface GitProfile {
   /** Directories whose repos are the neighbours an author is proposed from; default — the project's parent. */
   author_pool?: string[];
   hooks?: PersonalHook[];
+  /** Hosts whose repos are the owner's alone: Claude Code's memory goes under git there (claude-memory-in-project). */
+  personal_hosts?: string[];
 }
 
 export interface Environment {
@@ -252,6 +255,9 @@ export function parseEnvironment(text: string, source: string): Environment {
     if (gitDoc.author_pool !== undefined && !isStringList(gitDoc.author_pool)) {
       fail('git.author_pool', 'must be a list of directories');
     }
+    if (gitDoc.personal_hosts !== undefined && !isStringList(gitDoc.personal_hosts)) {
+      fail('git.personal_hosts', 'must be a list of host names');
+    }
     if (gitDoc.hooks !== undefined) {
       if (!Array.isArray(gitDoc.hooks)) fail('git.hooks', 'must be a list');
       const names = new Set<string>();
@@ -535,7 +541,8 @@ export function missingArgs(procArgs: string, required: string[]): string[] {
   return required.filter((a) => (/\s/.test(a) ? !procArgs.includes(a) : !tokens.has(a)));
 }
 
-function resolveProjectRoot(p: string): string | null {
+/** The git checkout `p` is in (its top), else the directory itself; null when `p` is no directory. */
+export function resolveProjectRoot(p: string): string | null {
   const abs = path.resolve(p);
   try {
     if (!fs.statSync(abs).isDirectory()) return null;
@@ -1140,6 +1147,61 @@ export function ensureAuthor(projectRoot: string, poolDirs: string[], deps: AiDe
   }
 }
 
+/**
+ * Claude Code's memory of the project lives inside it, `.claude/memory/`
+ * (claude-memory-in-project): a start says when it does not, and at a terminal asks
+ * to put it there — Enter does. With an agent of the project running it only says so:
+ * that session keeps the old place until it restarts. Without a terminal it names
+ * `vdx doctor --fix`, the same move.
+ */
+export function ensureMemory(
+  projectRoot: string,
+  command: string,
+  personalHosts: string[],
+  deps: AiDeps,
+  dryRun: boolean,
+  agentRunning: boolean,
+): void {
+  if (!isClaude(command)) return;
+  const ctx = { env: deps.env, home: deps.home };
+  const state = memoryState(projectRoot, ctx);
+  if (dryRun) {
+    deps.out(`  memory:   ${describeMemory(state, ctx)}\n`);
+    return;
+  }
+  if (!memoryNeedsFix(state)) return;
+  const fix = `vdx doctor --fix ${shellQuote(projectRoot)}`;
+  deps.log(`⚠ ${path.basename(projectRoot)}: Claude memory ${describeMemory(state, ctx)}`);
+  if (!deps.interactive || agentRunning) {
+    deps.log(`  ${agentRunning ? 'once the running agent of the project ends' : 'put it there'}: ${fix}`);
+    return;
+  }
+  const question =
+    state.kind === 'outside'
+      ? 'Move it into .claude/memory/ now?'
+      : state.kind === 'leftovers'
+        ? 'Set the old place aside?'
+        : state.kind === 'moved' && state.conversations
+          ? 'Point it here, and bring the conversations along?'
+          : 'Point it here?';
+  const answer = deps.ask(`  ${question} [Y/n] `);
+  if (answer === null || /^n(o)?$/i.test(answer.trim())) {
+    deps.log(`  skipped — later: ${fix}`);
+    return;
+  }
+  try {
+    const done = fixProjectMemory(projectRoot, state, ctx, {
+      ask: deps.ask,
+      log: deps.log,
+      today: new Date().toLocaleDateString('sv-SE'),
+      personalHosts,
+    });
+    for (const d of done) deps.log(`✓ ${d}`);
+  } catch (e) {
+    deps.log(`✗ ${errorMessage(e)} — ${fix}`);
+  }
+}
+
 /** `from` — where the person sits; a vdx that `vdx ai@<host>` started passes its own on. */
 export function runAiRemote(opts: AiOptions, host: string, deps: AiDeps, from: string = seatLabel(deps.env)): number {
   const projectPath = resolveProjectRoot(opts.path) ?? path.resolve(opts.path);
@@ -1866,6 +1928,7 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     for (const l of choice?.lines ?? []) deps.out(`  conversation: ${l}\n`);
     for (const l of folders) deps.out(`  ${l}\n`);
     ensureAuthor(projectRoot, poolDirs, deps, true);
+    ensureMemory(projectRoot, plan.command, environment.git?.personal_hosts ?? [], deps, true, agentsHere.length > 0);
     return EXIT_OK;
   }
   for (const l of choice?.lines ?? []) log(l);
@@ -1901,6 +1964,7 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     plan = { ...plan, resumeArgs: resumeId(id) };
   }
   ensureAuthor(projectRoot, poolDirs, deps, false);
+  ensureMemory(projectRoot, plan.command, environment.git?.personal_hosts ?? [], deps, false, agentsHere.length > 0);
 
   if (multiplexer === 'none') {
     if (opts.restart) {

package/src/doctor.ts

@@ -4,9 +4,24 @@ import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { effectiveAuthor, isGitRepo, rankAuthors, remoteParts, scanPool } from './author.ts';
-import { authorPoolDirs, loadEnvironment, resolveEnvironmentPath, shellQuote, type Environment } from './ai.ts';
+import {
+  authorPoolDirs,
+  loadEnvironment,
+  resolveEnvironmentPath,
+  resolveProjectRoot,
+  shellQuote,
+  type Environment,
+} from './ai.ts';
 import { checkRepoHooks } from './clone-checks.ts';
 import { githubToken, machineIo, type HostingIo } from './hosting.ts';
+import {
+  describeMemory,
+  fixProjectMemory,
+  memoryNeedsFix,
+  memoryState,
+  type MemoryCtx,
+  type MemoryState,
+} from './memory.ts';
 import { at, dict, errorMessage, str } from './narrow.ts';
 import {
   checkPersonalHooks,
@@ -24,6 +39,8 @@ export interface CheckResult {
   level?: number;
   message: string;
   remedy?: string;
+  /** For the agent's own session (`--check`): what the fix does not change for it. */
+  sessionNote?: string;
 }
 
 /**
@@ -473,6 +490,52 @@ export function checkGithubToken(
   };
 }
 
+/** The profile, or none: a broken one is `vdx ai`'s report, not a reason for doctor to stop. */
+function profile(): Environment {
+  const file = resolveEnvironmentPath();
+  try {
+    return file ? loadEnvironment(file) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Claude Code is the project's agent: the profile names it, or names no agent at all. */
+function claudeIsTheAgent(environment: Environment): boolean {
+  return path.basename(environment.agent?.command ?? 'claude') === 'claude';
+}
+
+function memoryCtx(): MemoryCtx {
+  return { env: process.env, home: os.homedir() };
+}
+
+/**
+ * Where Claude Code keeps the project's memory (claude-memory-in-project): inside the
+ * project, `.claude/memory/`, so a moved folder takes it along — and the path set there
+ * is the trace a move leaves.
+ */
+export function checkClaudeMemory(
+  ctx: DoctorCtx,
+  environment: Environment = profile(),
+  mctx: MemoryCtx = memoryCtx(),
+): CheckResult | null {
+  if (ctx.projectRoot === null || !claudeIsTheAgent(environment)) return null;
+  // Claude Code's slot is the folder the agent starts in — the checkout's top for vdx ai.
+  const root = resolveProjectRoot(ctx.projectRoot) ?? ctx.projectRoot;
+  const state = memoryState(root, mctx);
+  return {
+    id: 'claude-memory',
+    label: 'Claude memory',
+    status: memoryNeedsFix(state) ? 'warning' : 'ok',
+    message: describeMemory(state, mctx),
+    ...(memoryNeedsFix(state) ? { remedy: `vdx doctor --fix ${shellQuote(root)}` } : {}),
+    // A session read the place when it started: after a fix it keeps writing to the old one.
+    ...(state.kind === 'outside' || state.kind === 'moved' || state.kind === 'elsewhere'
+      ? { sessionNote: 'This session keeps the old place until it restarts (vdx ai --restart).' }
+      : {}),
+  };
+}
+
 const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   checkVdxVersion,
   checkVdx,
@@ -487,6 +550,7 @@ const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   (ctx) => checkPersonalHooks(ctx.projectRoot),
   checkGitAuthor,
   (ctx) => checkGithubToken(ctx),
+  (ctx) => checkClaudeMemory(ctx),
 ];
 
 export function resolveDoctorCtx(cwd: string = process.cwd()): DoctorCtx {
@@ -510,13 +574,20 @@ export function runDoctor(ctx: DoctorCtx = resolveDoctorCtx()): DoctorReport {
 export function runDoctorCheck(
   ctx: DoctorCtx = resolveDoctorCtx(),
   deps: PersonalHookDeps = defaultPersonalHookDeps(),
+  environment: Environment = profile(),
+  mctx: MemoryCtx = memoryCtx(),
 ): string {
-  const rows = [checkRepoHooks(ctx.projectRoot), checkPersonalHooks(ctx.projectRoot, deps)].filter(
-    (c): c is CheckResult => c !== null && c.status !== 'ok',
-  );
+  const rows = [
+    checkRepoHooks(ctx.projectRoot),
+    checkPersonalHooks(ctx.projectRoot, deps),
+    checkClaudeMemory(ctx, environment, mctx),
+  ].filter((c): c is CheckResult => c !== null && c.status !== 'ok');
   return rows
     .map(
-      (c) => `vdx doctor: ${c.label} — ${c.message}.` + (c.remedy ? ` Fix, on the user's word: \`${c.remedy}\`.` : ''),
+      (c) =>
+        `vdx doctor: ${c.label} — ${c.message}.` +
+        (c.remedy ? ` Fix, on the user's word: \`${c.remedy}\`.` : '') +
+        (c.sessionNote ? ` ${c.sessionNote}` : ''),
     )
     .join('\n');
 }
@@ -530,6 +601,18 @@ export function runDoctorFix(deps: PersonalHookDeps = defaultPersonalHookDeps())
   return fixPersonalHooks(deps);
 }
 
+/** `vdx doctor --fix` for the memory: the profile's personal hosts, this machine's Claude Code. */
+export function fixDoctorMemory(
+  projectRoot: string,
+  state: MemoryState,
+  io: { ask: (prompt: string) => string | null; log: (line: string) => void; today: string },
+): string[] {
+  return fixProjectMemory(projectRoot, state, memoryCtx(), {
+    ...io,
+    personalHosts: profile().git?.personal_hosts ?? [],
+  });
+}
+
 const PROJECT_MARKER_FILES = [
   'package.json',
   'composer.json',

package/src/index.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { loadRubric } from './rubric.ts';
@@ -16,6 +17,8 @@ import {
   reportDoctorAnsi,
 } from './report.ts';
 import {
+  checkClaudeMemory,
+  fixDoctorMemory,
   runDoctor,
   runDoctorCheck,
   runDoctorFix,
@@ -23,6 +26,7 @@ import {
   looksLikeProject,
   readCliVersion,
 } from './doctor.ts';
+import { memoryState } from './memory.ts';
 import { planInit, writeInit, renderPlanSummary } from './init.ts';
 import {
   planPublish,
@@ -35,7 +39,17 @@ import {
 } from './publish.ts';
 import { resolveDefaultRubric } from './defaults.ts';
 import { defaultGateDeps, GATE_PREFIX, planGate, pushThroughGate } from './gate.ts';
-import { askLine, runAi, runAiCheck, runAiClose, runAiRemote, defaultDeps, hostLabel, REMOTE_HOST_RE } from './ai.ts';
+import {
+  askLine,
+  runAi,
+  runAiCheck,
+  runAiClose,
+  runAiRemote,
+  defaultDeps,
+  hostLabel,
+  REMOTE_HOST_RE,
+  resolveProjectRoot,
+} from './ai.ts';
 import { isConversationId } from './conversations.ts';
 
 const DEFAULT_RUBRIC = resolveDefaultRubric();
@@ -132,6 +146,11 @@ ones marked — Enter takes the newest; without a terminal it takes this
 machine's. A new conversation (--new, or none to continue) while an agent of
 the project runs on another machine starts only after a yes.
 
+Claude Code's memory of the project (Claude Code only): when it is not inside the
+project, .claude/memory/, or the folder was moved, a start in a terminal asks to
+put it there — Enter does, as vdx doctor --fix; with an agent of the project
+running, or no terminal, it only names that command.
+
 Exit codes: 0 the agent runs per the profile; 2 profile or usage error;
 3 the running agent lacks profile flags, or is not focused under --focused,
 and was left as is — no terminal, or q (rerun with --restart); 4 the start
@@ -221,14 +240,23 @@ Claude Code plugin) and, inside a project (default: cwd), its commit author and
 its git hooks: are the hooks the repository declares on in this clone, and do
 the personal hooks of your profile (git.hooks) run on this machine; with origin on
 GitHub, the token vdx asks GitHub with ($GH_TOKEN, $GITHUB_TOKEN or gh) and
-whether it works — without one GitHub answers 60 requests an hour. Reads only.
-Exit 2 when something is missing.
+whether it works — without one GitHub answers 60 requests an hour; and where
+Claude Code keeps the project's memory: inside it, .claude/memory/, a moved folder
+takes it along. Reads only, unless --fix. Exit 2 when something is missing.
 
   --check  for the agent's own session (the vdx plugin's SessionStart hook): one
-           line per hook that is declared but does not run here; nothing when in order
+           line per hook that is declared but does not run here, and one when the
+           memory is not inside; nothing when in order
   --fix    write the profile's personal hooks into ~/.gitconfig where they are
-           missing or differ; repository hooks are switched on by the project's
-           install step, which the report names
+           missing or differ (repository hooks are switched on by the project's
+           install step, which the report names); and put the memory inside:
+           notes from ~/.claude/projects/<path>/memory into .claude/memory/, none
+           overwritten, the old place renamed, autoMemoryDirectory written —
+           into .claude/settings.json in a personal project (no origin, or origin
+           on a host of git.personal_hosts), else into .claude/settings.local.json,
+           with the memory kept out of git (.git/info/exclude) unless you say
+           yes. After a folder is moved: the path follows it, and the project's
+           conversations move to the new path
 `,
     bools: ['json', 'check', 'fix'],
     values: ['format'],
@@ -598,6 +626,22 @@ function cmdDoctor(opts: ParsedArgs): void {
       process.stderr.write(`vdx doctor --fix: ${errorMessage(e)}\n`);
       process.exit(2);
     }
+    const root = ctx.projectRoot ? resolveProjectRoot(ctx.projectRoot) : null;
+    const memory = root ? checkClaudeMemory({ projectRoot: root }) : null;
+    if (root && memory?.remedy) {
+      try {
+        const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
+        const done = fixDoctorMemory(root, memoryState(root, { env: process.env, home: os.homedir() }), {
+          ask: (prompt) => (interactive ? askLine(prompt) : null),
+          log: (line) => process.stderr.write(line + '\n'),
+          today: new Date().toLocaleDateString('sv-SE'),
+        });
+        process.stderr.write(done.map((d) => `✓ ${d}`).join('\n') + (done.length ? '\n' : ''));
+      } catch (e) {
+        process.stderr.write(`vdx doctor --fix: Claude memory — ${errorMessage(e)}\n`);
+        process.exit(2);
+      }
+    }
   }
   const report = runDoctor(ctx);
 

package/src/init.ts

@@ -6,7 +6,7 @@ import { at } from './narrow.ts';
 export const STANDARD_VERBS = ['up', 'down', 'build', 'test', 'check', 'fix'] as const;
 export type Verb = (typeof STANDARD_VERBS)[number];
 
-export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v1.6.1';
+export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v1.7.0';
 
 const VERB_ALIASES: Record<Verb, string[]> = {
   up: ['docker:up', 'docker-up', 'docker:up:detached', 'start', 'dev', 'serve'],

package/src/memory.ts

@@ -0,0 +1,367 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { remoteParts } from './author.ts';
+import { claudeConfigDir, projectDirName } from './conversations.ts';
+import { dict, str } from './narrow.ts';
+
+/**
+ * Where Claude Code keeps a project's memory (docs/tasks/claude-memory-in-project).
+ * Unset, it is `<config>/projects/<path, non-letters → "-">/memory/` — tied to the
+ * folder's path, so a moved folder loses it, and its conversations with it. The
+ * owner keeps it inside the project, `.claude/memory/`, named by
+ * `autoMemoryDirectory`: an absolute path or `~/`, nothing relative, no variables
+ * (Claude Code 2.1.308, DL #2). A path written there outlives a move as the trace of
+ * the old place.
+ */
+export type MemoryState =
+  /** In `.claude/memory/`, nothing left in the old place. */
+  | { kind: 'inside' }
+  /** In `.claude/memory/`, and notes still lie in the old place — a move made by hand. */
+  | { kind: 'leftovers'; old: string; notes: number; differ: number; onlyOld: number }
+  /** Not set: memory goes to the old place. */
+  | { kind: 'outside'; old: string; notes: number }
+  /**
+   * Set to `<X>/.claude/memory/` of a folder that is gone: the project moved from X. `stray`: X
+   * holds nothing but that memory — a session that read the old path wrote there after the move.
+   */
+  | { kind: 'moved'; setting: MemorySetting; from: string; conversations: string | null; stray: string | null }
+  /** Set to `<X>/.claude/memory/` of another folder that exists. */
+  | { kind: 'elsewhere'; setting: MemorySetting; from: string }
+  /** Set to a path of the owner's own choosing. */
+  | { kind: 'custom'; setting: MemorySetting };
+
+interface MemorySetting {
+  /** The settings file that names it. */
+  file: string;
+  /** The path it names, `~/` expanded, without the trailing slash. */
+  dir: string;
+}
+
+export interface MemoryCtx {
+  env: NodeJS.ProcessEnv;
+  home: string;
+}
+
+const MEMORY = path.join('.claude', 'memory');
+
+function realRoot(root: string): string {
+  try {
+    return fs.realpathSync(root);
+  } catch {
+    return path.resolve(root);
+  }
+}
+
+/** Where the setting is read, in Claude Code's order: local settings, the project's, the user's. */
+function settingFiles(root: string, ctx: MemoryCtx): string[] {
+  return [
+    path.join(root, '.claude', 'settings.local.json'),
+    path.join(root, '.claude', 'settings.json'),
+    path.join(claudeConfigDir(ctx.env, ctx.home), 'settings.json'),
+  ];
+}
+
+function readJson(file: string): Record<string, unknown> | null {
+  try {
+    return dict(JSON.parse(fs.readFileSync(file, 'utf8'))) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function readSetting(root: string, ctx: MemoryCtx): MemorySetting | null {
+  for (const file of settingFiles(root, ctx)) {
+    const value = str(readJson(file)?.['autoMemoryDirectory']);
+    if (!value) continue;
+    const expanded = value.startsWith('~/') ? path.join(ctx.home, value.slice(2)) : value;
+    // Claude Code drops a relative path without a word (DL #2): it is no setting.
+    if (!path.isAbsolute(expanded)) continue;
+    return { file, dir: path.resolve(expanded) };
+  }
+  return null;
+}
+
+/** The old place: what Claude Code uses when nothing is set. */
+export function defaultMemoryDir(root: string, ctx: MemoryCtx): string {
+  return path.join(claudeConfigDir(ctx.env, ctx.home), 'projects', projectDirName(realRoot(root)), 'memory');
+}
+
+function entries(dir: string): string[] {
+  try {
+    return fs.readdirSync(dir).filter((n) => n !== '.DS_Store');
+  } catch {
+    return [];
+  }
+}
+
+function sameFile(a: string, b: string): boolean {
+  try {
+    return fs.readFileSync(a).equals(fs.readFileSync(b));
+  } catch {
+    return false;
+  }
+}
+
+export function memoryState(projectRoot: string, ctx: MemoryCtx): MemoryState {
+  const root = realRoot(projectRoot);
+  const target = path.join(root, MEMORY);
+  const old = defaultMemoryDir(root, ctx);
+  const setting = readSetting(root, ctx);
+  const notes = entries(old);
+  if (!setting) return { kind: 'outside', old, notes: notes.length };
+  if (setting.dir === target) {
+    if (notes.length === 0) return { kind: 'inside' };
+    const differ = notes.filter(
+      (n) => fs.existsSync(path.join(target, n)) && !sameFile(path.join(old, n), path.join(target, n)),
+    );
+    const onlyOld = notes.filter((n) => !fs.existsSync(path.join(target, n)));
+    return { kind: 'leftovers', old, notes: notes.length, differ: differ.length, onlyOld: onlyOld.length };
+  }
+  if (path.basename(setting.dir) === 'memory' && path.basename(path.dirname(setting.dir)) === '.claude') {
+    const from = path.dirname(path.dirname(setting.dir));
+    const stub = entries(from).join() === '.claude' && entries(path.join(from, '.claude')).join() === 'memory';
+    if (fs.existsSync(from) && !stub) return { kind: 'elsewhere', setting, from };
+    const conversations = path.join(claudeConfigDir(ctx.env, ctx.home), 'projects', projectDirName(from));
+    return {
+      kind: 'moved',
+      setting,
+      from,
+      conversations: fs.existsSync(conversations) ? conversations : null,
+      stray: stub ? setting.dir : null,
+    };
+  }
+  return { kind: 'custom', setting };
+}
+
+function git(root: string, args: string[]): string | null {
+  try {
+    return execFileSync('git', ['--no-optional-locks', '-C', root, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A personal project's memory goes under git with it; anyone else's would reach
+ * whoever clones it (DL #3, #4). Personal: no origin, or origin on a host the
+ * profile names in `git.personal_hosts`.
+ */
+export function isPersonalProject(projectRoot: string, personalHosts: string[]): boolean {
+  const url = git(projectRoot, ['remote', 'get-url', 'origin']);
+  if (!url) return true;
+  const host = remoteParts(url).host.toLowerCase();
+  return personalHosts.some((h) => h.toLowerCase() === host);
+}
+
+/** Needs `vdx doctor --fix`: anything but inside, or a path of the owner's own. */
+export function memoryNeedsFix(state: MemoryState): boolean {
+  return state.kind !== 'inside' && state.kind !== 'custom';
+}
+
+function tilde(p: string, home: string): string {
+  return p === home || p.startsWith(home + path.sep) ? '~' + p.slice(home.length) : p;
+}
+
+/** One line on where the memory is, for doctor and `vdx ai`. */
+export function describeMemory(state: MemoryState, ctx: MemoryCtx): string {
+  switch (state.kind) {
+    case 'inside':
+      return 'in .claude/memory/';
+    case 'leftovers': {
+      const parts = [state.differ ? `${state.differ} differ` : '', state.onlyOld ? `${state.onlyOld} only there` : '']
+        .filter(Boolean)
+        .join(', ');
+      return `in .claude/memory/, and ${state.notes} note(s) still in the old place, ${tilde(state.old, ctx.home)}${parts ? ` (${parts})` : ''} — the project's agent takes what it needs, vdx copies nothing back`;
+    }
+    case 'outside':
+      return state.notes
+        ? `outside the project: ${state.notes} note(s) in ${tilde(state.old, ctx.home)} — a moved folder loses them, and its conversations`
+        : `not set: notes would go to ${tilde(state.old, ctx.home)}, by the folder's path — a moved folder loses them, and its conversations`;
+    case 'moved':
+      return `autoMemoryDirectory points to ${tilde(state.setting.dir, ctx.home)}/, ${state.stray ? 'in a folder that holds nothing else' : 'a folder that is gone'} — the project moved from ${tilde(state.from, ctx.home)}${state.conversations ? ', and its conversations stay under the old path' : ''}`;
+    case 'elsewhere':
+      return `autoMemoryDirectory points to the memory of another folder, ${tilde(state.from, ctx.home)} (set in ${tilde(state.setting.file, ctx.home)})`;
+    case 'custom':
+      return `in ${tilde(state.setting.dir, ctx.home)}/ (autoMemoryDirectory, set in ${tilde(state.setting.file, ctx.home)})`;
+  }
+}
+
+export interface MemoryFixOptions {
+  /** Personal project (`isPersonalProject`): the path goes into `.claude/settings.json`, the memory under git. */
+  personal: boolean;
+  /** Not personal: keep `.claude/memory/` under git anyway — the person said yes. */
+  underGit: boolean;
+  /** YYYY-MM-DD, for the name the old place is set aside under. */
+  today: string;
+}
+
+/** A free name beside `dir`: `<dir>.moved-<date>`, then `-2`, `-3`… */
+function asideName(dir: string, today: string): string {
+  const base = `${dir}.moved-${today}`;
+  let name = base;
+  for (let i = 2; fs.existsSync(name); i++) name = `${base}-${i}`;
+  return name;
+}
+
+/** Copies what `to` lacks; a name `to` already has stays as it is there. Returns the names kept. */
+function copyMissing(from: string, to: string): { copied: number; kept: string[] } {
+  fs.mkdirSync(to, { recursive: true });
+  let copied = 0;
+  const kept: string[] = [];
+  for (const name of entries(from)) {
+    const src = path.join(from, name);
+    const dst = path.join(to, name);
+    if (fs.existsSync(dst)) {
+      if (!sameFile(src, dst)) kept.push(name);
+      continue;
+    }
+    fs.cpSync(src, dst, { recursive: true, errorOnExist: true, force: false });
+    copied++;
+  }
+  return { copied, kept };
+}
+
+/** Sets `autoMemoryDirectory` in a settings file, keeping its other keys. */
+function writeSetting(file: string, dir: string): void {
+  let doc: Record<string, unknown> = {};
+  if (fs.existsSync(file)) {
+    const parsed = readJson(file);
+    if (!parsed)
+      throw new Error(`${file} is not a JSON object — nothing written; set autoMemoryDirectory there by hand`);
+    doc = parsed;
+  }
+  doc['autoMemoryDirectory'] = dir + '/';
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(doc, null, 2) + '\n');
+}
+
+/** `/.claude/memory/` in the clone's own exclude file — the repository itself does not change. */
+function excludeMemory(root: string): string | null {
+  const file = git(root, ['rev-parse', '--git-path', 'info/exclude']);
+  if (!file) return null;
+  const abs = path.resolve(root, file);
+  const line = '/.claude/memory/';
+  const text = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : '';
+  if (!text.split('\n').includes(line)) {
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, text + (text && !text.endsWith('\n') ? '\n' : '') + line + '\n');
+  }
+  return abs;
+}
+
+/**
+ * Moves the project's conversations to the folder's new path: Claude Code finds them
+ * by the path, and a moved folder starts with none. What the new place already has
+ * stays; the rest of the old place is set aside, never deleted.
+ */
+function moveConversations(from: string, to: string, today: string): string {
+  if (!fs.existsSync(to)) {
+    fs.renameSync(from, to);
+    return `conversations ${path.basename(from)} → ${path.basename(to)}`;
+  }
+  let moved = 0;
+  for (const name of entries(from)) {
+    const dst = path.join(to, name);
+    if (fs.existsSync(dst)) continue;
+    fs.renameSync(path.join(from, name), dst);
+    moved++;
+  }
+  const left = entries(from).length;
+  const aside = left ? asideName(from, today) : null;
+  if (aside) fs.renameSync(from, aside);
+  else fs.rmdirSync(from);
+  return `${moved} conversation file(s) ${path.basename(from)} → ${path.basename(to)}${aside ? `; ${left} already there, the rest set aside as ${path.basename(aside)}` : ''}`;
+}
+
+/**
+ * Puts the project's memory inside it — `vdx doctor --fix` and the question in
+ * `vdx ai`. Nothing is overwritten and nothing deleted: a name `.claude/memory/`
+ * already has stays, the old place is renamed. Returns what was done, one line each.
+ */
+export function fixMemory(projectRoot: string, state: MemoryState, ctx: MemoryCtx, opts: MemoryFixOptions): string[] {
+  const root = realRoot(projectRoot);
+  const target = path.join(root, MEMORY);
+  const done: string[] = [];
+  const setAside = (old: string) => {
+    if (!fs.existsSync(old)) return;
+    const aside = asideName(old, opts.today);
+    fs.renameSync(old, aside);
+    done.push(`the old place set aside: ${tilde(aside, ctx.home)}`);
+  };
+  switch (state.kind) {
+    case 'inside':
+    case 'custom':
+      return done;
+    case 'leftovers':
+      setAside(state.old);
+      return done;
+    case 'outside': {
+      const { copied, kept } = fs.existsSync(state.old) ? copyMissing(state.old, target) : { copied: 0, kept: [] };
+      if (!fs.existsSync(target)) fs.mkdirSync(target, { recursive: true });
+      done.push(`${copied} note(s) → .claude/memory/`);
+      if (kept.length) done.push(`kept .claude/memory/ as it is for ${kept.join(', ')} — the old copy differs`);
+      const file = path.join(root, '.claude', opts.personal ? 'settings.json' : 'settings.local.json');
+      writeSetting(file, target);
+      done.push(`autoMemoryDirectory → .claude/${path.basename(file)}`);
+      if (!opts.personal && !opts.underGit && excludeMemory(root)) done.push('.claude/memory/ → .git/info/exclude');
+      setAside(state.old);
+      if (opts.personal && git(root, ['rev-parse', '--git-dir']) !== null) {
+        done.push('commit .claude/memory/ and .claude/settings.json with the project');
+      }
+      return done;
+    }
+    case 'moved':
+    case 'elsewhere': {
+      writeSetting(state.setting.file, target);
+      done.push(`autoMemoryDirectory → ${target}/ (${path.relative(root, state.setting.file)})`);
+      if (state.kind === 'moved' && state.stray) {
+        const { copied, kept } = copyMissing(state.stray, target);
+        done.push(
+          `${copied} note(s) written at the old path after the move → .claude/memory/${kept.length ? `; kept .claude/memory/ as it is for ${kept.join(', ')}` : ''} — ${tilde(state.from, ctx.home)} holds only them, remove it`,
+        );
+      }
+      if (state.kind === 'moved' && state.conversations) {
+        const here = path.join(claudeConfigDir(ctx.env, ctx.home), 'projects', projectDirName(root));
+        done.push(moveConversations(state.conversations, here, opts.today));
+      }
+      return done;
+    }
+  }
+}
+
+export interface ProjectMemoryDeps {
+  /** One line from the person at the terminal; null without one. */
+  ask: (prompt: string) => string | null;
+  log: (line: string) => void;
+  today: string;
+  /** The profile's `git.personal_hosts`. */
+  personalHosts: string[];
+}
+
+/**
+ * `fixMemory` with the question it needs: outside a personal project the memory stays
+ * out of git unless the person says yes — a publication cannot be taken back (DL #3,
+ * #4); without a terminal, out.
+ */
+export function fixProjectMemory(
+  projectRoot: string,
+  state: MemoryState,
+  ctx: MemoryCtx,
+  deps: ProjectMemoryDeps,
+): string[] {
+  const personal = isPersonalProject(projectRoot, deps.personalHosts);
+  let underGit = false;
+  if (state.kind === 'outside' && !personal && git(projectRoot, ['rev-parse', '--git-dir']) !== null) {
+    deps.log(`  ${path.basename(projectRoot)} is not a personal repo: memory under git reaches whoever clones it`);
+    underGit = /^y(es)?$/i.test(deps.ask('  Keep .claude/memory/ under git? [y/N] ')?.trim() ?? '');
+  }
+  const done = fixMemory(projectRoot, state, ctx, { personal, underGit, today: deps.today });
+  if (done.length && (state.kind === 'outside' || state.kind === 'moved')) {
+    done.push('sessions of this project running now keep the old place until they restart');
+  }
+  return done;
+}