@2kw/ai 6.3.0-dev.24 → 6.3.0-dev.31

package/README.md

@@ -88,6 +88,8 @@ kubectl-style contexts switch between organizations and environments:
 2kw context create staging    # Create a new context
 ```
 
+`2kw config set memory true` makes an API-key context send `X-Backbone-Memory: enabled` on `ai respond` and `agents run` calls, which opts those runs into agent memory; `AI_2KW_MEMORY=true|false` overrides it per shell. Runs from a browser-login (session) context are always eligible for agent memory regardless of this setting, so `memory false` only affects API-key contexts.
+
 ## Commands
 
 | Command | Description |
@@ -106,6 +108,7 @@ kubectl-style contexts switch between organizations and environments:
 | `evaluators` | Manage evaluator templates |
 | `scores` | Record and inspect quality scores |
 | `tracing` | Inspect request traces and tracing settings |
+| `memory` | Your agent memory files (list, read, write, delete, forget); member totals and erasure for admins |
 | `providers` | Manage BYOK AI providers |
 | `analytics` | Usage analytics: spend, quality, providers, errors |
 | `billing` | Check subscription tier and usage limits |

package/dist/commands/auth.js

@@ -160,7 +160,12 @@ async function manualLogin(opts) {
         console.error(chalk.red("API key is required."));
         process.exit(1);
     }
-    setContext(contextName, { apiKey, baseUrl });
+    // Carry the memory opt-in over: re-entering a key should not silently turn it off (#721).
+    setContext(contextName, {
+        apiKey,
+        baseUrl,
+        ...(currentCtx?.memory !== undefined ? { memory: currentCtx.memory } : {}),
+    });
     setActiveContext(contextName);
     console.log(chalk.green("Credentials saved successfully."));
     console.log(chalk.dim(`Config stored at: ${store.path}`));

package/dist/commands/config.d.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-declare const ALLOWED_KEYS: readonly ["apiKey", "baseUrl"];
+declare const ALLOWED_KEYS: readonly ["apiKey", "baseUrl", "memory"];
 type ConfigKey = (typeof ALLOWED_KEYS)[number];
 /**
  * Write one config key onto the active context.

package/dist/commands/config.js

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import chalk from "chalk";
 import { store, isJsonOutput, getActiveContext, getActiveContextName, getContextCount, setContext, DEFAULT_BASE_URL, } from "../lib/config.js";
 import { maskApiKey } from "../lib/redact.js";
-const ALLOWED_KEYS = ["apiKey", "baseUrl"];
+const ALLOWED_KEYS = ["apiKey", "baseUrl", "memory"];
 const KEY_ALIASES = {
     "api-key": "apiKey",
     "base-url": "baseUrl",
@@ -43,6 +43,14 @@ export function applyConfigSet(key, value) {
         setContext(contextName, entry);
         return { clearedSession };
     }
+    if (key === "memory") {
+        if (value !== "true" && value !== "false") {
+            throw new Error('memory takes true or false');
+        }
+        entry.memory = value === "true";
+        setContext(contextName, entry);
+        return { clearedSession: false };
+    }
     entry[key] = value;
     setContext(contextName, entry);
     return { clearedSession: false };
@@ -82,7 +90,12 @@ export function makeConfigCommand() {
         const validKey = validateKey(key);
         const ctx = getActiveContext();
         const raw = ctx?.[validKey];
-        const value = raw && validKey === "apiKey" ? maskApiKey(raw) : raw;
+        // A stored "" apiKey stays "" (shown as "(not set)"); only a real key is masked.
+        const value = raw === undefined
+            ? undefined
+            : validKey === "apiKey" && typeof raw === "string"
+                ? raw && maskApiKey(raw)
+                : String(raw);
         if (isJsonOutput(command)) {
             console.log(JSON.stringify({ key: validKey, value: value ?? null }));
         }
@@ -103,6 +116,7 @@ export function makeConfigCommand() {
         const values = {
             apiKey: ctx?.apiKey ? maskApiKey(ctx.apiKey) : undefined,
             baseUrl: ctx?.baseUrl,
+            memory: ctx?.memory === undefined ? undefined : String(ctx.memory),
         };
         if (isJsonOutput(command)) {
             console.log(JSON.stringify(values, null, 2));

package/dist/commands/files.js

@@ -8,40 +8,22 @@ import { formatPage, formatDetail, formatSuccess, withSpinner } from "../lib/out
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
 import { fileToBlob } from "../lib/multipart.js";
 /**
- * Upload a single file with purpose=agent_input|knowledge. Bypasses the typed
- * client the same way convert.ts and transcribe.ts do: the generated types
- * describe the multipart body as an opaque `file: string`, which is not
- * something FormData can produce a match for.
+ * Upload a single file with purpose=agent_input|knowledge. The generated type
+ * describes the "file" part as a binary string, which FormData cannot match,
+ * so the placeholder body satisfies the type and bodySerializer sends the
+ * real part.
  */
 async function uploadFile(command, filePath, purpose) {
-    const config = resolveConfig(command);
-    const authHeader = await resolveAuthHeader(config);
     const { blob, filename } = fileToBlob(filePath);
     const formData = new FormData();
     formData.append("file", blob, filename);
-    const baseUrl = config.baseUrl.replace(/\/+$/, "");
-    const url = `${baseUrl}/v1/files?purpose=${encodeURIComponent(purpose)}`;
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { Authorization: authHeader },
-        body: formData,
+    const client = getClient(command);
+    const { data } = await client.POST("/v1/files", {
+        params: { query: { purpose } },
+        body: { file: "" },
+        bodySerializer: () => formData,
     });
-    if (!res.ok) {
-        let body;
-        try {
-            body = await res.json();
-        }
-        catch {
-            body = {
-                error: res.statusText,
-                message: `HTTP ${res.status}: ${res.statusText}`,
-                status: res.status,
-                timestamp: new Date().toISOString(),
-            };
-        }
-        throw new BackboneApiError(body);
-    }
-    return (await res.json());
+    return data;
 }
 /** Stream a file's bytes from /v1/files/{fileId}/content via a raw fetch. */
 async function downloadFile(command, fileId) {

package/dist/commands/knowledge-documents.js

@@ -1,49 +1,29 @@
 import { Command } from "commander";
 import chalk from "chalk";
-import { getClient, resolveAuthHeader, runAction } from "../lib/client.js";
-import { resolveConfig, isJsonOutput } from "../lib/config.js";
-import { BackboneApiError } from "../lib/errors.js";
+import { getClient, runAction } from "../lib/client.js";
+import { isJsonOutput } from "../lib/config.js";
 import { formatPage, formatDetail, formatSuccess, withSpinner } from "../lib/output.js";
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
 import { fileToBlob } from "../lib/multipart.js";
 /**
- * Upload one or more local files to a knowledge base. Bypasses the typed
- * client the same way convert.ts's multipartConvert does: springdoc mis-shapes
- * this endpoint's `files` parameter as a query array of binary strings, but the
- * controller (`KnowledgeDocumentController.upload`) actually reads it off a
- * multipart/form-data body with repeated "files" parts.
+ * Upload one or more local files to a knowledge base as repeated "files"
+ * parts of a multipart/form-data body. The generated type describes each part
+ * as a binary string, which FormData cannot match, so the placeholder body
+ * satisfies the type and bodySerializer sends the real parts.
  */
 async function uploadDocuments(command, knowledgeBaseId, paths) {
-    const config = resolveConfig(command);
-    const authHeader = await resolveAuthHeader(config);
     const formData = new FormData();
     for (const p of paths) {
         const { blob, filename } = fileToBlob(p);
         formData.append("files", blob, filename);
     }
-    const baseUrl = config.baseUrl.replace(/\/+$/, "");
-    const url = `${baseUrl}/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/documents`;
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { Authorization: authHeader },
-        body: formData,
+    const client = getClient(command);
+    const { data } = await client.POST("/v1/knowledge-bases/{knowledgeBaseId}/documents", {
+        params: { path: { knowledgeBaseId } },
+        body: { files: [] },
+        bodySerializer: () => formData,
     });
-    if (!res.ok) {
-        let body;
-        try {
-            body = await res.json();
-        }
-        catch {
-            body = {
-                error: res.statusText,
-                message: `HTTP ${res.status}: ${res.statusText}`,
-                status: res.status,
-                timestamp: new Date().toISOString(),
-            };
-        }
-        throw new BackboneApiError(body);
-    }
-    return (await res.json());
+    return data ?? [];
 }
 function printUploadResults(results, command) {
     if (isJsonOutput(command)) {

package/dist/commands/memory.d.ts

@@ -0,0 +1,10 @@
+import { Command } from "commander";
+/** The If-Match value for a version a GET returned: the quoted ETag the API expects. */
+export declare function ifMatchHeader(version: string): string;
+/**
+ * Agent memory (agent memory spec §7.1, §7.4). `ls`, `cat`, `put`, `rm` and `forget` act on
+ * the caller's own memory; `members` and `erase` are for ADMIN and OWNER and never show
+ * paths or content. Content is lossless: `cat` prints it raw, `put` sends the file as is.
+ */
+export declare function makeMemoryCommand(): Command;
+//# sourceMappingURL=memory.d.ts.map

package/dist/commands/memory.js

@@ -0,0 +1,132 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { getClient, runAction } from "../lib/client.js";
+import { isJsonOutput } from "../lib/config.js";
+import { CliUsageError } from "../lib/errors.js";
+import { formatDetail, formatList, formatSuccess } from "../lib/output.js";
+/** The If-Match value for a version a GET returned: the quoted ETag the API expects. */
+export function ifMatchHeader(version) {
+    if (!/^\d{1,18}$/.test(version)) {
+        throw new CliUsageError(`--if-match takes the file's version, a whole number: ${version}`);
+    }
+    return `"${version}"`;
+}
+function requireYes(opts, what) {
+    if (!opts.yes) {
+        throw new CliUsageError(`${what} cannot be undone. Pass --yes to confirm.`);
+    }
+}
+/**
+ * Agent memory (agent memory spec §7.1, §7.4). `ls`, `cat`, `put`, `rm` and `forget` act on
+ * the caller's own memory; `members` and `erase` are for ADMIN and OWNER and never show
+ * paths or content. Content is lossless: `cat` prints it raw, `put` sends the file as is.
+ */
+export function makeMemoryCommand() {
+    const cmd = new Command("memory").description("Your agent memory files; member totals and erasure for admins");
+    cmd
+        .command("ls")
+        .description("List your memory files")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/memories/me/files");
+            formatList(data, command, [
+                "path",
+                "sizeBytes",
+                "version",
+                "updatedAt",
+                "lastWrittenByAgentId",
+            ]);
+        });
+    });
+    cmd
+        .command("cat <path>")
+        .description("Print one of your memory files, raw (--json for the file object)")
+        .action(async (path, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/memories/me/file", {
+                params: { query: { path } },
+            });
+            if (isJsonOutput(command)) {
+                formatDetail(data, command);
+            }
+            else {
+                process.stdout.write(data.content);
+            }
+        });
+    });
+    cmd
+        .command("put <path>")
+        .description("Create or replace one of your memory files from a local UTF-8 file")
+        .requiredOption("--file <file>", "Local file whose content is stored")
+        .option("--if-match <version>", "Only replace the file if it still has this version")
+        .action(async (path, opts, command) => {
+        await runAction(command, async () => {
+            // An empty --if-match (e.g. an unset shell variable) must be refused, never dropped
+            // into an unconditional overwrite.
+            const headers = opts.ifMatch !== undefined ? { "If-Match": ifMatchHeader(opts.ifMatch) } : undefined;
+            const content = readFileSync(opts.file, "utf8");
+            const client = getClient(command);
+            const { data } = await client.PUT("/v1/memories/me/file", {
+                params: { query: { path } },
+                body: { content },
+                headers,
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("rm <path>")
+        .description("Delete one of your memory files, or a directory with everything below it")
+        .action(async (path, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            await client.DELETE("/v1/memories/me/file", { params: { query: { path } } });
+            formatSuccess(`Deleted ${path}`, command);
+        });
+    });
+    cmd
+        .command("forget")
+        .description("Delete your whole memory (cannot be undone)")
+        .option("--yes", "Confirm")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            requireYes(opts, "Forgetting your whole memory");
+            const client = getClient(command);
+            await client.DELETE("/v1/memories/me");
+            formatSuccess("Forgot your whole memory", command);
+        });
+    });
+    cmd
+        .command("members")
+        .description("Memory totals per member, without paths or content (ADMIN+)")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/memories/users");
+            formatList(data, command, [
+                "userId",
+                "fileCount",
+                "totalBytes",
+                "lastUpdatedAt",
+            ]);
+        });
+    });
+    cmd
+        .command("erase <userId>")
+        .description("Erase a member's whole memory (ADMIN+, cannot be undone)")
+        .option("--yes", "Confirm")
+        .action(async (userId, opts, command) => {
+        await runAction(command, async () => {
+            requireYes(opts, "Erasing a member's memory");
+            const client = getClient(command);
+            await client.DELETE("/v1/memories/users/{userId}", {
+                params: { path: { userId } },
+            });
+            formatSuccess(`Erased the memory of ${userId}`, command);
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=memory.js.map

package/dist/index.js

@@ -22,6 +22,7 @@ import { makeContextCommand } from "./commands/context.js";
 import { makeExperimentsCommand } from "./commands/experiments.js";
 import { makeTracingCommand } from "./commands/tracing.js";
 import { makeSettingsCommand } from "./commands/settings.js";
+import { makeMemoryCommand } from "./commands/memory.js";
 import { makeEvaluatorsCommand } from "./commands/evaluators.js";
 import { makeScoresCommand } from "./commands/scores.js";
 import { makeQueuesCommand } from "./commands/queues.js";
@@ -64,6 +65,7 @@ program.addCommand(makeScoresCommand());
 program.addCommand(makeQueuesCommand());
 program.addCommand(makeTracingCommand());
 program.addCommand(makeSettingsCommand());
+program.addCommand(makeMemoryCommand());
 program.addCommand(makeAgentsCommand());
 program.addCommand(makeConversationsCommand());
 program.addCommand(makeKnowledgeCommand());

package/dist/lib/client.d.ts

@@ -39,6 +39,14 @@ export declare function apiKeyAuthMiddleware(config: ApiKeyConfig): Middleware;
  * fires and cannot be replayed safely.
  */
 export declare function sessionAuthMiddleware(config: SessionConfig, deps?: SessionAuthDeps): Middleware;
+/** The per-request opt-in to agent memory for API-key runs (spec §3.3, D6, D7). */
+export declare const MEMORY_HEADER = "X-Backbone-Memory";
+/**
+ * Adds `X-Backbone-Memory: enabled` to `POST …/v1/responses`, the call that starts a run
+ * and that also carries approval decisions (`lib/agent-decide.ts`). No other request gets
+ * it; the server reads it only there.
+ */
+export declare const memoryHeaderMiddleware: Middleware;
 /**
  * The middleware stack for a resolved config, in registration order.
  *

package/dist/lib/client.js

@@ -1,5 +1,5 @@
 import createClient from "openapi-fetch";
-import { resolveConfig, isJsonOutput } from "./config.js";
+import { resolveConfig, isJsonOutput, memoryEnabled } from "./config.js";
 import { ensureJwt } from "./auth-session.js";
 import { BackboneApiError, handleError } from "./errors.js";
 /**
@@ -85,6 +85,21 @@ export function sessionAuthMiddleware(config, deps = {}) {
         },
     };
 }
+/** The per-request opt-in to agent memory for API-key runs (spec §3.3, D6, D7). */
+export const MEMORY_HEADER = "X-Backbone-Memory";
+/**
+ * Adds `X-Backbone-Memory: enabled` to `POST …/v1/responses`, the call that starts a run
+ * and that also carries approval decisions (`lib/agent-decide.ts`). No other request gets
+ * it; the server reads it only there.
+ */
+export const memoryHeaderMiddleware = {
+    onRequest({ request }) {
+        if (request.method === "POST" && new URL(request.url).pathname.endsWith("/v1/responses")) {
+            request.headers.set(MEMORY_HEADER, "enabled");
+        }
+        return request;
+    },
+};
 /**
  * The middleware stack for a resolved config, in registration order.
  *
@@ -125,6 +140,8 @@ export function getClient(command) {
         baseUrl: config.baseUrl.replace(/\/+$/, ""),
     });
     client.use(...buildMiddleware(config));
+    if (memoryEnabled())
+        client.use(memoryHeaderMiddleware);
     return client;
 }
 /**

package/dist/lib/config.d.ts

@@ -14,6 +14,8 @@ export interface ContextEntry {
     cachedJwt?: string;
     /** Epoch millis when cachedJwt expires. */
     cachedJwtExp?: number;
+    /** Send `X-Backbone-Memory: enabled` on responses calls (`2kw config set memory true`, #721). */
+    memory?: boolean;
 }
 export interface BackboneConfigStore {
     activeContext: string;
@@ -55,6 +57,12 @@ export { store };
 export declare function validateContextName(name: string): void;
 export declare function getActiveContextName(): string;
 export declare function getActiveContext(): ContextEntry | undefined;
+/**
+ * Whether responses calls opt into agent memory (spec §3.3, D6). `AI_2KW_MEMORY` wins when
+ * set (`true` on, anything else off), so CI can switch it without touching the store;
+ * otherwise the active context's `memory` key decides. Off by default.
+ */
+export declare function memoryEnabled(env?: NodeJS.ProcessEnv): boolean;
 export declare function getAllContexts(): Record<string, ContextEntry>;
 export declare function getContextCount(): number;
 export declare function setContext(name: string, entry: ContextEntry): void;

package/dist/lib/config.js

@@ -142,6 +142,17 @@ export function getActiveContext() {
     const contexts = store.get("contexts") ?? {};
     return contexts[name];
 }
+/**
+ * Whether responses calls opt into agent memory (spec §3.3, D6). `AI_2KW_MEMORY` wins when
+ * set (`true` on, anything else off), so CI can switch it without touching the store;
+ * otherwise the active context's `memory` key decides. Off by default.
+ */
+export function memoryEnabled(env = process.env) {
+    const fromEnv = env.AI_2KW_MEMORY;
+    if (fromEnv !== undefined && fromEnv !== "")
+        return fromEnv === "true";
+    return getActiveContext()?.memory === true;
+}
 export function getAllContexts() {
     return store.get("contexts") ?? {};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2kw/ai",
-  "version": "6.3.0-dev.24",
+  "version": "6.3.0-dev.31",
   "description": "CLI for 2kw.ai — schema-driven document extraction, an OpenAI-compatible EU LLM gateway, transcription, prompts, datasets, and experiments from your terminal or agentic workflows. Ships as 2kw, backbone, and bb.",
   "keywords": [
     "cli",