@aliyunrds/ctxdb 1.0.1-beta.2 → 1.0.1

package/dist/cli/main.js

@@ -2,18 +2,16 @@
 import {
   DEFAULT_FILE_INGEST_TIMEOUT_MS,
   DEFAULT_INGEST_TIMEOUT_MS,
-  compactChunk,
   compactKbQueryResponse,
   createKb,
   getDocument,
   listDocuments,
   listKnowledgeBases,
-  minimalChunk,
   minimalKbQueryResponse,
   pollIngest,
   uploadFile,
   uploadText
-} from "../chunk-6S5RJYBC.js";
+} from "../chunk-UH7AJF6F.js";
 import {
   DEFAULT_BASE_URL,
   DEFAULT_USER_ID,
@@ -31,7 +29,7 @@ import {
   removeAgent,
   save,
   writeInstalledPkgVersion
-} from "../chunk-TKMIWM6Q.js";
+} from "../chunk-6FZL67GH.js";
 
 // src/cli/util.ts
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
@@ -42,6 +40,9 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   // setup / init
   "no-install-skill",
   "no-validate",
+  // update / upgrade
+  "self-update",
+  "no-self-update",
   // uninstall
   "purge-config",
   "purge-logs",
@@ -174,6 +175,10 @@ function formatStatusResult(r) {
     ["connected", r.connected],
     ["version", r.version]
   ];
+  if (r.hooks_node !== void 0) {
+    display.push(["hooks_node", r.hooks_node]);
+    display.push(["hooks_node_ok", r.hooks_node_ok]);
+  }
   if (r.ping_error) display.push(["ping_error", r.ping_error]);
   const maxKey = Math.max(...display.map(([k]) => k.length));
   for (const [k, v] of display) {
@@ -240,6 +245,7 @@ import { homedir } from "os";
 import { join, dirname, resolve } from "path";
 import { fileURLToPath } from "url";
 import { execFileSync } from "child_process";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 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 uninstall --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) {
@@ -254,12 +260,14 @@ function skillInstallRoot(agent) {
       return join(homedir(), ".claude", "skills");
     case "opencode":
       return join(homedir(), ".config", "opencode", "skills");
+    case "hermes":
+      return join(homedir(), ".hermes", "skills");
   }
 }
 var SKILL_DIRS = ["contextdb-memory", "contextdb-knowledge"];
 var LEGACY_SKILL_DIRS = ["ctxdb"];
 function agentSupportsHooks(agent) {
-  if (agent === "opencode") return false;
+  if (agent === "opencode" || agent === "hermes") return false;
   return isBuiltinAgent(agent);
 }
 function hookConfigPath(agent) {
@@ -273,6 +281,7 @@ function hookConfigPath(agent) {
     case "claude":
       return join(homedir(), ".claude", "settings.json");
     case "opencode":
+    case "hermes":
       return null;
   }
 }
@@ -352,6 +361,21 @@ async function runSetup(options) {
   }
   if (installSkill && isBuiltinAgent(agent)) {
     const installRoot = skillInstallRoot(agent);
+    for (const legacy of LEGACY_SKILL_DIRS) {
+      const legacyDir = join(installRoot, legacy);
+      if (!existsSync(legacyDir)) continue;
+      try {
+        rmSync(legacyDir, { recursive: true, force: true });
+        steps.push({ step: "remove-legacy-skill", ok: true, detail: legacyDir });
+      } catch (err) {
+        steps.push({
+          step: "remove-legacy-skill",
+          ok: false,
+          detail: `${legacyDir}: ${err?.message ?? String(err)}`
+        });
+        return { ok: false, steps };
+      }
+    }
     const skillResult = installSkillsTo(installRoot, agent);
     steps.push(...skillResult.steps);
     if (!skillResult.ok) return { ok: false, steps };
@@ -438,6 +462,76 @@ async function runSetup(options) {
       }
     }
   }
