@memstack/cli 0.7.3 → 0.8.0

package/dist/cli.js

@@ -1,58 +1,246 @@
 #!/usr/bin/env node
 import { parseArgs } from 'util';
 import { readFile, writeFile } from 'fs/promises';
-import { MemStack, AnthropicLLMAdapter, OpenAILLMAdapter, OpenAIEmbeddingAdapter, RedisStorageAdapter, SQLiteStorageAdapter, PostgresStorageAdapter, DiskStorageAdapter, MarkdownStorageAdapter, InMemoryStorageAdapter } from '@memstack/core';
+import { MemStack, HarnessMemory, projectNamespace, defaultRecallNamespaces, AnthropicLLMAdapter, OpenAILLMAdapter, OpenAIEmbeddingAdapter, RedisStorageAdapter, SQLiteStorageAdapter, PostgresStorageAdapter, DiskStorageAdapter, MarkdownStorageAdapter, InMemoryStorageAdapter } from '@memstack/core';
+import { existsSync, mkdirSync, realpathSync, readFileSync, writeFileSync, statSync, chmodSync, renameSync, rmSync, copyFileSync, constants } from 'fs';
+import { homedir } from 'os';
+import { join, resolve, delimiter, dirname, basename } from 'path';
+import { execFile, spawn, execFileSync } from 'child_process';
+import { createHash } from 'crypto';
+import { createInterface } from 'readline/promises';
 
