@aliyunrds/ctxdb 1.0.1-beta.2 → 1.0.1

package/README.md

@@ -9,8 +9,9 @@ Unified access layer for RDS ContextDatabase. One `ctxdb` CLI (memory + KB ops),
 | **codex** | ✅ UserPromptSubmit + Stop + SessionStart | `~/.codex/skills/ctxdb/` | hooks-driven (auto capture/recall) |
 | **claude** | ✅ UserPromptSubmit + Stop + SessionStart | `~/.claude/skills/ctxdb/` | hooks-driven (auto capture/recall) |
 | **opencode** | Plugin shim (`~/.config/opencode/plugins/ctxdb.ts`) | `~/.config/opencode/skills/` | in-process plugin (auto capture/recall + KB catalog injection) |
+| **hermes** | ✅ `pre_llm_call` + `post_llm_call` | `~/.hermes/skills/` | shell hooks (auto capture/recall + first-turn warmup) |
 
-Config and logs live under `~/.ctxdb/`. `~/.ctxdb/ctxdb.json` is one file, but runtime config is isolated per agent under `agents.qoder`, `agents.qoderwork`, `agents.codex`, `agents.claude`, and `agents.opencode`. (Pre-2026-05-23 installs used `~/.ctxdb.json` at the home root; running `ctxdb setup --agent <name>` migrates the file into the selected agent section.)
+Config and logs live under `~/.ctxdb/`. `~/.ctxdb/ctxdb.json` is one file, but runtime config is isolated per agent under `agents.qoder`, `agents.qoderwork`, `agents.codex`, `agents.claude`, `agents.opencode`, and `agents.hermes`. (Pre-2026-05-23 installs used `~/.ctxdb.json` at the home root; running `ctxdb setup --agent <name>` migrates the file into the selected agent section.)
 
 ## Install
 
@@ -27,6 +28,8 @@ ctxdb setup --agent codex --api-key ctxdb-...
 ctxdb setup --agent claude --api-key ctxdb-...
 # OpenCode (plugin shim + skill)
 ctxdb setup --agent opencode --api-key ctxdb-...
+# Hermes (pre_llm_call recall/warmup + post_llm_call capture + skill; macOS/Linux)
+ctxdb setup --agent hermes --api-key ctxdb-...
 
 # --base-url defaults to https://context-database.aliyuncs.com (public prod).
 #   Pass --base-url <host> only if you target a different deployment