+  if (agent === "hermes") {
+    const hookPaths = locateHookPaths();
+    const hermesPreHook = hookPaths?.hermesPreLlmCall ?? null;
+    const hermesPostHook = hookPaths?.hermesPostLlmCall ?? null;
+    steps.push({
+      step: "locate-hermes-pre-hook",
+      ok: hermesPreHook !== null,
+      detail: hermesPreHook ?? "could not locate hermes-pre-llm-call in dist/ or src/"
+    });
+    steps.push({
+      step: "locate-hermes-post-hook",
+      ok: hermesPostHook !== null,
+      detail: hermesPostHook ?? "could not locate hermes-post-llm-call in dist/ or src/"
+    });
+    if (!hermesPreHook || !hermesPostHook) return { ok: false, steps };
+    const nodePath = process.execPath;
+    const nodeCheck = verifyNodeBinary(nodePath);
+    steps.push({
+      step: "resolve-node",
+      ok: nodeCheck.ok,
+      detail: nodeCheck.ok ? `${nodePath} (${nodeCheck.version})` : `node not executable: ${nodeCheck.error}`
+    });
+    if (!nodeCheck.ok) return { ok: false, steps };
+    try {
+      backupHermesConfig();
+      steps.push({ step: "backup-hermes-config", ok: true });
+      const removed = writeHermesHooksConfig(hermesPreHook, hermesPostHook, nodePath);
+      steps.push({
+        step: "append-hermes-hook",
+        ok: true,
+        detail: `pre_llm_call + post_llm_call written${removed > 0 ? `, replaced ${removed} stale` : ""}`
+      });
+    } catch (err) {
+      steps.push({
+        step: "hermes-config-update",
+        ok: false,
+        detail: err?.message ?? String(err)
+      });
+      return { ok: false, steps };
+    }
+    const chmodErrors = [];
+    for (const hookPath of [hermesPreHook, hermesPostHook]) {
+      try {
+        chmodSync(hookPath, 493);
+      } catch (err) {
+        chmodErrors.push(`${hookPath}: ${err?.message ?? String(err)}`);
+      }
+    }
+    steps.push({
+      step: "chmod-hermes-hook",
+      ok: true,
+      detail: chmodErrors.length > 0 ? `skipped: ${chmodErrors.join("; ")}` : void 0
+    });
+    try {
+      const allowlist = checkHermesHookAllowlist(
+        hermesCtxdbEntriesByEvent(readHermesConfig())
+      );
+      steps.push({
+        step: "check-hermes-hook-allowlist",
+        ok: allowlist.ok,
+        detail: allowlist.detail
+      });
+    } catch (err) {
+      steps.push({
+        step: "check-hermes-hook-allowlist",
+        ok: false,
+        detail: `${err?.message ?? String(err)}. ${hermesHookApprovalHint()}`
+      });
+    }
+  }
   if (agent === "opencode") {
     const absEntry = resolveOpencodePluginEntry();
     if (!absEntry) {
@@ -493,6 +587,11 @@ async function runSetup(options) {
       "Restart OpenCode to load the plugin. `ctxdb upgrade` auto-refreshes the shim after npm updates; only re-run setup if you move ctxdb's install dir."
     );
   }
+  if (ok && agent === "hermes") {
+    hints.unshift(
+      `Hermes shell hooks: ${hermesConfigPath()} \u2192 pre_llm_call + post_llm_call`
+    );
+  }
   return { ok, steps, hints: hints.length > 0 ? hints : void 0 };
 }
 function runRemove(agent, options = {}) {
@@ -626,6 +725,42 @@ function runRemove(agent, options = {}) {
       }
     }
   }
