hippo-memory 1.44.0 → 1.45.0

package/dist/cli.js

@@ -29,7 +29,7 @@
  *   hippo decide "<decision>" [--context "<why>"] [--supersedes <id>]
  *   hippo wm <push|read|clear|flush>
  */
-import { evalNow, isRecallBoostAblated } from './ablation.js';
+import { evalNow } from './ablation.js';
 import * as path from 'path';
 import * as fs from 'fs';
 import * as os from 'os';
@@ -38,14 +38,14 @@ import { execFileSync, execSync, spawn } from 'child_process';
 import { installJsonHooks, uninstallJsonHooks, resolveJsonHookPaths, detectInstalledTools, defaultSleepLogPath, ensureCodexWrapperInstalled, installCodexWrapper, isCodexWrapperInstalled, repairCodexWrapperIfInstalled, uninstallCodexWrapper, resolveCodexSessionTranscript, resolveCodexWrapperPaths, installOpencodePlugin, uninstallOpencodePlugin, resolveOpencodePluginPath, } from './hooks.js';
 import { createMemory, calculateStrength, calculateRewardFactor, deriveHalfLife, resolveConfidence, confidenceFacets, confidenceLabel, computeSchemaFit, Layer, } from './memory.js';
 import { detectSecret } from './secret-detect.js';
-import { getHippoRoot, isInitialized, initStore, writeEntry, readEntry, deleteEntry, loadAllEntries, loadSearchEntries, loadRecallSearchEntries, loadIndex, saveIndex, loadStats, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, createCard, loadCard, listCards, loadCardRuns, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, } from './store.js';
+import { getHippoRoot, isInitialized, initStore, writeEntry, strengthenRetrieved, readEntry, deleteEntry, loadAllEntries, loadSearchEntries, loadRecallSearchEntries, loadIndex, saveIndex, loadStats, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, createCard, loadCard, listCards, loadCardRuns, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, } from './store.js';
 import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
 import { RejectedValueError } from './rejection.js';
 import { isHandoffOutcome, formatHandoffEvidenceLine } from './handoff.js';
 import { isCardStatus } from './card.js';
 import { loadCardDetail } from './card-detail.js';
 import { passesScopeFilterForRecall } from './recall-scope.js';
-import { markRetrieved, hybridSearch, physicsSearch, explainMatch, textOverlap, tokenize as tokenizeQuery } from './search.js';
+import { hybridSearch, physicsSearch, explainMatch, textOverlap, tokenize as tokenizeQuery } from './search.js';
 import { compareEntryIdentity } from './compare.js';
 import { renderTraceContent, parseSteps } from './trace.js';
 import { writeRecallTraceAtRoot } from './recall-trace.js';