@@ -39,9 +42,40 @@ ctxdb setup --agent opencode --api-key ctxdb-...
 ctxdb status --json
 ```
 
-Setup first checks that the target agent home exists (`~/.qoder`, `~/.qoderwork`, `~/.codex`, or `~/.claude`). If the directory is missing, install or start that agent once before running `ctxdb setup --agent <name>`. OpenCode is XDG-style: setup creates `~/.config/opencode` and `~/.config/opencode/plugins` when they are missing.
+Setup first checks that the target agent home exists (`~/.qoder`, `~/.qoderwork`, `~/.codex`, or `~/.claude`). If the directory is missing, install or start that agent once before running `ctxdb setup --agent <name>`. OpenCode and Hermes are config-dir style: setup creates `~/.config/opencode` / `~/.hermes` when they are missing.
 
-For **qoder**, **qoderwork**, **codex**, and **claude**, restart the harness (CLI: just exit + restart; app: Cmd+R or quit/relaunch) so it picks up the new hooks/skill. For **codex**, setup also writes `[features].hooks = true` into `~/.codex/config.toml` (creating the file if missing) — Codex won't fire any hook entries without it. On first use Codex may prompt you to trust the new hook commands. For **opencode**, restart OpenCode so it loads `~/.config/opencode/plugins/ctxdb.ts`.
+For **qoder**, **qoderwork**, **codex**, and **claude**, restart the harness (CLI: just exit + restart; app: Cmd+R or quit/relaunch) so it picks up the new hooks/skill. For **codex**, setup also writes `[features].hooks = true` into `~/.codex/config.toml` (creating the file if missing) — Codex won't fire any hook entries without it. On first use Codex may prompt you to trust the new hook commands. For **opencode**, restart OpenCode so it loads `~/.config/opencode/plugins/ctxdb.ts`. For **hermes**, setup also checks `~/.hermes/shell-hooks-allowlist.json`; it reports setup as incomplete until both ctxdb hook commands are approved.
+
+Hermes owns this security allowlist, so ctxdb only checks it and never writes approvals. Approve the ctxdb `pre_llm_call` and `post_llm_call` hooks with:
+
+```sh
+hermes --accept-hooks chat
+```
+
+This command opens an interactive chat. After Hermes starts, exit the chat and rerun `ctxdb setup --agent hermes`; the allowlist check should then pass.
+
+The two ctxdb events are `pre_llm_call` and `post_llm_call`. `ctxdb status --agent hermes` also verifies their exact `(event, command)` pairs and reports the specific missing approval.
+
+## Update
+
+`ctxdb update` (alias: `ctxdb upgrade`) now updates the package from npm by default, then re-runs the setup lifecycle for every configured built-in agent using the credentials already stored in `~/.ctxdb/ctxdb.json`:
+
+```sh
+ctxdb update
+
+# Limit setup to one configured agent.
+ctxdb update --agent codex
+
+# Skip the npm step and only re-run setup (also used internally after install).
+ctxdb update --no-self-update
+```
+
+The existing `--self-update` flag remains accepted for compatibility, but is no longer required. If the npm version check, global install, or setup pass fails, ctxdb prints the manual recovery commands:
+
+```sh
+npm install -g @aliyunrds/ctxdb
+ctxdb setup
+```
 
 ## What it does
 
@@ -50,24 +84,30 @@ For **qoder**, **qoderwork**, **codex**, and **claude**, hooks fire automaticall
 | Trigger | Hook | What runs |
 |---|---|---|
 | Session starts | `SessionStart` | Build a short cwd/git-signal query, recall relevant memories, and inject warm-up context as `additionalContext` |
-| User submits a prompt | `UserPromptSubmit` | Search `/v3/memories/search/`, format a `<recalled-memories>` block, inject as additional context. **By default only memory is recalled.** Set `recall_knowledge: true` in the selected agent config to also pull KB chunks into a `<external-knowledge>` block; otherwise the recommended path for KB is the agent calling `ctxdb kb search --agent <name>` explicitly when the user asks (see SKILL.md) |
+| User submits a prompt | `UserPromptSubmit` | Search `/v3/memories/search/`, format a `<recalled-memories>` block, inject as additional context. **By default only memory is recalled.** Set `recall_knowledge: true` in the selected agent config to also pull KB context into an `<external-knowledge>` block; graph synthesis and document evidence are labeled separately inside that wrapper. Otherwise the recommended path for KB is the agent calling `ctxdb kb search --agent <name>` explicitly when the user asks (see SKILL.md) |
 | Agent finishes its turn | `Stop` | Read transcript, detect KB-upload turns and skip capture (so uploaded content doesn't bleed into long-term memory), slice the current turn, sanitize the input, POST to memory store |
 
 Implementation note: qoder/Claude consume the JSON `hookSpecificOutput.additionalContext` shape; Codex has been verified on this machine through `~/.codex/hooks.json`, `[features].hooks = true`, and hook audit logs, where non-empty stdout from `UserPromptSubmit`/`SessionStart` is treated as injected context. The same hook core is shared; setup passes `--agent=<name>` so each hook reads its own config section.
 
 For **opencode**, `ctxdb setup --agent opencode` copies the self-contained plugin bundle to `~/.config/opencode/plugins/ctxdb-bundle.js` and writes a re-export shim at `~/.config/opencode/plugins/ctxdb.ts` referencing it via the relative path `./ctxdb-bundle.js` (Bun on Windows can't resolve absolute-path specifiers from a .ts shim). `ctxdb upgrade --agent opencode` re-copies the bundle + refreshes the shim.
 
+For **hermes**, `ctxdb setup --agent hermes` writes two shell hooks under `~/.hermes/config.yaml`:
+
+- `pre_llm_call` maps to recall on each user prompt and first-turn warmup. Hermes does not persist hook context into conversation history, so ctxdb re-injects the KB catalog on every user turn even when `kb_catalog_injection` keeps its default `"session_start"` value; this prevents the catalog from disappearing after turn one.
+- stdout uses Hermes' `{"context":"..."}` protocol.
+- `post_llm_call` captures `extra.user_message` + `extra.assistant_response` without a transcript file, while `extra.conversation_history` supplies current-turn tool calls for the B-3c KB-upload guard.
+
 ## CLI
 
 `ctxdb` ships 18 subcommands:
 
-- **Top-level**: `setup` / `status` / `ping` / `uninstall` / `upgrade`
+- **Top-level**: `setup` / `status` / `ping` / `uninstall` / `update` (`upgrade` alias)
 - **Memory**: `memory add|search|list|get|update|delete`
 - **KB**: `kb upload-text|upload-file|list|documents-list|document-get|search`
 
 See `ctxdb --help`.
 
-`setup` without `--agent` writes `agents.default` in `~/.ctxdb/ctxdb.json` (CLI-only, no hooks or skills); with `--agent <qoder|qoderwork|codex|claude|opencode>` it writes agent config and installs hooks/plugins + skills for that harness. Memory and KB commands also accept `--agent <name>` so agents use their own config section; when omitted, `CTXDB_AGENT` env wins, otherwise `agents.default` is used. `uninstall` without `--agent` loops every supported agent; with `--agent <name>` it targets just that one. `teardown` is an alias for `uninstall`.
+`setup` without `--agent` writes `agents.default` in `~/.ctxdb/ctxdb.json` (CLI-only, no hooks or skills); with `--agent <qoder|qoderwork|codex|claude|opencode|hermes>` it writes agent config and installs hooks/plugins + skills for that harness. Memory and KB commands also accept `--agent <name>` so agents use their own config section; when omitted, `CTXDB_AGENT` env wins, otherwise `agents.default` is used. `uninstall` without `--agent` loops every supported agent; with `--agent <name>` it targets just that one. `teardown` is an alias for `uninstall`.
 
 `memory add … --no-infer` stores the text verbatim (skips server-side LLM
 fact-extraction). Use it when the user explicitly asks for a verbatim
@@ -81,6 +121,32 @@ search). The SKILL points the agent here when the user explicitly asks for
 KB lookup ("结合知识库查询" / "从知识库召回"). `--kb` is comma-separated;
 omit it to search across all KBs.
 
+Default and `--verbose` search output is graph-aware. Ordinary document
+evidence remains in `chunks`; a GraphRAG synthesis row is moved to the optional
+`graph_context` object and is explicitly non-citable:
+
+```json
+{
+  "graph_context": {
+    "type": "graph_context",
+    "content": "...",
+    "knowledge_base_ids": ["kb-id"],
+    "citation_eligible": false
+  },
+  "chunks": [{ "content": "direct document evidence", "score": 0.73 }],
+  "total": 1
+}
+```
+
+`--verbose` adds source fields to document chunks plus `source_label` / `tags`
+to graph context. `--raw` is unchanged and returns the server response verbatim,
+including the synthetic graph row inside `chunks`. Agents use graph context for
+relationship understanding and, only when direct evidence is missing, at most
+one layer of up to three targeted document searches; final claims and citations
+come from document chunks. A future server contract should expose an explicit
+graph result type and graph source document/chunk IDs so clients no longer need
+tag/label detection and can provide real provenance.
+
 ## Configuration
 
 Lives at `~/.ctxdb/ctxdb.json` (co-located with logs at `~/.ctxdb/logs/`). Schema:
@@ -105,12 +171,13 @@ Lives at `~/.ctxdb/ctxdb.json` (co-located with logs at `~/.ctxdb/logs/`). Schem
     "qoderwork": { "...": "same schema, independent values" },
     "codex": { "...": "same schema, independent values" },
     "claude": { "...": "same schema, independent values" },
-    "opencode": { "...": "same schema, independent values" }
+    "opencode": { "...": "same schema, independent values" },
+    "hermes": { "...": "same schema, independent values" }
   }
 }
 ```
 
