@aliyunrds/ctxdb 0.0.1

package/dist/cli/main.js

@@ -0,0 +1,1665 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_BASE_URL,
+  DEFAULT_USER_ID,
+  HttpClient,
+  NotFoundError,
+  SUPPORTED_AGENTS,
+  agentFromEnv,
+  agentHomeDir,
+  isAgent,
+  isComplete,
+  load,
+  removeAgent,
+  save
+} from "../chunk-L4YJ7LDI.js";
+
+// src/cli/util.ts
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
+  // universal
+  "json",
+  // setup / init
+  "no-install-skill",
+  "no-validate",
+  "remove",
+  // teardown
+  "purge-config",
+  "purge-logs",
+  "purge-all",
+  // memory
+  "no-infer",
+  // memory add
+  "knowledge",
+  // memory search
+  "all",
+  // memory delete
+  // kb
+  "no-wait",
+  // kb upload-text / upload-file
+  "raw"
+  // kb search / memory search --knowledge (W3 compaction bypass)
+]);
+function parseArgs(argv, booleanFlags = BOOLEAN_FLAGS) {
+  const positional = [];
+  const flags = {};
+  let separatorSeen = false;
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (separatorSeen) {
+      positional.push(tok);
+      continue;
+    }
+    if (tok === "--") {
+      separatorSeen = true;
+      continue;
+    }
+    if (tok.startsWith("--")) {
+      const eq = tok.indexOf("=");
+      if (eq > 0) {
+        const k = tok.slice(2, eq);
+        flags[k] = tok.slice(eq + 1);
+      } else {
+        const k = tok.slice(2);
+        if (booleanFlags.has(k)) {
+          flags[k] = true;
+        } else {
+          const next = argv[i + 1];
+          if (next !== void 0 && !next.startsWith("--")) {
+            flags[k] = next;
+            i++;
+          } else {
+            flags[k] = true;
+          }
+        }
+      }
+    } else {
+      positional.push(tok);
+    }
+  }
+  return { positional, flags };
+}
+function summarize(v) {
+  if (typeof v === "string") return v;
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}
+function printResult(value, json) {
+  if (json) {
+    process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+  } else {
+    process.stdout.write(summarize(value) + "\n");
+  }
+}
+function agentFromFlags(flags) {
+  const raw = flags.agent;
+  if (raw === void 0) return agentFromEnv();
+  if (isAgent(raw)) return raw;
+  fail(`unknown --agent: ${String(raw)} (expected one of ${SUPPORTED_AGENTS.join(" / ")})`, 2);
+}
+function buildContext(args) {
+  const agent = agentFromFlags(args?.flags ?? {});
+  const cfg = load({ agent });
+  if (!isComplete(cfg)) {
+    process.stderr.write(
+      `config incomplete for agent ${agent}: run \`ctxdb setup --agent ${agent}\` or set CTXDB_API_KEY / CTXDB_BASE_URL / CTXDB_USER_ID env vars
+`
+    );
+    process.exit(2);
+  }
+  const client = new HttpClient({
+    baseUrl: cfg.baseUrl,
+    apiKey: cfg.apiKey
+  });
+  return { cfg, client, agent };
+}
+function fail(message, code = 1) {
+  process.stderr.write(`${message}
+`);
+  process.exit(code);
+}
+var PACKAGE_VERSION = "0.0.1";
+
+// src/cli/top.ts
+import { homedir } from "os";
+import { join } from "path";
+async function init(args) {
+  const agent = agentFromFlags(args.flags);
+  const cfg = load({ agent });
+  if (typeof args.flags["api-key"] === "string") cfg.apiKey = args.flags["api-key"];
+  if (typeof args.flags["base-url"] === "string") {
+    cfg.baseUrl = args.flags["base-url"].replace(/\/+$/, "");
+  } else if (!cfg.baseUrl) {
+    cfg.baseUrl = DEFAULT_BASE_URL;
+  }
+  const cliUserId = typeof args.flags["user-id"] === "string" ? args.flags["user-id"] : void 0;
+  cfg.userId = cliUserId ?? cfg.userId ?? DEFAULT_USER_ID;
+  save(cfg, void 0, { agent });
+  let validated = false;
+  let pingError = null;
+  if (!args.flags["no-validate"] && cfg.apiKey) {
+    try {
+      const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
+      await client.get("/v1/ping/");
+      validated = true;
+    } catch (err) {
+      pingError = err?.message ?? String(err);
+    }
+  }
+  printResult(
+    {
+      ok: true,
+      config_path: join(homedir(), ".ctxdb", "ctxdb.json"),
+      agent,
+      api_key_set: Boolean(cfg.apiKey),
+      base_url: cfg.baseUrl,
+      user_id: cfg.userId,
+      validated,
+      ping_error: pingError
+    },
+    !!args.flags.json
+  );
+  return 0;
+}
+async function status(args) {
+  const agent = agentFromFlags(args.flags);
+  const cfg = load({ agent });
+  const complete = isComplete(cfg);
+  let connected = false;
+  let pingError = null;
+  if (complete) {
+    try {
+      const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
+      await client.get("/v1/ping/");
+      connected = true;
+    } catch (err) {
+      pingError = err?.message ?? String(err);
+    }
+  }
+  printResult(
+    {
+      ok: complete,
+      agent,
+      base_url: cfg.baseUrl,
+      user_id: cfg.userId,
+      api_key_set: Boolean(cfg.apiKey),
+      auto_capture: cfg.autoCapture,
+      auto_recall: cfg.autoRecall,
+      top_k: cfg.topK,
+      threshold: cfg.threshold,
+      knowledge_top_k: cfg.knowledgeTopK,
+      connected,
+      ping_error: pingError,
+      version: PACKAGE_VERSION
+    },
+    !!args.flags.json
+  );
+  return complete && connected ? 0 : 1;
+}
+async function ping(args) {
+  const agent = agentFromFlags(args.flags);
+  const cfg = load({ agent });
+  if (!isComplete(cfg)) {
+    fail(
+      `config incomplete for agent ${agent} \u2014 run \`ctxdb setup --agent ${agent}\` or set CTXDB_API_KEY / CTXDB_BASE_URL / CTXDB_USER_ID`
+    );
+  }
+  const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
+  const resp = await client.get("/v1/ping/");
+  printResult(resp, !!args.flags.json);
+  return 0;
+}
+
+// src/setup/installer.ts
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  copyFileSync,
+  chmodSync,
+  readdirSync,
+  rmSync,
+  rmdirSync,
+  unlinkSync,
+  statSync
+} from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2, dirname } from "path";
+import { fileURLToPath } from "url";
+var UNINSTALL_NPM_HINT = "To also remove the npm binaries: `npm uninstall -g @aliyunrds/ctxdb @aliyunrds/ctxdb-shared`";
+var UNINSTALL_ORDER_HINT = "When you eventually want to uninstall: run `ctxdb teardown --purge-all` FIRST, then `npm uninstall -g @aliyunrds/ctxdb @aliyunrds/ctxdb-shared`. (npm 7+ removed uninstall lifecycle hooks, so the order matters \u2014 otherwise agent settings.json hooks + ~/.ctxdb/ residue stay behind.)";
+function skillInstallRoot(agent) {
+  switch (agent) {
+    case "qoder":
+      return join2(homedir2(), ".qoder", "skills");
+    case "codex":
+      return join2(homedir2(), ".codex", "skills");
+    case "claude":
+      return join2(homedir2(), ".claude", "skills");
+  }
+}
+var SKILL_DIR_NAME = "ctxdb";
+function skillResourceDir(agent) {
+  return agentSupportsHooks(agent) ? "hooks-driven" : "cli-only";
+}
+function skillInstallDir(agent) {
+  return join2(skillInstallRoot(agent), SKILL_DIR_NAME);
+}
+function agentSupportsHooks(agent) {
+  return agent === "qoder" || agent === "codex" || agent === "claude";
+}
+function hookConfigPath(agent) {
+  switch (agent) {
+    case "qoder":
+      return join2(homedir2(), ".qoder", "settings.json");
+    case "codex":
+      return join2(homedir2(), ".codex", "hooks.json");
+    case "claude":
+      return join2(homedir2(), ".claude", "settings.json");
+  }
+}
+var LEGACY_QODER_SKILL_DIRS = [
+  "ctxdb-qoder",
+  "rds-ctxdb-qoder",
+  "qoder-ctxdb"
+];
+var HOOK_EVENTS = ["UserPromptSubmit", "Stop", "SessionStart"];
+async function runSetup(options) {
+  const steps = [];
+  if (!isAgent(options.agent)) {
+    steps.push({
+      step: "validate-agent",
+      ok: false,
+      detail: `unknown --agent: ${String(options.agent)} (expected one of ${SUPPORTED_AGENTS.join(" / ")})`
+    });
+    return { ok: false, steps };
+  }
+  const agent = options.agent;
+  const installSkill = options.installSkill !== false;
+  const validate = options.validate !== false;
+  const homeCheck = checkAgentHome(agent);
+  steps.push(homeCheck);
+  if (!homeCheck.ok) return { ok: false, steps };
+  const cfg = load({ agent });
+  if (options.apiKey) cfg.apiKey = options.apiKey;
+  if (options.baseUrl) cfg.baseUrl = options.baseUrl.replace(/\/+$/, "");
+  else if (!cfg.baseUrl) cfg.baseUrl = DEFAULT_BASE_URL;
+  cfg.userId = options.userId ?? cfg.userId ?? DEFAULT_USER_ID;
+  save(cfg, void 0, { agent });
+  steps.push({
+    step: "write-config",
+    ok: true,
+    detail: `${agent}: ${cfg.baseUrl} (user_id=${cfg.userId})`
+  });
+  if (installSkill) {
+    try {
+      const srcDir = locateSkillDir(skillResourceDir(agent));
+      if (srcDir) {
+        const dest = skillInstallDir(agent);
+        copySkillDir(srcDir, dest, agent);
+        steps.push({ step: "install-skill", ok: true, detail: dest });
+      } else {
+        steps.push({
+          step: "install-skill",
+          ok: false,
+          detail: `skill source directory not found (${skillResourceDir(agent)})`
+        });
+      }
+    } catch (err) {
+      steps.push({
+        step: "install-skill",
+        ok: false,
+        detail: err?.message ?? String(err)
+      });
+    }
+  }
+  if (agentSupportsHooks(agent)) {
+    const hookPaths = locateHookPaths();
+    steps.push({
+      step: "locate-hooks",
+      ok: hookPaths !== null,
+      detail: hookPaths ? `${hookPaths.userPromptSubmit} + ${hookPaths.stop}` : "could not locate hook scripts in dist/ or src/"
+    });
+    if (!hookPaths) return { ok: false, steps };
+    try {
+      backupSettingsJson(agent);
+      steps.push({ step: "backup-settings", ok: true });
+      const removed = stripCtxdbHooks(agent);
+      if (removed > 0) {
+        steps.push({
+          step: "clean-legacy-hooks",
+          ok: true,
+          detail: `removed ${removed} existing entries`
+        });
+      }
+      appendHooks(agent, hookPaths);
+      steps.push({ step: "append-hooks", ok: true });
+    } catch (err) {
+      steps.push({
+        step: "settings-update",
+        ok: false,
+        detail: err?.message ?? String(err)
+      });
+      return { ok: false, steps };
+    }
+    try {
+      chmodSync(hookPaths.userPromptSubmit, 493);
+      chmodSync(hookPaths.stop, 493);
+      chmodSync(hookPaths.sessionStart, 493);
+      if (hookPaths.preToolUse && existsSync(hookPaths.preToolUse)) {
+        chmodSync(hookPaths.preToolUse, 493);
+      }
+      steps.push({ step: "chmod-hooks", ok: true });
+    } catch (err) {
+      steps.push({
+        step: "chmod-hooks",
+        ok: false,
+        detail: err?.message ?? String(err)
+      });
+    }
+    if (agent === "codex") {
+      steps.push(enableCodexHooksFeature());
+    }
+  }
+  if (validate) {
+    if (!cfg.apiKey || !cfg.baseUrl) {
+      steps.push({
+        step: "validate-ping",
+        ok: false,
+        detail: "skipped \u2014 config incomplete after install"
+      });
+    } else {
+      try {
+        const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
+        await client.get("/v1/ping/");
+        steps.push({ step: "validate-ping", ok: true });
+      } catch (err) {
+        steps.push({
+          step: "validate-ping",
+          ok: false,
+          detail: err?.message ?? String(err)
+        });
+      }
+    }
+  }
+  const ok = steps.every((s) => s.ok);
+  const hints = ok ? [UNINSTALL_ORDER_HINT] : void 0;
+  return { ok, steps, hints };
+}
+function runRemove(agent, options = {}) {
+  const steps = [];
+  if (!isAgent(agent)) {
+    steps.push({
+      step: "validate-agent",
+      ok: false,
+      detail: `unknown --agent: ${String(agent)} (expected one of ${SUPPORTED_AGENTS.join(" / ")})`
+    });
+    return { ok: false, steps };
+  }
+  if (agentSupportsHooks(agent)) {
+    const path = hookConfigPath(agent);
+    if (!existsSync(path)) {
+      steps.push({
+        step: "settings-missing",
+        ok: true,
+        detail: "nothing to remove"
+      });
+    } else {
+      try {
+        backupSettingsJson(agent);
+        const data = JSON.parse(readFileSync(path, "utf-8"));
+        const hooks = data.hooks ?? {};
+        let removedTotal = 0;
+        for (const ev of HOOK_EVENTS) {
+          const arr = hooks[ev];
+          if (!Array.isArray(arr)) continue;
+          const before = arr.length;
+          hooks[ev] = arr.filter((entry) => !entryIsCtxdb(entry));
+          removedTotal += before - hooks[ev].length;
+        }
+        data.hooks = hooks;
+        writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+        steps.push({
+          step: "remove-hooks",
+          ok: true,
+          detail: `removed ${removedTotal} entries`
+        });
+      } catch (err) {
+        steps.push({
+          step: "remove-hooks",
+          ok: false,
+          detail: err?.message ?? String(err)
+        });
+        return { ok: false, steps };
+      }
+    }
+    const dirs = agent === "qoder" ? [
+      skillInstallDir("qoder"),
+      ...LEGACY_QODER_SKILL_DIRS.map(
+        (d) => join2(homedir2(), ".qoder", "skills", d)
+      )
+    ] : [skillInstallDir(agent)];
+    for (const p of dirs) {
+      if (!existsSync(p)) continue;
+      try {
+        rmSync(p, { recursive: true, force: true });
+        steps.push({ step: "remove-skill-dir", ok: true, detail: p });
+      } catch (err) {
+        steps.push({
+          step: "remove-skill-dir",
+          ok: false,
+          detail: `${p}: ${err?.message ?? String(err)}`
+        });
+      }
+    }
+  } else {
+    const dir = skillInstallDir(agent);
+    if (!existsSync(dir)) {
+      steps.push({
+        step: "skill-missing",
+        ok: true,
+        detail: `nothing to remove (${dir})`
+      });
+    } else {
+      try {
+        rmSync(dir, { recursive: true, force: true });
+        steps.push({ step: "remove-skill-dir", ok: true, detail: dir });
+      } catch (err) {
+        steps.push({
+          step: "remove-skill-dir",
+          ok: false,
+          detail: `${dir}: ${err?.message ?? String(err)}`
+        });
+      }
+    }
+  }
+  try {
+    const r = removeAgent(agent, void 0, {
+      keepEmptyShell: !!options.keepConfigShell
+    });
+    if (r.fileDeleted) {
+      steps.push({
+        step: "remove-config-section",
+        ok: true,
+        detail: `${agent} was last agent; deleted ~/.ctxdb/ctxdb.json`
+      });
+    } else if (r.removed) {
+      steps.push({
+        step: "remove-config-section",
+        ok: true,
+        detail: `removed agents.${agent}; remaining: ${r.remainingAgents.join(", ") || "(none)"}`
+      });
+    } else {
+      steps.push({
+        step: "remove-config-section",
+        ok: true,
+        detail: `nothing to remove (no agents.${agent} section)`
+      });
+    }
+  } catch (err) {
+    steps.push({
+      step: "remove-config-section",
+      ok: false,
+      detail: err?.message ?? String(err)
+    });
+  }
+  return { ok: steps.every((s) => s.ok), steps };
+}
+function checkAgentHome(agent) {
+  const dir = agentHomeDir(agent);
+  if (!existsSync(dir)) {
+    return {
+      step: "check-agent-home",
+      ok: false,
+      detail: `${dir} not found; install or start ${agent} once before running ctxdb setup --agent ${agent}`
+    };
+  }
+  return { step: "check-agent-home", ok: true, detail: dir };
+}
+function runTeardown(options = {}) {
+  const steps = [];
+  const purgeConfig = Boolean(options.purgeConfig || options.purgeAll);
+  const purgeLogs = Boolean(options.purgeLogs || options.purgeAll);
+  const purgeRoot = Boolean(options.purgeAll);
+  const keepConfigShell = !purgeConfig;
+  for (const agent of SUPPORTED_AGENTS) {
+    const sub = runRemove(agent, { keepConfigShell });
+    for (const s of sub.steps) {
+      steps.push({ ...s, step: `${agent}:${s.step}` });
+    }
+  }
+  if (purgeConfig) {
+    const cfgPath = join2(homedir2(), ".ctxdb", "ctxdb.json");
+    if (existsSync(cfgPath)) {
+      try {
+        unlinkSync(cfgPath);
+        steps.push({ step: "purge-config", ok: true, detail: cfgPath });
+      } catch (err) {
+        steps.push({
+          step: "purge-config",
+          ok: false,
+          detail: `${cfgPath}: ${err?.message ?? String(err)}`
+        });
+      }
+    } else {
+      steps.push({
+        step: "purge-config",
+        ok: true,
+        detail: `nothing to remove (${cfgPath})`
+      });
+    }
+  }
+  if (purgeLogs) {
+    const logsDir = join2(homedir2(), ".ctxdb", "logs");
+    if (existsSync(logsDir)) {
+      try {
+        rmSync(logsDir, { recursive: true, force: true });
+        steps.push({ step: "purge-logs", ok: true, detail: logsDir });
+      } catch (err) {
+        steps.push({
+          step: "purge-logs",
+          ok: false,
+          detail: `${logsDir}: ${err?.message ?? String(err)}`
+        });
+      }
+    } else {
+      steps.push({
+        step: "purge-logs",
+        ok: true,
+        detail: `nothing to remove (${logsDir})`
+      });
+    }
+  }
+  if (purgeRoot) {
+    const root = join2(homedir2(), ".ctxdb");
+    if (existsSync(root)) {
+      try {
+        const remaining = readdirSync(root);
+        if (remaining.length === 0) {
+          rmdirSync(root);
+          steps.push({ step: "purge-root", ok: true, detail: root });
+        } else {
+          steps.push({
+            step: "purge-root",
+            ok: true,
+            detail: `kept (not empty): ${remaining.join(", ")}`
+          });
+        }
+      } catch (err) {
+        steps.push({
+          step: "purge-root",
+          ok: false,
+          detail: `${root}: ${err?.message ?? String(err)}`
+        });
+      }
+    }
+  }
+  const ok = steps.every((s) => s.ok);
+  const hints = ok ? [UNINSTALL_NPM_HINT] : void 0;
+  return { ok, steps, hints };
+}
+var SETTINGS_BACKUP_KEEP = 5;
+function backupSettingsJson(agent) {
+  const path = hookConfigPath(agent);
+  if (!path || !existsSync(path)) return;
+  const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:T.]/g, "").replace(/Z$/, "");
+  const bak = `${path}.bak-ctxdb-${ts}`;
+  copyFileSync(path, bak);
+  rotateBackups(`${path}.bak-ctxdb-`, SETTINGS_BACKUP_KEEP);
+}
+function rotateBackups(prefix, keep) {
+  const dir = dirname(prefix);
+  const baseName = prefix.slice(dir.length + 1);
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  const candidates = [];
+  for (const name of entries) {
+    if (!name.startsWith(baseName)) continue;
+    const full = join2(dir, name);
+    try {
+      const st = statSync(full);
+      if (st.isFile()) candidates.push({ path: full, mtime: st.mtimeMs });
+    } catch {
+    }
+  }
+  if (candidates.length <= keep) return;
+  candidates.sort((a, b) => b.mtime - a.mtime);
+  for (const stale of candidates.slice(keep)) {
+    try {
+      unlinkSync(stale.path);
+    } catch (err) {
+      try {
+        process.stderr.write(
+          `[ctxdb] failed to prune backup ${stale.path}: ${err?.message ?? err}
+`
+        );
+      } catch {
+      }
+    }
+  }
+}
+function stripCtxdbHooks(agent) {
+  const path = hookConfigPath(agent);
+  if (!path || !existsSync(path)) return 0;
+  let data;
+  try {
+    data = JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return 0;
+  }
+  const hooks = data?.hooks ?? {};
+  let removed = 0;
+  for (const ev of HOOK_EVENTS) {
+    const arr = hooks[ev];
+    if (!Array.isArray(arr)) continue;
+    const before = arr.length;
+    hooks[ev] = arr.filter((entry) => !entryIsCtxdb(entry));
+    removed += before - hooks[ev].length;
+  }
+  if (removed === 0) return 0;
+  data.hooks = hooks;
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+  return removed;
+}
+function locateHookPaths() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const pkgRoot = walkUpToPackageJson(here, "@aliyunrds/ctxdb");
+  if (!pkgRoot) return null;
+  const preferSrc = here.includes("/src/") || here.includes("\\src\\");
+  if (preferSrc) {
+    const src = hookPathsFromDir(join2(pkgRoot, "src", "hooks"), "ts");
+    if (src) return src;
+  }
+  const distDir = join2(pkgRoot, "dist", "hooks");
+  const dist = hookPathsFromDir(distDir, "js");
+  if (dist) return dist;
+  return hookPathsFromDir(join2(pkgRoot, "src", "hooks"), "ts");
+}
+function hookPathsFromDir(dir, ext) {
+  if (!existsSync(dir)) return null;
+  const ups = join2(dir, `user-prompt-submit.${ext}`);
+  const stp = join2(dir, `stop.${ext}`);
+  const ss = join2(dir, `session-start.${ext}`);
+  const ptu = join2(dir, `pre-tool-use.${ext}`);
+  if (existsSync(ups) && existsSync(stp) && existsSync(ss)) {
+    return {
+      userPromptSubmit: ups,
+      stop: stp,
+      sessionStart: ss,
+      preToolUse: existsSync(ptu) ? ptu : void 0
+    };
+  }
+  return null;
+}
+function locateSkillDir(variant) {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const pkgRoot = walkUpToPackageJson(here, "@aliyunrds/ctxdb");
+  if (!pkgRoot) return null;
+  const preferSrc = here.includes("/src/") || here.includes("\\src\\");
+  if (preferSrc) {
+    const srcSkill2 = join2(pkgRoot, "src", "setup", "skills", variant);
+    if (existsSync(srcSkill2)) return srcSkill2;
+  }
+  const distSkill = join2(pkgRoot, "dist", "setup", "skills", variant);
+  if (existsSync(distSkill)) return distSkill;
+  const srcSkill = join2(pkgRoot, "src", "setup", "skills", variant);
+  if (existsSync(srcSkill)) return srcSkill;
+  return null;
+}
+function walkUpToPackageJson(start, expectedName) {
+  let cur = start;
+  for (let i = 0; i < 8; i++) {
+    const p = join2(cur, "package.json");
+    if (existsSync(p)) {
+      try {
+        const pkg = JSON.parse(readFileSync(p, "utf-8"));
+        if (pkg.name === expectedName) return cur;
+      } catch {
+      }
+    }
+    const parent = dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return null;
+}
+function copySkillDir(src, dest, agent) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcPath = join2(src, entry);
+    const destPath = join2(dest, entry);
+    const st = statSync(srcPath);
+    if (st.isDirectory()) {
+      copySkillDir(srcPath, destPath, agent);
+    } else {
+      if (entry.endsWith(".md")) {
+        const text = readFileSync(srcPath, "utf-8").replace(/\{\{agent\}\}/g, agent);
+        writeFileSync(destPath, text, "utf-8");
+      } else {
+        copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+}
+function appendHooks(agent, hookPaths) {
+  const path = hookConfigPath(agent);
+  if (!path) return;
+  let data = {};
+  if (existsSync(path)) {
+    try {
+      data = JSON.parse(readFileSync(path, "utf-8")) ?? {};
+    } catch {
+      data = {};
+    }
+  }
+  if (!data.hooks || typeof data.hooks !== "object") data.hooks = {};
+  appendOne(data.hooks, "UserPromptSubmit", hookPaths.userPromptSubmit, agent);
+  appendOne(data.hooks, "Stop", hookPaths.stop, agent);
+  appendOne(data.hooks, "SessionStart", hookPaths.sessionStart, agent);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+var ENTRY_MARKER_KEY = "_ctxdb";
+var ENTRY_MARKER_VALUE = "@aliyunrds/ctxdb";
+var ENTRY_AGENT_KEY = "_ctxdbAgent";
+var LEGACY_MARKER_KEYS = ["_ctxdbQoder", "_ctxdbPackage"];
+var LEGACY_MARKER_VALUES = ["@aliyunrds/ctxdb-qoder"];
+var TOOL_SCOPED_EVENTS = /* @__PURE__ */ new Set(["PreToolUse", "PostToolUse"]);
+function appendOne(hooks, event, command, agent) {
+  const commandWithAgent = `${command} --agent=${agent}`;
+  if (!Array.isArray(hooks[event])) hooks[event] = [];
+  const dup = hooks[event].some(
+    (entry2) => Array.isArray(entry2?.hooks) && entry2.hooks.some(
+      (h) => h?.type === "command" && typeof h.command === "string" && h.command === commandWithAgent
+    )
+  );
+  if (dup) return;
+  const entry = {
+    hooks: [{ type: "command", command: commandWithAgent, timeout: 60 }],
+    [ENTRY_MARKER_KEY]: ENTRY_MARKER_VALUE,
+    [ENTRY_AGENT_KEY]: agent
+  };
+  if (TOOL_SCOPED_EVENTS.has(event)) entry.matcher = "*";
+  hooks[event].push(entry);
+}
+function entryIsCtxdb(entry) {
+  if (!entry) return false;
+  if (entry[ENTRY_MARKER_KEY] === ENTRY_MARKER_VALUE) return true;
+  for (const k of LEGACY_MARKER_KEYS) {
+    if (entry[k] === ENTRY_MARKER_VALUE) return true;
+  }
+  for (const k of [ENTRY_MARKER_KEY, ...LEGACY_MARKER_KEYS]) {
+    if (typeof entry[k] === "string" && LEGACY_MARKER_VALUES.includes(entry[k])) {
+      return true;
+    }
+  }
+  if (!Array.isArray(entry.hooks)) return false;
+  return entry.hooks.some(
+    (h) => h?.type === "command" && typeof h.command === "string" && (h.command.includes("@aliyunrds/ctxdb-qoder") || h.command.includes("@aliyunrds/ctxdb") || h.command.includes("ctxdb-qoder") || h.command.includes("rds-ctxdb") || h.command.includes("qoder-ctxdb"))
+  );
+}
+function codexConfigTomlPath() {
+  return join2(homedir2(), ".codex", "config.toml");
+}
+function inspectCodexHooksFeature(rawContent) {
+  const content = rawContent.replace(/^/, "");
+  for (const raw of content.split("\n")) {
+    const stripped = raw.replace(/#.*$/, "").trim();
+    if (!stripped) continue;
+    if (/^features\s*=\s*\{/.test(stripped)) {
+      return {
+        kind: "ambiguous",
+        reason: "[features] declared as inline table \u2014 please set hooks = true manually"
+      };
+    }
+    if (/^features\.hooks\s*=/.test(stripped)) {
+      const value = stripped.split("=", 2)[1]?.trim();
+      if (value === "true") return { kind: "already-enabled" };
+      return {
+        kind: "ambiguous",
+        reason: `features.hooks already set to '${value}' via dotted-key \u2014 please set it to true manually`
+      };
+    }
+  }
+  const lines = content.split("\n");
+  let inFeatures = false;
+  let sawFeatures = false;
+  let featuresCount = 0;
+  for (const raw of lines) {
+    const stripped = raw.replace(/#.*$/, "").trim();
+    const headerMatch = stripped.match(/^\[([^\]]+)\]$/);
+    if (headerMatch) {
+      const name = headerMatch[1].trim();
+      if (name === "features") {
+        inFeatures = true;
+        sawFeatures = true;
+        featuresCount++;
+      } else {
+        inFeatures = false;
+      }
+      continue;
+    }
+    if (!inFeatures) continue;
+    const kv = stripped.match(/^hooks\s*=\s*(.+)$/);
+    if (kv) {
+      const value = kv[1].trim();
+      if (value === "true") return { kind: "already-enabled" };
+      if (value === "false") return { kind: "features-with-hooks-false" };
+      return {
+        kind: "ambiguous",
+        reason: `[features].hooks already set to '${value}' \u2014 please set it to true manually`
+      };
+    }
+  }
+  if (featuresCount > 1) {
+    return {
+      kind: "ambiguous",
+      reason: "multiple [features] sections detected \u2014 please set hooks = true manually"
+    };
+  }
+  if (sawFeatures) return { kind: "features-without-hooks" };
+  return { kind: "no-features-section" };
+}
+function applyCodexHooksFeature(rawContent, status2) {
+  switch (status2.kind) {
+    case "already-enabled":
+    case "ambiguous":
+      return rawContent;
+    case "no-config-file":
+      return "[features]\nhooks = true\n";
+    case "no-features-section": {
+      if (rawContent.length === 0) return "[features]\nhooks = true\n";
+      const trimmedTail = rawContent.replace(/\n+$/, "");
+      return `${trimmedTail}
+
+[features]
+hooks = true
+`;
+    }
+    case "features-without-hooks": {
+      const lines = rawContent.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        const stripped = lines[i].replace(/#.*$/, "").trim();
+        if (stripped === "[features]") {
+          lines.splice(i + 1, 0, "hooks = true");
+          return lines.join("\n");
+        }
+      }
+      return rawContent;
+    }
+    case "features-with-hooks-false": {
+      const lines = rawContent.split("\n");
+      let inFeatures = false;
+      for (let i = 0; i < lines.length; i++) {
+        const stripped = lines[i].replace(/#.*$/, "").trim();
+        const headerMatch = stripped.match(/^\[([^\]]+)\]$/);
+        if (headerMatch) {
+          inFeatures = headerMatch[1].trim() === "features";
+          continue;
+        }
+        if (!inFeatures) continue;
+        if (/^hooks\s*=\s*false\b/.test(stripped)) {
+          lines[i] = lines[i].replace(/(hooks\s*=\s*)false\b/, "$1true");
+          return lines.join("\n");
+        }
+      }
+      return rawContent;
+    }
+  }
+}
+function enableCodexHooksFeature() {
+  const path = codexConfigTomlPath();
+  let content = "";
+  let createdNew = false;
+  if (existsSync(path)) {
+    try {
+      content = readFileSync(path, "utf-8");
+    } catch (err) {
+      return {
+        step: "codex-features-hooks",
+        ok: false,
+        detail: `read ${path} failed: ${err?.message ?? err}`
+      };
+    }
+  } else {
+    createdNew = true;
+  }
+  const status2 = createdNew ? { kind: "no-config-file" } : inspectCodexHooksFeature(content);
+  if (status2.kind === "already-enabled") {
+    return {
+      step: "codex-features-hooks",
+      ok: true,
+      detail: "already enabled in ~/.codex/config.toml"
+    };
+  }
+  if (status2.kind === "ambiguous") {
+    try {
+      process.stderr.write(
+        `[ctxdb] ~/.codex/config.toml: ${status2.reason}
+[ctxdb] Codex won't fire any hooks until \`[features].hooks = true\` is set in that file.
+`
+      );
+    } catch {
+    }
+    return {
+      step: "codex-features-hooks",
+      ok: true,
+      detail: `skipped: ${status2.reason}`
+    };
+  }
+  const next = applyCodexHooksFeature(content, status2);
+  if (!createdNew) {
+    try {
+      const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:T.]/g, "").replace(/Z$/, "");
+      copyFileSync(path, `${path}.bak-ctxdb-${ts}`);
+      rotateBackups(`${path}.bak-ctxdb-`, SETTINGS_BACKUP_KEEP);
+    } catch (err) {
+      try {
+        process.stderr.write(
+          `[ctxdb] failed to back up ${path} before patching: ${err?.message ?? err}
+`
+        );
+      } catch {
+      }
+    }
+  }
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, next, "utf-8");
+    return {
+      step: "codex-features-hooks",
+      ok: true,
+      detail: describeCodexFeatureMutation(status2, createdNew)
+    };
+  } catch (err) {
+    return {
+      step: "codex-features-hooks",
+      ok: false,
+      detail: `write ${path} failed: ${err?.message ?? err}`
+    };
+  }
+}
+function describeCodexFeatureMutation(status2, createdNew) {
+  if (createdNew) {
+    return "created ~/.codex/config.toml with [features].hooks = true";
+  }
+  switch (status2.kind) {
+    case "no-features-section":
+      return "appended [features] section with hooks = true";
+    case "features-without-hooks":
+      return "added hooks = true under existing [features] section";
+    case "features-with-hooks-false":
+      return "flipped hooks from false to true under [features]";
+    default:
+      return "updated ~/.codex/config.toml";
+  }
+}
+
+// src/cli/setup-cli.ts
+function parseAgent(args) {
+  const raw = args.flags.agent;
+  if (typeof raw !== "string") return null;
+  return SUPPORTED_AGENTS.includes(raw) ? raw : null;
+}
+function agentError() {
+  process.stderr.write(
+    `ctxdb setup: --agent <${SUPPORTED_AGENTS.join("|")}> is required
+  e.g. ctxdb setup --agent qoder --api-key=<key>
+`
+  );
+}
+async function setup(args) {
+  const agent = parseAgent(args);
+  if (!agent) {
+    agentError();
+    return 2;
+  }
+  const json = !!args.flags.json;
+  if (args.flags.remove) {
+    const result2 = runRemove(agent);
+    printResult(result2, json);
+    if (!json && result2.hints) {
+      for (const h of result2.hints) process.stderr.write(`
+${h}
+`);
+    }
+    return result2.ok ? 0 : 1;
+  }
+  const result = await runSetup({
+    agent,
+    apiKey: typeof args.flags["api-key"] === "string" ? args.flags["api-key"] : void 0,
+    baseUrl: typeof args.flags["base-url"] === "string" ? args.flags["base-url"] : void 0,
+    userId: typeof args.flags["user-id"] === "string" ? args.flags["user-id"] : void 0,
+    installSkill: !args.flags["no-install-skill"],
+    validate: !args.flags["no-validate"]
+  });
+  printResult(result, json);
+  if (!json && result.hints) {
+    for (const h of result.hints) process.stderr.write(`
+${h}
+`);
+  }
+  return result.ok ? 0 : 1;
+}
+
+// src/cli/teardown.ts
+function teardown(args) {
+  const result = runTeardown({
+    purgeConfig: !!args.flags["purge-config"],
+    purgeLogs: !!args.flags["purge-logs"],
+    purgeAll: !!args.flags["purge-all"]
+  });
+  const json = !!args.flags.json;
+  printResult(result, json);
+  if (!json && result.hints) {
+    for (const h of result.hints) process.stderr.write(`
+${h}
+`);
+  }
+  return result.ok ? 0 : 1;
+}
+
+// src/lib/kb.ts
+import { readFileSync as readFileSync2, existsSync as existsSync2, statSync as statSync2 } from "fs";
+import { basename, extname } from "path";
+import { homedir as homedir3 } from "os";
+import { resolve } from "path";
+var KB_COLLECTION = "/v1/knowledge/knowledge_bases";
+var DOCUMENTS = "/v1/knowledge/documents";
+var FILES = "/v1/knowledge/files";
+var DOCUMENT_DETAIL = "/v1/knowledge/documents/detail";
+async function tryNewThenLegacy(newPath, newCall, legacyCall) {
+  try {
+    return await newCall();
+  } catch (err) {
+    if (err instanceof NotFoundError && err.path === newPath) {
+      return legacyCall();
+    }
+    throw err;
+  }
+}
+var DEFAULT_POLL_INTERVAL_MS = 1500;
+var DEFAULT_INGEST_TIMEOUT_MS = 3e4;
+var DEFAULT_FILE_INGEST_TIMEOUT_MS = 6e4;
+var MIME_BY_EXT = {
+  ".pdf": "application/pdf",
+  ".txt": "text/plain",
+  ".md": "text/markdown",
+  ".markdown": "text/markdown",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".doc": "application/msword",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".json": "application/json",
+  ".csv": "text/csv",
+  ".xml": "application/xml",
+  ".rtf": "application/rtf"
+};
+async function listKnowledgeBases(client) {
+  const resp = await client.get(KB_COLLECTION);
+  if (Array.isArray(resp)) return resp;
+  if (resp && typeof resp === "object") {
+    const o = resp;
+    return o.knowledge_bases ?? o.results ?? [];
+  }
+  return [];
+}
+async function findKb(client, kbNameOrId) {
+  for (const kb of await listKnowledgeBases(client)) {
+    if (!kb || typeof kb !== "object") continue;
+    if (kb.name === kbNameOrId || kb.id === kbNameOrId) return kb;
+  }
+  return null;
+}
+async function createKb(client, kbName, description = "") {
+  return client.postJson(KB_COLLECTION, { name: kbName, description: description || "" });
+}
+async function findOrCreateKb(client, kbName, description = "") {
+  const existing = await findKb(client, kbName);
+  if (existing) return { kb: existing, created: false };
+  const created = await createKb(client, kbName, description);
+  return { kb: created, created: true };
+}
+async function uploadText(client, kbId, docName, text, mimeType = "text/plain", filePath) {
+  const body = {
+    knowledge_base_id: kbId,
+    name: docName,
+    text,
+    mime_type: mimeType
+  };
+  if (filePath !== void 0 && filePath !== "") body.file_path = filePath;
+  return tryNewThenLegacy(
+    DOCUMENTS,
+    () => client.postJson(DOCUMENTS, body),
+    () => {
+      const { knowledge_base_id: _drop, ...legacyBody } = body;
+      return client.postJson(`${KB_COLLECTION}/${encodeURIComponent(kbId)}/documents`, legacyBody);
+    }
+  );
+}
+async function uploadFile(client, kbId, localPath, options = {}) {
+  const expanded = expandHome(localPath);
+  if (!existsSync2(expanded)) throw new Error(`file not found: ${expanded}`);
+  const stat = statSync2(expanded);
+  if (!stat.isFile()) throw new Error(`not a file: ${expanded}`);
+  const filename = basename(expanded);
+  const docName = options.docName ?? filename;
+  const content = readFileSync2(expanded);
+  const mime = guessMime(expanded);
+  const fields = {
+    knowledge_base_id: kbId,
+    name: docName
+  };
+  if (options.filePath !== void 0 && options.filePath !== "") {
+    fields.file_path = options.filePath;
+  }
+  return tryNewThenLegacy(
+    FILES,
+    () => client.postMultipart(
+      FILES,
+      fields,
+      { file: { filename, content, mimeType: mime } }
+    ),
+    () => {
+      const { knowledge_base_id: _drop, ...legacyFields } = fields;
+      return client.postMultipart(
+        `${KB_COLLECTION}/${encodeURIComponent(kbId)}/files`,
+        legacyFields,
+        { file: { filename, content, mimeType: mime } }
+      );
+    }
+  );
+}
+function guessMime(path) {
+  const ext = extname(path).toLowerCase();
+  if (ext in MIME_BY_EXT) return MIME_BY_EXT[ext];
+  return "application/octet-stream";
+}
+async function getDocument(client, kbId, docId) {
+  return tryNewThenLegacy(
+    DOCUMENT_DETAIL,
+    () => client.get(DOCUMENT_DETAIL, {
+      knowledge_base_id: kbId,
+      document_id: docId
+    }),
+    () => client.get(
+      `${KB_COLLECTION}/${encodeURIComponent(kbId)}/documents/${encodeURIComponent(docId)}`
+    )
+  );
+}
+async function listDocuments(client, kbId) {
+  const resp = await tryNewThenLegacy(
+    DOCUMENTS,
+    () => client.get(DOCUMENTS, { knowledge_base_id: kbId }),
+    () => client.get(`${KB_COLLECTION}/${encodeURIComponent(kbId)}/documents`)
+  );
+  if (Array.isArray(resp)) return resp;
+  if (resp && typeof resp === "object") {
+    const o = resp;
+    return o.documents ?? o.results ?? [];
+  }
+  return [];
+}
+async function pollIngest(client, kbId, docId, options = {}) {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_INGEST_TIMEOUT_MS;
+  const intervalMs = options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const now = options.now ?? (() => performance.now());
+  const deadline = now() + timeoutMs;
+  let doc = await getDocument(client, kbId, docId);
+  let timedOut = false;
+  while (ingestInFlight(doc)) {
+    if (now() >= deadline) {
+      timedOut = true;
+      break;
+    }
+    await sleep(intervalMs);
+    try {
+      doc = await getDocument(client, kbId, docId);
+    } catch {
+      break;
+    }
+  }
+  if (doc && typeof doc === "object") {
+    return { ...doc, _pollingTimedOut: timedOut };
+  }
+  return { _pollingTimedOut: timedOut };
+}
+function ingestInFlight(doc) {
+  if (!doc || typeof doc !== "object") return false;
+  const status2 = doc.ingest_status;
+  return status2 === "processing" || status2 === "pending" || status2 === "in_progress";
+}
+function expandHome(p) {
+  if (p.startsWith("~/") || p === "~") {
+    return resolve(homedir3(), p.slice(2));
+  }
+  return resolve(p);
+}
+function compactChunk(raw) {
+  const c = raw ?? {};
+  const content = c.content_with_weight ?? c.content ?? c.chunk ?? c.text ?? "";
+  const doc_name = c.docnm_kwd ?? c.doc_name ?? c.docnm ?? "";
+  const kbRaw = c.kb_id ?? c.dataset_id;
+  const kb_id = Array.isArray(kbRaw) ? typeof kbRaw[0] === "string" ? kbRaw[0] : "" : typeof kbRaw === "string" ? kbRaw : "";
+  const docIdRaw = c.doc_id;
+  const scoreRaw = c.similarity ?? c.rerank_score;
+  const tagsRaw = c.tag_kwd;
+  const out = {
+    content,
+    doc_name,
+    kb_id,
+    score: typeof scoreRaw === "number" ? scoreRaw : 0
+  };
+  if (typeof docIdRaw === "string" && docIdRaw.length > 0) {
+    out.doc_id = docIdRaw;
+  }
+  if (Array.isArray(tagsRaw) && tagsRaw.length > 0) {
+    out.tags = tagsRaw;
+  }
+  return out;
+}
+function compactKbQueryResponse(raw) {
+  if (!raw || typeof raw !== "object") return { chunks: [] };
+  const r = raw;
+  const chunksIn = Array.isArray(r.chunks) ? r.chunks : [];
+  const out = {
+    chunks: chunksIn.map(compactChunk)
+  };
+  if (typeof r.total === "number") out.total = r.total;
+  return out;
+}
+function minimalChunk(raw) {
+  const c = compactChunk(raw);
+  return { content: c.content, score: c.score };
+}
+function minimalKbQueryResponse(raw) {
+  if (!raw || typeof raw !== "object") return { chunks: [] };
+  const r = raw;
+  const chunksIn = Array.isArray(r.chunks) ? r.chunks : [];
+  const out = {
+    chunks: chunksIn.map(minimalChunk)
+  };
+  if (typeof r.total === "number") out.total = r.total;
+  return out;
+}
+
+// src/cli/memory.ts
+async function memoryAdd(args) {
+  const text = args.positional[0];
+  if (!text) fail("usage: ctxdb memory add <text> [--user-id=...] [--metadata=K=V] [--no-infer]");
+  const ctx = buildContext(args);
+  const userId = args.flags["user-id"] ?? ctx.cfg.userId;
+  const metadata = parseMetadataFlags(args.flags["metadata"]);
+  const body = {
+    messages: [{ role: "user", content: text }],
+    user_id: userId,
+    async_mode: false
+  };
+  if (Object.keys(metadata).length > 0) body.metadata = metadata;
+  if (args.flags["no-infer"]) body.infer = false;
+  const resp = await ctx.client.postJson("/v3/memories/add/", body);
+  printResult(resp, !!args.flags.json);
+  return 0;
+}
+async function memorySearch(args) {
+  const query = args.positional[0];
+  if (!query) fail("usage: ctxdb memory search <query> [--top-k=10] [--threshold=0.4] [--knowledge] [--verbose] [--raw]");
+  const ctx = buildContext(args);
+  const userId = args.flags["user-id"] ?? ctx.cfg.userId;
+  const topK = numFlag(args.flags["top-k"], ctx.cfg.topK);
+  const threshold = numFlag(args.flags["threshold"], ctx.cfg.threshold);
+  const body = {
+    query,
+    user_id: userId,
+    top_k: topK,
+    threshold
+  };
+  if (args.flags.knowledge) {
+    body.knowledge = { enable: true, top_k: ctx.cfg.knowledgeTopK };
+  }
+  const resp = await ctx.client.postJson("/v3/memories/search/", body);
+  const out = projectKnowledgeChunks(resp, args.flags);
+  printResult(out, !!args.flags.json);
+  return 0;
+}
+function projectKnowledgeChunks(resp, flags) {
+  if (flags.raw) return resp;
+  if (!resp || typeof resp !== "object") return resp;
+  const r = resp;
+  const k = r.knowledge;
+  if (!k || typeof k !== "object") return resp;
+  const chunks = k.chunks;
+  if (!Array.isArray(chunks)) return resp;
+  const project = flags.verbose ? compactChunk : minimalChunk;
+  return {
+    ...r,
+    knowledge: { ...k, chunks: chunks.map(project) }
+  };
+}
+async function memoryList(args) {
+  const ctx = buildContext(args);
+  const userId = args.flags["user-id"] ?? ctx.cfg.userId;
+  const pageSize = numFlag(args.flags["page-size"], 100);
+  const body = {
+    filters: { user_id: userId },
+    page_size: pageSize
+  };
+  const cat = args.flags["category"];
+  if (typeof cat === "string") body.filters.category = cat;
+  const resp = await ctx.client.postJson("/v3/memories/", body);
+  printResult(resp, !!args.flags.json);
+  return 0;
+}
+async function memoryGet(args) {
+  const id = args.positional[0];
+  if (!id) fail("usage: ctxdb memory get <memory-id>");
+  const ctx = buildContext(args);
+  const resp = await ctx.client.get(`/v1/memories/${encodeURIComponent(id)}/`);
+  printResult(resp, !!args.flags.json);
+  return 0;
+}
+async function memoryUpdate(args) {
+  const id = args.positional[0];
+  const text = args.flags["text"];
+  if (!id || typeof text !== "string") {
+    fail("usage: ctxdb memory update <memory-id> --text=<new-text>");
+  }
+  const ctx = buildContext(args);
+  const resp = await ctx.client.putJson(
+    `/v1/memories/${encodeURIComponent(id)}/`,
+    { text }
+  );
+  printResult(resp, !!args.flags.json);
+  return 0;
+}
+async function memoryDelete(args) {
+  const ctx = buildContext(args);
+  const userId = args.flags["user-id"] ?? ctx.cfg.userId;
+  if (args.flags.all) {
+    if (typeof userId !== "string" || userId.length === 0) {
+      fail("memory delete --all requires --user-id=... or a userId in ctxdb config");
+    }
+    const resp2 = await ctx.client.delete("/v1/memories", { user_id: userId });
+    printResult(resp2, !!args.flags.json);
+    return 0;
+  }
+  const id = args.positional[0];
+  if (!id) fail("usage: ctxdb memory delete <memory-id> | --all");
+  const resp = await ctx.client.delete(
+    `/v1/memories/${encodeURIComponent(id)}/`
+  );
+  printResult(resp, !!args.flags.json);
+  return 0;
+}
+function numFlag(v, fallback) {
+  if (typeof v !== "string") return fallback;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : fallback;
+}
+function parseMetadataFlags(raw) {
+  if (typeof raw !== "string") return {};
+  const out = {};
+  for (const pair of raw.split(",")) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0) continue;
+    out[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
+  }
+  return out;
+}
+
+// src/cli/kb-cli.ts
+async function kbUploadText(args) {
+  const [kbName, docName] = args.positional;
+  const text = args.flags["text"];
+  if (!kbName || !docName || typeof text !== "string") {
+    fail(
+      "usage: ctxdb kb upload-text <kb-name> <doc-name> --text=<body> [--kb-description=...] [--file-path=<server-logical-path>] [--no-wait]"
+    );
+  }
+  const ctx = buildContext(args);
+  const description = args.flags["kb-description"] ?? "";
+  const filePath = typeof args.flags["file-path"] === "string" ? args.flags["file-path"] : void 0;
+  const { kb, created } = await findOrCreateKb(ctx.client, kbName, description);
+  const doc = await uploadText(ctx.client, kb.id, docName, text, "text/plain", filePath);
+  if (args.flags["no-wait"]) {
+    printResult({ kb, kb_created: created, document: doc }, !!args.flags.json);
+    return 0;
+  }
+  const final = await pollIngest(ctx.client, kb.id, doc.id, {
+    timeoutMs: DEFAULT_INGEST_TIMEOUT_MS
+  });
+  printResult(
+    { kb, kb_created: created, document: final },
+    !!args.flags.json
+  );
+  return 0;
+}
+async function kbUploadFile(args) {
+  const [kbName, localPath] = args.positional;
+  if (!kbName || !localPath) {
+    fail(
+      "usage: ctxdb kb upload-file <kb-name> <local-path> [--doc-name=...] [--file-path=<server-logical-path>] [--no-wait]"
+    );
+  }
+  const ctx = buildContext(args);
+  const { kb, created } = await findOrCreateKb(ctx.client, kbName);
+  const doc = await uploadFile(ctx.client, kb.id, localPath, {
+    docName: typeof args.flags["doc-name"] === "string" ? args.flags["doc-name"] : void 0,
+    filePath: typeof args.flags["file-path"] === "string" ? args.flags["file-path"] : void 0
+  });
+  if (args.flags["no-wait"]) {
+    printResult({ kb, kb_created: created, document: doc }, !!args.flags.json);
+    return 0;
+  }
+  const final = await pollIngest(ctx.client, kb.id, doc.id, {
+    timeoutMs: DEFAULT_FILE_INGEST_TIMEOUT_MS
+  });
+  printResult(
+    { kb, kb_created: created, document: final },
+    !!args.flags.json
+  );
+  return 0;
+}
+async function kbList(args) {
+  const ctx = buildContext(args);
+  const kbs = await listKnowledgeBases(ctx.client);
+  printResult({ knowledge_bases: kbs, count: kbs.length }, !!args.flags.json);
+  return 0;
+}
+async function kbDocumentsList(args) {
+  const kbNameOrId = args.positional[0];
+  if (!kbNameOrId) fail("usage: ctxdb kb documents-list <kb-name-or-id>");
+  const ctx = buildContext(args);
+  const kb = await findKb(ctx.client, kbNameOrId);
+  if (!kb) fail(`KB not found: ${kbNameOrId}`);
+  const docs = await listDocuments(ctx.client, kb.id);
+  printResult(
+    { kb, documents: docs, count: docs.length },
+    !!args.flags.json
+  );
+  return 0;
+}
+async function kbDocumentGet(args) {
+  const [kbNameOrId, docId] = args.positional;
+  if (!kbNameOrId || !docId) {
+    fail("usage: ctxdb kb document-get <kb-name-or-id> <doc-id>");
+  }
+  const ctx = buildContext(args);
+  const kb = await findKb(ctx.client, kbNameOrId);
+  if (!kb) fail(`KB not found: ${kbNameOrId}`);
+  const doc = await getDocument(ctx.client, kb.id, docId);
+  printResult({ kb, document: doc }, !!args.flags.json);
+  return 0;
+}
+async function kbSearch(args) {
+  const query = args.positional[0];
+  if (!query) {
+    fail(
+      "usage: ctxdb kb search <query> [--kb=name1,name2] [--top-k=N] [--threshold=F] [--verbose] [--raw]"
+    );
+  }
+  const ctx = buildContext(args);
+  const kbList2 = (typeof args.flags.kb === "string" ? args.flags.kb : "").split(",").map((s) => s.trim()).filter(Boolean);
+  const datasetIds = [];
+  for (const name of kbList2) {
+    const kb = await findKb(ctx.client, name);
+    if (!kb) fail(`KB not found: ${name}`);
+    datasetIds.push(kb.id);
+  }
+  const body = {
+    question: query,
+    dataset_ids: datasetIds
+  };
+  if (typeof args.flags["top-k"] === "string") {
+    const n = Number(args.flags["top-k"]);
+    if (Number.isFinite(n)) body.top_k = n;
+  }
+  if (typeof args.flags["threshold"] === "string") {
+    const f = Number(args.flags["threshold"]);
+    if (Number.isFinite(f)) body.similarity_threshold = f;
+  }
+  const resp = await ctx.client.postJson("/v1/knowledge/query", body);
+  const out = args.flags.raw ? resp : args.flags.verbose ? compactKbQueryResponse(resp) : minimalKbQueryResponse(resp);
+  printResult(out, !!args.flags.json);
+  return 0;
+}
+
+// src/cli/main.ts
+var HELP = `ctxdb v${PACKAGE_VERSION} \u2014 RDS ContextDatabase CLI (multi-agent)
+
+USAGE
+  ctxdb <command> [args] [--flags]
+
+COMMANDS
+  init [--agent <qoder|codex|claude>] [--api-key=K] [--base-url=URL] [--user-id=ID] [--no-validate]
+  status [--agent <qoder|codex|claude>] [--json]
+  ping [--agent <qoder|codex|claude>] [--json]
+  setup --agent <qoder|codex|claude>
+        [--api-key=K] [--base-url=URL] [--user-id=ID]
+        [--no-install-skill] [--no-validate] [--json] [--remove]
+                                 Qoder    \u2192 writes agents.qoder config + ~/.qoder/settings.json hooks + skill
+                                 Codex    \u2192 writes agents.codex config + ~/.codex/hooks.json hooks + skill
+                                 Claude   \u2192 writes agents.claude config + ~/.claude/settings.json hooks + skill
+  teardown [--purge-config] [--purge-logs] [--purge-all] [--json]
+                                 Removes hooks + skills for every agent.
+                                 --purge-config also deletes ~/.ctxdb/ctxdb.json.
+                                 --purge-logs   also deletes ~/.ctxdb/logs/.
+                                 --purge-all    deletes everything under ~/.ctxdb/
+                                 (does not run npm uninstall).
+
+  memory add <text> [--agent=<name>] [--user-id=...] [--metadata=K1=V1,K2=V2] [--no-infer]
+  memory search <query> [--agent=<name>] [--top-k=10] [--threshold=0.4] [--knowledge]
+                        [--verbose] [--raw]
+                                 --knowledge enables KB chunks alongside memory.
+                                 Default chunk view: {content, score} only.
+                                 --verbose adds doc_name/kb_id/doc_id/tags.
+                                 --raw ships server response verbatim.
+  memory list [--agent=<name>] [--page-size=100] [--category=...]
+  memory get <memory-id> [--agent=<name>]
+  memory update <memory-id> --text=<new-text> [--agent=<name>]
+  memory delete <memory-id> | --all [--agent=<name>]
+
+  kb upload-text <kb-name> <doc-name> --text=<body> [--agent=<name>]
+                 [--kb-description=...] [--no-wait]
+  kb upload-file <kb-name> <file-path> [--agent=<name>] [--doc-name=...] [--no-wait]
+  kb list [--agent=<name>]
+  kb documents-list <kb-name-or-id> [--agent=<name>]
+  kb document-get <kb-name-or-id> <doc-id> [--agent=<name>]
+  kb search <query> [--agent=<name>] [--kb=name1,name2] [--top-k=N] [--threshold=F]
+                    [--verbose] [--raw]
+                                 Standalone KB recall (independent of memory).
+                                 Default: minimal {content, score} per chunk.
+                                 --verbose: compact view adds doc_name/kb_id/
+                                 doc_id?/tags? for citation.
+                                 --raw: server response verbatim (curl parity).
+
+ENV VARS (override selected ~/.ctxdb/ctxdb.json agent config):
+  CTXDB_AGENT  CTXDB_API_KEY  CTXDB_BASE_URL  CTXDB_USER_ID
+
+CONFIG: ~/.ctxdb/ctxdb.json (agents.qoder / agents.codex / agents.claude)
+LOGS:   ~/.ctxdb/logs/ctxdb.log
+`;
+var ROUTES = {
+  init,
+  status,
+  ping,
+  setup,
+  teardown,
+  memory: {
+    add: memoryAdd,
+    search: memorySearch,
+    list: memoryList,
+    get: memoryGet,
+    update: memoryUpdate,
+    delete: memoryDelete
+  },
+  kb: {
+    "upload-text": kbUploadText,
+    "upload-file": kbUploadFile,
+    list: kbList,
+    "documents-list": kbDocumentsList,
+    "document-get": kbDocumentGet,
+    search: kbSearch
+  }
+};
+async function main(argv = process.argv.slice(2)) {
+  if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (argv[0] === "-v" || argv[0] === "--version") {
+    process.stdout.write(`ctxdb ${PACKAGE_VERSION}
+`);
+    return 0;
+  }
+  const [first, ...rest] = argv;
+  const route = ROUTES[first];
+  if (!route) {
+    process.stderr.write(`unknown command: ${first}
+`);
+    process.stderr.write(HELP);
+    return 2;
+  }
+  if (typeof route === "function") {
+    return Promise.resolve(route(parseArgs(rest)));
+  }
+  if (rest.length === 0) {
+    process.stderr.write(
+      `usage: ctxdb ${first} <${Object.keys(route).join("|")}> ...
+`
+    );
+    return 2;
+  }
+  const [sub, ...subRest] = rest;
+  const handler = route[sub];
+  if (!handler) {
+    process.stderr.write(`unknown subcommand: ${first} ${sub}
+`);
+    return 2;
+  }
+  return Promise.resolve(handler(parseArgs(subRest)));
+}
+main().then(
+  (code) => {
+    if (typeof code === "number") process.exit(code);
+  },
+  (err) => {
+    process.stderr.write(`error: ${err?.message ?? err}
+`);
+    if (process.env.RDS_CTXDB_DEBUG === "1" && err?.stack) {
+      process.stderr.write(err.stack + "\n");
+    }
+    process.exit(1);
+  }
+);
+export {
+  main
+};