@vellumai/assistant 0.4.35 → 0.4.37

package/src/cli/{config-commands.ts → memory.ts}

@@ -1,12 +1,5 @@
 import type { Command } from "commander";
 
-import {
-  API_KEY_PROVIDERS,
-  getNestedValue,
-  loadRawConfig,
-  saveRawConfig,
-  setNestedValue,
-} from "../config/loader.js";
 import {
   dismissPendingConflicts,
   getMemorySystemStatus,
@@ -18,255 +11,65 @@ import {
 import { listPendingConflictDetails } from "../memory/conflict-store.js";
 import { listConversations } from "../memory/conversation-store.js";
 import { initializeDb, rawGet } from "../memory/db.js";
-import {
-  clearAllRules,
-  getAllRules,
-  removeRule,
-} from "../permissions/trust-store.js";
-import {
-  deleteSecureKey,
-  getSecureKey,
-  setSecureKey,
-} from "../security/secure-keys.js";
 import { getCliLogger } from "../util/logger.js";
 
 const log = getCliLogger("cli");
 
 const SHORT_HASH_LENGTH = 8;
 
-export function registerConfigCommand(program: Command): void {
-  const config = program.command("config").description("Manage configuration");
-
-  config
-    .command("set <key> <value>")
-    .description(
-      "Set a config value (supports dotted paths like apiKeys.anthropic)",
-    )
-    .action((key: string, value: string) => {
-      const raw = loadRawConfig();
-      // Try to parse as JSON for booleans/numbers, fall back to string
-      let parsed: unknown = value;
-      try {
-        parsed = JSON.parse(value);
-      } catch {
-        // keep as string
-      }
-      setNestedValue(raw, key, parsed);
-      saveRawConfig(raw);
-      log.info(`Set ${key} = ${JSON.stringify(parsed)}`);
-    });
-
-  config
-    .command("get <key>")
-    .description("Get a config value (supports dotted paths)")
-    .action((key: string) => {
-      const raw = loadRawConfig();
-      const value = getNestedValue(raw, key);
-      if (value === undefined) {
-        log.info(`(not set)`);
-      } else {
-        log.info(
-          typeof value === "object"
-            ? JSON.stringify(value, null, 2)
-            : String(value),
-        );
-      }
-    });
-
-  config
-    .command("list")
-    .description("List all config values")
-    .action(() => {
-      const raw = loadRawConfig();
-      if (Object.keys(raw).length === 0) {
-        log.info("No configuration set");
-      } else {
-        log.info(JSON.stringify(raw, null, 2));
-      }
-    });
-
-  config
-    .command("validate-allowlist")
-    .description("Validate regex patterns in secret-allowlist.json")
-    .action(() => {
-      const { validateAllowlistFile } =
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        require("../security/secret-allowlist.js") as typeof import("../security/secret-allowlist.js");
-      try {
-        const errors = validateAllowlistFile();
-        if (errors == null) {
-          log.info("No secret-allowlist.json file found");
-          return;
-        }
-        if (errors.length === 0) {
-          log.info("All patterns in secret-allowlist.json are valid");
-          return;
-        }
-        log.error(
-          `Found ${errors.length} invalid pattern(s) in secret-allowlist.json:`,
-        );
-        for (const e of errors) {
-          log.error(`  [${e.index}] "${e.pattern}": ${e.message}`);
-        }
-        process.exit(1);
-      } catch (err) {
-        log.error(
-          `Failed to read secret-allowlist.json: ${(err as Error).message}`,
-        );
-        process.exit(1);
-      }
-    });
-}
-
-export function registerKeysCommand(program: Command): void {
-  const keys = program
-    .command("keys")
-    .description("Manage API keys in secure storage");
-
-  keys
-    .command("list")
-    .description("List all stored API key names")
-    .action(() => {
-      const stored: string[] = [];
-      for (const provider of API_KEY_PROVIDERS) {
-        const value = getSecureKey(provider);
-        if (value) stored.push(provider);
-      }
-      if (stored.length === 0) {
-        log.info("No API keys stored");
-      } else {
-        for (const name of stored) {
-          log.info(`  ${name}`);
-        }
-      }
-    });
-
-  keys
-    .command("set <provider> <key>")
-    .description("Store an API key (e.g. vellum keys set anthropic sk-ant-...)")
-    .action((provider: string, key: string) => {
-      if (setSecureKey(provider, key)) {
-        log.info(`Stored API key for "${provider}"`);
-      } else {
-        log.error(`Failed to store API key for "${provider}"`);
-        process.exit(1);
-      }
-    });
-
-  keys
-    .command("delete <provider>")
-    .description("Delete a stored API key")
-    .action((provider: string) => {
-      if (deleteSecureKey(provider)) {
-        log.info(`Deleted API key for "${provider}"`);
-      } else {
-        log.error(`No API key found for "${provider}"`);
-        process.exit(1);
-      }
-    });
-}
-
-export function registerTrustCommand(program: Command): void {
-  const trust = program.command("trust").description("Manage trust rules");
-
-  trust
-    .command("list")
-    .description("List all trust rules")
-    .action(() => {
-      const rules = getAllRules();
-      if (rules.length === 0) {
-        log.info("No trust rules");
-        return;
-      }
-      const idW = 8;
-      const toolW = 12;
-      const patternW = 30;
-      const scopeW = 20;
-      const decW = 6;
-      const priW = 4;
-      log.info(
-        "ID".padEnd(idW) +
-          "Tool".padEnd(toolW) +
-          "Pattern".padEnd(patternW) +
-          "Scope".padEnd(scopeW) +
-          "Dcn".padEnd(decW) +
-          "Pri".padEnd(priW) +
-          "Created",
-      );
-      log.info("-".repeat(idW + toolW + patternW + scopeW + decW + priW + 20));
-      for (const r of rules) {
-        const id = r.id.slice(0, SHORT_HASH_LENGTH);
-        const created = new Date(r.createdAt).toISOString().slice(0, 10);
-        log.info(
-          id.padEnd(idW) +
-            r.tool.padEnd(toolW) +
-            r.pattern.slice(0, patternW - 2).padEnd(patternW) +
-            r.scope.slice(0, scopeW - 2).padEnd(scopeW) +
-            r.decision.slice(0, decW - 1).padEnd(decW) +
-            String(r.priority).padEnd(priW) +
-            created,
-        );
-      }
-    });
-
-  trust
-    .command("remove <id>")
-    .description("Remove a trust rule by ID (or prefix)")
-    .action((id: string) => {
-      const rules = getAllRules();
-      const match = rules.find((r) => r.id.startsWith(id));
-      if (!match) {
-        log.error(`No rule found matching "${id}"`);
-        process.exit(1);
-      }
-      try {
-        removeRule(match.id);
-      } catch (err) {
-        log.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-      }
-      log.info(
-        `Removed rule ${match.id.slice(0, SHORT_HASH_LENGTH)} (${match.tool}: ${
-          match.pattern
-        })`,
-      );
-    });
-
-  trust
-    .command("clear")
-    .description("Remove all trust rules")
-    .action(async () => {
-      const rules = getAllRules();
-      if (rules.length === 0) {
-        log.info("No trust rules to clear");
-        return;
-      }
-      const readline = await import("node:readline");
-      const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-      });
-      const answer = await new Promise<string>((resolve) => {
-        rl.question(`Remove all ${rules.length} trust rules? (y/N) `, resolve);
-      });
-      rl.close();
-      if (answer.toLowerCase() === "y") {
-        clearAllRules();
-        log.info(`Cleared ${rules.length} trust rules`);
-      } else {
-        log.info("Cancelled");
-      }
-    });
-}
-
 export function registerMemoryCommand(program: Command): void {
   const memory = program
     .command("memory")
     .description("Manage long-term memory indexing/retrieval");
 
+  memory.addHelpText(
+    "after",
+    `
+The memory subsystem indexes conversation segments into full-text search (FTS)
+and vector embeddings for semantic recall. When the assistant encounters new
+information that contradicts a stored fact, a conflict is created and held in
+"pending_clarification" status until explicitly dismissed or resolved.
+
+Key concepts:
+  segments     Chunks of conversation text extracted for indexing
+  items        Distilled facts/statements derived from segments
+  summaries    Compressed representations of conversation history
+  embeddings   Vector representations used for semantic similarity search
+  conflicts    Pairs of contradictory statements awaiting resolution
+
+Examples:
+  $ vellum memory status
+  $ vellum memory query "What is the project deadline?"
+  $ vellum memory backfill
+  $ vellum memory dismiss-conflicts --all`,
+  );
+
   memory
     .command("status")
     .description("Show memory subsystem status")
+    .addHelpText(
+      "after",
+      `
+Displays a comprehensive snapshot of the memory subsystem's health and counts.
+
+Fields shown:
+  enabled/degraded   Whether memory is active and whether it is running in a
+                     degraded mode (e.g. missing embedding backend)
+  embedding backend  The provider/model pair used for vector embeddings (or "none")
+  segments           Total conversation segments indexed
+  items              Total distilled fact items stored
+  summaries          Total compressed conversation summaries
+  embeddings         Total vector embeddings computed
+  pending conflicts  Conflicts awaiting user resolution
+  resolved conflicts Conflicts that have been dismissed or resolved
+  oldest pending age How long the oldest unresolved conflict has been waiting
+  cleanup backlogs   Number of resolved conflicts and superseded items pending cleanup
+  cleanup throughput Number of cleanup operations completed in the last 24 hours
+  jobs               Status of background jobs (backfill, cleanup, rebuild-index)
+
+Examples:
+  $ vellum memory status`,
+    )
     .action(() => {
       initializeDb();
       const status = getMemorySystemStatus();
@@ -318,6 +121,21 @@ export function registerMemoryCommand(program: Command): void {
     .command("backfill")
     .description("Queue a memory backfill job")
     .option("-f, --force", "Restart backfill from the beginning")
+    .addHelpText(
+      "after",
+      `
+Queues a background job to index unprocessed conversation segments into FTS
+and vector embeddings. The job resumes from where the last backfill left off,
+processing only new or unindexed segments.
+
+The --force flag restarts the backfill from the very beginning, reprocessing
+all segments regardless of whether they have already been indexed. This is
+useful after bulk imports or if the incremental state has become inconsistent.
+
+Examples:
+  $ vellum memory backfill
+  $ vellum memory backfill --force`,
+    )
     .action((opts: { force?: boolean }) => {
       initializeDb();
       const jobId = requestMemoryBackfill(Boolean(opts?.force));
@@ -333,6 +151,23 @@ export function registerMemoryCommand(program: Command): void {
       "--retention-ms <ms>",
       "Optional retention threshold in milliseconds",
     )
+    .addHelpText(
+      "after",
+      `
+Queues two background cleanup jobs:
+  1. Resolved conflicts cleanup — removes conflict records that have been
+     dismissed or resolved past the retention threshold.
+  2. Stale superseded items cleanup — removes memory items that have been
+     superseded by newer, corrected facts past the retention threshold.
+
+The optional --retention-ms flag sets the minimum age (in milliseconds) a
+record must have before it is eligible for cleanup. If omitted, the system
+default retention period is used.
+
+Examples:
+  $ vellum memory cleanup
+  $ vellum memory cleanup --retention-ms 86400000`,
+    )
     .action((opts: { retentionMs?: string }) => {
       initializeDb();
       const retentionMs = opts.retentionMs
@@ -355,6 +190,27 @@ export function registerMemoryCommand(program: Command): void {
       "Run a memory recall query and print the injected memory payload",
     )
     .option("-s, --session <id>", "Optional conversation/session ID")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  text   The recall query string used to search memory (e.g. "What is the
+         project deadline?"). Matched against indexed segments using the full
+         recall pipeline: lexical (FTS), semantic (vector similarity), recency
+         (time-weighted), and entity (named entity extraction).
+
+Runs the complete memory recall pipeline and displays hit counts for each
+retrieval strategy, the total injected token count, query latency, and the
+assembled memory text that would be injected into context.
+
+The optional --session flag provides a conversation/session ID for
+context-aware recall. If omitted, the most recent conversation is used.
+
+Examples:
+  $ vellum memory query "What is the project deadline?"
+  $ vellum memory query "preferred communication style" --session conv_abc123
+  $ vellum memory query "API rate limits"`,
+    )
     .action(async (text: string, opts?: { session?: string }) => {
       initializeDb();
       let sessionId = opts?.session;
@@ -383,6 +239,21 @@ export function registerMemoryCommand(program: Command): void {
   memory
     .command("rebuild-index")
     .description("Queue a memory FTS+embedding index rebuild job")
+    .addHelpText(
+      "after",
+      `
+Queues a background job that performs a full rebuild of both the FTS (full-text
+search) index and the vector embedding index. All existing index data is
+dropped and reconstructed from the source memory items.
+
+This is useful after schema changes, embedding model upgrades, or if index
+corruption is suspected. The rebuild runs asynchronously; use "vellum memory
+status" to monitor job progress.
+
+Examples:
+  $ vellum memory rebuild-index
+  $ vellum memory status`,
+    )
     .action(() => {
       initializeDb();
       const jobId = requestMemoryRebuildIndex();
@@ -399,6 +270,26 @@ export function registerMemoryCommand(program: Command): void {
     )
     .option("-s, --scope <id>", 'Memory scope (default: "default")')
     .option("--dry-run", "Show what would be dismissed without making changes")
+    .addHelpText(
+      "after",
+      `
+Two modes of operation:
+  --all              Dismiss every pending conflict in the scope
+  --pattern <regex>  Dismiss only conflicts where either the existing or
+                     candidate statement matches the given regex (case-insensitive)
+
+At least one of --all or --pattern must be provided. If both are given,
+--all takes priority and all pending conflicts are dismissed.
+
+The --scope flag targets a specific memory scope. Defaults to "default" if
+omitted. The --dry-run flag previews which conflicts would be dismissed
+without actually modifying any records.
+
+Examples:
+  $ vellum memory dismiss-conflicts --all
+  $ vellum memory dismiss-conflicts --pattern "project deadline" --dry-run
+  $ vellum memory dismiss-conflicts --pattern "^preferred\\b" --scope work`,
+    )
     .action(
       (opts: {
         all?: boolean;
@@ -407,9 +298,7 @@ export function registerMemoryCommand(program: Command): void {
         dryRun?: boolean;
       }) => {
         if (!opts.all && !opts.pattern) {
-          log.info(
-            "Usage: vellum memory dismiss-conflicts --all  OR  --pattern <regex>",
-          );
+          log.info("At least one of --all or --pattern must be provided.");
           log.info("Use --dry-run to preview without making changes.");
           return;
         }