@aliyunrds/ctxdb 1.0.0 → 1.0.1-beta.2

package/README.md

@@ -117,6 +117,8 @@ Field reference:
 | Key | Type | Default | Meaning |
 |---|---|---|---|
 | `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_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) |
@@ -125,7 +127,11 @@ Field reference:
 | `knowledge_top_k` | int | `6` | KB chunks pulled per recall (only effective when `recall_knowledge: true`) |
 | `debug` | bool | `false` | Verbose hook logging (`~/.ctxdb/logs/ctxdb.log`) |
 
-Env-var overrides apply to the selected agent config (env wins): `CTXDB_AGENT` / `CTXDB_API_KEY` / `CTXDB_BASE_URL` / `CTXDB_USER_ID`.
+Env-var overrides apply to the selected agent config (env wins): `CTXDB_AGENT` / `CTXDB_API_KEY` / `CTXDB_BASE_URL` / `CTXDB_USER_ID` / `CTXDB_AGENT_ID` / `CTXDB_APP_ID`. The last two default to unset — the request body omits `agent_id`/`app_id` entirely; set them only when you want per-agent / per-app scope isolation on the server.
+
+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).
 
 ## Architecture
 

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

@@ -6,10 +6,10 @@ import {
   isConnectionError,
   resetCircuit,
   tripCircuit
-} from "./chunk-PLWEIEFH.js";
+} from "./chunk-UULWJJT4.js";
 import {
   CtxdbError
-} from "./chunk-QHYJ7OXC.js";
+} from "./chunk-TKMIWM6Q.js";
 
 // src/lib/recall-orchestrator.ts
 import {
@@ -109,6 +109,8 @@ async function recallTurn(prompt, cfg, client, agent = "default") {
   if (cfg.recallKnowledge) {
     body.knowledge = { enable: true, top_k: cfg.knowledgeTopK };
   }
+  if (cfg.agentId) body.agent_id = cfg.agentId;
+  if (cfg.appId) body.app_id = cfg.appId;
   let resp;
   try {
     resp = await client.postJson("/v3/memories/search/", body);

package/dist/{chunk-QHYJ7OXC.js → chunk-TKMIWM6Q.js}

@@ -387,6 +387,8 @@ function configFromDisk(raw) {
     apiKey: typeof raw.api_key === "string" && raw.api_key ? raw.api_key : null,
     baseUrl: typeof raw.base_url === "string" && raw.base_url ? String(raw.base_url).replace(/\/+$/, "") : DEFAULT_BASE_URL,
     userId: typeof raw.user_id === "string" && raw.user_id ? raw.user_id : DEFAULT_USER_ID,
+    agentId: typeof raw.agent_id === "string" && raw.agent_id ? raw.agent_id : null,
+    appId: typeof raw.app_id === "string" && raw.app_id ? raw.app_id : null,
     autoCapture: coerceBool(raw.auto_capture, true),
     autoRecall: coerceBool(raw.auto_recall, true),
     warmupRecall: coerceBool(raw.warmup_recall, false),
@@ -402,6 +404,8 @@ function applyEnv(cfg, env) {
   if (env.CTXDB_API_KEY) cfg.apiKey = env.CTXDB_API_KEY;
   if (env.CTXDB_BASE_URL) cfg.baseUrl = env.CTXDB_BASE_URL.replace(/\/+$/, "");
   if (env.CTXDB_USER_ID) cfg.userId = env.CTXDB_USER_ID;
+  if (env.CTXDB_AGENT_ID) cfg.agentId = env.CTXDB_AGENT_ID;
+  if (env.CTXDB_APP_ID) cfg.appId = env.CTXDB_APP_ID;
   return cfg;
 }
 function load(options = {}) {
@@ -437,6 +441,8 @@ function configToDisk(cfg) {
     api_key: cfg.apiKey,
     base_url: cfg.baseUrl,
     user_id: cfg.userId,
+    agent_id: cfg.agentId,
+    app_id: cfg.appId,
     auto_capture: cfg.autoCapture,
     auto_recall: cfg.autoRecall,
     warmup_recall: cfg.warmupRecall,

package/dist/chunk-UEKR2Z3S.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+// src/lib/hook-env.ts
+var CTXDB_SKIP_HOOKS = "CTXDB_SKIP_HOOKS";
+function shouldSkipHooks(env = process.env) {
+  return env[CTXDB_SKIP_HOOKS] === "TRUE";
+}
+
+export {
+  shouldSkipHooks
+};

package/dist/{chunk-PLWEIEFH.js → chunk-UULWJJT4.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   configDir
-} from "./chunk-QHYJ7OXC.js";
+} from "./chunk-TKMIWM6Q.js";
 
 // src/lib/circuit.ts
 import { statSync, writeFileSync, unlinkSync, mkdirSync, readdirSync, readFileSync } from "fs";

package/dist/cli/main.js

@@ -31,7 +31,7 @@ import {
   removeAgent,
   save,
   writeInstalledPkgVersion
-} from "../chunk-QHYJ7OXC.js";
+} from "../chunk-TKMIWM6Q.js";
 
 // src/cli/util.ts
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
@@ -2257,6 +2257,11 @@ AGENT RESOLUTION (when --agent is omitted):
 
 ENV VARS (override selected ~/.ctxdb/ctxdb.json agent config):
   CTXDB_AGENT  CTXDB_API_KEY  CTXDB_BASE_URL  CTXDB_USER_ID
+  CTXDB_AGENT_ID  CTXDB_APP_ID
+
+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)
 LOGS:   ~/.ctxdb/logs/ctxdb.log

package/dist/hooks/pre-tool-use.js

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
+import {
+  shouldSkipHooks
+} from "../chunk-UEKR2Z3S.js";
 
 // src/hooks/pre-tool-use.ts
 async function main() {
+  if (shouldSkipHooks()) return 0;
   for await (const _chunk of process.stdin) {
   }
   return 0;

package/dist/hooks/session-start.js

@@ -2,11 +2,11 @@
 import {
   fetchKbCatalogBlock,
   recallTurn
-} from "../chunk-QPFFMW52.js";
+} from "../chunk-CYCD234A.js";
 import "../chunk-6S5RJYBC.js";
 import {
   isCircuitOpen
-} from "../chunk-PLWEIEFH.js";
+} from "../chunk-UULWJJT4.js";
 import {
   HttpClient,
   agentFromArgvWithFallback,
@@ -14,7 +14,10 @@ import {
   isComplete,
   load,
   setDebug
-} from "../chunk-QHYJ7OXC.js";
+} from "../chunk-TKMIWM6Q.js";
+import {
+  shouldSkipHooks
+} from "../chunk-UEKR2Z3S.js";
 
 // src/hooks/session-start.ts
 import { pathToFileURL } from "url";
@@ -120,6 +123,7 @@ async function readStdinJson() {
 }
 async function main() {
   try {
+    if (shouldSkipHooks()) return 0;
     const event = await readStdinJson();
     const { agent, fellBack } = agentFromArgvWithFallback();
     if (fellBack) {

package/dist/hooks/stop.js

@@ -4,7 +4,7 @@ import {
   isConnectionError,
   resetCircuit,
   tripCircuit
-} from "../chunk-PLWEIEFH.js";
+} from "../chunk-UULWJJT4.js";
 import {
   CtxdbError,
   HttpClient,
@@ -13,7 +13,10 @@ import {
   isDebug,
   load,
   setDebug
-} from "../chunk-QHYJ7OXC.js";
+} from "../chunk-TKMIWM6Q.js";
+import {
+  shouldSkipHooks
+} from "../chunk-UEKR2Z3S.js";
 
 // src/lib/capture-orchestrator.ts
 import {
@@ -304,7 +307,7 @@ function extractSkillSignals(rows) {
 }
 
 // src/lib/capture-orchestrator.ts
-async function captureTurn(transcriptPath, cfg, client, agent = "default") {
+async function captureTurn(transcriptPath, cfg, client, agent = "default", sessionId) {
   if (!cfg.apiKey || !cfg.baseUrl) {
     return { captured: false, reason: "config_incomplete", messageCount: 0 };
   }
@@ -373,6 +376,9 @@ async function captureTurn(transcriptPath, cfg, client, agent = "default") {
     user_id: cfg.userId,
     async_mode: true
   };
+  if (cfg.agentId) payload.agent_id = cfg.agentId;
+  if (cfg.appId) payload.app_id = cfg.appId;
+  if (sessionId) payload.run_id = sessionId;
   let resp;
   try {
     resp = await client.postJson("/v3/memories/add/", payload);
@@ -504,8 +510,13 @@ async function readStdinJson() {
     return {};
   }
 }
+function extractHookSessionId(event) {
+  const v = event.session_id ?? event.sessionId;
+  return typeof v === "string" && v ? v : void 0;
+}
 async function main() {
   try {
+    if (shouldSkipHooks()) return 0;
     const event = await readStdinJson();
     const { agent, fellBack } = agentFromArgvWithFallback();
     if (fellBack) {
@@ -516,6 +527,7 @@ async function main() {
     }
     const transcriptPath = event.transcript_path;
     if (typeof transcriptPath !== "string" || !transcriptPath) return 0;
+    const sessionId = extractHookSessionId(event);
     const cfg = load({ agent });
     setDebug(cfg.debug);
     debug("capture", "start", { transcriptPath, userId: cfg.userId });
@@ -524,7 +536,7 @@ async function main() {
       return 0;
     }
     const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey, timeoutMs: 5e3 });
-    const result = await captureTurn(transcriptPath, cfg, client, agent);
+    const result = await captureTurn(transcriptPath, cfg, client, agent, sessionId);
     if (result.captured) {
       debug("capture", `ok (${result.messageCount} msgs)`, result);
       process.stderr.write(

package/dist/hooks/user-prompt-submit.js

@@ -2,11 +2,11 @@
 import {
   fetchKbCatalogBlock,
   recallTurn
-} from "../chunk-QPFFMW52.js";
+} from "../chunk-CYCD234A.js";
 import "../chunk-6S5RJYBC.js";
 import {
   isCircuitOpen
-} from "../chunk-PLWEIEFH.js";
+} from "../chunk-UULWJJT4.js";
 import {
   HttpClient,
   agentFromArgvWithFallback,
@@ -14,7 +14,10 @@ import {
   isComplete,
   load,
   setDebug
-} from "../chunk-QHYJ7OXC.js";
+} from "../chunk-TKMIWM6Q.js";
+import {
+  shouldSkipHooks
+} from "../chunk-UEKR2Z3S.js";
 
 // src/hooks/user-prompt-submit.ts
 import { pathToFileURL } from "url";
@@ -52,6 +55,7 @@ async function readStdinJson() {
 }
 async function main() {
   try {
+    if (shouldSkipHooks()) return 0;
     const event = await readStdinJson();
     const { agent, fellBack } = agentFromArgvWithFallback();
     if (fellBack) {

package/dist/opencode/index.js

@@ -54,6 +54,8 @@ function applyEnv(cfg, env) {
   if (env.CTXDB_API_KEY) cfg.apiKey = env.CTXDB_API_KEY;
   if (env.CTXDB_BASE_URL) cfg.baseUrl = env.CTXDB_BASE_URL.replace(/\/+$/, "");
   if (env.CTXDB_USER_ID) cfg.userId = env.CTXDB_USER_ID;
+  if (env.CTXDB_AGENT_ID) cfg.agentId = env.CTXDB_AGENT_ID;
+  if (env.CTXDB_APP_ID) cfg.appId = env.CTXDB_APP_ID;
   return cfg;
 }
 function loadOpencodeConfig(options = {}) {
@@ -65,6 +67,8 @@ function loadOpencodeConfig(options = {}) {
     apiKey: typeof section.api_key === "string" && section.api_key ? section.api_key : null,
     baseUrl: typeof section.base_url === "string" && section.base_url ? String(section.base_url).replace(/\/+$/, "") : DEFAULT_BASE_URL,
     userId: typeof section.user_id === "string" && section.user_id ? section.user_id : DEFAULT_USER_ID,
+    agentId: typeof section.agent_id === "string" && section.agent_id ? section.agent_id : null,
+    appId: typeof section.app_id === "string" && section.app_id ? section.app_id : null,
     autoCapture: coerceBool(section.auto_capture, true),
     autoRecall: coerceBool(section.auto_recall, true),
     warmupRecall: coerceBool(section.warmup_recall, false),
@@ -590,6 +594,8 @@ async function searchAndFormatRecall(prompt, cfg, client, timeoutMs) {
   if (cfg.recallKnowledge) {
     body.knowledge = { enable: true, top_k: cfg.knowledgeTopK };
   }
+  if (cfg.agentId) body.agent_id = cfg.agentId;
+  if (cfg.appId) body.app_id = cfg.appId;
   let resp;
   try {
     resp = await client.postJson("/v3/memories/search/", body, { timeoutMs });
@@ -772,7 +778,7 @@ function fingerprintMessages(messages) {
   }
   return h.digest("hex");
 }
-async function runCapture(messages, cfg, client, timeoutMs, lastFingerprint) {
+async function runCapture(messages, cfg, client, timeoutMs, lastFingerprint, sessionId) {
   if (!cfg.autoCapture) return { ...EMPTY2, reason: "auto_capture_disabled" };
   if (!cfg.baseUrl) return { ...EMPTY2, reason: "config_incomplete" };
   if (messages.length === 0) return { ...EMPTY2, reason: "empty_transcript" };
@@ -796,6 +802,9 @@ async function runCapture(messages, cfg, client, timeoutMs, lastFingerprint) {
     user_id: cfg.userId,
     async_mode: true
   };
+  if (cfg.agentId) payload.agent_id = cfg.agentId;
+  if (cfg.appId) payload.app_id = cfg.appId;
+  if (sessionId) payload.run_id = sessionId;
   let resp;
   try {
     resp = await client.postJson("/v3/memories/add/", payload, { timeoutMs });
@@ -816,6 +825,12 @@ async function runCapture(messages, cfg, client, timeoutMs, lastFingerprint) {
   };
 }
 
+// src/hook-env.ts
+var CTXDB_SKIP_HOOKS = "CTXDB_SKIP_HOOKS";
+function shouldSkipHooks(env = process.env) {
+  return env[CTXDB_SKIP_HOOKS] === "TRUE";
+}
+
 // src/hooks.ts
 var SESSION_TTL_MS = 15 * 60 * 1e3;
 var SESSION_MAX = 100;
@@ -861,6 +876,7 @@ function extractTextPrompt(parts) {
   return chunks.join("\n").trim();
 }
 async function buildHooks(input) {
+  if (shouldSkipHooks()) return {};
   const config = loadOpencodeConfig();
   if (!isConfigured(config)) {
     logDebug(
@@ -944,7 +960,8 @@ async function buildHooks(input) {
           rt.config,
           rt.http,
           CAPTURE_TIMEOUT_MS,
-          state.lastFingerprint
+          state.lastFingerprint,
+          sessionID
         );
         if (outcome.captured && outcome.fingerprint) {
           state.lastFingerprint = outcome.fingerprint;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliyunrds/ctxdb",
-  "version": "1.0.0",
+  "version": "1.0.1-beta.2",
   "type": "module",
   "description": "Unified access layer for RDS ContextDatabase: `ctxdb` CLI (memory + KB ops), one-shot `setup --agent <qoder|qoderwork|codex|claude|opencode>` installer, per-agent config, hooks/plugins, and SKILL.md.",
   "license": "Apache-2.0",