hippo-memory 1.69.0 → 1.71.0

package/dist/cli/transfer.js

@@ -1,33 +1,38 @@
 // Verbs that move memories in and out: watch, learn, import, export, promote, sync, share and peers.
 import * as path from 'path';
 import * as fs from 'fs';
-import { calculateStrength, deriveHalfLife, computeSchemaFit } from '../memory.js';
 import { isInitialized } from '../store/open.js';
-import { writeEntry } from '../store/entry-writes.js';
-import { readEntry, loadAllEntries } from '../store/entry-reads.js';
-import { updateStats } from '../store/index-and-stats.js';
-import { RejectedValueError } from '../rejection.js';
-import { embedAll, embedMemory } from '../embeddings.js';
-import { loadConfig } from '../config.js';
-import { captureError, runWatched } from '../autolearn.js';
+import { loadAllEntries } from '../store/entry-reads.js';
+import { RejectedValueError } from '../store/rejection.js';
+import { embedAll } from '../store/embeddings/index.js';
+import { loadEmbeddingIndex } from '../store/vector-index.js';
+import { captureError, runWatched } from '../learn/autolearn.js';
 import { currentMachine, importAtSessionEnd, importForStore } from '../agent-memories/sync.js';
 import { detailLines } from '../agent-memories/report.js';
-import { getGlobalRoot, initGlobal, shareMemory, listPeers, autoShare, transferScore, syncGlobalToLocal, } from '../shared.js';
+import { getGlobalRoot, initGlobal } from '../sharing/global-store.js';
+import { shareMemory, listPeers, autoShare, transferScore } from '../sharing/share.js';
+import { syncGlobalToLocal } from '../sharing/global-sync.js';
 import { importChatGPT, importClaude, importCursor, importGenericFile, } from '../importers/sources.js';
 import { importMarkdown } from '../importers/markdown.js';
 import { importVault } from '../importers/vault.js';
-import * as api from '../api.js';
-import * as client from '../client.js';
-import { resolveTenantId } from '../tenant.js';
+import * as api from '../api/index.js';
+import { getMemory } from '../api/memories.js';
+import * as client from './client.js';
+import { cliApiContext } from './api-context.js';
 import { printError } from './output.js';
-import { requireInit, runViaServerIfAvailable, fmt, learnFromRepo } from './shared.js';
-// ---------------------------------------------------------------------------
+import { errorMessage, log } from '../util/log.js';
+import { requireInit, runViaServerIfAvailable, learnFromRepo } from './shared.js';
+import { fmt } from './print.js';
+import { boolFlag, flagIsTrue, isStringFlag, nonEmptyStringFlag } from './flag-values.js';
+import { CONTENT_PREVIEW_CHARS, DATE_PREFIX_CHARS } from '../util/token-text.js';
+import { CliExit } from './exit.js';
+const STDERR_PREVIEW_CHARS = 80;
+const MAX_ENTRIES_SHOWN = 10;
 // Watch command