-Agent selection is driven by `--agent <qoder|qoderwork|codex|claude|opencode|default>` on every CLI invocation, falling back to `CTXDB_AGENT` env, then to `default`. There is no `default_agent` field — older installs that have one written get it dropped on the next save.
+Agent selection is driven by `--agent <qoder|qoderwork|codex|claude|opencode|hermes|default>` on every CLI invocation, falling back to `CTXDB_AGENT` env, then to `default`. There is no `default_agent` field — older installs that have one written get it dropped on the next save.
 
 Field reference:
 
@@ -119,7 +186,7 @@ Field reference:
 | `user_id` | str | `"default"` | mem0-layer bucket key on every capture/recall call. The server's tenant isolation runs on `member_id` (injected from `X-API-Key`), so this is an optional per-user/agent slice. Override with `ctxdb setup --agent <a> --user-id <bucket>` or `CTXDB_USER_ID=<bucket>` when you need to isolate this install from another access layer or machine sharing the same workspace |
 | `agent_id` | str | null | Optional scope dimension on every capture/recall call. **Default null = not sent** — the server counts `agent_id` as scope on the search path, so emitting it by default would narrow every existing user's recall. Set only when you want per-agent isolation: `CTXDB_AGENT_ID=<id>` (env-only; no setup flag) |
 | `app_id` | str | null | Optional app-scope dimension, same contract as `agent_id` (default null = not sent). Set via `CTXDB_APP_ID=<id>` (env-only) |