-function buildLLMAdapter() {
-  if (!process.env.ANTHROPIC_API_KEY && !process.env.OPENAI_API_KEY) {
+var STORAGE_TYPES = ["memory", "markdown", "disk", "postgres", "sqlite", "redis"];
+function memstackHome() {
+  return process.env.MEMSTACK_HOME ?? join(homedir(), ".memstack");
+}
+function configFilePath(home = memstackHome()) {
+  return join(home, "config.json");
+}
+function readConfigFile(path = configFilePath()) {
+  if (!existsSync(path)) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(`${path} is not valid JSON: ${error.message}`);
+  }
+  return validateConfigFile(parsed, path);
+}
+function writeConfigFile(config, path = configFilePath()) {
+  validateConfigFile(config, path);
+  const dir = join(path, "..");
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  chmodSync(dir, 448);
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(config, null, 2)}
+`, { mode: 384 });
+  chmodSync(tmp, 384);
+  renameSync(tmp, path);
+}
+function checkConfigPermissions(path = configFilePath()) {
+  if (process.platform === "win32" || !existsSync(path)) return [];
+  const warnings = [];
+  const fileMode = statSync(path).mode & 511;
+  if (fileMode & 63) {
+    warnings.push(`${path} is readable by other users (mode ${fileMode.toString(8)}). Run: chmod 600 ${path}`);
+  }
+  const dir = join(path, "..");
+  const dirMode = statSync(dir).mode & 511;
+  if (dirMode & 63) {
+    warnings.push(`${dir} is accessible by other users (mode ${dirMode.toString(8)}). Run: chmod 700 ${dir}`);
+  }
+  return warnings;
+}
+function validateConfigFile(value, path) {
+  const fail2 = (message) => {
+    throw new Error(`Invalid ${path}: ${message}`);
+  };
+  if (!isObject(value)) fail2("expected a JSON object");
+  const config = value;
+  if (config.version !== 1) fail2(`unsupported version ${JSON.stringify(config.version)}, expected 1`);
+  if (config.llm !== void 0) {
+    if (!isObject(config.llm)) fail2("llm must be an object");
+    const llm = config.llm;
+    if (llm.provider !== "openai-compatible" && llm.provider !== "anthropic") {
+      fail2('llm.provider must be "openai-compatible" or "anthropic"');
+    }
+    if (typeof llm.apiKey !== "string" || !llm.apiKey) fail2("llm.apiKey must be a non-empty string");
+    for (const key of ["baseURL", "model"]) {
+      if (llm[key] !== void 0 && typeof llm[key] !== "string") fail2(`llm.${key} must be a string`);
+    }
+  }
+  if (config.storage !== void 0) {
+    if (!isObject(config.storage)) fail2("storage must be an object");
+    const storage = config.storage;
+    if (!STORAGE_TYPES.includes(storage.type)) {
+      fail2(`storage.type must be one of ${STORAGE_TYPES.join(", ")}`);
+    }
+    for (const key of ["path", "url"]) {
+      if (storage[key] !== void 0 && typeof storage[key] !== "string") fail2(`storage.${key} must be a string`);
+    }
+  }
+  return config;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var PIN_FILE = ".memstack.json";
+var PIN_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+function resolveProject(cwd = process.cwd()) {
+  const dir = realpathSync(resolve(cwd));
+  const root = git(dir, ["rev-parse", "--show-toplevel"]);
+  const base = root ?? dir;
+  const pinned = readPin(base);
+  const fallbacks = transitionalIds(dir, root);
+  if (pinned) return { id: pinned, source: "pin", key: pinned, root: base, previousIds: [] };
+  if (!root) return { ...identity("directory", dir), root: dir, previousIds: [] };
+  const shallow = git(root, ["rev-parse", "--is-shallow-repository"]) === "true";
+  const rootCommit = shallow ? null : firstCommit(root);
+  if (rootCommit) return { ...identity("root-commit", rootCommit), root, previousIds: fallbacks };
+  const remote = git(root, ["config", "--get", "remote.origin.url"]);
+  const normalized = shallow && remote ? normalizeRemote(remote) : null;
+  if (normalized) return { ...identity("remote", normalized), root, previousIds: fallbacks };
+  const gitId = identity("git", gitRepoKey(root));
+  return { ...gitId, root, previousIds: fallbacks.filter((id) => id !== gitId.id) };
+}
+function pinProject(name, cwd = process.cwd()) {
+  if (!PIN_PATTERN.test(name)) {
+    throw new Error("A pinned project ID uses letters, digits, '.', '_', or '-', starts with a letter or digit, and is at most 64 characters.");
+  }
+  const dir = realpathSync(resolve(cwd));
+  const base = git(dir, ["rev-parse", "--show-toplevel"]) ?? dir;
+  const path = join(base, PIN_FILE);
+  const existing = existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {};
+  writeFileSync(path, `${JSON.stringify({ ...existing, project: name }, null, 2)}
+`);
+  return path;
+}
+function normalizeRemote(url) {
+  const value = url.trim();
+  if (!value) return null;
+  let host;
+  let path;
+  const scp = value.match(/^(?:[^@/]+@)?([^:/]+):(?!\/)(.+)$/);
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value)) {
+    let parsed;
+    try {
+      parsed = new URL(value);
+    } catch {
+      return null;
+    }
+    if (parsed.protocol === "file:" || !parsed.hostname) return null;
+    host = parsed.hostname;
+    path = decodeURIComponent(parsed.pathname);
+  } else if (scp) {
+    host = scp[1];
+    path = scp[2];
+  } else {
+    return null;
+  }
+  path = path.replace(/^\/+|\/+$/g, "").replace(/\.git$/i, "");
+  if (!path) return null;
+  return `${host.toLowerCase()}/${path}`;
+}
+function readPin(base) {
+  const path = join(base, PIN_FILE);
+  if (!existsSync(path)) return null;
+  let project;
+  try {
+    project = JSON.parse(readFileSync(path, "utf8")).project;
+  } catch (error) {
+    throw new Error(`${path} is not valid JSON: ${error.message}`);
+  }
+  if (project === void 0) return null;
+  if (typeof project !== "string" || !PIN_PATTERN.test(project)) {
+    throw new Error(`${path}: "project" must use letters, digits, '.', '_', or '-' and be at most 64 characters.`);
+  }
+  return project;
+}
+function firstCommit(root) {
+  const out2 = git(root, ["rev-list", "--max-parents=0", "--first-parent", "HEAD"]);
+  return out2 ? out2.split("\n").pop().trim() : null;
+}
+function gitRepoKey(root) {
+  const commonDir = git(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+  return commonDir ? dirname(realpathSync(commonDir)) : root;
+}
+function transitionalIds(dir, root) {
+  const ids = /* @__PURE__ */ new Set();
+  if (root) ids.add(identity("git", gitRepoKey(root)).id);
+  ids.add(identity("directory", dir).id);
+  return [...ids];
+}
+function identity(source, key) {
+  const id = createHash("sha256").update(`${source}:${key}`).digest("hex").slice(0, 16);
+  return { id, source, key };
+}
+function git(cwd, args) {
+  try {
+    const out2 = execFileSync("git", ["-C", cwd, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5e3
+    }).trim();
+    return out2 || null;
+  } catch {
+    return null;
+  }
+}
+function isMissingModule(error) {
+  const code = error?.code;
+  return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+function buildLLMAdapter(env) {
+  if (!env.ANTHROPIC_API_KEY && !env.OPENAI_API_KEY) {
     throw new Error("At least one of OPENAI_API_KEY or ANTHROPIC_API_KEY must be set");
   }
-  if (process.env.ANTHROPIC_API_KEY) {
-    return new AnthropicLLMAdapter({ apiKey: process.env.ANTHROPIC_API_KEY });
+  if (env.ANTHROPIC_API_KEY) {
+    return new AnthropicLLMAdapter({ apiKey: env.ANTHROPIC_API_KEY, defaultModel: env.MEMSTACK_LLM_MODEL });
   }
   return new OpenAILLMAdapter({
-    apiKey: process.env.OPENAI_API_KEY ?? "",
-    baseURL: process.env.MEMSTACK_OPENAI_BASE_URL,
-    defaultModel: process.env.MEMSTACK_LLM_MODEL
+    apiKey: env.OPENAI_API_KEY ?? "",
+    baseURL: env.MEMSTACK_OPENAI_BASE_URL,
+    defaultModel: env.MEMSTACK_LLM_MODEL
   });
 }
-function buildEmbeddingAdapter() {
-  if (process.env.MEMSTACK_OPENAI_BASE_URL) return void 0;
-  if (process.env.OPENAI_API_KEY) {
-    return new OpenAIEmbeddingAdapter({ apiKey: process.env.OPENAI_API_KEY });
+function buildEmbeddingAdapter(env) {
+  if (env.MEMSTACK_OPENAI_BASE_URL) return void 0;
+  if (env.OPENAI_API_KEY) {
+    return new OpenAIEmbeddingAdapter({ apiKey: env.OPENAI_API_KEY });
   }
   return void 0;
 }
-async function buildStorageAdapter() {
-  const storage = process.env.MEMSTACK_STORAGE ?? "memory";
+async function buildStorageAdapter(env) {
+  const storage = env.MEMSTACK_STORAGE ?? "memory";
   switch (storage) {
     case "memory":
       return new InMemoryStorageAdapter();
     case "markdown":
       return new MarkdownStorageAdapter({
-        dir: process.env.MEMSTACK_DIR ?? "./memories"
+        dir: env.MEMSTACK_DIR ?? "./memories"
       });
     case "disk":
       return new DiskStorageAdapter({
-        storageDir: process.env.MEMSTACK_DIR ?? "./memstack-data"
+        storageDir: env.MEMSTACK_DIR ?? "./memstack-data"
       });
     case "postgres":
-      if (!process.env.DATABASE_URL) {
+      if (!env.DATABASE_URL) {
         throw new Error("postgres storage requires DATABASE_URL");
       }
       return new PostgresStorageAdapter({
-        connectionString: process.env.DATABASE_URL
+        connectionString: env.DATABASE_URL
       });
     case "sqlite": {
       try {
         const BetterSqlite3 = await import('better-sqlite3');
         const db = new BetterSqlite3.default(
-          process.env.SQLITE_PATH ?? "./memstack.db"
+          env.SQLITE_PATH ?? "./memstack.db"
         );
         return new SQLiteStorageAdapter({ db });
-      } catch {
+      } catch (error) {
+        if (!isMissingModule(error)) throw error;
         throw new Error(
-          "SQLite requires better-sqlite3. Install: npm install better-sqlite3"
+          "SQLite requires better-sqlite3. Install: npm install better-sqlite3@^11.10.0"
         );
       }
     }
@@ -60,12 +248,13 @@ async function buildStorageAdapter() {
       try {
         const Redis = await import('ioredis');
         const client = new Redis.default(
-          process.env.REDIS_URL ?? "redis://localhost:6379"
+          env.REDIS_URL ?? "redis://localhost:6379"
         );
         return new RedisStorageAdapter({ redis: client });
-      } catch {
+      } catch (error) {
+        if (!isMissingModule(error)) throw error;
         throw new Error(
-          "Redis requires ioredis. Install: npm install ioredis"
+          "Redis requires ioredis. Install: npm install ioredis@^5.11.1"
         );
       }
     }
@@ -74,11 +263,39 @@ async function buildStorageAdapter() {
   }
 }
 async function loadConfigFromEnv() {
-  const llm = buildLLMAdapter();
-  const embedding = buildEmbeddingAdapter();
-  const storage = await buildStorageAdapter();
-  const embedOnStore = process.env.MEMSTACK_EMBED_ON_STORE !== "false";
-  const defaultActorId = process.env.MEMSTACK_ACTOR ?? "default";
+  return buildConfig(process.env);
+}
+async function loadConfig(options = {}) {
+  return buildConfig(mergeConfigFile(readConfigFile(options.configPath), process.env));
+}
+function mergeConfigFile(file, env) {
+  const merged = { ...env };
+  const envHasLLM = LLM_ENV.some((key) => env[key] !== void 0);
+  if (file?.llm && !envHasLLM) {
+    if (file.llm.provider === "anthropic") merged.ANTHROPIC_API_KEY = file.llm.apiKey;
+    else {
+      merged.OPENAI_API_KEY = file.llm.apiKey;
+      merged.MEMSTACK_OPENAI_BASE_URL = file.llm.baseURL;
+    }
+    merged.MEMSTACK_LLM_MODEL = file.llm.model;
+  }
+  if (file?.storage && env.MEMSTACK_STORAGE === void 0) {
+    const { type, path, url } = file.storage;
+    merged.MEMSTACK_STORAGE = type;
+    if (type === "sqlite") merged.SQLITE_PATH = path;
+    if (type === "disk" || type === "markdown") merged.MEMSTACK_DIR = path;
+    if (type === "postgres") merged.DATABASE_URL = url;
+    if (type === "redis") merged.REDIS_URL = url;
+  }
+  return merged;
+}
+var LLM_ENV = ["OPENAI_API_KEY", "ANTHROPIC_API_KEY", "MEMSTACK_OPENAI_BASE_URL", "MEMSTACK_LLM_MODEL"];
+async function buildConfig(env) {
+  const llm = buildLLMAdapter(env);
+  const embedding = buildEmbeddingAdapter(env);
+  const storage = await buildStorageAdapter(env);
+  const embedOnStore = env.MEMSTACK_EMBED_ON_STORE !== "false";
+  const defaultActorId = env.MEMSTACK_ACTOR ?? "default";
   return {
     config: { llm, embedding, storage, defaults: { embedOnStore } },
     defaultActorId
@@ -86,12 +303,935 @@ async function loadConfigFromEnv() {
 }
 
 // src/config.ts
-async function loadConfig() {
+async function loadConfig2() {
   const { config } = await loadConfigFromEnv();
   return config;
 }
+var createRunner = (env = process.env) => (command, args) => new Promise((resolve2) => {
+  execFile(command, args, { env, timeout: 6e4, maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
+    if (!error) return resolve2({ code: 0, stdout, stderr });
+    const code = error.code === "ENOENT" ? 127 : typeof error.code === "number" ? error.code : 1;
+    resolve2({ code, stdout, stderr: stderr || error.message });
+  });
+});
+var run = createRunner();
+
+// src/harness/types.ts
+var SERVER_NAME = "memstack";
+function sameLaunch(a, b) {
+  if (!a || !b) return a === b;
+  return a.command === b.command && JSON.stringify(a.args) === JSON.stringify(b.args) && JSON.stringify(a.env ?? {}) === JSON.stringify(b.env ?? {});
+}
+
+// src/harness/claude-code.ts
+function claudeCodeAdapter(options = {}) {
+  const env = options.env ?? process.env;
+  const runner = options.runner ?? createRunner(env);
+  const binary = "claude";
+  const configPath = join(env.CLAUDE_CONFIG_DIR ?? homedir(), ".claude.json");
+  const settingsPath = env.CLAUDE_CONFIG_DIR ? join(env.CLAUDE_CONFIG_DIR, "settings.json") : join(homedir(), ".claude", "settings.json");
+  return {
+    id: "claude-code",
+    displayName: "Claude Code",
+    binary,
+    // Also on clear and compact, so the memories survive /clear and context compaction.
+    sessionHook: { path: settingsPath, matcher: "startup|resume|clear|compact" },
+    async inspect() {
+      const version = await runner(binary, ["--version"]);
+      const state = { installed: version.code === 0, configPath };
+      if (state.installed) state.version = version.stdout.trim().split(/\s+/)[0];
+      state.entry = readEntry(configPath);
+      return state;
+    },
+    addSteps(launch) {
+      const json = JSON.stringify({ type: "stdio", command: launch.command, args: launch.args, ...launch.env ? { env: launch.env } : {} });
+      return [{ command: binary, args: ["mcp", "add-json", "-s", "user", SERVER_NAME, json] }];
+    },
+    removeSteps() {
+      return [{ command: binary, args: ["mcp", "remove", "-s", "user", SERVER_NAME] }];
+    }
+  };
+}
+function readEntry(configPath) {
+  if (!existsSync(configPath)) return void 0;
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch (error) {
+    throw new Error(`Could not read ${configPath}: ${error.message}`);
+  }
+  const entry = config.mcpServers?.[SERVER_NAME];
+  if (!entry || typeof entry.command !== "string") return void 0;
+  return {
+    command: entry.command,
+    args: Array.isArray(entry.args) ? entry.args.map(String) : [],
+    ...entry.env && typeof entry.env === "object" ? { env: entry.env } : {}
+  };
+}
+function writeFileAtomic(path, content) {
+  if (content === null) {
+    rmSync(path, { force: true });
+    return;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  const mode = existsSync(path) ? statSync(path).mode & 511 : 420;
+  const tmp = `${path}.memstack-${process.pid}.tmp`;
+  writeFileSync(tmp, content, { mode });
+  renameSync(tmp, path);
+}
+function backupFile(path, backupDir) {
+  mkdirSync(backupDir, { recursive: true, mode: 448 });
+  const base = join(backupDir, `${basename(path)}.${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`);
+  for (let n = 0; ; n++) {
+    try {
+      copyFileSync(path, n === 0 ? base : `${base}-${n}`, constants.COPYFILE_EXCL);
+      return;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+    }
+  }
+}
+function snapshot(path) {
+  return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+
+// src/harness/instructions.ts
+var BEGIN = "<!-- memstack:begin";
+var END = "<!-- memstack:end -->";
+var BLOCK_PATTERN = /\n?<!-- memstack:begin[^\n]*-->\n[\s\S]*?<!-- memstack:end -->\n?/;
+var CODEX_INSTRUCTIONS = [
+  "## Project memory (MemStack)",
+  "",
+  "When the user asks you to remember something, save it with the memstack `memory_store` tool. Do not only acknowledge it, and do not write it into project files unless the user asks for a file change.",
+  "Before answering questions about this project's conventions, decisions, or the user's preferences, check `memory_retrieve`."
+].join("\n");
+function renderBlock(body, harness) {
+  return `${BEGIN} (managed by \`memstack connect ${harness}\`; removed by \`memstack disconnect ${harness}\`) -->
+${body}
+${END}
+`;
+}
+function readBlock(path) {
+  if (!existsSync(path)) return null;
+  const match = readFileSync(path, "utf8").match(BLOCK_PATTERN);
+  return match ? match[0].replace(/^\n/, "") : null;
+}
+function upsertBlock(path, block, backupDir) {
+  const current = existsSync(path) ? readFileSync(path, "utf8") : null;
+  if (current !== null && readBlock(path) === block) return false;
+  let next;
+  if (current === null || current.trim() === "") next = block;
+  else if (BLOCK_PATTERN.test(current)) next = current.replace(BLOCK_PATTERN, (m) => `${m.startsWith("\n") ? "\n" : ""}${block}`);
+  else next = `${current}${current.endsWith("\n") ? "" : "\n"}
+${block}`;
+  write(path, next, current, backupDir);
+  return true;
+}
+function removeBlock(path, backupDir) {
+  if (!existsSync(path)) return false;
+  const current = readFileSync(path, "utf8");
+  if (!BLOCK_PATTERN.test(current)) return false;
+  const next = current.replace(BLOCK_PATTERN, "");
+  if (next.trim() === "") {
+    backupFile(path, backupDir);
+    rmSync(path);
+  } else {
+    write(path, next, current, backupDir);
+  }
+  return true;
+}
+function write(path, content, previous, backupDir) {
+  if (previous !== null) backupFile(path, backupDir);
+  writeFileAtomic(path, content);
+}
+
+// src/harness/codex.ts
+function codexAdapter(options = {}) {
+  const env = options.env ?? process.env;
+  const runner = options.runner ?? createRunner(env);
+  const binary = "codex";
+  const home = env.CODEX_HOME ?? join(homedir(), ".codex");
+  const configPath = join(home, "config.toml");
+  return {
+    id: "codex",
+    displayName: "Codex",
+    binary,
+    // Codex gives MCP server instructions little weight, so without this it
+    // acknowledges "remember that..." instead of calling memory_store.
+    instructions: { path: join(home, "AGENTS.md"), body: CODEX_INSTRUCTIONS },
+    sessionHook: { path: join(home, "hooks.json"), matcher: "startup|resume" },
+    async inspect() {
+      const version = await runner(binary, ["--version"]);
+      const state = { installed: version.code === 0, configPath };
+      if (!state.installed) return state;
+      state.version = version.stdout.trim().split(/\s+/).pop();
+      const got = await runner(binary, ["mcp", "get", SERVER_NAME, "--json"]);
+      if (got.code !== 0) {
+        if (/No MCP server named/i.test(got.stderr + got.stdout)) return state;
+        throw new Error(`codex mcp get failed: ${(got.stderr || got.stdout).trim()}`);
+      }
+      const transport = JSON.parse(got.stdout).transport;
+      if (transport && typeof transport.command === "string") {
+        state.entry = {
+          command: transport.command,
+          args: Array.isArray(transport.args) ? transport.args.map(String) : [],
+          ...transport.env && typeof transport.env === "object" && Object.keys(transport.env).length > 0 ? { env: transport.env } : {}
+        };
+      }
+      return state;
+    },
+    addSteps(launch) {
+      const envFlags = Object.entries(launch.env ?? {}).flatMap(([key, value]) => ["--env", `${key}=${value}`]);
+      return [{ command: binary, args: ["mcp", "add", SERVER_NAME, ...envFlags, "--", launch.command, ...launch.args] }];
+    },
+    removeSteps() {
+      return [{ command: binary, args: ["mcp", "remove", SERVER_NAME] }];
+    }
+  };
+}
+var OURS = /\bhook session-start --harness (claude-code|codex)\b/;
+function sessionStartHook(launch, harness) {
+  const script = launch.args[0]?.endsWith(".js") ? [launch.args[0]] : [];
+  const parts = [launch.command, ...script].map(shellQuote);
+  return {
+    type: "command",
+    command: `${parts.join(" ")} hook session-start --harness ${harness}`,
+    timeout: 10,
+    statusMessage: "Loading MemStack project memory"
+  };
+}
+function readHook(path) {
+  const file = read(path);
+  for (const group of file?.hooks?.SessionStart ?? []) {
+    for (const hook of group.hooks ?? []) {
+      if (typeof hook.command === "string" && OURS.test(hook.command)) return hook;
+    }
+  }
+  return null;
+}
+function upsertHook(path, hook, matcher, backupDir) {
+  const file = read(path) ?? {};
+  const current = readHook(path);
+  if (current && JSON.stringify(current) === JSON.stringify(hook) && ourGroups(file).every((g) => g.matcher === matcher)) return false;
+  const hooks = file.hooks ??= {};
+  hooks.SessionStart = [...withoutOurs(hooks.SessionStart ?? []), { matcher, hooks: [hook] }];
+  save(path, file, backupDir);
+  return true;
+}
+function removeHook(path, backupDir) {
+  const file = read(path);
+  if (!file || !readHook(path)) return false;
+  const remaining = withoutOurs(file.hooks.SessionStart ?? []);
+  if (remaining.length > 0) file.hooks.SessionStart = remaining;
+  else delete file.hooks.SessionStart;
+  if (Object.keys(file.hooks).length === 0) delete file.hooks;
+  save(path, file, backupDir);
+  return true;
+}
+function ourGroups(file) {
+  return (file.hooks?.SessionStart ?? []).filter((g) => (g.hooks ?? []).some((h) => typeof h.command === "string" && OURS.test(h.command)));
+}
+function withoutOurs(groups) {
+  return groups.map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !(typeof h.command === "string" && OURS.test(h.command))) })).filter((g, i) => g.hooks.length > 0 || (groups[i].hooks ?? []).length === 0);
+}
+function read(path) {
+  if (!existsSync(path)) return null;
+  const text = readFileSync(path, "utf8");
+  if (!text.trim()) return {};
+  try {
+    const parsed = JSON.parse(text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("expected a JSON object");
+    return parsed;
+  } catch (error) {
+    throw new Error(`${path} is not valid JSON, so MemStack left it unchanged: ${error.message}`);
+  }
+}
+function save(path, file, backupDir) {
+  const previous = existsSync(path) ? readFileSync(path, "utf8") : null;
+  if (previous !== null) backupFile(path, backupDir);
+  const indent = previous?.match(/^[ \t]+(?=")/m)?.[0] ?? "  ";
+  const newline = previous === null || previous.endsWith("\n") ? "\n" : "";
+  writeFileAtomic(path, Object.keys(file).length === 0 ? null : `${JSON.stringify(file, null, indent)}${newline}`);
+}
+function shellQuote(value) {
+  return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
+}
+var HARNESS_TOOLS = ["memory_store", "memory_retrieve", "memory_get", "memory_delete", "memory_stats"];
+var verifyServer = (launch, options = {}) => new Promise((resolve2) => {
+  const child = spawn(launch.command, launch.args, {
+    cwd: options.cwd,
+    env: { ...options.env ?? process.env, ...launch.env },
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  let stdout = "";
+  let stderr = "";
+  let settled = false;
+  const pending = /* @__PURE__ */ new Map();
+  const finish = (result) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    child.kill();
+    resolve2(result);
+  };
+  const timer = setTimeout(() => finish({ ok: false, error: `No response within 20 s. ${lastLine(stderr)}`.trim() }), 2e4);
+  child.on("error", (error) => finish({ ok: false, error: `Could not start ${launch.command}: ${error.message}` }));
+  child.on("exit", (code) => finish({ ok: false, error: `Server exited with code ${code}. ${lastLine(stderr)}`.trim() }));
+  child.stderr.on("data", (chunk) => stderr += chunk);
+  child.stdout.on("data", (chunk) => {
+    stdout += chunk;
+    let newline;
+    while ((newline = stdout.indexOf("\n")) >= 0) {
+      const line = stdout.slice(0, newline).trim();
+      stdout = stdout.slice(newline + 1);
+      if (!line) continue;
+      try {
+        const message = JSON.parse(line);
+        pending.get(message.id)?.(message);
+      } catch {
+      }
+    }
+  });
+  let nextId = 1;
+  const request = (method, params) => new Promise((reply) => {
+    const id = nextId++;
+    pending.set(id, reply);
+    child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}
+`);
+  });
+  void (async () => {
+    const init2 = await request("initialize", {
+      protocolVersion: "2025-06-18",
+      capabilities: {},
+      clientInfo: { name: "memstack-connect", version: "1" }
+    });
+    if (init2.error) return finish({ ok: false, error: init2.error.message });
+    child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })}
+`);
+    const list = await request("tools/list", {});
+    const names = (list.result?.tools ?? []).map((t) => t.name);
+    const missing = HARNESS_TOOLS.filter((t) => !names.includes(t));
+    if (missing.length > 0) return finish({ ok: false, error: `Server is missing harness tools: ${missing.join(", ")}` });
+    const stats = await request("tools/call", { name: "memory_stats", arguments: {} });
+    const result = stats.result;
+    const text = result?.content?.map((c) => c.text).join("\n") ?? stats.error?.message ?? "";
+    if (!result || result.isError) return finish({ ok: false, error: text || "memory_stats failed" });
+    finish({ ok: true, stats: text });
+  })();
+});
+function lastLine(text) {
+  return text.trim().split("\n").filter(Boolean).pop() ?? "";
+}
+
+// src/harness/connect.ts
+async function connectHarness({
+  adapter,
+  launch,
+  runner = run,
+  verify = verifyServer,
+  dryRun,
+  instructions = true,
+  hooks = true,
+  backupDir = join(memstackHome(), "backups")
+}) {
+  const state = await adapter.inspect();
+  if (!state.installed) throw new Error(`${adapter.displayName} is not installed: \`${adapter.binary}\` is not on PATH.`);
+  const alreadyConnected = sameLaunch(state.entry, launch);
+  const plan = {
+    harness: adapter.id,
+    previous: state.entry,
+    target: launch,
+    steps: alreadyConnected ? [] : [...state.entry ? adapter.removeSteps() : [], ...adapter.addSteps(launch)]
+  };
+  const block = adapter.instructions && instructions ? renderBlock(adapter.instructions.body, adapter.id) : void 0;
+  if (adapter.instructions && block) {
+    const current = readBlock(adapter.instructions.path);
+    plan.instructions = { path: adapter.instructions.path, change: current === null ? "add" : current === block ? "none" : "update" };
+  }
+  const hook = adapter.sessionHook && hooks ? sessionStartHook(launch, adapter.id) : void 0;
+  if (adapter.sessionHook && hook) {
+    const current = readHook(adapter.sessionHook.path);
+    plan.hook = { path: adapter.sessionHook.path, change: current === null ? "add" : JSON.stringify(current) === JSON.stringify(hook) ? "none" : "update" };
+  }
+  const verification = await verify(launch);
+  if (!verification.ok) {
+    throw new Error(`MemStack's MCP server did not start correctly, so ${adapter.displayName} was not changed: ${verification.error}`);
+  }
+  if (dryRun) return { plan, changed: false, verification };
+  const undo = [];
+  let changed = false;
+  try {
+    if (!alreadyConnected) {
+      await applyWithRollback(adapter, plan, runner);
+      undo.push(() => restore(adapter, plan.previous, runner));
+      changed = true;
+    }
+    if (block && plan.instructions && plan.instructions.change !== "none") {
+      const path = plan.instructions.path;
+      const before = snapshot(path);
+      fileStep(path, () => upsertBlock(path, block, backupDir));
+      undo.push(async () => (writeFileAtomic(path, before), true));
+      changed = true;
+    }
+    if (hook && adapter.sessionHook && plan.hook && plan.hook.change !== "none") {
+      const path = plan.hook.path;
+      const before = snapshot(path);
+      const matcher = adapter.sessionHook.matcher;
+      fileStep(path, () => upsertHook(path, hook, matcher, backupDir));
+      undo.push(async () => (writeFileAtomic(path, before), true));
+      changed = true;
+    }
+  } catch (error) {
+    let restored = true;
+    for (const step of undo.reverse()) restored = await step().catch(() => false) && restored;
+    const message = error instanceof Error ? error.message : String(error);
+    if (/previous configuration/.test(message)) throw error;
+    throw new Error(`${message} ${restored ? "The previous configuration was restored." : "Restoring the previous configuration failed; run `memstack doctor`."}`);
+  }
+  return { plan, changed, verification };
+}
+async function disconnectHarness({
+  adapter,
+  runner = run,
+  dryRun,
+  backupDir = join(memstackHome(), "backups")
+}) {
+  const state = await adapter.inspect();
+  if (!state.installed) throw new Error(`${adapter.displayName} is not installed: \`${adapter.binary}\` is not on PATH.`);
+  const plan = { harness: adapter.id, previous: state.entry, steps: state.entry ? adapter.removeSteps() : [] };
+  if (adapter.instructions) {
+    plan.instructions = { path: adapter.instructions.path, change: readBlock(adapter.instructions.path) === null ? "none" : "remove" };
+  }
+  if (adapter.sessionHook) {
+    plan.hook = { path: adapter.sessionHook.path, change: readHook(adapter.sessionHook.path) === null ? "none" : "remove" };
+  }
+  if (dryRun) return { plan, changed: false };
+  let changed = false;
+  if (plan.steps.length > 0) {
+    await applyWithRollback(adapter, plan, runner);
+    changed = true;
+  }
+  if (plan.instructions?.change === "remove") changed = removeBlock(plan.instructions.path, backupDir) || changed;
+  if (plan.hook?.change === "remove") changed = removeHook(plan.hook.path, backupDir) || changed;
+  return { plan, changed };
+}
+async function applyWithRollback(adapter, plan, runner) {
+  try {
+    for (const step of plan.steps) await runStep(step, runner);
+    const after = await adapter.inspect();
+    if (!sameLaunch(after.entry, plan.target)) {
+      throw new Error(`${adapter.displayName} does not show the expected MemStack entry after the change.`);
+    }
+  } catch (error) {
+    const restored = await restore(adapter, plan.previous, runner);
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${message} ${restored ? "The previous configuration was restored." : "Restoring the previous configuration failed; run `memstack doctor`."}`);
+  }
+}
+async function restore(adapter, previous, runner) {
+  try {
+    const current = await adapter.inspect();
+    if (sameLaunch(current.entry, previous)) return true;
+    if (current.entry) for (const step of adapter.removeSteps()) await runStep(step, runner);
+    if (previous) for (const step of adapter.addSteps(previous)) await runStep(step, runner);
+    return sameLaunch((await adapter.inspect()).entry, previous);
+  } catch {
+    return false;
+  }
+}
+function fileStep(path, apply) {
+  try {
+    apply();
+  } catch (error) {
+    throw new Error(`Could not update ${path}: ${error.message}.`);
+  }
+}
+async function runStep(step, runner) {
+  const result = await runner(step.command, step.args);
+  if (result.code !== 0) {
+    throw new Error(`\`${step.command} ${step.args.slice(0, 3).join(" ")}\` failed: ${(result.stderr || result.stdout).trim()}`);
+  }
+}
+function describeStep(step) {
+  return [step.command, ...step.args.map((a) => /^[\w@%+=:,./-]+$/.test(a) ? a : `'${a.replace(/'/g, "'\\''")}'`)].join(" ");
+}
+var STORAGE_DRIVERS = {
+  sqlite: { module: "better-sqlite3", spec: "better-sqlite3@^11.10.0" },
+  postgres: { module: "postgres", spec: "postgres@^3.4.9" },
+  redis: { module: "ioredis", spec: "ioredis@^5.11.1" }
+};
+function installCommand(storage) {
+  const driver = storage ? STORAGE_DRIVERS[storage] : void 0;
+  return `npm install -g @memstack/mcp${driver ? ` ${driver.spec}` : ""}`;
+}
+function findMemstackMcp(env = process.env) {
+  const names = process.platform === "win32" ? ["memstack-mcp.cmd", "memstack-mcp"] : ["memstack-mcp"];
+  for (const dir of (env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    for (const name of names) {
+      const candidate = join(dir, name);
+      if (existsSync(candidate)) return realpathSync(candidate);
+    }
+  }
+  return null;
+}
+function canResolveFrom(scriptPath, module) {
+  let dir = dirname(scriptPath);
+  for (; ; ) {
+    if (existsSync(join(dir, "node_modules", module, "package.json"))) return true;
+    const parent = dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+}
+function harnessLaunch(mcpScript, harness) {
+  const isScript = /\.(c|m)?js$/.test(mcpScript);
+  const args = ["--profile", "harness", "--harness", harness];
+  return isScript ? { command: process.execPath, args: [mcpScript, ...args] } : { command: mcpScript, args };
+}
+
+// src/harness/index.ts
+var HARNESS_IDS = ["claude-code", "codex"];
+function harnessAdapter(id, options = {}) {
+  if (id === "claude-code") return claudeCodeAdapter(options);
+  if (id === "codex") return codexAdapter(options);
+  throw new Error(`Unknown harness "${id}". Supported: ${HARNESS_IDS.join(", ")}.`);
+}
+
+// src/harness-commands.ts
+var HARNESS_COMMANDS = ["init", "connect", "disconnect", "status", "doctor", "memories", "project"];
+var out = (line = "") => process.stdout.write(`${line}
+`);
+async function runHarnessCommand(command, args, flags) {
+  switch (command) {
+    case "init":
+      return init(flags);
+    case "connect":
+      return connect(args, flags);
+    case "disconnect":
+      return disconnect(args, flags);
+    case "status":
+      return status();
+    case "doctor":
+      return doctor(flags);
+    case "memories":
+      return memories(args, flags);
+    case "project":
+      return projectCommand(args);
+    default:
+      throw new Error(`Unknown command: ${command}`);
+  }
+}
+async function init(flags) {
+  const existing = readConfigFile();
+  const interactive = process.stdin.isTTY && !flags.yes;
+  const prompt = interactive ? createPrompter() : void 0;
+  try {
+    const provider = flags.provider ?? await prompt?.choose("LLM provider", ["openai-compatible", "anthropic"], existing?.llm?.provider ?? "openai-compatible") ?? existing?.llm?.provider ?? "openai-compatible";
+    if (provider !== "openai-compatible" && provider !== "anthropic") throw new Error('--provider must be "openai-compatible" or "anthropic"');
+    const sameProvider = existing?.llm?.provider === provider;
+    let baseURL;
+    if (provider === "openai-compatible") {
+      baseURL = flags["base-url"] ?? await prompt?.ask("Base URL (empty for OpenAI)", sameProvider ? existing?.llm?.baseURL ?? "" : "") ?? (sameProvider ? existing?.llm?.baseURL : void 0);
+      baseURL = baseURL || void 0;
+    }
+    const model = flags.model ?? await prompt?.ask("Model (empty for the provider default)", sameProvider ? existing?.llm?.model ?? "" : "") ?? (sameProvider ? existing?.llm?.model : void 0);
+    let apiKey;
+    if (flags["api-key-env"]) {
+      apiKey = process.env[flags["api-key-env"]];
+      if (!apiKey) throw new Error(`Environment variable ${flags["api-key-env"]} is empty.`);
+    } else if (prompt) {
+      apiKey = await prompt.secret(sameProvider && existing?.llm?.apiKey ? "API key (empty to keep the current one)" : "API key") || (sameProvider ? existing?.llm?.apiKey : void 0);
+    } else if (sameProvider) {
+      apiKey = existing?.llm?.apiKey;
+    }
+    if (!apiKey) throw new Error("An API key is required. Pass --api-key-env <VAR> to read it from an environment variable.");
+    const store = flags.store ?? await prompt?.choose("Storage", [...STORAGE_TYPES], existing?.storage?.type ?? "sqlite") ?? existing?.storage?.type ?? "sqlite";
+    if (!STORAGE_TYPES.includes(store)) throw new Error(`--store must be one of ${STORAGE_TYPES.join(", ")}`);
+    const storage = await storageSettings(store, flags, existing, prompt);
+    const llm = { provider, apiKey, ...baseURL ? { baseURL } : {}, ...model ? { model } : {} };
+    out("Checking the LLM provider with a test request...");
+    await checkLLM(buildLLM(llm));
+    out("  \u2713 The provider answered.");
+    const config = { version: 1, llm, storage };
+    if (storage.type === "sqlite" && storage.path) mkdirSync(join(storage.path, ".."), { recursive: true, mode: 448 });
+    writeConfigFile(config);
+    out(`Saved ${configFilePath()} (readable only by you).`);
+    const mcp = findMemstackMcp();
+    const driver = STORAGE_DRIVERS[store];
+    out();
+    if (!mcp || driver && !canResolveFrom(mcp, driver.module)) {
+      out("Next, install the MCP server and your storage driver (MemStack does not install them for you):");
+      out(`  ${installCommand(store)}`);
+    }
+    out("Then connect your agents:");
+    out("  memstack connect claude-code");
+    out("  memstack connect codex");
+    return 0;
+  } finally {
+    prompt?.close();
+  }
+}
+async function storageSettings(type, flags, existing, prompt) {
+  const previous = existing?.storage?.type === type ? existing.storage : void 0;
+  switch (type) {
+    case "sqlite":
+    case "disk":
+    case "markdown": {
+      const fallback = previous?.path ?? join(memstackHome(), type === "sqlite" ? "memstack.db" : type === "disk" ? "data" : "memories");
+      const path = flags.path ?? await prompt?.ask(type === "sqlite" ? "Database file" : "Directory", fallback) ?? fallback;
+      return { type, path };
+    }
+    case "postgres":
+    case "redis": {
+      const url = flags.url ?? await prompt?.ask(`${type === "postgres" ? "Postgres" : "Redis"} connection URL`, previous?.url ?? "") ?? previous?.url;
+      if (!url) throw new Error(`--url is required for ${type}.`);
+      return { type, url };
+    }
+    case "memory":
+      return { type };
+  }
+}
+function buildLLM(llm) {
+  return llm.provider === "anthropic" ? new AnthropicLLMAdapter({ apiKey: llm.apiKey, defaultModel: llm.model }) : new OpenAILLMAdapter({ apiKey: llm.apiKey, baseURL: llm.baseURL, defaultModel: llm.model });
+}
+async function checkLLM(llm) {
+  let text;
+  try {
+    ({ text } = await llm.complete({ system: "Reply with the single word OK.", user: "ping", maxTokens: 1024, temperature: 0 }));
+  } catch (error) {
+    throw new Error(`The LLM provider rejected the test request: ${error.message}`);
+  }
+  if (!text.trim()) throw new Error("The LLM provider returned an empty reply to the test request.");
+}
+async function connect(ids, flags) {
+  if (ids.length === 0) throw new Error(`Name a harness: memstack connect <${HARNESS_IDS.join("|")}>`);
+  const file = readConfigFile();
+  if (!file && !process.env.OPENAI_API_KEY && !process.env.ANTHROPIC_API_KEY) {
+    throw new Error("No MemStack configuration found. Run `memstack init` first.");
+  }
+  const mcp = findMemstackMcp();
+  if (!mcp) {
+    throw new Error(`memstack-mcp is not installed. MemStack does not install it for you; run:
+  ${installCommand(file?.storage?.type)}`);
+  }
+  for (const id of ids) {
+    const adapter = harnessAdapter(id);
+    const launch = harnessLaunch(mcp, adapter.id);
+    const result = await connectHarness({
+      adapter,
+      launch,
+      dryRun: flags["dry-run"],
+      instructions: !flags["no-agents-md"],
+      hooks: !flags["no-hooks"]
+    });
+    const instructions = result.plan.instructions;
+    const hook = result.plan.hook;
+    if (flags["dry-run"]) {
+      out(`${adapter.displayName}: the server works (${result.verification.stats}).`);
+      const pending = result.plan.steps.length > 0 || instructions && instructions.change !== "none" || hook && hook.change !== "none";
+      out(pending ? "Would run:" : "Already connected; nothing to change.");
+      for (const step of result.plan.steps) out(`  ${describeStep(step)}`);
+      if (instructions && instructions.change !== "none") {
+        out(`  ${instructions.change === "add" ? "add" : "update"} the marked MemStack block in ${instructions.path}:`);
+        for (const line of renderBlock(adapter.instructions.body, adapter.id).trimEnd().split("\n")) out(`    ${line}`);
+      }
+      if (hook && hook.change !== "none") {
+        out(`  ${hook.change} the MemStack session-start hook in ${hook.path}:`);
+        out(`    ${sessionStartHook(launch, adapter.id).command}`);
+      }
+    } else if (result.changed) {
+      out(`\u2713 Connected ${adapter.displayName}. ${result.verification.stats}`);
+      if (instructions && instructions.change !== "none") {
+        out(`  ${instructions.change === "add" ? "Added" : "Updated"} MemStack guidance in ${instructions.path} (between memstack:begin/end markers).`);
+      }
+      if (hook && hook.change !== "none") {
+        out(`  ${hook.change === "add" ? "Added" : "Updated"} a session-start hook in ${hook.path} that loads project memories.`);
+        if (adapter.id === "codex") out("  Codex runs new hooks only after you approve them: open Codex and run /hooks once.");
+      }
+      out(`  ${adapter.id === "claude-code" ? "Restart Claude Code" : "Start a new Codex session"} to load MemStack.`);
+    } else {
+      out(`\u2713 ${adapter.displayName} is already connected. ${result.verification.stats}`);
+    }
+  }
+  return 0;
+}
+async function disconnect(ids, flags) {
+  if (ids.length === 0) throw new Error(`Name a harness: memstack disconnect <${HARNESS_IDS.join("|")}>`);
+  for (const id of ids) {
+    const adapter = harnessAdapter(id);
+    const result = await disconnectHarness({ adapter, dryRun: flags["dry-run"] });
+    const removeBlock2 = result.plan.instructions?.change === "remove";
+    const removeHook2 = result.plan.hook?.change === "remove";
+    if (flags["dry-run"]) {
+      const pending = result.plan.steps.length > 0 || removeBlock2 || removeHook2;
+      out(pending ? `${adapter.displayName}: would run:` : `${adapter.displayName}: not connected; nothing to change.`);
+      for (const step of result.plan.steps) out(`  ${describeStep(step)}`);
+      if (removeBlock2) out(`  remove the marked MemStack block from ${result.plan.instructions.path}`);
+      if (removeHook2) out(`  remove the MemStack session-start hook from ${result.plan.hook.path}`);
+    } else {
+      out(result.changed ? `\u2713 Disconnected ${adapter.displayName}. Your memories are kept.` : `${adapter.displayName} was not connected.`);
+    }
+  }
+  return 0;
+}
+var label = (name) => (name ? `${name}:` : "").padEnd(14);
+async function status() {
+  const file = readConfigFile();
+  out(`${label("Config")}${file ? configFilePath() : "none (run `memstack init`)"}`);
+  if (file?.llm) out(`${label("LLM")}${file.llm.provider}${file.llm.model ? ` (${file.llm.model})` : ""}${file.llm.baseURL ? ` at ${file.llm.baseURL}` : ""}`);
+  if (file?.storage) out(`${label("Storage")}${file.storage.type}${file.storage.path ? ` at ${file.storage.path}` : file.storage.url ? " (URL configured)" : ""}`);
+  const project = resolveProject();
+  out(`${label("Project")}${project.id} (${describeSource(project.source)}: ${project.key})`);
+  const mcp = findMemstackMcp();
+  out(`${label("Server")}${mcp ?? "memstack-mcp not installed"}`);
+  for (const id of HARNESS_IDS) {
+    const adapter = harnessAdapter(id);
+    const state = await adapter.inspect();
+    let line;
+    if (!state.installed) line = "not installed";
+    else if (!state.entry) line = "not connected";
+    else if (!mcp) {
+      const present = [state.entry.command, ...state.entry.args.filter((a) => a.startsWith("/"))].every((p) => existsSync(p));
+      line = present ? "connected (memstack-mcp is not on PATH, so updates can't be checked)" : "connected to a command that no longer exists (run `memstack doctor`)";
+    } else if (sameLaunch(state.entry, harnessLaunch(mcp, adapter.id))) line = "connected";
+    else line = "connected with a different command (run `memstack connect` to update)";
+    out(`${label(adapter.displayName)}${line}`);
+    if (adapter.instructions && state.installed) {
+      const block = readBlock(adapter.instructions.path);
+      const current = block === renderBlock(adapter.instructions.body, adapter.id);
+      out(`${label("")}guidance in ${adapter.instructions.path}: ${block === null ? "none" : current ? "present" : "outdated (run `memstack connect`)"}`);
+    }
+    if (adapter.sessionHook && state.installed) {
+      out(`${label("")}session-start hook in ${adapter.sessionHook.path}: ${hookState(adapter, mcp)}`);
+    }
+  }
+  return 0;
+}
+function hookState(adapter, mcp) {
+  const current = readHook(adapter.sessionHook.path);
+  if (!current) return "missing";
+  if (mcp && JSON.stringify(current) !== JSON.stringify(sessionStartHook(harnessLaunch(mcp, adapter.id), adapter.id))) return "outdated";
+  return "present";
+}
+async function doctor(flags) {
+  let failures = 0;
+  const pass = (message) => out(`\u2713 ${message}`);
+  const warn = (message) => out(`! ${message}`);
+  const fail2 = (message) => {
+    failures++;
+    out(`\u2717 ${message}`);
+  };
+  let file;
+  try {
+    file = readConfigFile();
+    if (file) pass(`Config file ${configFilePath()}`);
+    else warn(`No config file at ${configFilePath()}; run \`memstack init\`.`);
+  } catch (error) {
+    fail2(error.message);
+  }
+  for (const warning of checkConfigPermissions()) warn(warning);
+  const env = mergeConfigFile(file, process.env);
+  if (env.OPENAI_API_KEY || env.ANTHROPIC_API_KEY) {
+    pass(`LLM key configured (${env.ANTHROPIC_API_KEY ? "anthropic" : "openai-compatible"}${env.MEMSTACK_LLM_MODEL ? `, ${env.MEMSTACK_LLM_MODEL}` : ""})`);
+    if (flags.live && file?.llm && !process.env.OPENAI_API_KEY && !process.env.ANTHROPIC_API_KEY) {
+      try {
+        await checkLLM(buildLLM(file.llm));
+        pass("LLM provider answered a test request");
+      } catch (error) {
+        fail2(error.message);
+      }
+    }
+  } else {
+    fail2("No LLM key. Run `memstack init`.");
+  }
+  const storageType = env.MEMSTACK_STORAGE ?? "memory";
+  if (storageType === "memory") warn("Storage is in-memory: memories are lost when a session ends. Run `memstack init` to choose a store.");
+  else pass(`Storage: ${storageType}`);
+  const mcp = findMemstackMcp();
+  if (!mcp) {
+    fail2(`memstack-mcp is not installed. Run: ${installCommand(storageType)}`);
+  } else {
+    pass(`memstack-mcp at ${mcp}`);
+    const driver = STORAGE_DRIVERS[storageType];
+    if (driver) {
+      if (canResolveFrom(mcp, driver.module)) pass(`Storage driver ${driver.module} is installed`);
+      else fail2(`Storage driver ${driver.module} is not installed next to memstack-mcp. Run: npm install -g ${driver.spec}`);
+    }
+  }
+  const project = resolveProject();
+  pass(`Project ${project.id} (${describeSource(project.source)}: ${project.key})`);
+  for (const id of HARNESS_IDS) {
+    const adapter = harnessAdapter(id);
+    let state;
+    try {
+      state = await adapter.inspect();
+    } catch (error) {
+      fail2(`${adapter.displayName}: ${error.message}`);
+      continue;
+    }
+    if (!state.installed) {
+      out(`- ${adapter.displayName} is not installed`);
+      continue;
+    }
+    if (!state.entry) {
+      warn(`${adapter.displayName} is not connected. Run: memstack connect ${id}`);
+      continue;
+    }
+    const missing = [state.entry.command, ...state.entry.args.filter((a) => a.startsWith("/"))].filter((p) => !existsSync(p));
+    if (missing.length > 0) fail2(`${adapter.displayName} points at ${missing.join(", ")}, which no longer exists. Run: memstack connect ${id}`);
+    else if (mcp && !sameLaunch(state.entry, harnessLaunch(mcp, adapter.id))) warn(`${adapter.displayName} uses a different MemStack command. Run: memstack connect ${id}`);
+    else pass(`${adapter.displayName} is connected`);
+    if (adapter.instructions) {
+      const block = readBlock(adapter.instructions.path);
+      if (block === null) warn(`${adapter.displayName} has no MemStack guidance in ${adapter.instructions.path}, so it may not save memories when asked. Run: memstack connect ${id}`);
+      else if (block !== renderBlock(adapter.instructions.body, adapter.id)) warn(`MemStack guidance in ${adapter.instructions.path} is outdated. Run: memstack connect ${id}`);
+      else pass(`${adapter.displayName} guidance in ${adapter.instructions.path}`);
+    }
+    if (adapter.sessionHook) {
+      const hookStatus = hookState(adapter, mcp);
+      if (hookStatus === "present") {
+        pass(`${adapter.displayName} session-start hook in ${adapter.sessionHook.path}${id === "codex" ? " (approve it once in Codex with /hooks)" : ""}`);
+      } else {
+        warn(`${adapter.displayName} session-start hook is ${hookStatus}. Run: memstack connect ${id}`);
+      }
+    }
+  }
+  if (mcp) {
+    const verification = await verifyServer(harnessLaunch(mcp, "claude-code"));
+    if (verification.ok) pass(`MCP server starts and answers: ${verification.stats}`);
+    else fail2(`MCP server check failed: ${verification.error}`);
+  }
+  out();
+  out(failures === 0 ? "No problems found." : `${failures} problem${failures === 1 ? "" : "s"} found.`);
+  return failures === 0 ? 0 : 1;
+}
+async function memories(args, flags) {
+  const { config } = await loadConfig();
+  if (!config.storage) throw new Error("No storage configured. Run `memstack init`.");
+  const project = resolveProject();
+  const namespaces = defaultRecallNamespaces(project.id);
+  const memory = new HarnessMemory({ storage: config.storage, llm: config.llm, autoTags: false });
+  try {
+    await memory.adoptProjects(project.previousIds, project.id);
+    if (flags.delete) {
+      await memory.forget(flags.delete, namespaces);
+      out(`Deleted ${flags.delete}.`);
+      return 0;
+    }
+    const query = args.join(" ").trim() || void 0;
+    const { hits, fallback } = await memory.recall({
+      namespaces: flags.global ? ["global"] : namespaces,
+      query,
+      limit: flags.limit ? Number(flags.limit) : 20,
+      maxChars: 5e4
+    });
+    out(`Project ${project.id} (${project.key})`);
+    if (hits.length === 0) {
+      out("No memories.");
+      return 0;
+    }
+    if (query && fallback) out(`Nothing matched "${query}". The most important memories instead:`);
+    for (const { memory: m } of hits) {
+      const source = m.metadata?.source?.harness;
+      const scope = m.actorId === "global" ? "global" : "project";
+      out(`${m.id}  ${m.memoryType}, ${scope}${source ? `, from ${source}` : ""}, ${m.createdAt.toISOString().slice(0, 10)}`);
+      out(`  ${m.content}`);
+    }
+    return 0;
+  } finally {
+    await config.storage.close();
+  }
+}
+async function projectCommand(args) {
+  const [sub, value] = args;
+  if (sub === "pin") {
+    if (!value) throw new Error("Name the project: memstack project pin <id>");
+    const before = resolveProject();
+    const path = pinProject(value);
+    out(`Pinned this repository to project "${value}" in ${path}. Commit it so every clone uses the same project.`);
+    if (before.id !== value) {
+      out(`Memories stored under the previous ID stay there. To move them: memstack project merge ${before.id}`);
+    }
+    return 0;
+  }
+  if (sub === "merge") {
+    if (!value) throw new Error("Name the old project ID: memstack project merge <old-id>");
+    const oldId = value.replace(/^project:/, "");
+    const project2 = resolveProject();
+    const { config } = await loadConfig();
+    if (!config.storage) throw new Error("No storage configured. Run `memstack init`.");
+    const memory = new HarnessMemory({ storage: config.storage, llm: config.llm, autoTags: false });
+    try {
+      const moved = await memory.moveNamespace(projectNamespace(oldId), projectNamespace(project2.id));
+      out(`Moved ${moved} ${moved === 1 ? "memory" : "memories"} from ${oldId} to ${project2.id}.`);
+    } finally {
+      await config.storage.close();
+    }
+    return 0;
+  }
+  if (sub) throw new Error(`Unknown subcommand "${sub}". Use: memstack project [pin <id> | merge <old-id>]`);
+  const project = resolveProject();
+  out(`${label("Project")}${project.id}`);
+  out(`${label("From")}${describeSource(project.source)}: ${project.key}`);
+  out(`${label("Root")}${project.root}`);
+  return 0;
+}
+function describeSource(source) {
+  switch (source) {
+    case "pin":
+      return `pinned in ${PIN_FILE}`;
+    case "root-commit":
+      return "first commit";
+    case "remote":
+      return "origin remote (shallow clone)";
+    case "git":
+      return "git directory (no commits yet)";
+    default:
+      return "directory";
+  }
+}
+function createPrompter() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+  let muted = false;
+  const output = rl;
+  const write2 = output._writeToOutput.bind(rl);
+  output._writeToOutput = (text) => {
+    if (!muted || text.includes("\n") || text.includes("\r")) write2(text);
+  };
+  return {
+    async ask(question, fallback) {
+      const answer = (await rl.question(`${question}${fallback ? ` [${fallback}]` : ""}: `)).trim();
+      return answer || fallback;
+    },
+    async choose(question, options, fallback) {
+      for (; ; ) {
+        const answer = (await rl.question(`${question} (${options.join(", ")}) [${fallback}]: `)).trim() || fallback;
+        if (options.includes(answer)) return answer;
+        out(`Choose one of: ${options.join(", ")}`);
+      }
+    },
+    async secret(question) {
+      const pending = rl.question(`${question}: `);
+      muted = true;
+      try {
+        return (await pending).trim();
+      } finally {
+        muted = false;
+        out();
+      }
+    },
+    close() {
+      rl.close();
+    }
+  };
+}
 
 // src/cli.ts
+process.stdout.on("error", (error) => {
+  if (error.code === "EPIPE") process.exit(0);
+  throw error;
+});
 async function main() {
   const { positionals, values } = parseArgs({
     allowPositionals: true,
@@ -115,7 +1255,20 @@ async function main() {
       "created-before": { type: "string" },
       "dry-run": { type: "boolean" },
       out: { type: "string" },
-      file: { type: "string" }
+      file: { type: "string" },
+      provider: { type: "string" },
+      "base-url": { type: "string" },
+      model: { type: "string" },
+      "api-key-env": { type: "string" },
+      store: { type: "string" },
+      path: { type: "string" },
+      url: { type: "string" },
+      yes: { type: "boolean" },
+      live: { type: "boolean" },
+      global: { type: "boolean" },
+      delete: { type: "string" },
+      "no-agents-md": { type: "boolean" },
+      "no-hooks": { type: "boolean" }
     }
   });
   const command = positionals[0];
@@ -123,7 +1276,11 @@ async function main() {
     printUsage();
     process.exit(1);
   }
-  const config = await loadConfig();
+  if (HARNESS_COMMANDS.includes(command)) {
+    process.exitCode = await runHarnessCommand(command, positionals.slice(1), values);
+    return;
+  }
+  const config = await loadConfig2();
   const ms = new MemStack(config);
   let result;
   switch (command) {
@@ -219,27 +1376,27 @@ async function main() {
       break;
     }
     case "export": {
-      const snapshot = await ms.export(values.actor);
+      const snapshot2 = await ms.export(values.actor);
       const outPath = values.out;
       if (outPath) {
-        await writeFile(outPath, JSON.stringify(snapshot, null, 2), "utf-8");
+        await writeFile(outPath, JSON.stringify(snapshot2, null, 2), "utf-8");
       }
-      result = outPath ? { saved: outPath, count: snapshot.memories.length } : snapshot;
+      result = outPath ? { saved: outPath, count: snapshot2.memories.length } : snapshot2;
       break;
     }
     case "import": {
       if (!values.actor) fail("--actor is required");
       if (!values.file) fail("--file is required");
       const raw = await readFile(String(values.file), "utf-8");
-      let snapshot = JSON.parse(raw);
-      if (Array.isArray(snapshot)) {
-        snapshot = { version: 1, memories: snapshot, exportedAt: (/* @__PURE__ */ new Date()).toISOString() };
+      let snapshot2 = JSON.parse(raw);
+      if (Array.isArray(snapshot2)) {
+        snapshot2 = { version: 1, memories: snapshot2, exportedAt: (/* @__PURE__ */ new Date()).toISOString() };
       }
-      if (!snapshot.memories || !Array.isArray(snapshot.memories) || snapshot.memories.length === 0) {
+      if (!snapshot2.memories || !Array.isArray(snapshot2.memories) || snapshot2.memories.length === 0) {
         fail("Snapshot contains no memories to import");
       }
-      await ms.import(snapshot);
-      result = { imported: snapshot.memories.length };
+      await ms.import(snapshot2);
+      result = { imported: snapshot2.memories.length };
       break;
     }
     default:
@@ -273,6 +1430,17 @@ function parseDuration(input) {
 function printUsage() {
   process.stderr.write(`memstack <command> [flags]
 
+Agent harnesses (Claude Code, Codex):
+  init        Choose an LLM provider and store; writes ~/.memstack/config.json
+  connect     Register MemStack with a harness: connect claude-code|codex [--dry-run]
+              Adds a session-start hook that loads project memories (skip with --no-hooks)
+              For Codex, also adds a marked block to ~/.codex/AGENTS.md (skip with --no-agents-md)
+  disconnect  Remove MemStack from a harness; memories are kept
+  status      Show configuration, project, and harness connections
+  doctor      Diagnose setup problems [--live to test the LLM key]
+  memories    List or search this project's memories [query] [--delete <id>]
+  project     Show this repository's project ID; project pin <id>; project merge <old-id>
+
 Commands:
   store       Store a memory
   retrieve    Retrieve memories