hippo-memory 1.69.0 → 1.70.0

package/dist/cli/sleep.d.ts

@@ -1,10 +1,4 @@
-import * as api from '../api.js';
+import { type CliFlags } from './flag-values.js';
 /** Runs `hippo sleep`; with `--log-file` it also tees its output to that file. */
-export declare function cmdSleep(hippoRoot: string, flags: Record<string, string | boolean | string[]>): Promise<void>;
-/**
- * Render an api.sleep result as console output, byte-identical to the
- * pre-extraction inline implementation in cmdSleepCore.
- */
-/** @internal — exported for snapshot tests (tests/cli-context-render-snapshot.test.ts). NOT a stable public API. */
-export declare function renderSleepResult(result: api.SleepResult): void;
+export declare function cmdSleep(hippoRoot: string, flags: CliFlags): Promise<void>;
 //# sourceMappingURL=sleep.d.ts.map

package/dist/cli/sleep.js

@@ -1,17 +1,19 @@
 // The `hippo sleep` verb; main() loads it lazily, since most invocations never sleep.
 import * as path from 'path';
 import * as fs from 'fs';
-import { loadConfig } from '../config.js';
-import { isGitRepo } from '../autolearn.js';
+import { loadConfig } from '../core/config.js';
+import { isGitRepo } from '../learn/autolearn.js';
 import { importForStore, currentMachine } from '../agent-memories/sync.js';
-import { replayCompactionsAt } from '../compaction-record.js';
-import * as api from '../api.js';
-import { resolveTenantId } from '../tenant.js';
-import { renderAmbientSummary } from '../ambient.js';
-import { errorMessage, log } from '../log.js';
-import { closeHippoDb, openHippoDb } from '../db.js';
-import { repairOnceOnSleep } from '../project-merge.js';
-import { requireInit, learnFromRepo, runChurnStaleForRepo, printAgentImport, skipLearnOnSharedStore } from './shared.js';
+import { replayCompactionsAt } from '../capture/compaction-record.js';
+import * as api from '../api/index.js';
+import { resolveTenantId } from '../store/tenant.js';
+import { sleepResultLines } from './sleep-render.js';
+import { errorMessage, log } from '../util/log.js';
+import { closeHippoDb, openHippoDb } from '../db/index.js';
+import { repairOnceOnSleep } from '../sharing/project-merge.js';
+import { boolFlag, stringFlag } from './flag-values.js';
+import { requireInit, learnFromRepo, runChurnStaleForRepo, skipLearnOnSharedStore } from './shared.js';
+import { printAgentImport } from './print.js';
 import { repairQualityOnceAt } from './quality-repair-once.js';
 import { printError } from './output.js';
 /** Runs `hippo sleep`; with `--log-file` it also tees its output to that file. */
