@aliyunrds/ctxdb 1.0.0 → 1.0.1-beta.1

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,9 @@ 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.
+
+`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-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([

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,7 @@ import {
   isComplete,
   load,
   setDebug
-} from "../chunk-QHYJ7OXC.js";
+} from "../chunk-TKMIWM6Q.js";
 
 // src/hooks/session-start.ts
 import { pathToFileURL } from "url";

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,7 @@ import {
   isDebug,
   load,
   setDebug
-} from "../chunk-QHYJ7OXC.js";
+} from "../chunk-TKMIWM6Q.js";
 
 // src/lib/capture-orchestrator.ts
 import {
@@ -304,7 +304,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 +373,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,6 +507,10 @@ 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 {
     const event = await readStdinJson();
@@ -516,6 +523,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 +532,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,7 @@ import {
   isComplete,
   load,
   setDebug
-} from "../chunk-QHYJ7OXC.js";
+} from "../chunk-TKMIWM6Q.js";
 
 // src/hooks/user-prompt-submit.ts
 import { pathToFileURL } from "url";

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 });
@@ -944,7 +953,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.1",
   "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",