@@ -195,8 +195,8 @@ function requireInit(hippoRoot) {
  * H2: when HIPPO_REQUIRE_SERVER is set, the CLI must not silently fall back to
  * direct DB mode — a missing server then masks a real misconfiguration (the
  * configured HIPPO_API_KEY is also silently discarded on fallback). Throws a
- * clear, actionable error in that case; a no-op when the knob is unset, so
- * default behaviour is unchanged.
+ * clear error then. It guards only the routed writes (remember, forget, archive,
+ * promote); every other command opens the store directly, knob or not.
  */
 function failIfServerRequired(reason) {
     if (process.env['HIPPO_REQUIRE_SERVER']) {
@@ -263,6 +263,42 @@ export const BOOLEAN_FLAGS = new Set([
     'reset-physics', 'save-baseline', 'show-cases', 'stats', 'stdin',
     'strict', 'suite', 'value-aware', 'verified', 'version', 'why',
 ]);
+// Every flag some command reads. Anything else is a typo that no command would act on.
+export const KNOWN_FLAGS = new Set([
+    ...BOOLEAN_FLAGS,
+    'actual', 'artifact', 'artifact-ref', 'as-of', 'author', 'baseline', 'body', 'budget', 'card-id',
+    'change', 'channel', 'chatgpt', 'class', 'claude', 'codex-home', 'compare', 'constraint', 'content',
+    'context', 'contract', 'cursor', 'customer', 'days', 'depends-on', 'depth', 'description',
+    'embedding-weight', 'entity', 'estimate', 'file', 'format', 'framing', 'fresh-tail', 'from', 'goal',
+    'graph-hops', 'graph-seeds', 'history-path', 'hops', 'host', 'id', 'importance', 'include-recent',
+    'instructions', 'keep', 'kind', 'label', 'layer', 'level', 'limit', 'link', 'local-bump', 'log-file',
+    'markdown', 'max', 'max-cases', 'max-neighbors', 'min-mrr', 'min-results', 'min-score', 'mmr-lambda',
+    'model', 'name', 'next', 'next-step', 'note', 'older-than', 'op', 'out', 'outcome', 'owner', 'parent',
+    'path', 'policy', 'port', 'reason', 'repo', 'repos', 'reranker', 'reranker-top-k', 'resolution',
+    'role', 'run', 'runtime', 'salience-threshold', 'scan', 'scope', 'session', 'session-id', 'since',
+    'source', 'start-offset', 'started-at', 'state', 'status', 'step', 'steps', 'success', 'summary',
+    'supersedes', 'tag', 'target', 'target-runtime', 'task', 'team', 'tenant', 'tenant-id', 'tests',
+    'text', 'threshold', 'title', 'to', 'transcript', 'trigger', 'type', 'unit', 'value', 'vault',
+]);
+// Commands that delete or hide memories: an unknown flag here stops the run instead of being ignored.
+const DESTRUCTIVE_COMMANDS = new Set([
+    'audit', 'dedup', 'forget', 'invalidate', 'reject', 'resolve', 'sleep', 'supersede',
+]);
+// Commands that honour --dry-run. Any other command would ignore it and run for real.
+const DRY_RUN_COMMANDS = new Set([
+    'audit', 'capture', 'dedup', 'forget', 'import', 'invalidate', 'refine', 'setup', 'sleep',
+]);
+// share and brief honour --dry-run in one form only; their other forms write for real.
+function dryRunRefusal(command, args, flags) {
+    const isBrief = command === 'brief' || command === 'project-brief';
+    const onlyForm = command === 'share' ? 'share --auto' : isBrief ? `${command} refresh` : null;
+    const honoured = command === 'share' ? args[0] === '--auto' || Boolean(flags['auto'])
+        : isBrief ? args[0] === 'refresh' : DRY_RUN_COMMANDS.has(command);
+    if (honoured)
+        return null;
+    const where = onlyForm ? ` outside \`hippo ${onlyForm}\`` : '';
+    return `hippo ${command} has no --dry-run${where}, so it would run for real. Nothing was changed.`;
+}
 // Shared by both the separated and glued (`=`) forms so the list can't drift.
 function isRepeatableFlag(key) {
     return key === 'tag' || key === 'artifact' || key === 'link' || key === 'step' || key === 'constraint' || key === 'depends-on';
@@ -658,7 +694,7 @@ async function cmdRemember(hippoRoot, text, flags) {
     if (flags['verified'])
         confidence = 'verified';
     // Compute schema fit against existing memories
-    const existing = loadAllEntries(targetRoot);
+    const existing = loadAllEntries(targetRoot, resolveTenantId({}));
     const schemaFit = computeSchemaFit(text, rawTags, existing);
     // A3 envelope flags
     const kindFlagRaw = typeof flags['kind'] === 'string' ? flags['kind'] : undefined;
@@ -688,6 +724,7 @@ async function cmdRemember(hippoRoot, text, flags) {
     // A5 stub auth: stamp tenant_id from env (HIPPO_TENANT) so recall isolation
     // can filter on this row. Default tenant 'default' for unauthenticated CLI.
     const tenantId = resolveTenantId({});
+    const rememberConfig = loadConfig(targetRoot);
     const entry = createMemory(text, {
         layer: Layer.Episodic,
         tags: rawTags,
@@ -700,6 +737,7 @@ async function cmdRemember(hippoRoot, text, flags) {
         owner: ownerFlag,
         artifact_ref: artifactRefFlag,
         tenantId,
+        baseHalfLifeDays: rememberConfig.defaultHalfLifeDays,
     });
     // Auto-tag with path context
     const pathTags = extractPathTags(process.cwd());
@@ -716,7 +754,6 @@ async function cmdRemember(hippoRoot, text, flags) {
             entry.tags.push(scopeTag);
     }
     // Salience gate: decide if this memory is worth storing
-    const rememberConfig = loadConfig(targetRoot);
     if (rememberConfig.salience.enabled && !Boolean(flags['pin']) && !Boolean(flags['force'])) {
         const salienceResult = computeSalience(text, entry.tags, existing, {
             recentWindow: rememberConfig.salience.recentWindow,
@@ -758,14 +795,16 @@ async function cmdRemember(hippoRoot, text, flags) {
             const facts = await extractFacts(entry.content, {
                 apiKey,
                 model: config.extraction.model,
+                onError: (msg) => console.error(`  (extraction failed: ${msg})`),
             });
             if (facts.length > 0) {
                 storeExtractedFacts(targetRoot, entry, facts);
                 console.error(`  extracted ${facts.length} fact(s)`);
             }
         }
-        catch {
-            // Extraction is best-effort — never block remember
+        catch (err) {
+            // Extraction is best-effort: report it, never block remember.
+            console.error(`  (extraction failed: ${err instanceof Error ? err.message : String(err)})`);
         }
     }
     else if (shouldExtract && !apiKey) {
@@ -797,6 +836,7 @@ function cmdSupersede(hippoRoot, oldId, newContent, flags) {
         pinned,
         source: old.source,
         confidence: 'verified',
+        tenantId: old.tenantId,
     });
     // AT1: write the SUCCESSOR first. The rejection guard fires on the new
     // content — if it refuses, nothing has been mutated yet (the old ordering
@@ -854,8 +894,9 @@ async function cmdRecall(hippoRoot, query, flags) {
     // detected-project recalls would change shape.
     const recallExplicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
     const requestedScopeForFilter = recallExplicitScope || undefined;
-    let localEntries = loadRecallSearchEntries(hippoRoot, query, undefined, tenantId, requestedScopeForFilter, 'additive');
-    let globalEntries = isInitialized(globalRoot) ? loadRecallSearchEntries(globalRoot, query, undefined, tenantId, requestedScopeForFilter, 'additive') : [];
+    const loadSuperseded = includeSuperseded || Boolean(asOf);
+    let localEntries = loadRecallSearchEntries(hippoRoot, query, undefined, tenantId, requestedScopeForFilter, 'additive', loadSuperseded);
+    let globalEntries = isInitialized(globalRoot) ? loadRecallSearchEntries(globalRoot, query, undefined, tenantId, requestedScopeForFilter, 'additive', loadSuperseded) : [];
     // v1.12.13 / C5 — WYSIATI counters. Track filter activity per the plan v3
     // Task 3 mapping table. dropped_pre_rank is the SUM of all non-budget
     // filter drops (pre-rank AND post-rank); its meaning is unchanged by C5.
@@ -1725,21 +1766,13 @@ async function cmdRecall(hippoRoot, query, flags) {
         console.log('No memories found for:', query);
         return;
     }
-    // Update retrieval metadata and persist
-    const updated = markRetrieved(results.map((r) => r.entry));
+    const retrievedIds = results.map((r) => r.entry.id);
     const localIndex = loadIndex(hippoRoot);
-    // EVAL-ONLY ablation (see ablation.ts): under the recall flag, markRetrieved
-    // returns unmutated entries (ids preserved for outcome attribution below)
-    // and persistence is skipped - writeEntry on identical rows still refreshes
-    // updated_at, rewrites mirrors, and marks DAG parents dirty.
-    if (!isRecallBoostAblated()) {
-        for (const u of updated) {
-            const targetRoot = localIndex.entries[u.id] ? hippoRoot : (isInitialized(globalRoot) ? globalRoot : hippoRoot);
-            writeEntry(targetRoot, u);
-        }
-    }
+    const strengthenedHere = strengthenRetrieved(hippoRoot, retrievedIds);
+    if (isInitialized(globalRoot))
+        strengthenRetrieved(globalRoot, retrievedIds.filter((id) => !strengthenedHere.has(id)));
     // Track last retrieval IDs for outcome command
-    localIndex.last_retrieval_ids = updated.map((u) => u.id);
+    localIndex.last_retrieval_ids = retrievedIds;
     // LC1 F1 structural fix (docs/plans/2026-08-02-lc1-recall-trace-persistence.md):
     // ONE trace at hippoRoot (where last_retrieval_ids and outcome
     // attribution live). Write the trace FIRST, then fold its id into
@@ -1971,8 +2004,9 @@ async function cmdExplain(hippoRoot, query, flags) {
     // command honest for an operator debugging a hidden row.
     const explainExplicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
     const explainRequestedScope = explainExplicitScope || undefined;
-    let explainLocalEntries = loadRecallSearchEntries(hippoRoot, query, undefined, tenantId, explainRequestedScope, 'additive');
-    let explainGlobalEntries = isInitialized(globalRoot) ? loadRecallSearchEntries(globalRoot, query, undefined, tenantId, explainRequestedScope, 'additive') : [];
+    const explainLoadSuperseded = explainIncludeSuperseded || Boolean(explainAsOf);
+    let explainLocalEntries = loadRecallSearchEntries(hippoRoot, query, undefined, tenantId, explainRequestedScope, 'additive', explainLoadSuperseded);
+    let explainGlobalEntries = isInitialized(globalRoot) ? loadRecallSearchEntries(globalRoot, query, undefined, tenantId, explainRequestedScope, 'additive', explainLoadSuperseded) : [];
     const passesExplainScope = (e) => api.passesCliRecallScopeFilter(e.scope ?? null, explainRequestedScope);
     explainLocalEntries = explainLocalEntries.filter(passesExplainScope);
     explainGlobalEntries = explainGlobalEntries.filter(passesExplainScope);
@@ -2376,6 +2410,7 @@ function cmdTraceRecord(hippoRoot, flags) {
         source: String(flags['source'] ?? 'cli'),
         trace_outcome: outcome,
         source_session_id: sessionId,
+        tenantId: resolveTenantId({}),
     });
     writeEntry(hippoRoot, entry);
     console.log(`Recorded trace ${entry.id} (outcome=${outcome}, ${steps.length} steps)`);
@@ -2540,7 +2575,7 @@ export function learnFromMemoryMd(hippoRoot, homeDir = os.homedir()) {
     }
     if (memoryDirs.length === 0)
         return 0;
-    const existing = loadAllEntries(hippoRoot);
+    const existing = loadAllEntries(hippoRoot, resolveTenantId({}));
     let imported = 0;
     let skippedSecret = 0;
     // AT1 (plan §3 containment): a rejection guard refusal is per-VALUE — one
@@ -2583,6 +2618,7 @@ export function learnFromMemoryMd(hippoRoot, homeDir = os.homedir()) {
                     tags: ['claude-code-memory'],
                     source: `claude-memory:${file}`,
                     confidence: 'observed',
+                    tenantId: resolveTenantId({}),
                 });
                 try {
                     writeEntry(hippoRoot, entry);
@@ -2731,11 +2767,11 @@ export function renderSleepResult(result) {
             parts.push(`${epiDups} duplicate episodic lessons`);
         if (crossDups > 0)
             parts.push(`${crossDups} cross-layer duplicates`);
-        console.log(`\nDeduped ${removed} duplicates (${parts.join(', ')}). Kept stronger copies.`);
+        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: removed ${result.audit.errorsRemoved} junk memories (too short/empty).`);
+            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).`);
@@ -2760,7 +2796,10 @@ async function cmdSleepCore(hippoRoot, flags) {
     requireInit(hippoRoot);
     // Phase 1: Auto-learn from git + MEMORY.md (CLI-only, uses process.cwd() / os.homedir()).
     // Stays in cli.ts; api.sleep covers Phase 2-6 only.
-    if (!flags['no-learn']) {
+    if (!flags['no-learn'] && flags['dry-run']) {
+        console.log('Dry run: skipped learning from git commits and MEMORY.md files.');
+    }
+    else if (!flags['no-learn']) {
         const config = loadConfig(hippoRoot);
         if (config.autoLearnOnSleep && isGitRepo(process.cwd())) {
             const { added } = learnFromRepo(hippoRoot, process.cwd(), 1);
@@ -3227,13 +3266,13 @@ async function cmdCodexSessionEndWorker(hippoRoot, flags) {
         // capture path logs its own failures
     }
 }
-function shouldAutoRepairCodexWrapper(currentCommand, currentArgs) {
+export function shouldAutoRepairCodexWrapper(currentCommand, flags) {
     if (process.env.HIPPO_SKIP_AUTO_INTEGRATIONS === '1')
         return false;
     if (!['context', 'remember', 'recall', 'sleep', 'capture', 'outcome', 'status', 'init'].includes(currentCommand)) {
         return false;
     }
-    if (currentCommand === 'init' && currentArgs.includes('--no-hooks'))
+    if (currentCommand === 'init' && flags['no-hooks'] === true)
         return false;
     return true;
 }
@@ -3242,8 +3281,8 @@ function shouldAutoRepairCodexWrapper(currentCommand, currentArgs) {
 // shim). Never first-installs — silently swapping the codex binary on routine
 // commands is a consent violation and reads as binary hijacking to
 // supply-chain scanners (issue #133).
-function maybeRepairCodexWrapper(currentCommand, currentArgs) {
-    if (!shouldAutoRepairCodexWrapper(currentCommand, currentArgs))
+function maybeRepairCodexWrapper(currentCommand, flags) {
+    if (!shouldAutoRepairCodexWrapper(currentCommand, flags))
         return;
     try {
         repairCodexWrapperIfInstalled();
@@ -3465,8 +3504,7 @@ function cmdForget(hippoRoot, id, flags) {
         if (/append-only/i.test(msg)) {
             // The delete was refused by the append-only trigger — this is a raw
             // memory, not a missing one. Point the user at the archive path.
-            console.error(`Cannot forget ${id}: it is a raw, append-only memory. ` +
-                `Archive it instead: hippo forget ${id} --archive --reason "<why>"`);
+            console.error(rawForgetRefusal(id));
         }
         else {
             console.error(`Memory not found: ${id}`);
@@ -3474,6 +3512,28 @@ function cmdForget(hippoRoot, id, flags) {
         process.exit(1);
     }
 }
+function rawForgetRefusal(id) {
+    return `Cannot forget ${id}: it is a raw, append-only memory. Archive it instead: hippo forget ${id} --archive --reason "<why>"`;
+}
+// Refuses exactly where the real run would, so "Would forget" is a promise, not a guess.
+function previewForget(hippoRoot, id, archive) {
+    requireInit(hippoRoot);
+    const entry = readEntry(hippoRoot, id, resolveTenantId({}));
+    if (!entry) {
+        console.error(`Memory not found: ${id}`);
+        process.exit(1);
+    }
+    if (!archive && entry.kind === 'raw') {
+        console.error(rawForgetRefusal(id));
+        process.exit(1);
+    }
+    if (archive && entry.kind !== 'raw') {
+        console.error(`Could not archive ${id}: memory ${id} is not raw (kind=${entry.kind})`);
+        process.exit(1);
+    }
+    const snippet = entry.content.length > 80 ? `${entry.content.slice(0, 80)}...` : entry.content;
+    console.log(`Would ${archive ? 'archive' : 'forget'} ${id} (dry run, nothing changed): "${snippet}"`);
+}
 function cmdInspect(hippoRoot, id) {
     requireInit(hippoRoot);
     const entry = readEntry(hippoRoot, id, resolveTenantId({}));
@@ -6304,9 +6364,9 @@ async function cmdWatch(command, hippoRoot) {
         console.error('Command failed but .hippo not initialized. Run `hippo init` to enable auto-learn.');
         process.exit(exitCode);
     }
-    const entry = captureError(exitCode, stderr, command);
+    const entry = captureError(exitCode, stderr, command, resolveTenantId({}));
     // Compute schema fit against existing memories
-    const existingWatch = loadAllEntries(hippoRoot);
+    const existingWatch = loadAllEntries(hippoRoot, entry.tenantId);
     const watchFit = computeSchemaFit(entry.content, entry.tags, existingWatch);
     entry.schema_fit = watchFit;
     entry.half_life_days = deriveHalfLife(7, entry);
@@ -6392,14 +6452,9 @@ function learnFromRepo(hippoRoot, repoPath, days, label) {
     // the existing summary line.
     let rejected = 0;
     const gitLearnTags = ['error', 'git-learned'];
-    const existingForSchema = loadAllEntries(hippoRoot);
+    const existingForSchema = loadAllEntries(hippoRoot, resolveTenantId({}));
     for (const lesson of lessons) {
-        // L9: learnFromRepo's existingForSchema load just above (the
-        // `loadAllEntries(hippoRoot)` call a few lines up) is host-wide and
-        // intentionally out-of-L9-scope per plan §11 (cli.ts is
-        // single-tenant-per-process). The tenantId arg here is a defensive no-op:
-        // deduplicateLesson's array overload ignores it; the parameter exists
-        // only to mirror the canonical caller pattern used elsewhere in cli.ts.
+        // The array overload ignores the tenant arg; existingForSchema is already scoped.
         if (deduplicateLesson(existingForSchema, lesson, 0.7, resolveTenantId({}))) {
             skipped++;
             continue;
@@ -6418,6 +6473,7 @@ function learnFromRepo(hippoRoot, repoPath, days, label) {
             source: 'git-learn',
             confidence: 'observed',
             schema_fit: schemaFitVal,
+            tenantId: resolveTenantId({}),
         });
         // Auto-tag with path context from the repo being learned
         const learnPathTags = extractPathTags(repoPath);
@@ -8632,25 +8688,16 @@ Examples:
 // ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
-const { command, args, flags } = parseArgs(process.argv);
-const hippoRoot = getHippoRoot(process.cwd());
-async function main() {
+async function main(command, args, flags, hippoRoot) {
     if (command === '--version' || command === '-v' || flags['version']) {
         const __filename_local = fileURLToPath(import.meta.url);
         const __dirname_local = path.dirname(__filename_local);
-        const pkgPath = path.join(__dirname_local, '..', 'package.json');
-        let pkgJson;
-        try {
-            pkgJson = fs.readFileSync(pkgPath, 'utf-8');
-        }
-        catch {
-            pkgJson = fs.readFileSync(path.join(__dirname_local, '..', '..', 'package.json'), 'utf-8');
-        }
+        const pkgJson = fs.readFileSync(path.join(__dirname_local, '..', 'package.json'), 'utf-8');
         const { version } = JSON.parse(pkgJson);
         console.log(version);
         process.exit(0);
     }
-    maybeRepairCodexWrapper(command, args);
+    maybeRepairCodexWrapper(command, flags);
     /** Global --scope well-formedness guard (v1.26.2). parseArgs stores a value-less
      *  flag as boolean true; downstream the 14 consumer sites either coerced that to
      *  the literal scope string 'true' (recall filter/unlock input, wm session scope,
@@ -8685,6 +8732,21 @@ async function main() {
             process.exit(1);
         }
     }
+    // card checks its flags per subcommand, with a stricter message.
+    const unknownFlags = command === 'card' ? [] : Object.keys(flags).filter((key) => !KNOWN_FLAGS.has(key));
+    if (unknownFlags.length > 0) {
+        const names = unknownFlags.map((key) => `--${key}`).join(', ');
+        if (DESTRUCTIVE_COMMANDS.has(command)) {
+            console.error(`Unknown flag ${names} for hippo ${command}. Nothing was changed.`);
+            process.exit(2);
+        }
+        console.error(`hippo: ignoring unknown flag ${names}. A later release will reject it.`);
+    }
+    const refusal = Object.hasOwn(flags, 'dry-run') ? dryRunRefusal(command, args, flags) : null;
+    if (refusal) {
+        console.error(refusal);
+        process.exit(2);
+    }
     switch (command) {
         case 'init':
             cmdInit(hippoRoot, flags);
@@ -8876,7 +8938,7 @@ async function main() {
                 break;
             }
             requireInit(hippoRoot);
-            const entries = loadAllEntries(hippoRoot);
+            const entries = loadAllEntries(hippoRoot, resolveTenantId({}));
             const result = auditMemories(entries);
             const shouldFix = Boolean(flags['fix']);
             if (result.issues.length === 0) {
@@ -8890,13 +8952,15 @@ async function main() {
                     console.log(`         "${issue.content.slice(0, 80)}${issue.content.length > 80 ? '...' : ''}"`);
                 }
                 if (shouldFix) {
-                    const errorIds = result.issues.filter(i => i.severity === 'error').map(i => i.memoryId);
-                    if (errorIds.length > 0) {
-                        for (const id of errorIds) {
-                            deleteEntry(hippoRoot, id);
-                        }
-                        console.log(`\nRemoved ${errorIds.length} error-severity memories.`);
-                        console.log(`${result.issues.length - errorIds.length} warnings remain (review manually).`);
+                    const errors = result.issues.filter(i => i.severity === 'error');
+                    if (errors.length > 0 && flags['dry-run'] === true) {
+                        console.log(`\nWould remove ${errors.length} error-severity memories (dry run, nothing deleted).`);
+                        console.log(`${result.issues.length - errors.length} warnings would remain (review manually).`);
+                    }
+                    else if (errors.length > 0) {
+                        const removedCount = errors.filter((issue) => deleteEntry(hippoRoot, issue.memoryId, { reason: `audit --fix: ${issue.reason}`, automatic: true })).length;
+                        console.log(`\nRemoved ${removedCount} error-severity memories.`);
+                        console.log(`${result.issues.length - errors.length} warnings remain (review manually).`);
                     }
                     else {
                         console.log(`\nNo error-severity issues. Warnings require manual review.`);
@@ -9017,6 +9081,10 @@ async function main() {
                 console.error(ARCHIVE_REASON_REQUIRED);
                 process.exit(1);
             }
+            if (flags['dry-run'] === true) {
+                previewForget(hippoRoot, id, archive);
+                break;
+            }
             const routed = await runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
                 try {
                     if (archive) {
@@ -9182,7 +9250,7 @@ async function main() {
             requireInit(hippoRoot);
             const format = flags['format'] || 'json';
             const outputPath = args[0] || null;
-            const entries = loadAllEntries(hippoRoot);
+            const entries = loadAllEntries(hippoRoot, resolveTenantId({}));
             let output;
             if (format === 'markdown' || format === 'md') {
                 output = entries.map(e => {
@@ -9282,11 +9350,11 @@ async function main() {
             }
             const host = typeof flags['host'] === 'string' ? flags['host'] : '127.0.0.1';
             const { serve } = await import('./server.js');
-            const handle = await serve({ hippoRoot, port, host });
+            const handle = await serve({ hippoRoot, port, host, handleSignals: true });
             console.log(`hippo serve listening on ${handle.url} (pid ${process.pid})`);
             console.log(`pidfile: ${path.join(hippoRoot, 'server.pid')}`);
             console.log('press Ctrl+C to stop');
-            // SIGINT/SIGTERM handlers wired in server.ts (skipped under VITEST). Hang.
+            // The SIGINT/SIGTERM handlers stop the server and exit. Hang until then.
             await new Promise(() => { });
             break;
         }
@@ -9380,8 +9448,19 @@ async function main() {
             process.exit(1);
     }
 }
-main().catch((err) => {
-    console.error('Error:', err.message ?? err);
-    process.exit(1);
-});
+export async function runCli(argv = process.argv) {
+    const { command, args, flags } = parseArgs(argv);
+    try {
+        await main(command, args, flags, getHippoRoot(process.cwd()));
+    }
+    catch (err) {
+        console.error('Error:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+}
+// bin/hippo.js calls runCli(); this keeps `node dist/cli.js` working while an import runs nothing.
+const entryPath = process.argv[1];
+if (entryPath && fs.existsSync(entryPath) && fs.realpathSync(entryPath) === fileURLToPath(import.meta.url)) {
+    void runCli();
+}
 //# sourceMappingURL=cli.js.map

package/dist/client.d.ts

@@ -1,9 +1,9 @@
 /**
  * HTTP client wrapper for `hippo serve`.
  *
- * Mirrors the function signatures in src/api.ts so the CLI can route through
- * either path uniformly. Each function takes (serverUrl, apiKey?, ...) and
- * returns the same shape that api.ts would.
+ * Only the writes the CLI routes (remember, forget, archive, promote), which are
+ * also all HIPPO_REQUIRE_SERVER covers; every other command opens the store
+ * directly. Each call returns the same shape that api.ts would.
  *
  * Errors from the server (4xx/5xx) are mapped back into thrown Errors with
  * the server's `error` message preserved verbatim so existing CLI handlers
@@ -13,9 +13,7 @@
  * Network errors (ECONNREFUSED on a stale pidfile, etc.) propagate as the
  * native fetch failure so the caller can detect them and self-heal.
  */
-import type { AuditEvent } from './audit.js';
-import type { ApiKeyListItem } from './auth.js';
-import type { RememberOpts, RememberResult, RecallOpts, RecallResult, AuthCreateOpts, AuthCreateResult, AuditListOpts } from './api.js';
+import type { RememberOpts, RememberResult } from './api.js';
 /** An error the server answered with, not one the transport raised. The
  *  refused-connection classifier sniffs message text, and a server message
  *  quotes the caller's own id or content back verbatim. */
@@ -24,7 +22,6 @@ export declare class HttpResponseError extends Error {
     constructor(message: string, status: number);
 }
 export declare function remember(serverUrl: string, apiKey: string | undefined, opts: RememberOpts): Promise<RememberResult>;
-export declare function recall(serverUrl: string, apiKey: string | undefined, opts: RecallOpts): Promise<RecallResult>;
 export declare function forget(serverUrl: string, apiKey: string | undefined, id: string): Promise<{
     ok: true;
     id: string;
@@ -34,24 +31,10 @@ export declare function promote(serverUrl: string, apiKey: string | undefined, i
     sourceId: string;
     globalId: string;
 }>;
-export declare function supersede(serverUrl: string, apiKey: string | undefined, oldId: string, newContent: string): Promise<{
-    ok: true;
-    oldId: string;
-    newId: string;
-}>;
 export declare function archiveRaw(serverUrl: string, apiKey: string | undefined, id: string, reason: string): Promise<{
     ok: true;
     archivedAt: string;
 }>;
-export declare function authCreate(serverUrl: string, apiKey: string | undefined, opts: AuthCreateOpts): Promise<AuthCreateResult>;
-export declare function authList(serverUrl: string, apiKey: string | undefined, opts: {
-    active: boolean;
-}): Promise<ApiKeyListItem[]>;
-export declare function authRevoke(serverUrl: string, apiKey: string | undefined, keyId: string): Promise<{
-    ok: true;
-    revokedAt: string;
-}>;
-export declare function auditList(serverUrl: string, apiKey: string | undefined, opts: AuditListOpts): Promise<AuditEvent[]>;
 /**
  * How far a request got before the transport failed.
  *