+  if (agent === "hermes") {
+    try {
+      backupHermesConfig();
+      const removed = removeHermesHooksConfig();
+      steps.push({
+        step: "remove-hermes-hooks",
+        ok: true,
+        detail: removed > 0 ? `removed ${removed} entries` : "nothing to remove"
+      });
+    } catch (err) {
+      steps.push({
+        step: "remove-hermes-hooks",
+        ok: false,
+        detail: err?.message ?? String(err)
+      });
+      return { ok: false, steps };
+    }
+    const root = skillInstallRoot(agent);
+    const dirs = [
+      ...SKILL_DIRS.map((d) => join(root, d)),
+      ...LEGACY_SKILL_DIRS.map((d) => join(root, d))
+    ];
+    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)}`
+        });
+      }
+    }
+  }
   try {
     const r = removeAgent(agent, void 0, {
       keepEmptyShell: !!options.keepConfigShell
@@ -659,7 +794,14 @@ function runRemove(agent, options = {}) {
   return { ok: steps.every((s) => s.ok), steps };
 }
 function checkAgentHome(agent) {
-  if (agent === "opencode") {
+  if (agent === "hermes" && process.platform === "win32") {
+    return {
+      step: "check-agent-home",
+      ok: false,
+      detail: "hermes setup currently supports macOS/Linux only; Windows Hermes will be handled separately"
+    };
+  }
+  if (agent === "opencode" || agent === "hermes") {
     const primary = agentHomeDir(agent);
     try {
       mkdirSync(primary, { recursive: true });
@@ -782,6 +924,7 @@ function verifyNodeBinary(nodePath) {
 }
 function checkHookNodePaths(agent) {
   if (agent === "opencode") return checkOpencodeShimHealth();
+  if (agent === "hermes") return checkHermesHookHealth();
   const empty = {
     installed: false,
     nodePaths: [],
@@ -986,12 +1129,16 @@ function hookPathsFromDir(dir, ext) {
   const stp = join(dir, `stop.${ext}`);
   const ss = join(dir, `session-start.${ext}`);
   const ptu = join(dir, `pre-tool-use.${ext}`);
+  const hpl = join(dir, `hermes-pre-llm-call.${ext}`);
+  const hpost = join(dir, `hermes-post-llm-call.${ext}`);
   if (existsSync(ups) && existsSync(stp) && existsSync(ss)) {
     return {
       userPromptSubmit: ups,
       stop: stp,
       sessionStart: ss,
-      preToolUse: existsSync(ptu) ? ptu : void 0
+      preToolUse: existsSync(ptu) ? ptu : void 0,
+      hermesPreLlmCall: existsSync(hpl) ? hpl : void 0,
+      hermesPostLlmCall: existsSync(hpost) ? hpost : void 0
     };
   }
   return null;
@@ -1194,6 +1341,242 @@ function entryIsCtxdb(entry) {
     (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"))
   );
 }
+var HERMES_PRE_LLM_CALL_EVENT = "pre_llm_call";
+var HERMES_POST_LLM_CALL_EVENT = "post_llm_call";
+var HERMES_HOOK_EVENTS = [
+  HERMES_PRE_LLM_CALL_EVENT,
+  HERMES_POST_LLM_CALL_EVENT
+];
+var HERMES_HOOK_TIMEOUT_SECONDS = 60;
+var HERMES_ALLOWLIST_FILENAME = "shell-hooks-allowlist.json";
+function hermesConfigPath() {
+  return join(homedir(), ".hermes", "config.yaml");
+}
+function hermesAllowlistPath() {
+  return join(dirname(hermesConfigPath()), HERMES_ALLOWLIST_FILENAME);
+}
+function hermesHookApprovalHint(events = HERMES_HOOK_EVENTS) {
+  const hookNames = events.map((event) => `\`${event}\``).join(" and ");
+  return `Approve the Hermes ctxdb hooks ${hookNames}: run \`hermes --accept-hooks chat\` once. This command opens an interactive chat; after Hermes starts, exit the chat, then rerun \`ctxdb setup --agent hermes\`.`;
+}
+function backupHermesConfig() {
+  backupSettingsFile(hermesConfigPath());
+}
+function readHermesConfig() {
+  const path = hermesConfigPath();
+  if (!existsSync(path)) return {};
+  const raw = readFileSync(path, "utf-8");
+  if (!raw.trim()) return {};
+  const parsed = parseYaml(raw);
+  if (parsed === null || parsed === void 0) return {};
+  if (typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${path}: expected a YAML mapping at the top level`);
+  }
+  return parsed;
+}
+function writeHermesConfig(data) {
+  const path = hermesConfigPath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, stringifyYaml(data, { lineWidth: 0 }), "utf-8");
+}
+function hermesHooksMap(data) {
+  if (!data.hooks || typeof data.hooks !== "object" || Array.isArray(data.hooks)) {
+    data.hooks = {};
+  }
+  return data.hooks;
+}
+function quoteHermesCommandPart(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function hermesHookCommand(scriptPath, nodePath) {
+  return `${quoteHermesCommandPart(nodePath)} ${quoteHermesCommandPart(scriptPath)} --agent=hermes`;
+}
+function hermesEntryIsCtxdb(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  if (entry[ENTRY_MARKER_KEY] === ENTRY_MARKER_VALUE) return true;
+  if (typeof entry.command === "string" && (entry.command.includes("hermes-pre-llm-call") || entry.command.includes("hermes-post-llm-call")) && entry.command.includes("--agent=hermes")) {
+    return true;
+  }
+  return false;
+}
+function hermesCtxdbEntriesByEvent(data) {
+  const hooks = data.hooks && typeof data.hooks === "object" && !Array.isArray(data.hooks) ? data.hooks : {};
+  const entriesByEvent = /* @__PURE__ */ new Map();
+  for (const event of HERMES_HOOK_EVENTS) {
+    const entries = Array.isArray(hooks[event]) ? hooks[event].filter(hermesEntryIsCtxdb) : [];
+    entriesByEvent.set(event, entries);
+  }
+  return entriesByEvent;
+}
+function checkHermesHookAllowlist(entriesByEvent) {
+  const path = hermesAllowlistPath();
+  let approvals = [];
+  let readError = null;
+  if (existsSync(path)) {
+    try {
+      const data = JSON.parse(readFileSync(path, "utf-8"));
+      if (!Array.isArray(data?.approvals)) {
+        readError = "expected an approvals array";
+      } else {
+        approvals = data.approvals;
+      }
+    } catch (err) {
+      readError = err?.message ?? String(err);
+    }
+  }
+  const missingEvents = HERMES_HOOK_EVENTS.filter((event) => {
+    const entries = entriesByEvent.get(event) ?? [];
+    return entries.length === 0 || entries.some((entry) => {
+      if (typeof entry?.command !== "string") return true;
+      return !approvals.some(
+        (approval) => approval && typeof approval === "object" && approval.event === event && approval.command === entry.command
+      );
+    });
+  });
+  if (missingEvents.length === 0) {
+    return {
+      ok: true,
+      detail: `pre_llm_call + post_llm_call approved in ${path}`
+    };
+  }
+  const reason = readError ? `${path} is invalid (${readError})` : `${missingEvents.join(", ")} not allowlisted in ${path}`;
+  return {
+    ok: false,
+    detail: `${reason}. ${hermesHookApprovalHint(missingEvents)}`
+  };
+}
+function stripHermesHooks(data) {
+  const hooks = hermesHooksMap(data);
+  let removed = 0;
+  for (const event of HERMES_HOOK_EVENTS) {
+    const arr = hooks[event];
+    if (!Array.isArray(arr)) continue;
+    const before = arr.length;
+    hooks[event] = arr.filter((entry) => !hermesEntryIsCtxdb(entry));
+    removed += before - hooks[event].length;
+  }
+  return removed;
+}
+function writeHermesHooksConfig(preScriptPath, postScriptPath, nodePath) {
+  const data = readHermesConfig();
+  const removed = stripHermesHooks(data);
+  const hooks = hermesHooksMap(data);
+  const scripts = /* @__PURE__ */ new Map([
+    [HERMES_PRE_LLM_CALL_EVENT, preScriptPath],
+    [HERMES_POST_LLM_CALL_EVENT, postScriptPath]
+  ]);
+  for (const event of HERMES_HOOK_EVENTS) {
+    if (!Array.isArray(hooks[event])) hooks[event] = [];
+    hooks[event].push({
+      command: hermesHookCommand(scripts.get(event), nodePath),
+      timeout: HERMES_HOOK_TIMEOUT_SECONDS,
+      [ENTRY_MARKER_KEY]: ENTRY_MARKER_VALUE,
+      [ENTRY_AGENT_KEY]: "hermes"
+    });
+  }
+  writeHermesConfig(data);
+  return removed;
+}
+function removeHermesHooksConfig() {
+  const path = hermesConfigPath();
+  if (!existsSync(path)) return 0;
+  const data = readHermesConfig();
+  const removed = stripHermesHooks(data);
+  if (removed > 0) writeHermesConfig(data);
+  return removed;
+}
+function firstCommandToken(command) {
+  const s = command.trim();
+  if (!s) return null;
+  const quote = s[0];
+  if (quote === "'" || quote === '"') {
+    const end = s.indexOf(quote, 1);
+    if (end > 1) return s.slice(1, end);
+  }
+  return s.split(/\s+/, 1)[0] ?? null;
+}
+function checkHermesHookHealth() {
+  const path = hermesConfigPath();
+  const empty = {
+    installed: false,
+    nodePaths: [],
+    nodeOk: true,
+    detail: "no hermes hooks installed"
+  };
+  if (!existsSync(path)) return empty;
+  let data;
+  try {
+    data = readHermesConfig();
+  } catch {
+    return empty;
+  }
+  const entriesByEvent = hermesCtxdbEntriesByEvent(data);
+  const installedEvents = HERMES_HOOK_EVENTS.filter(
+    (event) => (entriesByEvent.get(event)?.length ?? 0) > 0
+  );
+  if (installedEvents.length === 0) return empty;
+  const missingEvents = HERMES_HOOK_EVENTS.filter(
+    (event) => (entriesByEvent.get(event)?.length ?? 0) === 0
+  );
+  if (missingEvents.length > 0) {
+    return {
+      installed: true,
+      nodePaths: [],
+      nodeOk: false,
+      detail: `missing ctxdb Hermes hooks: ${missingEvents.join(", ")} \u2014 re-run \`ctxdb setup --agent hermes\``
+    };
+  }
+  const nodePaths = /* @__PURE__ */ new Set();
+  for (const event of HERMES_HOOK_EVENTS) {
+    for (const entry of entriesByEvent.get(event) ?? []) {
+      if (typeof entry.command !== "string") continue;
+      const nodePath = firstCommandToken(entry.command);
+      if (nodePath && (nodePath.includes("/") || nodePath.includes("\\"))) {
+        nodePaths.add(nodePath);
+      }
+    }
+  }
+  if (nodePaths.size === 0) {
+    const allowlist2 = checkHermesHookAllowlist(entriesByEvent);
+    return {
+      installed: true,
+      nodePaths: [],
+      nodeOk: allowlist2.ok,
+      detail: allowlist2.ok ? "hermes pre_llm_call + post_llm_call hooks installed; allowlisted" : allowlist2.detail
+    };
+  }
+  const paths = [...nodePaths];
+  const bad = [];
+  let goodVersion = "";
+  for (const p of paths) {
+    const v = verifyNodeBinary(p);
+    if (!v.ok) bad.push(`${p}: ${v.error}`);
+    else if (!goodVersion) goodVersion = v.version ?? "";
+  }
+  if (bad.length > 0) {
+    return {
+      installed: true,
+      nodePaths: paths,
+      nodeOk: false,
+      detail: `node not executable: ${bad.join("; ")} \u2014 re-run \`ctxdb setup --agent hermes\``
+    };
+  }
+  const allowlist = checkHermesHookAllowlist(entriesByEvent);
+  if (!allowlist.ok) {
+    return {
+      installed: true,
+      nodePaths: paths,
+      nodeOk: false,
+      detail: allowlist.detail
+    };
+  }
+  return {
+    installed: true,
+    nodePaths: paths,
+    nodeOk: true,
+    detail: `hermes pre_llm_call + post_llm_call hooks: ${paths[0]} (${goodVersion}); allowlisted`
+  };
+}
 function codexConfigTomlPath() {
   return join(homedir(), ".codex", "config.toml");
 }