-| `auto_capture` | bool | `true` | Stop hook captures each turn into long-term memory for the selected agent |
+| `auto_capture` | bool | `true` | End-of-turn hook/plugin captures each turn into long-term memory for the selected agent |
 | `auto_recall` | bool | `true` | UserPromptSubmit hook recalls memory on each user prompt for the selected agent |
 | `warmup_recall` | bool | `false` | SessionStart hook recalls cwd/git-related memories for the selected agent. **Default is off** — open it per-agent when you want session-start warmup (adds one bounded, circuit-protected recall call on session start) |
 | `recall_knowledge` | bool | `false` | When `auto_recall` is on, also pull KB chunks alongside memory. Default is **off** — the recommended KB-recall path is the agent calling `kb search --agent <name>` explicitly when the user asks |
@@ -131,7 +198,7 @@ Env-var overrides apply to the selected agent config (env wins): `CTXDB_AGENT` /
 
 Hook/plugin escape hatch: set `CTXDB_SKIP_HOOKS=TRUE` on the agent process to make all ctxdb hook entrypoints exit immediately before reading config or calling the API. Direct `ctxdb memory` / `ctxdb kb` / `ctxdb setup` CLI commands are unchanged.
 
-`run_id` is **not** env-driven: the Stop hook reads the host's `session_id` from the hook payload (Qoder / Codex / Claude Code all pass it at the top level; opencode reads `ev.properties.sessionID`) and sends it as `run_id` on capture only, so the server can associate turns within one session for richer extraction context. Recall never sends `run_id`. If the payload has no `session_id`, `run_id` is omitted and capture proceeds normally (the server falls back to baseMessages).
+`run_id` is **not** env-driven: capture reads the host's session id from the lifecycle payload (Qoder / Codex / Claude Code and Hermes pass `session_id`; opencode reads `ev.properties.sessionID`) and sends it as `run_id` on capture only, so the server can associate turns within one session for richer extraction context. Recall never sends `run_id`. If the payload has no session id, `run_id` is omitted and capture proceeds normally (the server falls back to baseMessages).
 
 ## Architecture
 
@@ -177,6 +244,7 @@ ctxdb uninstall --agent qoderwork
 ctxdb uninstall --agent codex
 ctxdb uninstall --agent claude
 ctxdb uninstall --agent opencode