-// ---------------------------------------------------------------------------
-async function cmdWatch(command, hippoRoot) {
+async function cmdWatch(command, hippoRoot, tenantId) {
     if (!command) {
         printError('Usage: hippo watch "<command>"');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const { exitCode, stderr } = await runWatched(command);
     if (exitCode === 0) {
@@ -37,22 +42,22 @@ async function cmdWatch(command, hippoRoot) {
     // Only create memory if hippo is initialized
     if (!isInitialized(hippoRoot)) {
         printError('Command failed but .hippo not initialized. Run `hippo init` to enable auto-learn.');
-        process.exit(exitCode);
-    }
-    const entry = captureError(exitCode, stderr, command, resolveTenantId({}));
-    // Compute schema fit against existing memories
-    const existingWatch = loadAllEntries(hippoRoot, entry.tenantId);
-    const watchFit = computeSchemaFit(entry.content, entry.tags, existingWatch);
-    entry.schema_fit = watchFit;
-    entry.half_life_days = deriveHalfLife(loadConfig(hippoRoot).defaultHalfLifeDays, entry);
-    entry.strength = calculateStrength(entry);
+        throw new CliExit(exitCode);
+    }
+    const failure = captureError(exitCode, stderr, command, tenantId);
     // A rejection-guard refusal of a failed command's output must not crash the watcher:
     // skip with the message below and still exit with the wrapped command's real exit code.
     try {
-        writeEntry(hippoRoot, entry);
-        updateStats(hippoRoot, { remembered: 1 });
-        void embedMemory(hippoRoot, entry);
-        const preview = stderr.trim().slice(0, 80);
+        api.rememberLocally(cliApiContext(hippoRoot, tenantId), {
+            content: failure.content,
+            tags: failure.tags,
+            layer: failure.layer,
+            source: failure.source,
+            confidence: failure.confidence,
+            // A failure is stored each time it happens: watch has never put it to the salience gate.
+            force: true,
+        });
+        const preview = stderr.trim().slice(0, STDERR_PREVIEW_CHARS);
         printError(`\nHippo learned from failure: "${preview}"`);
     }
     catch (err) {
@@ -63,21 +68,19 @@ async function cmdWatch(command, hippoRoot) {
             throw err;
         }
     }
-    process.exit(exitCode);
+    throw new CliExit(exitCode);
 }
-// ---------------------------------------------------------------------------
 // Learn command
-// ---------------------------------------------------------------------------
-export function cmdLearn(hippoRoot, flags) {
+export function handleLearn({ hippoRoot, flags }) {
     requireInit(hippoRoot);
     if (!flags['git']) {
         printError('Usage: hippo learn --git [--days <n>] [--repos <paths>]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const days = parseInt(String(flags['days'] ?? '7'), 10);
     console.log(`Scanning git log for the last ${days} days...`);
-    const reposFlag = flags['repos'];
-    if (reposFlag && typeof reposFlag === 'string') {
+    const reposFlag = nonEmptyStringFlag(flags, 'repos');
+    if (reposFlag) {
         const repos = reposFlag.split(',').map((r) => r.trim()).filter(Boolean);
         let totalAdded = 0;
         let totalSkipped = 0;
@@ -94,16 +97,26 @@ export function cmdLearn(hippoRoot, flags) {
         console.log(`Git learn complete: ${added} new lessons added, ${skipped} duplicates skipped.`);
     }
 }
-// ---------------------------------------------------------------------------
 // Import command
-// ---------------------------------------------------------------------------
+/** The rows are saved either way; a failed backfill only delays vectors, so it warns with how many wait and the command that finishes them. */
+function warnBackfillFailed(root, embedCommand, err) {
+    let waiting;
+    try {
+        const vectors = loadEmbeddingIndex(root);
+        waiting = String(loadAllEntries(root).filter((entry) => !Object.hasOwn(vectors, entry.id)).length);
+    }
+    catch (countErr) {
+        waiting = `an unknown number of (count failed: ${errorMessage(countErr)})`;
+    }
+    log.warn(`import: embedding backfill failed (${errorMessage(err)}); ${waiting} rows have no vector; run '${embedCommand}' to backfill`);
+}
 function warnRedacted(count) {
     if (count)
         printError(`Warning: secret-shaped text was redacted from ${count} imported ${count === 1 ? 'entry' : 'entries'} before storing`);
 }
-export function cmdImport(hippoRoot, args, flags) {
-    const useGlobal = Boolean(flags['global']);
-    const dryRun = Boolean(flags['dry-run']);
+export function handleImport({ hippoRoot, tenantId, args, flags }) {
+    const useGlobal = boolFlag(flags, 'global');
+    const dryRun = boolFlag(flags, 'dry-run');
     const extraTags = Array.isArray(flags['tag'])
         ? flags['tag']
         : flags['tag']
@@ -124,15 +137,11 @@ export function cmdImport(hippoRoot, args, flags) {
         extraTags,
         hippoRoot,
     };
-    // Vault import: a FOLDER importer that mirrors the connector pattern
-    // (kind='raw' + tag provenance + archiveRaw deletions), so it dispatches
-    // separately from the single-file `importer` function-pointer slot below.
-    // It writes through api.remember/archiveRaw which are tenant-scoped, so we
-    // resolve the tenant and pass it through. --global is not supported for
-    // vault import (the connector raw-archive path is tenant-local).
+    // Vault import is a FOLDER importer that dispatches apart from the single-file slot below; it writes through tenant-scoped api calls,
+    // so the tenant is resolved and passed through. --global is unsupported (the connector raw-archive path is tenant-local).
     if (flags['vault'])
-        return importVaultFolder(hippoRoot, flags, importOptions, useGlobal, dryRun);
-    importFromFile(targetRoot, args, flags, importOptions, useGlobal, dryRun);
+        return importVaultFolder(hippoRoot, tenantId, flags, importOptions, useGlobal, dryRun);
+    importFromFile(targetRoot, args, flags, { importOptions, useGlobal, dryRun });
 }
 // Determine which importer to use based on flag
 function pickImporter(args, flags) {
@@ -151,27 +160,27 @@ function pickImporter(args, flags) {
         return { filePath: args[0], importer: importGenericFile, importerName: 'File' };
     return { filePath: undefined, importer: undefined, importerName: '' };
 }
-function importFromFile(targetRoot, args, flags, importOptions, useGlobal, dryRun) {
+function importFromFile(targetRoot, args, flags, options) {
+    const { importOptions, useGlobal, dryRun } = options;
     const { filePath, importer, importerName } = pickImporter(args, flags);
     if (!filePath || !importer) {
         printError('Usage: hippo import <--chatgpt|--claude|--cursor|--file|--markdown|--vault> <path>, or hippo import --agents [--dry-run]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     if (!fs.existsSync(filePath)) {
         printError(`File not found: ${filePath}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const result = importer(filePath, importOptions);
-    // Batch producer: embed newly-imported rows on targetRoot in one pass
-    // rather than per-row (importers.ts writeEntry sites don't embed). The
-    // floating promise is deliberate: libuv keeps the process alive until it
-    // settles, so it is not dropped on process exit; `hippo embed --global` (or
-    // a local `hippo embed`) is the backstop if it does get interrupted. Do not
-    // "fix" this by awaiting it, that would block the CLI on model load/backfill.
+    // Batch-embed newly imported rows in one pass (the importers' writeEntry sites don't embed). The floating promise is deliberate: libuv keeps the process
+    // alive until it settles; do not await it, that would block the CLI on model load. `hippo embed` is the backstop if interrupted.
     if (!dryRun && result.imported >= 1) {
-        void embedAll(targetRoot).catch(() => { });
+        void embedAll(targetRoot).catch((err) => warnBackfillFailed(targetRoot, useGlobal ? 'hippo embed --global' : 'hippo embed', err));
     }
     const storeLabel = useGlobal ? `global (${getGlobalRoot()})` : targetRoot;
+    printFileImportSummary(result, importerName, filePath, storeLabel, dryRun);
+}
+function printFileImportSummary(result, importerName, filePath, storeLabel, dryRun) {
     console.log(`\nImport ${importerName}: ${filePath}`);
     console.log(`  Source entries found:  ${result.total}`);
     console.log(`  Imported:              ${result.imported}`);
@@ -184,8 +193,8 @@ function importFromFile(targetRoot, args, flags, importOptions, useGlobal, dryRu
         console.log('\n  (dry run - nothing written)');
         if (result.entries.length > 0) {
             console.log('\n  Would import:');
-            for (const e of result.entries.slice(0, 10)) {
-                console.log(`    - ${e.content.slice(0, 80)}`);
+            for (const e of result.entries.slice(0, MAX_ENTRIES_SHOWN)) {
+                console.log(`    - ${e.content.slice(0, CONTENT_PREVIEW_CHARS)}`);
             }
             if (result.entries.length > 10) {
                 console.log(`    ... and ${result.entries.length - 10} more`);
@@ -207,37 +216,41 @@ function importAgentMemories(hippoRoot, useGlobal, dryRun) {
     for (const warning of report.warnings)
         printError(`hippo: agent memories: ${warning}`);
 }
-function importVaultFolder(hippoRoot, flags, importOptions, useGlobal, dryRun) {
+function importVaultFolder(hippoRoot, tenantId, flags, importOptions, useGlobal, dryRun) {
     const folderPath = String(flags['vault']);
+    checkVaultArgs(folderPath, flags, useGlobal);
+    const vaultOptions = {
+        ...importOptions,
+        tenantId,
+        name: flags['name'] ? String(flags['name']) : undefined,
+        scope: flags['scope'] ? String(flags['scope']) : undefined,
+    };
+    const vaultResult = importVault(folderPath, vaultOptions);
+    printVaultSummary(vaultResult, folderPath, hippoRoot, dryRun);
+}
+function checkVaultArgs(folderPath, flags, useGlobal) {
     if (!fs.existsSync(folderPath) || !fs.statSync(folderPath).isDirectory()) {
         printError(`Vault folder not found (or not a directory): ${folderPath}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     if (useGlobal) {
         printError('hippo import --vault does not support --global (raw rows are tenant-local).');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    if (typeof flags['name'] !== 'string' || !flags['name'].trim()) {
+    if (!isStringFlag(flags['name']) || !flags['name'].trim()) {
         // --name keys the destructive source-deletion sync; a folder-basename default lets same-basename vaults clobber
         // each other, and a valueless `--name` (boolean true) would silently import under vault:true:*.
         printError('hippo import --vault requires --name <vault> (a non-empty identity key for source-deletion sync).');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    if (flags['scope'] !== undefined && (typeof flags['scope'] !== 'string' || !flags['scope'].trim())) {
-        // Same valueless-flag trap: a bare `--scope` must not become scope "true".
-        // Example uses the source-prefixed private form, since a bare `private` scope
-        // is NOT treated as private by recall and importVault rejects it.
+    if (flags['scope'] !== undefined && (!isStringFlag(flags['scope']) || !flags['scope'].trim())) {
+        // Same valueless-flag trap: a bare `--scope` must not become scope "true". The example uses the source-prefixed private form,
+        // since a bare `private` scope is not treated as private by recall and importVault rejects it.
         printError('hippo import --vault: --scope requires a value (e.g. --scope vault:private:notes).');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const tenantId = resolveTenantId({});
-    const vaultOptions = {
-        ...importOptions,
-        tenantId,
-        name: flags['name'] ? String(flags['name']) : undefined,
-        scope: flags['scope'] ? String(flags['scope']) : undefined,
-    };
-    const vaultResult = importVault(folderPath, vaultOptions);
+}
+function printVaultSummary(vaultResult, folderPath, hippoRoot, dryRun) {
     console.log(`\nImport Vault: ${folderPath}${dryRun ? ' (dry run - no writes)' : ''}`);
     console.log(`  Notes found:           ${vaultResult.total}`);
     console.log(`  ${dryRun ? 'Would import:         ' : 'Imported:             '}${vaultResult.imported}`);
@@ -248,41 +261,32 @@ function importVaultFolder(hippoRoot, flags, importOptions, useGlobal, dryRun) {
     warnRedacted(vaultResult.redacted);
     console.log(`  ${dryRun ? 'Would archive:        ' : 'Archived (removed):   '}${vaultResult.archived ?? 0}`);
     console.log(`  Store:                 ${hippoRoot}`);
-    // Batch producer, same contract as the single-file import above: vault rows
-    // write through api.remember (which never embeds), so backfill them here.
-    // Floating promise is deliberate; see the comment at the single-file site.
+    // Batch producer, same contract as the single-file import above: vault rows write through api.remember (which never embeds), so backfill them here.
+    // The floating promise is deliberate; see the single-file site.
     if (!dryRun && vaultResult.imported >= 1) {
-        void embedAll(hippoRoot).catch(() => { });
+        void embedAll(hippoRoot).catch((err) => warnBackfillFailed(hippoRoot, 'hippo embed', err));
     }
 }
-// ---------------------------------------------------------------------------
 // Promote command
-// ---------------------------------------------------------------------------
-function cmdPromote(hippoRoot, id) {
+function cmdPromote(hippoRoot, tenantId, id) {
     requireInit(hippoRoot);
     if (!id) {
         printError('Usage: hippo promote <id>');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const ctx = {
-        hippoRoot,
-        tenantId: resolveTenantId({}),
-        actor: api.adminActor('cli'),
-    };
+    const ctx = cliApiContext(hippoRoot, tenantId);
     try {
         const result = api.promote(ctx, id);
         console.log(`Promoted ${id} to global store as ${result.globalId}`);
         console.log(`   Global store: ${getGlobalRoot()}`);
     }
     catch (err) {
-        printError(`Failed to promote: ${err.message}`);
-        process.exit(1);
+        printError(`Failed to promote: ${errorMessage(err)}`);
+        throw new CliExit(1);
     }
 }
-// ---------------------------------------------------------------------------
 // Sync command
-// ---------------------------------------------------------------------------
-export function cmdSync(hippoRoot, flags = {}) {
+export function handleSync({ hippoRoot, flags }) {
     requireInit(hippoRoot);
     const globalRoot = getGlobalRoot();
     if (!isInitialized(globalRoot)) {
@@ -290,19 +294,19 @@ export function cmdSync(hippoRoot, flags = {}) {
         return;
     }
     // v39: other-project rows are skipped by default; secrets always are.
-    const includeCrossProject = flags['cross-project'] === true;
+    const includeCrossProject = flagIsTrue(flags, 'cross-project');
     const count = syncGlobalToLocal(hippoRoot, globalRoot, { includeCrossProject });
     console.log(`Synced ${count} global memories into local project.${includeCrossProject ? '' : ' (other-project rows skipped; use --cross-project to include them)'}`);
 }
-export async function handleWatch({ hippoRoot, args }) {
+export async function handleWatch({ hippoRoot, tenantId, args }) {
     const watchCmd = args.join(' ').trim();
-    await cmdWatch(watchCmd, hippoRoot);
+    await cmdWatch(watchCmd, hippoRoot, tenantId);
 }
-export async function handlePromote({ hippoRoot, args }) {
+export async function handlePromote({ hippoRoot, tenantId, args }) {
     const id = args[0];
     if (!id) {
         printError('Please provide a memory ID.');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const promoted = await runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
         try {
@@ -310,22 +314,22 @@ export async function handlePromote({ hippoRoot, args }) {
             console.log(`Promoted ${id} to global store as ${result.globalId}`);
         }
         catch (err) {
-            printError(`Failed to promote: ${err.message}`);
-            process.exit(1);
+            printError(`Failed to promote: ${errorMessage(err)}`);
+            throw new CliExit(1);
         }
     });
     if (promoted)
         return;
-    cmdPromote(hippoRoot, id);
+    cmdPromote(hippoRoot, tenantId, id);
 }
-export function handleShare({ hippoRoot, args, flags }) {
+export async function handleShare({ hippoRoot, tenantId, args, flags }) {
     const shareId = args[0];
     if (shareId === '--auto' || flags['auto']) {
         // Auto-share mode
         requireInit(hippoRoot);
         const minScore = parseFloat(String(flags['min-score'] ?? '0.6'));
-        const dryRun = Boolean(flags['dry-run']);
-        const results = autoShare(hippoRoot, { minScore, dryRun, tenantId: resolveTenantId({}) });
+        const dryRun = boolFlag(flags, 'dry-run');
+        const results = autoShare(hippoRoot, { minScore, dryRun, tenantId });
         if (results.length === 0) {
             console.log('No memories meet the sharing threshold.');
         }
@@ -333,7 +337,7 @@ export function handleShare({ hippoRoot, args, flags }) {
             console.log(`Would share ${results.length} memories:\n`);
             for (const e of results) {
                 const score = transferScore(e);
-                console.log(`  ${e.id} (transfer=${fmt(score)}) ${e.content.slice(0, 80)}...`);
+                console.log(`  ${e.id} (transfer=${fmt(score)}) ${e.content.slice(0, CONTENT_PREVIEW_CHARS)}...`);
             }
         }
         else {
@@ -345,15 +349,14 @@ export function handleShare({ hippoRoot, args, flags }) {
     }
     else if (shareId) {
         requireInit(hippoRoot);
-        const force = Boolean(flags['force']);
-        const tenantId = resolveTenantId({});
+        const force = boolFlag(flags, 'force');
         const result = shareMemory(hippoRoot, shareId, { force, tenantId });
         if (result) {
             console.log(`Shared [${result.id}] to global store.`);
             console.log(`  Source: ${result.source}`);
         }
         else {
-            const entry = readEntry(hippoRoot, shareId, tenantId);
+            const entry = await getMemory(cliApiContext(hippoRoot, tenantId), shareId);
             if (entry) {
                 const score = transferScore(entry);
                 console.log(`Transfer score too low (${fmt(score)}). This memory looks project-specific.`);
@@ -361,19 +364,19 @@ export function handleShare({ hippoRoot, args, flags }) {
             }
             else {
                 printError(`Memory not found: ${shareId}`);
-                process.exit(1);
+                throw new CliExit(1);
             }
         }
     }
     else {
         printError('Usage: hippo share <memory_id> [--force] or hippo share --auto [--dry-run]');
-        process.exit(1);
+        throw new CliExit(1);
     }
 }
-export function handlePeers({ flags }) {
+export function handlePeers({ tenantId, flags }) {
     // Tenant-scoped by default; --all-tenants gives the host-wide view for cross-tenant peer discovery.
-    const allTenants = flags['all-tenants'] === true;
-    const tenantScope = allTenants ? undefined : resolveTenantId({});
+    const allTenants = flagIsTrue(flags, 'all-tenants');
+    const tenantScope = allTenants ? undefined : tenantId;
     const peers = listPeers(undefined, tenantScope);
     if (peers.length === 0) {
         console.log('No peers found. Share memories with: hippo share <id>');
@@ -382,15 +385,15 @@ export function handlePeers({ flags }) {
         const scopeLabel = allTenants ? 'global store (all tenants)' : `global store (tenant "${tenantScope}")`;
         console.log(`${peers.length} project${peers.length === 1 ? '' : 's'} contributing to ${scopeLabel}:\n`);
         for (const p of peers) {
-            console.log(`  ${p.project.padEnd(25)} ${String(p.count).padStart(4)} memories  (latest: ${p.latest.slice(0, 10)})`);
+            console.log(`  ${p.project.padEnd(25)} ${String(p.count).padStart(4)} memories  (latest: ${p.latest.slice(0, DATE_PREFIX_CHARS)})`);
         }
     }
 }
-export function handleExport({ hippoRoot, args, flags }) {
+export function handleExport({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
-    const format = flags['format'] || 'json';
+    const format = String(flags['format'] || 'json');
     const outputPath = args[0] || null;
-    const entries = loadAllEntries(hippoRoot, resolveTenantId({}));
+    const entries = loadAllEntries(hippoRoot, tenantId);
     let output;
     if (format === 'markdown' || format === 'md') {
         output = entries.map(e => {

package/dist/cli/usage.js

@@ -1,7 +1,8 @@
 // Help text for every verb, keyed like the command table in cli.ts; no command logic lives here.
 import { TAIL_MAX_LINES } from '../support-bundle.js';
-import { DEFAULT_LOCAL_BUMP, DEFAULT_RECALL_BUDGET } from '../search/types.js';
+import { DEFAULT_LOCAL_BUMP, DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
 import { DEFAULT_ASSEMBLE_BUDGET } from '../api/assemble.js';
+import { DEFAULT_SERVER_HOST, DEFAULT_SERVER_PORT } from '../server/defaults.js';
 export function printAuditPruneUsage() {
     console.log('hippo audit prune --older-than <Nd> [--dry-run] [--tenant <t>]');
     console.log('  --older-than <Nd>  Delete audit_log rows with ts older than N days (e.g. 90d).');
@@ -165,7 +166,7 @@ export const VERB_USAGE = {
                            the goal tag get a 1.5x score boost and results are
                            re-sorted. Default off. RESEARCH.md §PFC.dlPFC.
     --session-id <id>      Session identifier for dlPFC goal-stack boost.
-                           Defaults to \$HIPPO_SESSION_ID. When set and the
+                           Defaults to $HIPPO_SESSION_ID. When set and the
                            (tenant, session) has active goals (see
                            'hippo goal push'), recall auto-boosts memories
                            whose tags match an active goal name. Boost stacks
@@ -291,7 +292,9 @@ export const VERB_USAGE = {
   auth <sub>               Manage API keys (A5 stub auth)
     auth create            Mint a new API key (plaintext shown ONCE)
       --label <s>          Optional human label
-      --role <r>           admin | member (default: admin; member blocked from /v1/sleep)
+      --role <r>           admin | member (default: member; member blocked from /v1/sleep)
+      --ttl-days <n>       Days until the key expires (default: 90, at most 3650)
+      --no-expiry          Mint a key that never expires
       --tenant <id>        Override tenant (defaults to HIPPO_TENANT)
       --json               Output as JSON
       --global             Operate on the global store
@@ -662,8 +665,13 @@ export const VERB_USAGE = {
   mcp                      Start MCP server (stdio transport)`],
     serve: [`
   serve                    Start the HTTP API server for this store (Ctrl+C stops it)
-    --port <n>             Port to serve on (default: $HIPPO_PORT or 6789)
-    --host <host>          Address to bind (default: 127.0.0.1)`],
+    --port <n>             Port to serve on (default: $HIPPO_PORT or ${DEFAULT_SERVER_PORT})
+    --host <host>          Address to bind (default: ${DEFAULT_SERVER_HOST})
+    --tls-cert <file>      PEM certificate; serve HTTPS only (or $HIPPO_TLS_CERT)
+    --tls-key <file>       PEM private key for it; give both (or $HIPPO_TLS_KEY)
+                           Every request needs an API key (hippo auth create).
+                           $HIPPO_ALLOW_KEYLESS_LOCAL=1 lets requests from this machine
+                           in without one; $HIPPO_REQUIRE_AUTH=1 wins over it.`],
     invalidate: [`
   invalidate "<pattern>"   Actively weaken memories matching an old pattern
                            (content overlap, or a tag EXACTLY equal to the