@@ -1390,7 +1773,7 @@ function describeCodexFeatureMutation(status2, createdNew) {
       return "updated ~/.codex/config.toml";
   }
 }
-function runUpgrade(options = {}) {
+async function runUpgrade(options = {}) {
   const agents = options.agent ? [options.agent] : configuredAgents(options.configPath).filter(isBuiltinAgent);
   if (agents.length === 0) {
     return {
@@ -1411,113 +1794,15 @@ function runUpgrade(options = {}) {
   }
   const results = {};
   for (const agent of agents) {
-    results[agent] = upgradeOneAgent(agent);
-  }
-  const anyOk = Object.values(results).some((r) => r.ok);
-  return { ok: anyOk, agents: results };
-}
-function upgradeOneAgent(agent) {
-  const steps = [];
-  const homeCheck = checkAgentHome(agent);
-  steps.push(homeCheck);
-  if (!homeCheck.ok) {
-    return { ok: true, steps, hints: [`${agent}: skipped \u2014 agent home not found`] };
-  }
-  const root = skillInstallRoot(agent);
-  for (const legacy of LEGACY_SKILL_DIRS) {
-    const legacyDir = join(root, legacy);
-    if (!existsSync(legacyDir)) continue;
-    try {
-      rmSync(legacyDir, { recursive: true, force: true });
-      steps.push({ step: "remove-legacy-skill", ok: true, detail: legacyDir });
-    } catch {
-    }
-  }
-  const skillResult = installSkillsTo(root, agent);
-  steps.push(...skillResult.steps);
-  if (!skillResult.ok) return { ok: false, steps };
-  if (agentSupportsHooks(agent)) {
-    const hookPaths = locateHookPaths();
-    if (!hookPaths) {
-      steps.push({ step: "locate-hooks", ok: false, detail: "hook scripts not found in dist/ or src/" });
-      return { ok: false, steps };
-    }
-    const nodePath = process.execPath;
-    const nodeCheck = verifyNodeBinary(nodePath);
-    if (!nodeCheck.ok) {
-      steps.push({ step: "resolve-node", ok: false, detail: `node not executable: ${nodeCheck.error}` });
-      return { ok: false, steps };
-    }
-    try {
-      backupSettingsJson(agent);
-      const removed = stripCtxdbHooks(agent);
-      appendHooks(agent, hookPaths);
-      steps.push({
-        step: "refresh-hooks",
-        ok: true,
-        detail: `${HOOK_EVENTS.length} hooks written (node: ${nodePath})${removed > 0 ? `, replaced ${removed} stale` : ""}`
-      });
-    } catch (err) {
-      steps.push({ step: "refresh-hooks", 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);
-      }
-    } catch {
-    }
-    if (agent === "codex") {
-      steps.push(enableCodexHooksFeature());
-    }
-    const primaryHome = agentHomeDir(agent);
-    const variantHomes = agentHomeDirs(agent).filter((d) => d !== primaryHome && existsSync(d));
-    for (const vHome of variantHomes) {
-      const tag = vHome.split("/").pop() ?? vHome;
-      const vSkillRoot = join(vHome, "skills");
-      const vr = installSkillsTo(vSkillRoot, agent);
-      steps.push(...vr.steps.map((s) => ({ ...s, step: `${tag}:${s.step}` })));
-      try {
-        const vPath = join(vHome, "settings.json");
-        backupSettingsFile(vPath);
-        const vRemoved = stripCtxdbHooksFromFile(vPath);
-        appendHooksToFile(vPath, agent, hookPaths);
-        steps.push({
-          step: `${tag}:refresh-hooks`,
-          ok: true,
-          detail: vRemoved > 0 ? `replaced ${vRemoved} stale` : void 0
-        });
-      } catch (err) {
-        steps.push({ step: `${tag}:refresh-hooks`, ok: false, detail: err?.message ?? String(err) });
-      }
-    }
-  }
-  if (agent === "opencode") {
-    const absEntry = resolveOpencodePluginEntry();
-    if (!absEntry) {
-      steps.push({
-        step: "refresh-opencode-shim",
-        ok: false,
-        detail: "could not resolve plugin entry under @aliyunrds/ctxdb/dist/opencode"
-      });
-      return { ok: false, steps };
-    }
-    try {
-      writeOpencodeShim(absEntry);
-      steps.push({
-        step: "refresh-opencode-shim",
-        ok: true,
-        detail: `${opencodeShimPath()} \u2192 ${absEntry}`
-      });
-    } catch (err) {
-      steps.push({ step: "refresh-opencode-shim", ok: false, detail: err?.message ?? String(err) });
-      return { ok: false, steps };
-    }
+    results[agent] = await runSetup({
+      agent,
+      // Updating local package artifacts must not depend on service
+      // connectivity. Users can run `ctxdb ping` separately.
+      validate: false
+    });
   }
-  return { ok: steps.every((s) => s.ok), steps };
+  const allOk = Object.values(results).every((r) => r.ok);
+  return { ok: allOk, agents: results };
 }
 
 // src/cli/top.ts
@@ -1577,7 +1862,7 @@ async function ping(args) {
 var HELP = `ctxdb setup \u2014 configure an agent
 
 USAGE
-  ctxdb setup [--agent <qoder|qoderwork|codex|claude|opencode>]
+  ctxdb setup [--agent <qoder|qoderwork|codex|claude|opencode|hermes>]
               [--api-key=K] [--base-url=URL] [--user-id=ID]
               [--no-install-skill] [--no-validate] [--json]
 
@@ -1586,9 +1871,13 @@ BEHAVIOR
                    no hooks or skills installed).
   With --agent     Writes agent config + installs hooks + skills for the
                    specified agent harness.
+  Hermes           Also verifies ~/.hermes/shell-hooks-allowlist.json.
+                   Approve pre_llm_call + post_llm_call with
+                   \`hermes --accept-hooks chat\`. It opens interactive chat;
+                   exit after Hermes starts, then rerun ctxdb setup.
 
 FLAGS
-  --agent <name>        Target agent (qoder|qoderwork|codex|claude|opencode)
+  --agent <name>        Target agent (qoder|qoderwork|codex|claude|opencode|hermes)
   --api-key <key>       API key (required on first setup)
   --base-url <url>      Server URL (default: https://context-database.aliyuncs.com)
   --user-id <id>        User bucket (default: "default")
@@ -1615,7 +1904,7 @@ async function setup(args) {
   const json = !!args.flags.json;
   if (agent === "default" && !json && !configuredAgents().includes("default")) {
     process.stderr.write(
-      `hint: creating CLI-only "default" agent (no hooks/skills). Use --agent <claude|qoder|qoderwork|codex|opencode> for full setup.
+      `hint: creating CLI-only "default" agent (no hooks/skills). Use --agent <claude|qoder|qoderwork|codex|opencode|hermes> for full setup.
 `
     );
   }
@@ -1647,11 +1936,11 @@ ${dim("codex hooks \u914D\u7F6E\u540E\uFF0C\u9700\u8981\u91CD\u542F Codex \u5BF9
 var HELP2 = `ctxdb uninstall \u2014 remove hooks + skills
 
 USAGE
-  ctxdb uninstall [--agent <qoder|qoderwork|codex|claude|opencode>] [--purge-config] [--purge-logs] [--purge-all] [--json]
+  ctxdb uninstall [--agent <qoder|qoderwork|codex|claude|opencode|hermes>] [--purge-config] [--purge-logs] [--purge-all] [--json]
 
 DEFAULT BEHAVIOR (no --agent, no purge flags)
   Strips ctxdb hook entries and skill directories for ALL agents (qoder,
-  qoderwork, codex, claude, opencode). Keeps ~/.ctxdb/ctxdb.json (credentials) and ~/.ctxdb/logs/
+  qoderwork, codex, claude, opencode, hermes). Keeps ~/.ctxdb/ctxdb.json (credentials) and ~/.ctxdb/logs/
   so you can re-run \`ctxdb setup\` later without losing configuration.
 
 WITH --agent <name>
@@ -1659,7 +1948,7 @@ WITH --agent <name>
   Other agents remain untouched.
 
 FLAGS
-  --agent <name>   Target a single agent (qoder|qoderwork|codex|claude|opencode)
+  --agent <name>   Target a single agent (qoder|qoderwork|codex|claude|opencode|hermes)
   --purge-config   Also delete ~/.ctxdb/ctxdb.json
   --purge-logs     Also delete ~/.ctxdb/logs/
   --purge-all      Delete everything under ~/.ctxdb/
@@ -1760,8 +2049,8 @@ function isNewerVersion(candidate, current) {
   if (cMin !== uMin) return cMin > uMin;
   return cPat > uPat;
 }
-function runSelfUpdate(currentVersion, passthroughArgs = []) {
-  const method = detectInstallMethod();
+function runSelfUpdate(currentVersion, passthroughArgs = [], options = {}) {
+  const method = options.installMethod ?? detectInstallMethod();
   if (method !== "npm") {
     return {
       ok: false,
@@ -1772,9 +2061,12 @@ function runSelfUpdate(currentVersion, passthroughArgs = []) {
   }
   const check = checkLatestVersion(currentVersion);
   if (check.error) {
-    process.stderr.write(`ctxdb: npm view failed (${check.error}), skipping self-update
-`);
-    return { ok: true, updated: false, fromVersion: currentVersion };
+    return {
+      ok: false,
+      updated: false,
+      fromVersion: currentVersion,
+      error: `npm view failed: ${check.error}`
+    };
   }
   if (!check.isNewer) {
     process.stderr.write(`ctxdb: package already up to date (v${currentVersion})
@@ -1796,10 +2088,10 @@ function runSelfUpdate(currentVersion, passthroughArgs = []) {
       error: spawnFailureMessage(install, "npm install -g")
     };
   }
-  process.stderr.write(`ctxdb: package updated to v${check.latest}, refreshing skills/hooks...
+  process.stderr.write(`ctxdb: package updated to v${check.latest}, running setup...
 `);
-  const upgradeArgs = ["upgrade", ...passthroughArgs];
-  const refresh = spawnSync(ctxdbCommand(), upgradeArgs, {
+  const setupArgs = ["update", "--no-self-update", ...passthroughArgs];
+  const refresh = spawnSync(ctxdbCommand(), setupArgs, {
     stdio: "inherit",
     encoding: "utf-8",
     shell: process.platform === "win32"
@@ -1809,7 +2101,8 @@ function runSelfUpdate(currentVersion, passthroughArgs = []) {
     updated: true,
     fromVersion: currentVersion,
     toVersion: check.latest,
-    error: refresh.status !== 0 ? spawnFailureMessage(refresh, "ctxdb upgrade") : void 0
+    error: refresh.status !== 0 ? spawnFailureMessage(refresh, "ctxdb setup") : void 0,
+    failureHandled: refresh.status !== null && refresh.status !== 0
   };
 }
 
@@ -1817,58 +2110,68 @@ function runSelfUpdate(currentVersion, passthroughArgs = []) {
 var HELP3 = `ctxdb upgrade \u2014 refresh skills + hooks
 
 USAGE
-  ctxdb upgrade [--agent <qoder|qoderwork|codex|claude|opencode>] [--self-update] [--json]
+  ctxdb upgrade [--agent <qoder|qoderwork|codex|claude|opencode|hermes>] [--no-self-update] [--json]
 
 BEHAVIOR
-  Refreshes skill files and hook entries for configured agents without
-  touching credentials. Designed for the post-npm-update path.
+  Pulls the latest @aliyunrds/ctxdb package from npm, then re-runs setup
+  for configured agents using their existing credentials.
 
-  Without --agent: upgrades all configured built-in agents.
-  With --agent:    upgrades only the specified agent.
+  Without --agent: sets up all configured built-in agents.
+  With --agent:    sets up only the specified agent.
 
 FLAGS
-  --agent <name>   Target a single agent (qoder|qoderwork|codex|claude|opencode)
-  --self-update    Also pull latest package from npm before upgrading
+  --agent <name>   Target a single agent (qoder|qoderwork|codex|claude|opencode|hermes)
+  --self-update    Pull latest package from npm (enabled by default)
+  --no-self-update Skip the npm package update and only re-run setup
   --json           Machine-readable JSON output
 `;
-function upgrade(args) {
+var MANUAL_UPDATE_HINT = "Automatic update failed. Please run manually:\n  npm install -g @aliyunrds/ctxdb\n  ctxdb setup";
+function printUpdateFailure(error, json) {
+  if (json) {
+    process.stdout.write(JSON.stringify({ ok: false, error, hint: MANUAL_UPDATE_HINT }) + "\n");
+    return;
+  }
+  process.stderr.write(`ctxdb: automatic update/setup failed: ${error}
+${MANUAL_UPDATE_HINT}
+`);
+}
+async function upgrade(args) {
   if (args.flags.help || args.flags.h) {
     process.stdout.write(HELP3);
     return 0;
   }
-  const selfUpdate = !!args.flags["self-update"];
+  if (args.flags["self-update"] && args.flags["no-self-update"]) {
+    process.stderr.write("--self-update and --no-self-update cannot be used together\n");
+    return 2;
+  }
+  const agentFlag = args.flags.agent;
+  if (agentFlag && agentFlag !== "default" && !isBuiltinAgent(agentFlag)) {
+    process.stderr.write(
+      `unknown --agent: ${agentFlag} (expected one of ${SUPPORTED_AGENTS.join(" / ")})
+`
+    );
+    return 2;
+  }
+  const selfUpdate = !args.flags["no-self-update"];
   if (selfUpdate) {
     const passthrough = [];
-    const agentFlag2 = args.flags.agent;
-    if (agentFlag2) passthrough.push("--agent", agentFlag2);
+    if (agentFlag) passthrough.push("--agent", agentFlag);
     if (args.flags.json) passthrough.push("--json");
     const result2 = runSelfUpdate(PACKAGE_VERSION, passthrough);
     if (!result2.ok) {
-      if (args.flags.json) {
-        process.stdout.write(JSON.stringify({ ok: false, error: result2.error }) + "\n");
-      } else {
-        process.stderr.write(`ctxdb: self-update failed: ${result2.error}
-`);
-      }
+      if (result2.failureHandled) return 1;
+      printUpdateFailure(result2.error ?? "unknown error", !!args.flags.json);
       return 1;
     }
     if (result2.updated) {
       return 0;
     }
   }
-  const agentFlag = args.flags.agent;
   if (agentFlag === "default") {
     process.stderr.write("nothing to upgrade for default agent (no hooks or skills)\n");
     return 0;
   }
-  if (agentFlag && !isBuiltinAgent(agentFlag)) {
-    process.stderr.write(
-      `unknown --agent: ${agentFlag} (expected one of ${SUPPORTED_AGENTS.join(" / ")})
-`
-    );
-    return 2;
-  }
-  const result = runUpgrade({ agent: agentFlag });
+  const result = await runUpgrade({ agent: agentFlag });
   if (result.ok) {
     try {
       writeInstalledPkgVersion(PACKAGE_VERSION);
@@ -1876,12 +2179,22 @@ function upgrade(args) {
     }
   }
   const json = !!args.flags.json;
+  const detail = result.hints?.[0] ?? "ctxdb setup failed";
+  if (!result.ok && json) {
+    process.stdout.write(
+      JSON.stringify({ ...result, error: detail, hint: MANUAL_UPDATE_HINT }, null, 2) + "\n"
+    );
+    return 1;
+  }
   printResult(result, json);
   if (!json && result.hints) {
     for (const h of result.hints) process.stderr.write(`
 ${h}
 `);
   }
+  if (!result.ok) {
+    printUpdateFailure(detail, false);
+  }
   return result.ok ? 0 : 1;
 }
 
@@ -2000,12 +2313,13 @@ function projectKnowledgeChunks(resp, flags) {
   const r = resp;
   const k = r.knowledge;
   if (!k || typeof k !== "object") return resp;
-  const chunks = k.chunks;
+  const knowledge = k;
+  const chunks = knowledge.chunks;
   if (!Array.isArray(chunks)) return resp;
-  const project = flags.verbose ? compactChunk : minimalChunk;
+  const normalized = flags.verbose ? compactKbQueryResponse(knowledge) : minimalKbQueryResponse(knowledge);
   return {
     ...r,
-    knowledge: { ...k, chunks: chunks.map(project) }
+    knowledge: { ...knowledge, ...normalized }
   };
 }
 async function memoryList(args) {
@@ -2194,7 +2508,7 @@ USAGE
   ctxdb <command> [args] [--flags]
 
 COMMANDS
-  setup [--agent <qoder|qoderwork|codex|claude|opencode>]
+  setup [--agent <qoder|qoderwork|codex|claude|opencode|hermes>]
         [--api-key=K] [--base-url=URL] [--user-id=ID]
         [--no-install-skill] [--no-validate] [--json]
                                  Without --agent \u2192 writes agents.default (CLI-only, no hooks/skills)
@@ -2203,6 +2517,9 @@ COMMANDS
                                  Codex      \u2192 writes agents.codex config + ~/.codex/hooks.json hooks + skill
                                  Claude     \u2192 writes agents.claude config + ~/.claude/settings.json hooks + skill
                                  OpenCode   \u2192 writes agents.opencode config + ~/.config/opencode/plugins/ctxdb.ts shim + skill
+                                 Hermes     \u2192 writes agents.hermes config + ~/.hermes/config.yaml pre/post_llm_call hooks + skill
+                                              Approve pre_llm_call + post_llm_call with \`hermes --accept-hooks chat\`
+                                              (opens interactive chat; exit after Hermes starts)
   status [--agent <name>] [--json]
   ping [--agent <name>] [--json]
   uninstall [--agent <name>] [--purge-config] [--purge-logs] [--purge-all] [--json]
@@ -2213,15 +2530,16 @@ COMMANDS
                                  --purge-logs   also deletes ~/.ctxdb/logs/.
                                  --purge-all    deletes everything under ~/.ctxdb/
                                  (does not run npm uninstall).
-  upgrade|update [--agent <name>] [--self-update] [--json]
-                                 Refresh skills + hooks. --self-update also
-                                 pulls latest package from npm.
+  upgrade|update [--agent <name>] [--no-self-update] [--json]
+                                 Pull latest package from npm, then re-run
+                                 setup. Self-update is enabled by default.
 
   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.
+                                 Graph synthesis moves to non-citable graph_context.
                                  --verbose adds doc_name/kb_id/doc_id/tags.
                                  --raw ships server response verbatim.
   memory list [--agent=<name>] [--page-size=100] [--category=...]
@@ -2241,6 +2559,7 @@ COMMANDS
                     [--verbose] [--raw]
                                  Standalone KB recall (independent of memory).
                                  Default: minimal {content, score} per chunk.
+                                 Graph synthesis moves to non-citable graph_context.
                                  --verbose: compact view adds doc_name/kb_id/
                                  doc_id?/tags? for citation.
                                  --raw: server response verbatim (curl parity).
@@ -2263,7 +2582,7 @@ HOOK ENV VARS:
   CTXDB_SKIP_HOOKS=TRUE       Hook/plugin entrypoints exit immediately.
                               Direct ctxdb CLI commands are unchanged.
 
-CONFIG: ~/.ctxdb/ctxdb.json (agents.default / agents.qoder / agents.qoderwork / agents.codex / agents.claude / agents.opencode)
+CONFIG: ~/.ctxdb/ctxdb.json (agents.default / agents.qoder / agents.qoderwork / agents.codex / agents.claude / agents.opencode / agents.hermes)
 LOGS:   ~/.ctxdb/logs/ctxdb.log
 `;
 var ROUTES = {
@@ -2341,7 +2660,7 @@ async function main(argv = process.argv.slice(2)) {
 }
 main().then(
   (code) => {
-    if (typeof code === "number") process.exit(code);
+    if (typeof code === "number") process.exitCode = code;
   },
   (err) => {
     process.stderr.write(`error: ${err?.message ?? err}
@@ -2349,7 +2668,7 @@ main().then(
     if (process.env.RDS_CTXDB_DEBUG === "1" && err?.stack) {
       process.stderr.write(err.stack + "\n");
     }
-    process.exit(1);
+    process.exitCode = 1;
   }
 );
 export {