+ctxdb uninstall --agent hermes
 
 # Wholesale across all agents, but keep config + logs for re-setup later:
 ctxdb uninstall                  # all agents, keeps ~/.ctxdb/{ctxdb.json,logs/}
@@ -186,7 +254,7 @@ ctxdb uninstall --purge-logs     # also deletes ~/.ctxdb/logs/
 
 ### What uninstall does (and doesn't) touch
 
-- **Hook entries in `~/.qoder/settings.json`, `~/.codex/hooks.json`, and `~/.claude/settings.json`**: stripped precisely by marker (`_ctxdb = @aliyunrds/ctxdb`, plus legacy keys `_ctxdbQoder` / `_ctxdbPackage` and the legacy `@aliyunrds/ctxdb-qoder` value for installs predating the unified marker). Any hooks you added yourself stay. A timestamped `*.bak-ctxdb-<TS>` is written before each modification (rotation keeps the 5 most recent).
+- **Hook entries in `~/.qoder/settings.json`, `~/.qoderwork/settings.json`, `~/.codex/hooks.json`, `~/.claude/settings.json`, and `~/.hermes/config.yaml`**: stripped precisely by marker (`_ctxdb = @aliyunrds/ctxdb`, plus legacy keys `_ctxdbQoder` / `_ctxdbPackage` and the legacy `@aliyunrds/ctxdb-qoder` value for installs predating the unified marker). Any hooks you added yourself stay. A timestamped `*.bak-ctxdb-<TS>` is written before each modification (rotation keeps the 5 most recent).
 - **Skill directories**: `~/.<agent>/skills/ctxdb/` for each set-up agent, plus legacy dirs (`ctxdb-qoder`, `rds-ctxdb-qoder`, `qoder-ctxdb`) under `~/.qoder/skills/` from older package names.
 - **`~/.ctxdb/` state**: only with `--purge-config` / `--purge-logs` / `--purge-all`. Defensive: `--purge-all` removes the `~/.ctxdb/` root only if it's empty after the named files are deleted (won't blanket-rm an unknown directory).
 - **`~/.codex/config.toml` `[features].hooks`**: **NOT** reverted. Setup adds `hooks = true` so Codex will fire ctxdb's hook entries; uninstall leaves the flag alone because (a) the user may have wanted it on for non-ctxdb hooks, and (b) it's harmless when `~/.codex/hooks.json` is empty. If you want it off, edit the file by hand.

package/dist/{chunk-TKMIWM6Q.js → chunk-6FZL67GH.js}