@@ -19,7 +21,7 @@ export async function cmdSleep(hippoRoot, flags) {
     // Tee stdout/stderr to a log file when --log-file is set. The SessionEnd
     // hook uses this so the output is captured somewhere the SessionStart hook
     // can re-display it next time the agent UI starts.
-    const logFile = typeof flags['log-file'] === 'string' ? flags['log-file'] : null;
+    const logFile = stringFlag(flags, 'log-file') ?? null;
     let restoreStdout = null;
     if (logFile) {
         try {
@@ -50,7 +52,7 @@ export async function cmdSleep(hippoRoot, flags) {
             };
         }
         catch (err) {
-            log.warn(`could not open log file ${logFile}: ${err.message}`);
+            log.warn(`could not open log file ${logFile}: ${errorMessage(err)}`);
         }
     }
     try {
@@ -60,7 +62,7 @@ export async function cmdSleep(hippoRoot, flags) {
     }
     catch (err) {
         if (logFile)
-            console.log(`[hippo] sleep failed: ${err.message}`);
+            console.log(`[hippo] sleep failed: ${errorMessage(err)}`);
         throw err;
     }
     finally {
@@ -68,67 +70,9 @@ export async function cmdSleep(hippoRoot, flags) {
             restoreStdout();
     }
 }
-/**
- * Render an api.sleep result as console output, byte-identical to the
- * pre-extraction inline implementation in cmdSleepCore.
- */
-/** @internal — exported for snapshot tests (tests/cli-context-render-snapshot.test.ts). NOT a stable public API. */
-export function renderSleepResult(result) {
-    console.log(`Running consolidation${result.dryRun ? ' (dry run)' : ''}...`);
-    console.log(`\nResults:`);
-    console.log(`   Active memories:  ${result.active}`);
-    console.log(`   Removed (decayed): ${result.removed}`);
-    // Only when dormant.enabled moved something, so every other render stays
-    // byte-identical (tests/cli-context-render-snapshot.test.ts).
-    if (result.dormant !== undefined && result.dormant > 0) {
-        console.log(`   Kept dormant:      ${result.dormant}  (hippo dormant to list)`);
-    }
-    if (result.dormantExpired !== undefined && result.dormantExpired > 0) {
-        console.log(`   Expired dormant:   ${result.dormantExpired}  (past dormant.retentionDays)`);
-    }
-    console.log(`   Merged episodic:   ${result.mergedEpisodic}`);
-    console.log(`   New semantic:      ${result.newSemantic}`);
-    if (result.details && result.details.length > 0) {
-        console.log('\nDetails:');
-        for (const d of result.details) {
-            console.log(d);
-        }
-    }
-    if (result.dryRun)
-        console.log('\n(dry run  - nothing written)');
-    if (result.deduped && result.deduped.removed > 0) {
-        const { removed, semDups, epiDups, crossDups } = result.deduped;
-        const parts = [];
-        if (semDups > 0)
-            parts.push(`${semDups} redundant semantic patterns`);
-        if (epiDups > 0)
-            parts.push(`${epiDups} duplicate episodic lessons`);
-        if (crossDups > 0)
-            parts.push(`${crossDups} cross-layer duplicates`);
-        console.log(`\n${result.dryRun ? 'Would dedupe' : 'Deduped'} ${removed} duplicates (${parts.join(', ')}). ${result.dryRun ? 'Would keep' : 'Kept'} stronger copies.`);
-    }
-    if (result.audit) {
-        if (result.audit.errorsRemoved > 0) {
-            console.log(`\nAudit: ${result.dryRun ? 'would remove' : 'removed'} ${result.audit.errorsRemoved} junk memories (too short/empty).`);
-        }
-        if (result.audit.warningCount > 0) {
-            console.log(`Audit: ${result.audit.warningCount} low-quality memories detected (run \`hippo audit\` for details).`);
-        }
-    }
-    if (result.shared !== undefined && result.shared > 0) {
-        console.log(`\nAuto-shared ${result.shared} high-value memories to global store.`);
-    }
-    if (result.secretSkipped !== undefined && result.secretSkipped > 0) {
-        // The secret veto is never silent.
-        console.log(`\nAuto-share: withheld ${result.secretSkipped} secret-flagged ${result.secretSkipped === 1 ? 'memory' : 'memories'} (secret veto).`);
-    }
-    if (result.ambient) {
-        console.log(`\n${renderAmbientSummary(result.ambient)}`);
-    }
-    if (result.graph && result.graph.tenants > 0) {
-        const { tenants, entities, relations } = result.graph;
-        console.log(`\nGraph: rebuilt ${tenants} tenant${tenants === 1 ? '' : 's'} (${entities} entities, ${relations} relations).`);
-    }
+function renderSleepResult(result) {
+    for (const line of sleepResultLines(result))
+        console.log(line);
 }
 /** Fault-isolated: a failed repair warns and runs again next sleep, and never stops the sleep. */
 function repairProjectTagsOnce(hippoRoot) {
@@ -194,8 +138,8 @@ async function cmdSleepCore(hippoRoot, flags) {
         actor: api.adminActor('cli'),
     };
     const result = await api.sleep(ctx, {
-        dryRun: Boolean(flags['dry-run']),
-        noShare: Boolean(flags['no-share']),
+        dryRun: boolFlag(flags, 'dry-run'),
+        noShare: boolFlag(flags, 'no-share'),
     });
     renderSleepResult(result);
 }

package/dist/cli/status.d.ts

@@ -1,4 +1,4 @@
-import { type CommandContext } from './shared.js';
+import { type CliFlags, type CommandContext } from './flag-values.js';
 export declare function cmdStatus(hippoRoot: string): void;
 /**
  * `hippo tokens [--days <n>] [--json] [--global]`: the token ledger.
@@ -7,9 +7,9 @@ export declare function cmdStatus(hippoRoot: string): void;
  * and the hook blocks' tokens later model calls re-read, counted when each session ends.
  * Counts are estimates (characters / 4), the same estimate every budget uses.
  */
-export declare function cmdTokens(hippoRoot: string, flags: Record<string, string | boolean | string[]>): void;
+export declare function cmdTokens(hippoRoot: string, flags: CliFlags): void;
 /** `hippo failures [--days <n>] [--json] [--global]`: failed tool calls by outcome, and repeats across sessions. */
-export declare function cmdFailures(hippoRoot: string, flags: Record<string, string | boolean | string[]>): void;
+export declare function cmdFailures(hippoRoot: string, flags: CliFlags): void;
 export declare function handleCorrectionLatency({ hippoRoot, flags }: CommandContext): void;
 export declare function handleProvenance({ hippoRoot, flags }: CommandContext): void;
 export declare function handleDoctor({ flags }: CommandContext): void;

package/dist/cli/status.js

@@ -1,31 +1,35 @@
 // Read-only report verbs: status, inspect, tokens, failures, provenance, correction latency, doctor and support bundle.
-import { envHomeDir } from '../env.js';
-import { evalNow } from '../ablation.js';
+import { envHomeDir } from '../util/env.js';
+import { evalNow } from '../core/ablation.js';
 import * as path from 'path';
 import * as fs from 'fs';
 import * as os from 'os';
 import { fileURLToPath } from 'node:url';
-import { calculateStrength, calculateRewardFactor, resolveConfidence, confidenceFacets, Layer } from '../memory.js';
+import { calculateStrength, calculateRewardFactor, resolveConfidence, confidenceFacets, Layer } from '../core/memory.js';
 import { readEntry, loadAllEntries } from '../store/entry-reads.js';
 import { loadStats } from '../store/index-and-stats.js';
 import { listMemoryConflicts } from '../store/conflicts.js';
-import { loadEmbeddingIndex, embeddingModelRequiresReindex } from '../embeddings.js';
-import { resolveEmbeddingProvider } from '../embedding-provider.js';
-import { loadPhysicsState } from '../physics-state.js';
-import { computeSystemEnergy, vecNorm } from '../physics.js';
-import { loadConfig } from '../config.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
+import { loadEmbeddingIndex, embeddingModelRequiresReindex } from '../store/embeddings/index.js';
+import { resolveEmbeddingProvider } from '../store/embeddings/provider.js';
+import { loadStoredParticles } from '../store/vector-writes.js';
+import { computeSystemEnergy, vecNorm } from '../core/physics.js';
+import { loadConfig } from '../core/config.js';
 import { runDoctor, formatDoctor } from '../doctor.js';
 import { buildSupportBundle, TAIL_MAX_LINES } from '../support-bundle.js';
-import { PACKAGE_VERSION } from '../version.js';
-import { FAILURE_LOG_RETENTION_DAYS } from '../failure-log.js';
-import { getGlobalRoot } from '../shared.js';
-import { buildProvenanceCoverage } from '../provenance-coverage.js';
-import { buildCorrectionLatency } from '../correction-latency.js';
-import * as api from '../api.js';
-import { resolveTenantId } from '../tenant.js';
+import { PACKAGE_VERSION } from '../util/version.js';
+import { FAILURE_LOG_RETENTION_DAYS } from '../store/failure-log.js';
+import { getGlobalRoot } from '../sharing/shared.js';
+import { buildProvenanceCoverage } from './provenance-coverage.js';
+import { buildCorrectionLatency } from './correction-latency.js';
+import * as api from '../api/index.js';
+import { resolveTenantId } from '../store/tenant.js';
+import { errorMessage, log } from '../util/log.js';
 import { printError } from './output.js';
-import { parseCountFlag, requireInit, fmt, cardStringFlag, hookStoreRoot, resolveAuthRoot, } from './shared.js';
+import { parseCountFlag, stringFlagOrExit, flagIsTrue } from './flag-values.js';
+import { requireInit, resolveAuthRoot } from './shared.js';
+import { fmt } from './print.js';
+import { hookStoreRoot } from './hook-runtime.js';
+import { DAY_MS } from '../util/time.js';
 export function cmdStatus(hippoRoot) {
     requireInit(hippoRoot);
     const entries = loadAllEntries(hippoRoot);
@@ -151,27 +155,21 @@ function printEmbeddingStatus(hippoRoot, entries) {
 // Physics status
 function printPhysicsStatus(hippoRoot) {
     try {
-        const db = openHippoDb(hippoRoot);
-        try {
-            const physicsMap = loadPhysicsState(db);
-            if (physicsMap.size > 0) {
-                const particles = Array.from(physicsMap.values());
-                const physConfig = loadConfig(hippoRoot);
-                const energy = computeSystemEnergy(particles, physConfig.physics.G_memory);
-                let sumVelMag = 0;
-                for (const p of particles)
-                    sumVelMag += vecNorm(p.velocity);
-                const avgVelMag = sumVelMag / particles.length;
-                console.log('');
-                console.log(`Physics: ${particles.length} particles, energy: ${fmt(energy.total, 4)} (KE: ${fmt(energy.kinetic, 4)}, PE: ${fmt(energy.potential, 4)}), avg vel: ${fmt(avgVelMag, 4)}`);
-            }
-        }
-        finally {
-            closeHippoDb(db);
+        const particles = loadStoredParticles(hippoRoot);
+        if (particles.length > 0) {
+            const physConfig = loadConfig(hippoRoot);
+            const energy = computeSystemEnergy(particles, physConfig.physics.G_memory);
+            let sumVelMag = 0;
+            for (const p of particles)
+                sumVelMag += vecNorm(p.velocity);
+            const avgVelMag = sumVelMag / particles.length;
+            console.log('');
+            console.log(`Physics: ${particles.length} particles, energy: ${fmt(energy.total, 4)} (KE: ${fmt(energy.kinetic, 4)}, PE: ${fmt(energy.potential, 4)}), avg vel: ${fmt(avgVelMag, 4)}`);
         }
     }
-    catch {
-        // Physics table may not exist yet — degrade gracefully
+    catch (err) {
+        // The physics table may not exist yet, so status prints without that line.
+        log.debug(`physics status skipped: ${errorMessage(err)}`);
     }
 }
 function cmdInspect(hippoRoot, id) {
@@ -185,8 +183,8 @@ function cmdInspect(hippoRoot, id) {
     const currentStrength = calculateStrength(entry, now);
     const lastRetrieved = new Date(entry.last_retrieved);
     const created = new Date(entry.created);
-    const ageDays = (now.getTime() - created.getTime()) / (1000 * 60 * 60 * 24);
-    const daysSince = (now.getTime() - lastRetrieved.getTime()) / (1000 * 60 * 60 * 24);
+    const ageDays = (now.getTime() - created.getTime()) / DAY_MS;
+    const daysSince = (now.getTime() - lastRetrieved.getTime()) / DAY_MS;
     const effectiveConfidence = resolveConfidence(entry, now);
     console.log(`Memory: ${entry.id}`);
     console.log('---------------------------');
@@ -363,12 +361,12 @@ export function handleDoctor({ flags }) {
         process.exit(1);
 }
 export function handleSupportBundle({ flags }) {
-    const outFlag = cardStringFlag(flags, 'out');
+    const outFlag = stringFlagOrExit(flags, 'out');
     if (outFlag === '') {
         printError('--out requires a file path.');
         process.exit(1);
     }
-    const includeLogs = flags['include-logs'] === true;
+    const includeLogs = flagIsTrue(flags, 'include-logs');
     const home = envHomeDir() || os.homedir();
     const now = new Date();
     const bundle = buildSupportBundle({ cwd: process.cwd(), home, version: PACKAGE_VERSION, includeLogs, now });
@@ -383,7 +381,7 @@ export function handleSupportBundle({ flags }) {
             printError(`${file} already exists; pass --out to choose another file. Nothing was written.`);
         }
         else {
-            printError(err instanceof Error ? err.message : String(err));
+            printError(errorMessage(err));
         }
         process.exit(1);
     }

package/dist/{stdin.js → cli/stdin.js}

@@ -1,8 +1,8 @@
-import { envStdinWaitMs } from './env.js';
-import { isJsonObject } from './hooks/shared.js';
-import { isJsonString } from './json.js';
+import { envStdinWaitMs } from '../util/env.js';
+import { isJsonString, isJsonObjectLiteral } from '../util/json.js';
+const DEFAULT_STDIN_WAIT_MS = 1000;
 function defaultWaitMs() {
-    return envStdinWaitMs() ?? 1000;
+    return envStdinWaitMs() ?? DEFAULT_STDIN_WAIT_MS;
 }
 /** Never blocks: a TTY resolves at once, otherwise waits up to `waitMs` of
  * idle (default 1000ms, or `HIPPO_STDIN_WAIT_MS`), refreshed on each chunk
@@ -73,7 +73,7 @@ function snakeCaseFields(payload) {
         added.tool_input = parsedToolArgs(payload.toolArgs);
     const error = payload.error;
     // An error object gives its message, so readers that expect the documented string still get one.
-    if (isJsonObject(error) && isJsonString(error.message))
+    if (isJsonObjectLiteral(error) && isJsonString(error.message))
         added.error = error.message;
     return added;
 }
@@ -91,7 +91,7 @@ export function normaliseHookPayload(text) {
         // Not JSON: each reader already treats that as a malformed payload, so it passes through untouched.
         return text;
     }
-    if (!isJsonObject(payload))
+    if (!isJsonObjectLiteral(payload))
         return text;
     const added = snakeCaseFields(payload);
     return Object.keys(added).length === 0 ? text : JSON.stringify({ ...payload, ...added });

package/dist/cli/transfer.d.ts

@@ -1,7 +1,7 @@
-import { type CommandContext } from './shared.js';
-export declare function cmdLearn(hippoRoot: string, flags: Record<string, string | boolean | string[]>): void;
-export declare function cmdImport(hippoRoot: string, args: string[], flags: Record<string, string | boolean | string[]>): void;
-export declare function cmdSync(hippoRoot: string, flags?: Record<string, string | boolean | string[]>): void;
+import { type CliFlags, type CommandContext } from './flag-values.js';
+export declare function cmdLearn(hippoRoot: string, flags: CliFlags): void;
+export declare function cmdImport(hippoRoot: string, args: string[], flags: CliFlags): void;
+export declare function cmdSync(hippoRoot: string, flags?: CliFlags): void;
 export declare function handleWatch({ hippoRoot, args }: CommandContext): Promise<void>;
 export declare function handlePromote({ hippoRoot, args }: CommandContext): Promise<void>;
 export declare function handleShare({ hippoRoot, args, flags }: CommandContext): void;

package/dist/cli/transfer.js

@@ -1,26 +1,33 @@
 // 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 { calculateStrength, deriveHalfLife } from '../core/memory.js';
 import { isInitialized } from '../store/open.js';
 import { writeEntry } from '../store/entry-writes.js';
 import { readEntry, loadAllEntries } from '../store/entry-reads.js';
+import { schemaFitInStore } from '../store/candidates.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 { RejectedValueError } from '../store/rejection.js';
+import { embedAll, embedMemory, loadEmbeddingIndex } from '../store/embeddings/index.js';
+import { loadConfig } from '../core/config.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, shareMemory, listPeers, autoShare, transferScore, syncGlobalToLocal, } from '../sharing/shared.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 * as client from './client.js';
+import { resolveTenantId } from '../store/tenant.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, nonEmptyStringFlag } from './flag-values.js';
+import { CONTENT_PREVIEW_CHARS, DATE_PREFIX_CHARS } from '../util/token-text.js';
+const STDERR_PREVIEW_CHARS = 80;
+const MAX_ENTRIES_SHOWN = 10;
 // ---------------------------------------------------------------------------
 // Watch command
 // ---------------------------------------------------------------------------
@@ -40,10 +47,7 @@ async function cmdWatch(command, hippoRoot) {
         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.schema_fit = schemaFitInStore(hippoRoot, entry.tenantId, entry.content, entry.tags);
     entry.half_life_days = deriveHalfLife(loadConfig(hippoRoot).defaultHalfLifeDays, entry);
     entry.strength = calculateStrength(entry);
     // A rejection-guard refusal of a failed command's output must not crash the watcher:
@@ -52,7 +56,7 @@ async function cmdWatch(command, hippoRoot) {
         writeEntry(hippoRoot, entry);
         updateStats(hippoRoot, { remembered: 1 });
         void embedMemory(hippoRoot, entry);
-        const preview = stderr.trim().slice(0, 80);
+        const preview = stderr.trim().slice(0, STDERR_PREVIEW_CHARS);
         printError(`\nHippo learned from failure: "${preview}"`);
     }
     catch (err) {
@@ -76,8 +80,8 @@ export function cmdLearn(hippoRoot, flags) {
     }
     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;
@@ -97,13 +101,25 @@ export function cmdLearn(hippoRoot, flags) {
 // ---------------------------------------------------------------------------
 // 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']);
+    const useGlobal = boolFlag(flags, 'global');
+    const dryRun = boolFlag(flags, 'dry-run');
     const extraTags = Array.isArray(flags['tag'])
         ? flags['tag']
         : flags['tag']
@@ -132,7 +148,7 @@ export function cmdImport(hippoRoot, args, flags) {
     // vault import (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);
+    importFromFile(targetRoot, args, flags, { importOptions, useGlobal, dryRun });
 }
 // Determine which importer to use based on flag
 function pickImporter(args, flags) {
@@ -151,7 +167,8 @@ 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]');
@@ -169,9 +186,12 @@ function importFromFile(targetRoot, args, flags, importOptions, useGlobal, dryRu
     // 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.
     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 +204,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`);
@@ -209,6 +229,18 @@ function importAgentMemories(hippoRoot, useGlobal, dryRun) {
 }
 function importVaultFolder(hippoRoot, flags, importOptions, useGlobal, dryRun) {
     const folderPath = String(flags['vault']);
+    checkVaultArgs(folderPath, flags, useGlobal);
+    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);
+    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);
@@ -230,14 +262,8 @@ function importVaultFolder(hippoRoot, flags, importOptions, useGlobal, dryRun) {
         printError('hippo import --vault: --scope requires a value (e.g. --scope vault:private:notes).');
         process.exit(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}`);
@@ -252,7 +278,7 @@ function importVaultFolder(hippoRoot, flags, importOptions, useGlobal, dryRun) {
     // write through api.remember (which never embeds), so backfill them here.
     // Floating promise is deliberate; see the comment at the single-file site.
     if (!dryRun && vaultResult.imported >= 1) {
-        void embedAll(hippoRoot).catch(() => { });
+        void embedAll(hippoRoot).catch((err) => warnBackfillFailed(hippoRoot, 'hippo embed', err));
     }
 }
 // ---------------------------------------------------------------------------
@@ -275,7 +301,7 @@ function cmdPromote(hippoRoot, id) {
         console.log(`   Global store: ${getGlobalRoot()}`);
     }
     catch (err) {
-        printError(`Failed to promote: ${err.message}`);
+        printError(`Failed to promote: ${errorMessage(err)}`);
         process.exit(1);
     }
 }
@@ -290,7 +316,7 @@ 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)'}`);
 }
@@ -310,7 +336,7 @@ export async function handlePromote({ hippoRoot, args }) {
             console.log(`Promoted ${id} to global store as ${result.globalId}`);
         }
         catch (err) {
-            printError(`Failed to promote: ${err.message}`);
+            printError(`Failed to promote: ${errorMessage(err)}`);
             process.exit(1);
         }
     });
@@ -324,7 +350,7 @@ export function handleShare({ hippoRoot, args, flags }) {
         // Auto-share mode
         requireInit(hippoRoot);
         const minScore = parseFloat(String(flags['min-score'] ?? '0.6'));
-        const dryRun = Boolean(flags['dry-run']);
+        const dryRun = boolFlag(flags, 'dry-run');
         const results = autoShare(hippoRoot, { minScore, dryRun, tenantId: resolveTenantId({}) });
         if (results.length === 0) {
             console.log('No memories meet the sharing threshold.');
@@ -333,7 +359,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,7 +371,7 @@ export function handleShare({ hippoRoot, args, flags }) {
     }
     else if (shareId) {
         requireInit(hippoRoot);
-        const force = Boolean(flags['force']);
+        const force = boolFlag(flags, 'force');
         const tenantId = resolveTenantId({});
         const result = shareMemory(hippoRoot, shareId, { force, tenantId });
         if (result) {
@@ -372,7 +398,7 @@ export function handleShare({ hippoRoot, args, flags }) {
 }
 export function handlePeers({ flags }) {
     // Tenant-scoped by default; --all-tenants gives the host-wide view for cross-tenant peer discovery.
-    const allTenants = flags['all-tenants'] === true;
+    const allTenants = flagIsTrue(flags, 'all-tenants');
     const tenantScope = allTenants ? undefined : resolveTenantId({});
     const peers = listPeers(undefined, tenantScope);
     if (peers.length === 0) {
@@ -382,13 +408,13 @@ 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 }) {
     requireInit(hippoRoot);
-    const format = flags['format'] || 'json';
+    const format = (flags['format'] || 'json');
     const outputPath = args[0] || null;
     const entries = loadAllEntries(hippoRoot, resolveTenantId({}));
     let output;

package/dist/cli/usage.js

@@ -1,6 +1,6 @@
 // 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';
 export function printAuditPruneUsage() {
     console.log('hippo audit prune --older-than <Nd> [--dry-run] [--tenant <t>]');
@@ -663,7 +663,9 @@ export const VERB_USAGE = {
     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)`],
+    --host <host>          Address to bind (default: 127.0.0.1)
+    --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)`],
     invalidate: [`
   invalidate "<pattern>"   Actively weaken memories matching an old pattern
                            (content overlap, or a tag EXACTLY equal to the