@@ -262,7 +262,7 @@ function extractErrorDetail(text, fallback) {
 // src/lib/agents.ts
 import { homedir as homedir2 } from "os";
 import { join as join3 } from "path";
-var SUPPORTED_AGENTS = ["qoder", "qoderwork", "codex", "claude", "opencode"];
+var SUPPORTED_AGENTS = ["qoder", "qoderwork", "codex", "claude", "opencode", "hermes"];
 function isBuiltinAgent(v) {
   return typeof v === "string" && SUPPORTED_AGENTS.includes(v);
 }
@@ -282,6 +282,8 @@ function agentHomeDir(agent) {
       return join3(homedir2(), ".claude");
     case "opencode":
       return join3(homedir2(), ".config", "opencode");
+    case "hermes":
+      return join3(homedir2(), ".hermes");
   }
 }
 var AGENT_VARIANT_HOMES = {

package/dist/{chunk-CYCD234A.js → chunk-EUQ3OFCQ.js}

@@ -1,15 +1,42 @@
 #!/usr/bin/env node
 import {
   listKnowledgeBases
-} from "./chunk-6S5RJYBC.js";
+} from "./chunk-UH7AJF6F.js";
 import {
   isConnectionError,
   resetCircuit,
   tripCircuit
-} from "./chunk-UULWJJT4.js";
+} from "./chunk-TGVURF54.js";
 import {
   CtxdbError
-} from "./chunk-TKMIWM6Q.js";
+} from "./chunk-6FZL67GH.js";
+
+// src/lib/kb-catalog.ts
+function sanitizeKeyEntities(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const e of raw) {
+    if (typeof e !== "string") continue;
+    const cleaned = e.replace(/\s+/g, " ").trim();
+    if (cleaned.length > 0) out.push(cleaned);
+  }
+  return out;
+}
+async function fetchKbCatalogBlock(client, agent) {
+  const kbs = await listKnowledgeBases(client);
+  const active = kbs.filter((kb) => kb.status === "active");
+  if (active.length === 0) return "";
+  const lines = active.map((kb) => {
+    const ents = sanitizeKeyEntities(kb.key_entities);
+    return ents.length > 0 ? `\xB7 ${kb.name}: ${ents.join(", ")}` : `\xB7 ${kb.name}`;
+  });
+  return [
+    "<available-knowledge-bases>",
+    `When you identify that relevant information may exist in the knowledge bases below, you MUST run \`ctxdb kb search "<query>" --kb=<name> --agent=${agent}\` with targeted keywords after initial analysis to supplement and correct your approach. For keyword-based KB search, keep each single query focused: use at most 5 keywords or short phrases; run multiple targeted searches if more are needed. When \`graph_context\` is returned, use it only for relationship understanding and query planning, never as direct evidence. If document \`chunks\` are insufficient, derive up to 3 focused queries and run one additional search layer in the same KB; base final answers and citations only on document \`chunks\`. Knowledge bases:`,
+    ...lines,
+    "</available-knowledge-bases>"
+  ].join("\n");
+}
 
 // src/lib/recall-orchestrator.ts
 import {
@@ -18,6 +45,7 @@ import {
 
 // src/lib/format-recall.ts
 import {
+  RECALLED_MEMORIES_SAFETY_NOTICE,
   formatRecalledMemoriesBlock
 } from "@aliyunrds/ctxdb-shared";
 var OPEN_TAG = "<recalled-memories>";
@@ -48,6 +76,10 @@ function slimRewrite(raw, userId, memoryCount) {
       out.push(line);
       continue;
     }
+    if (line === RECALLED_MEMORIES_SAFETY_NOTICE) {
+      out.push(`${line} `);
+      continue;
+    }
     if (line.startsWith("Stored memories for ")) {
       out.push(`Recalled ${memoryCount} memories for "${userId}":`);
       continue;
@@ -146,34 +178,7 @@ async function recallTurn(prompt, cfg, client, agent = "default") {
   };
 }
 
-// src/lib/kb-catalog.ts
-function sanitizeKeyEntities(raw) {
-  if (!Array.isArray(raw)) return [];
-  const out = [];
-  for (const e of raw) {
-    if (typeof e !== "string") continue;
-    const cleaned = e.replace(/\s+/g, " ").trim();
-    if (cleaned.length > 0) out.push(cleaned);
-  }
-  return out;
-}
-async function fetchKbCatalogBlock(client, agent) {
-  const kbs = await listKnowledgeBases(client);
-  const active = kbs.filter((kb) => kb.status === "active");
-  if (active.length === 0) return "";
-  const lines = active.map((kb) => {
-    const ents = sanitizeKeyEntities(kb.key_entities);
-    return ents.length > 0 ? `\xB7 ${kb.name}: ${ents.join(", ")}` : `\xB7 ${kb.name}`;
-  });
-  return [
-    "<available-knowledge-bases>",
-    `When you identify that relevant information may exist in the knowledge bases below, you MUST run \`ctxdb kb search "<query>" --kb=<name> --agent=${agent}\` with targeted keywords after initial analysis to supplement and correct your approach. For keyword-based KB search, keep each single query focused: use at most 5 keywords or short phrases; run multiple targeted searches if more are needed. Knowledge bases:`,
-    ...lines,
-    "</available-knowledge-bases>"
-  ].join("\n");
-}
-
 export {
-  recallTurn,
-  fetchKbCatalogBlock
+  fetchKbCatalogBlock,
+  recallTurn
 };

package/dist/chunk-FD3AMXVU.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import {
+  fetchKbCatalogBlock,
+  recallTurn
+} from "./chunk-EUQ3OFCQ.js";
+import {
+  isCircuitOpen
+} from "./chunk-TGVURF54.js";
+import {
+  HttpClient,
+  agentFromArgvWithFallback,
+  debug,
+  isComplete,
+  load,
+  setDebug
+} from "./chunk-6FZL67GH.js";
+import {
+  shouldSkipHooks
+} from "./chunk-UEKR2Z3S.js";
+
+// src/hooks/user-prompt-submit.ts
+import { pathToFileURL } from "url";
+async function composeUserPromptSubmit(cfg, agent, client, prompt) {
+  const [recall, kbBlock] = await Promise.all([
+    recallTurn(prompt, cfg, client, agent),
+    cfg.kbCatalogInjection === "user_prompt_submit" ? fetchKbCatalogBlock(client, agent).catch(() => "") : Promise.resolve("")
+  ]);
+  let ctx = recall.additionalContext || "";
+  if (kbBlock) ctx = ctx ? `${ctx}
+
+${kbBlock}` : kbBlock;
+  return { ctx, recall, kbBlock };
+}
+function formatUserPromptSubmitStdout(agent, ctx) {
+  if (agent === "codex") return ctx + "\n";
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: ctx
+    }
+  };
+  return JSON.stringify(out) + "\n";
+}
+async function readStdinJson() {
+  let raw = "";
+  for await (const chunk of process.stdin) raw += chunk;
+  if (!raw.trim()) return {};
+  try {
+    const obj = JSON.parse(raw);
+    return obj && typeof obj === "object" && !Array.isArray(obj) ? obj : {};
+  } catch {
+    return {};
+  }
+}
+async function main() {
+  try {
+    if (shouldSkipHooks()) return 0;
+    const event = await readStdinJson();
+    const { agent, fellBack } = agentFromArgvWithFallback();
+    if (fellBack) {
+      process.stderr.write(
+        `ctxdb recall: agent unspecified, defaulting to ${agent}
+`
+      );
+    }
+    const prompt = typeof event.prompt === "string" ? event.prompt : "";
+    if (!prompt.trim()) return 0;
+    const cfg = load({ agent });
+    setDebug(cfg.debug);
+    debug("recall", "start", { prompt: prompt.slice(0, 200), userId: cfg.userId });
+    if (!isComplete(cfg) || !cfg.autoRecall) {
+      debug("recall", "skip (config incomplete or autoRecall=false)");
+      return 0;
+    }
+    if (isCircuitOpen(agent, cfg.baseUrl)) {
+      debug("recall", "skip (circuit open)");
+      process.stderr.write(`ctxdb recall: skip (circuit_open: ${cfg.baseUrl})
+`);
+      return 0;
+    }
+    const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey, timeoutMs: 5e3 });
+    const { ctx, recall, kbBlock } = await composeUserPromptSubmit(cfg, agent, client, prompt);
+    if (!recall.ok && !recall.additionalContext && !kbBlock) {
+      const reason = recall.reason ?? "no_context";
+      debug("recall", `no result: ${reason}`, recall);
+      if (recall.reason && recall.reason.startsWith("http_error:")) {
+        process.stderr.write(`ctxdb recall: ${recall.reason}
+`);
+      }
+      return 0;
+    }
+    if (!ctx) return 0;
+    debug("recall", `ok, additionalContext length=${ctx.length}`);
+    process.stdout.write(formatUserPromptSubmitStdout(agent, ctx));
+    return 0;
+  } catch (err) {
+    process.stderr.write(`ctxdb recall: unexpected error: ${err?.message ?? err}
+`);
+    return 0;
+  }
+}
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().then((code) => {
+    process.exitCode = code;
+  });
+}
+
+export {
+  composeUserPromptSubmit,
+  formatUserPromptSubmitStdout
+};