hippo-memory 0.34.0 → 0.36.0

package/dist/cli.js

@@ -45,11 +45,16 @@ import { captureError, extractLessons, deduplicateLesson, runWatched, fetchGitLo
 import { extractInvalidationTarget, invalidateMatching } from './invalidation.js';
 import { extractPathTags } from './path-context.js';
 import { detectScope, scopeMatch } from './scope.js';
-import { getGlobalRoot, initGlobal, promoteToGlobal, shareMemory, listPeers, autoShare, transferScore, searchBothHybrid, syncGlobalToLocal, } from './shared.js';
+import { getGlobalRoot, initGlobal, shareMemory, listPeers, autoShare, transferScore, searchBothHybrid, syncGlobalToLocal, } from './shared.js';
 import { DAILY_TASK_NAME, buildDailyRunnerCommand, listRegisteredWorkspaces, registerWorkspace, runDailyMaintenance, } from './scheduler.js';
 import { importChatGPT, importClaude, importCursor, importGenericFile, importMarkdown, } from './importers.js';
 import { cmdCapture } from './capture.js';
-import { auditMemories } from './audit.js';
+import { auditMemories, appendAuditEvent, } from './audit.js';
+import { listApiKeys, revokeApiKey } from './auth.js';
+import * as api from './api.js';
+import * as client from './client.js';
+import { detectServer, removePidfile } from './server-detect.js';
+import { resolveTenantId } from './tenant.js';
 import { runEval, bootstrapCorpus, compareSummaries } from './eval.js';
 import { runFeatureEval, formatResult, resultToBaseline, detectRegressions } from './eval-suite.js';
 import { refineStore } from './refine-llm.js';
@@ -66,12 +71,66 @@ function parseLimitFlag(value) {
     const parsed = parseInt(String(value), 10);
     return Number.isFinite(parsed) && parsed >= 1 ? parsed : Infinity;
 }
+/**
+ * Emit an audit event against `hippoRoot`'s db. Opens its own short-lived
+ * connection so callers don't have to thread a db handle. Swallows all errors
+ * — audit must never crash a CLI command.
+ */
+function emitCliAudit(hippoRoot, op, targetId, metadata) {
+    try {
+        const db = openHippoDb(hippoRoot);
+        try {
+            appendAuditEvent(db, {
+                tenantId: resolveTenantId({}),
+                actor: 'cli',
+                op,
+                targetId,
+                metadata,
+            });
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    catch {
+        // Audit is best-effort; surface failures only via missing rows.
+    }
+}
 function requireInit(hippoRoot) {
     if (!isInitialized(hippoRoot)) {
         console.error('No .hippo directory found. Run `hippo init` first.');
         process.exit(1);
     }
 }
+/**
+ * Run an HTTP-routed command if a `hippo serve` instance is detected for
+ * `hippoRoot`. Returns:
+ *   - true  if the HTTP path ran (success OR a structured server error that
+ *           was already surfaced to stdout/stderr by `httpFn`),
+ *   - false if no server was detected, or if the detected pidfile turned out
+ *           to be stale (connection refused). On stale, the pidfile is removed
+ *           and the caller should fall back to the direct path.
+ *
+ * Per the A1 plan footgun #1: stale pidfiles must self-heal, not crash.
+ */
+async function runViaServerIfAvailable(hippoRoot, httpFn) {
+    const info = detectServer(hippoRoot);
+    if (!info)
+        return false;
+    const apiKey = process.env['HIPPO_API_KEY'];
+    try {
+        await httpFn(info, apiKey);
+        return true;
+    }
+    catch (err) {
+        if (client.isConnectionRefused(err)) {
+            console.error('hippo: stale server pidfile detected, falling back to direct mode');
+            removePidfile(hippoRoot);
+            return false;
+        }
+        throw err;
+    }
+}
 function parseArgs(argv) {
     const [, , command = '', ...rest] = argv;
     const args = [];
@@ -421,6 +480,9 @@ async function cmdRemember(hippoRoot, text, flags) {
     const ownerFlag = typeof flags['owner'] === 'string' ? flags['owner'] : null;
     const artifactRefFlag = typeof flags['artifact-ref'] === 'string' ? flags['artifact-ref'] : null;
     const scopeForEnvelope = typeof flags['scope'] === 'string' ? flags['scope'].trim() || null : null;
+    // 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 entry = createMemory(text, {
         layer: Layer.Episodic,
         tags: rawTags,
@@ -432,6 +494,7 @@ async function cmdRemember(hippoRoot, text, flags) {
         scope: scopeForEnvelope,
         owner: ownerFlag,
         artifact_ref: artifactRefFlag,
+        tenantId,
     });
     // Auto-tag with path context
     const pathTags = extractPathTags(process.cwd());
@@ -533,6 +596,7 @@ function cmdSupersede(hippoRoot, oldId, newContent, flags) {
     old.superseded_by = newEntry.id;
     writeEntry(hippoRoot, old);
     writeEntry(hippoRoot, newEntry);
+    emitCliAudit(hippoRoot, 'supersede', oldId, { newId: newEntry.id });
     console.log(`Superseded ${oldId} → ${newEntry.id}`);
 }
 async function cmdRecall(hippoRoot, query, flags) {
@@ -550,8 +614,11 @@ async function cmdRecall(hippoRoot, query, flags) {
         process.exit(1);
     }
     const globalRoot = getGlobalRoot();
-    let localEntries = loadSearchEntries(hippoRoot, query);
-    let globalEntries = isInitialized(globalRoot) ? loadSearchEntries(globalRoot, query) : [];
+    // A5 stub auth: resolve the active tenant once and thread it through every
+    // recall-time SELECT against `memories`. Cross-tenant rows must never surface.
+    const tenantId = resolveTenantId({});
+    let localEntries = loadSearchEntries(hippoRoot, query, undefined, tenantId);
+    let globalEntries = isInitialized(globalRoot) ? loadSearchEntries(globalRoot, query, undefined, tenantId) : [];
     // Bi-temporal filtering for physics path (hybridSearch handles it internally)
     if (asOf) {
         const filterAsOf = (entries) => {
@@ -625,7 +692,7 @@ async function cmdRecall(hippoRoot, query, flags) {
     else if (hasGlobal) {
         // Use searchBothHybrid for merged results with embedding support
         results = await searchBothHybrid(query, hippoRoot, globalRoot, {
-            budget, mmr: mmrEnabled, mmrLambda, localBump, minResults, scope: recallActiveScope,
+            budget, mmr: mmrEnabled, mmrLambda, localBump, minResults, scope: recallActiveScope, tenantId,
         });
     }
     else {
@@ -811,6 +878,20 @@ async function cmdRecall(hippoRoot, query, flags) {
     if (limit < results.length) {
         results = results.slice(0, limit);
     }
+    // A5 audit: emit one 'recall' event per query, capturing the (truncated)
+    // query text and the post-filter result count. Tenant resolved by emitCliAudit.
+    // Emit before the early-empty return so zero-result recalls are still logged.
+    // recall reads from BOTH local and global stores when both are initialized;
+    // log against every participating store so the audit trail in either db
+    // shows the read access (no false negatives across --global flows).
+    const recallMetadata = {
+        query: query.slice(0, 200),
+        results: results.length,
+    };
+    emitCliAudit(hippoRoot, 'recall', undefined, recallMetadata);
+    if (isInitialized(globalRoot) && globalRoot !== hippoRoot) {
+        emitCliAudit(globalRoot, 'recall', undefined, recallMetadata);
+    }
     if (results.length === 0) {
         if (asJson) {
             console.log(JSON.stringify({ query, results: [], total: 0 }));
@@ -916,8 +997,10 @@ async function cmdExplain(hippoRoot, query, flags) {
         process.exit(1);
     }
     const globalRoot = getGlobalRoot();
-    let explainLocalEntries = loadSearchEntries(hippoRoot, query);
-    let explainGlobalEntries = isInitialized(globalRoot) ? loadSearchEntries(globalRoot, query) : [];
+    // A5: scope explain results to the active tenant.
+    const tenantId = resolveTenantId({});
+    let explainLocalEntries = loadSearchEntries(hippoRoot, query, undefined, tenantId);
+    let explainGlobalEntries = isInitialized(globalRoot) ? loadSearchEntries(globalRoot, query, undefined, tenantId) : [];
     // Bi-temporal filtering
     if (explainAsOf) {
         const filterAsOfExplain = (entries) => {
@@ -977,7 +1060,7 @@ async function cmdExplain(hippoRoot, query, flags) {
     else if (hasGlobal) {
         results = await searchBothHybrid(query, hippoRoot, globalRoot, {
             budget, explain: true, mmr: mmrEnabled, mmrLambda, localBump, scope: explainActiveScope,
-            includeSuperseded: explainIncludeSuperseded, asOf: explainAsOf,
+            includeSuperseded: explainIncludeSuperseded, asOf: explainAsOf, tenantId,
         });
         modeUsed = 'searchBothHybrid';
     }
@@ -2108,12 +2191,17 @@ function cmdOutcome(hippoRoot, flags) {
 }
 function cmdForget(hippoRoot, id) {
     requireInit(hippoRoot);
-    const ok = deleteEntry(hippoRoot, id);
-    if (ok) {
+    const ctx = {
+        hippoRoot,
+        tenantId: resolveTenantId({}),
+        actor: 'cli',
+    };
+    try {
+        api.forget(ctx, id);
         updateStats(hippoRoot, { forgotten: 1 });
         console.log(`Forgot ${id}`);
     }
-    else {
+    catch {
         console.error(`Memory not found: ${id}`);
         process.exit(1);
     }
@@ -2621,11 +2709,14 @@ async function cmdContext(hippoRoot, args, flags) {
     }
     const globalRoot = getGlobalRoot();
     const hasGlobal = isInitialized(globalRoot);
+    // A5: scope context-mode loads to the active tenant. Without this, every
+    // tenant's memories surface through the smart-context injection path.
+    const tenantId = resolveTenantId({});
     // When the local store isn't initialized (pinned-only path in a fresh dir),
     // skip the local load — loadAllEntries would auto-create .hippo here and
     // we don't want to pollute arbitrary cwds.
-    let localEntries = hasLocal ? loadAllEntries(hippoRoot) : [];
-    let globalEntries = hasGlobal ? loadAllEntries(globalRoot) : [];
+    let localEntries = hasLocal ? loadAllEntries(hippoRoot, tenantId) : [];
+    let globalEntries = hasGlobal ? loadAllEntries(globalRoot, tenantId) : [];
     // Default context always filters superseded (no --include-superseded / --as-of for context)
     localEntries = localEntries.filter(e => !e.superseded_by);
     globalEntries = globalEntries.filter(e => !e.superseded_by);
@@ -2714,7 +2805,7 @@ async function cmdContext(hippoRoot, args, flags) {
     else {
         let results;
         if (hasGlobal) {
-            const merged = await searchBothHybrid(query, hippoRoot, globalRoot, { budget, scope: ctxActiveScope });
+            const merged = await searchBothHybrid(query, hippoRoot, globalRoot, { budget, scope: ctxActiveScope, tenantId });
             const localIndex = loadIndex(hippoRoot);
             results = merged.map((r) => ({
                 entry: r.entry,
@@ -2738,6 +2829,20 @@ async function cmdContext(hippoRoot, args, flags) {
         }
         selectedItems = results;
         totalTokens = results.reduce((sum, r) => sum + r.tokens, 0);
+        // A5 H4: emit recall audit event for context-mode searches. The recall
+        // handler emits one of these per `hippo recall` invocation; context mode
+        // is the same surface (search → user) and must leave the same audit trail.
+        // Skip pinned-only and '*' fallback (handled in branches above which never
+        // hit the search engines).
+        const ctxRecallMetadata = {
+            query: query.slice(0, 200),
+            results: selectedItems.length,
+            mode: 'context',
+        };
+        if (hasLocal)
+            emitCliAudit(hippoRoot, 'recall', undefined, ctxRecallMetadata);
+        if (hasGlobal)
+            emitCliAudit(globalRoot, 'recall', undefined, ctxRecallMetadata);
     }
     if (limit < selectedItems.length) {
         selectedItems = selectedItems.slice(0, limit);
@@ -3170,9 +3275,14 @@ function cmdPromote(hippoRoot, id) {
         console.error('Usage: hippo promote <id>');
         process.exit(1);
     }
+    const ctx = {
+        hippoRoot,
+        tenantId: resolveTenantId({}),
+        actor: 'cli',
+    };
     try {
-        const globalEntry = promoteToGlobal(hippoRoot, id);
-        console.log(`Promoted ${id} to global store as ${globalEntry.id}`);
+        const result = api.promote(ctx, id);
+        console.log(`Promoted ${id} to global store as ${result.globalId}`);
         console.log(`   Global store: ${getGlobalRoot()}`);
     }
     catch (err) {
@@ -3725,6 +3835,226 @@ function cmdDag(hippoRoot, flags) {
         }
     }
 }
+// ---------------------------------------------------------------------------
+// Auth subcommands (A5 stub auth)
+// ---------------------------------------------------------------------------
+function resolveAuthRoot(hippoRoot, flags) {
+    if (flags['global']) {
+        initGlobal();
+        return getGlobalRoot();
+    }
+    requireInit(hippoRoot);
+    return hippoRoot;
+}
+function cmdAuthCreate(hippoRoot, flags) {
+    const root = resolveAuthRoot(hippoRoot, flags);
+    const tenantFlag = typeof flags['tenant'] === 'string' ? flags['tenant'] : undefined;
+    const labelFlag = typeof flags['label'] === 'string' ? flags['label'] : undefined;
+    const asJson = Boolean(flags['json']);
+    const ctx = {
+        hippoRoot: root,
+        tenantId: resolveTenantId({}),
+        actor: 'cli',
+    };
+    const result = api.authCreate(ctx, { tenantId: tenantFlag, label: labelFlag });
+    if (asJson) {
+        console.log(JSON.stringify({
+            keyId: result.keyId,
+            plaintext: result.plaintext,
+            tenantId: result.tenantId,
+            label: labelFlag ?? null,
+        }));
+        return;
+    }
+    console.log(`key_id:    ${result.keyId}`);
+    console.log(`plaintext: ${result.plaintext}`);
+    console.log('');
+    console.log('!! WARNING: this is the ONLY time the plaintext key will be shown. !!');
+    console.log('!! Copy it now. Hippo stores only a scrypt hash and cannot recover it. !!');
+}
+function formatKeyRow(item) {
+    const label = item.label ?? '-';
+    const created = item.createdAt;
+    const revoked = item.revokedAt ?? '-';
+    return `${item.keyId}  ${item.tenantId}  ${label}  ${created}  ${revoked}`;
+}
+function cmdAuthList(hippoRoot, flags) {
+    const root = resolveAuthRoot(hippoRoot, flags);
+    const includeRevoked = Boolean(flags['all']);
+    const asJson = Boolean(flags['json']);
+    const db = openHippoDb(root);
+    let items;
+    try {
+        items = listApiKeys(db, { active: !includeRevoked });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    if (asJson) {
+        console.log(JSON.stringify(items));
+        return;
+    }
+    if (items.length === 0) {
+        console.log(includeRevoked ? 'No API keys.' : 'No active API keys. (Use --all to include revoked.)');
+        return;
+    }
+    console.log('key_id  tenant  label  created  revoked');
+    for (const item of items) {
+        console.log(formatKeyRow(item));
+    }
+}
+function cmdAuthRevoke(hippoRoot, keyId, flags) {
+    const root = resolveAuthRoot(hippoRoot, flags);
+    const asJson = Boolean(flags['json']);
+    const db = openHippoDb(root);
+    let exists = false;
+    let alreadyRevoked = false;
+    let revokedAt = null;
+    let keyTenantId = null;
+    try {
+        const row = db.prepare(`SELECT key_id, tenant_id, revoked_at FROM api_keys WHERE key_id = ?`).get(keyId);
+        if (!row) {
+            // Let the finally{} block close the db. M4: avoid manual close before
+            // process.exit() — the finally already handles it on every path.
+            console.error(`Unknown key_id: ${keyId}`);
+            process.exit(1);
+        }
+        exists = true;
+        keyTenantId = row.tenant_id;
+        if (row.revoked_at) {
+            alreadyRevoked = true;
+            revokedAt = row.revoked_at;
+        }
+        else {
+            revokeApiKey(db, keyId);
+            const updated = db.prepare(`SELECT revoked_at FROM api_keys WHERE key_id = ?`).get(keyId);
+            revokedAt = updated?.revoked_at ?? null;
+        }
+        // M1: emit auth_revoke audit event. Skip on no-op revoke (already revoked)
+        // so re-running the command doesn't pad the audit log with duplicates.
+        if (!alreadyRevoked && keyTenantId) {
+            try {
+                appendAuditEvent(db, {
+                    tenantId: keyTenantId,
+                    actor: 'cli',
+                    op: 'auth_revoke',
+                    targetId: keyId,
+                });
+            }
+            catch {
+                // Audit must not crash a successful revoke.
+            }
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    if (!exists)
+        return;
+    if (asJson) {
+        console.log(JSON.stringify({ keyId, revokedAt }));
+        return;
+    }
+    console.log(`Revoked ${keyId} at ${revokedAt}`);
+}
+// ---------------------------------------------------------------------------
+// Audit log subcommands (A5 stub auth — `hippo audit list`)
+// ---------------------------------------------------------------------------
+const VALID_AUDIT_OPS = new Set([
+    'remember',
+    'recall',
+    'promote',
+    'supersede',
+    'forget',
+    'archive_raw',
+    'auth_revoke',
+]);
+function formatAuditRow(ev) {
+    const target = ev.targetId ?? '-';
+    const meta = JSON.stringify(ev.metadata ?? {});
+    return `${ev.ts}  ${ev.actor}  ${ev.op}  ${target}  ${meta}`;
+}
+function cmdAuditList(hippoRoot, flags) {
+    const root = resolveAuthRoot(hippoRoot, flags);
+    const asJson = Boolean(flags['json']);
+    const tenantId = resolveTenantId({});
+    const opFlag = typeof flags['op'] === 'string' ? flags['op'] : undefined;
+    if (opFlag && !VALID_AUDIT_OPS.has(opFlag)) {
+        console.error(`Unknown --op value: ${opFlag}. Expected one of: remember | recall | promote | supersede | forget | archive_raw.`);
+        process.exit(1);
+    }
+    const op = opFlag;
+    const since = typeof flags['since'] === 'string' ? flags['since'] : undefined;
+    if (since !== undefined && !Number.isFinite(new Date(since).getTime())) {
+        console.error(`Invalid --since: ${since} (expected an ISO timestamp like 2026-04-22 or 2026-04-22T12:00:00Z).`);
+        process.exit(1);
+    }
+    const limitRaw = flags['limit'];
+    let limit = 100;
+    if (limitRaw !== undefined && typeof limitRaw !== 'boolean') {
+        const parsed = parseInt(String(limitRaw), 10);
+        if (!Number.isFinite(parsed)) {
+            console.error(`Invalid --limit value: ${String(limitRaw)} (expected a positive integer).`);
+            process.exit(1);
+        }
+        limit = parsed;
+    }
+    if (limit < 1 || limit > 10000) {
+        console.error(`--limit must be between 1 and 10000 (got ${limit}).`);
+        process.exit(1);
+    }
+    const ctx = { hippoRoot: root, tenantId, actor: 'cli' };
+    const events = api.auditList(ctx, { op, since, limit });
+    if (asJson) {
+        console.log(JSON.stringify(events));
+        return;
+    }
+    if (events.length === 0) {
+        console.log('No audit events.');
+        return;
+    }
+    console.log('ts  actor  op  target_id  metadata');
+    for (const ev of events) {
+        console.log(formatAuditRow(ev));
+    }
+}
+function cmdAuditLog(hippoRoot, args, flags) {
+    const sub = args[0];
+    if (sub === 'list') {
+        cmdAuditList(hippoRoot, flags);
+        return;
+    }
+    console.error(`Unknown audit subcommand: ${sub}. Expected: list.`);
+    process.exit(1);
+}
+function cmdAuth(hippoRoot, args, flags) {
+    const sub = args[0];
+    if (!sub) {
+        console.error('Usage: hippo auth <create|list|revoke> [options]');
+        process.exit(1);
+    }
+    const subArgs = args.slice(1);
+    switch (sub) {
+        case 'create':
+            cmdAuthCreate(hippoRoot, flags);
+            return;
+        case 'list':
+            cmdAuthList(hippoRoot, flags);
+            return;
+        case 'revoke': {
+            const keyId = subArgs[0];
+            if (!keyId) {
+                console.error('Usage: hippo auth revoke <key_id>');
+                process.exit(1);
+            }
+            cmdAuthRevoke(hippoRoot, keyId, flags);
+            return;
+        }
+        default:
+            console.error(`Unknown auth subcommand: ${sub}. Expected: create | list | revoke.`);
+            process.exit(1);
+    }
+}
 function printUsage() {
     console.log(`
 Hippo - biologically-inspired memory system for AI agents
@@ -3961,6 +4291,27 @@ Commands:
   dashboard                Open web dashboard for memory health
     --port <n>             Port to serve on (default: 3333)
   mcp                      Start MCP server (stdio transport)
+  auth <sub>               Manage API keys (A5 stub auth)
+    auth create            Mint a new API key (plaintext shown ONCE)
+      --label <s>          Optional human label
+      --tenant <id>        Override tenant (defaults to HIPPO_TENANT)
+      --json               Output as JSON
+      --global             Operate on the global store
+    auth list              List API keys (active by default)
+      --all                Include revoked keys
+      --json               Output as JSON
+      --global             Operate on the global store
+    auth revoke <key_id>   Revoke an API key (subsequent validate fails)
+      --json               Output as JSON
+      --global             Operate on the global store
+  audit <sub>              Query the append-only audit log (A5 stub auth)
+    audit list             List audit events for the active tenant
+      --op <op>            Filter by op (remember | recall | promote |
+                           supersede | forget | archive_raw | auth_revoke)
+      --since <iso>        Lower bound on ts (ISO timestamp)
+      --limit <n>          Max events (default: 100, max: 10000)
+      --json               Output as JSON
+      --global             Operate on the global store
 
 Examples:
   hippo init
@@ -4027,6 +4378,37 @@ async function main() {
                 console.error('Memory content too short (minimum 3 characters).');
                 process.exit(1);
             }
+            // Thin-client routing. When a server is up, simple `remember` calls go
+            // over HTTP so the daemon stays single-writer (footgun #2). Rich CLI
+            // flags (--pin, --layer, --extract, --global, salience gates) still
+            // need the direct path; we only intercept the minimal envelope.
+            const richFlag = flags['pin'] || flags['global'] || flags['extract'] || flags['force'] ||
+                flags['observed'] || flags['inferred'] || flags['verified'] ||
+                flags['layer'] !== undefined;
+            if (!richFlag) {
+                const rememberKindRaw = typeof flags['kind'] === 'string' ? flags['kind'].toLowerCase() : undefined;
+                const rememberKindAllowed = ['distilled', 'superseded'];
+                if (rememberKindRaw === undefined || rememberKindAllowed.includes(rememberKindRaw)) {
+                    const tagsRaw = flags['tag'];
+                    const tags = Array.isArray(tagsRaw)
+                        ? tagsRaw.map(String)
+                        : typeof tagsRaw === 'string' ? [tagsRaw] : undefined;
+                    const remembered = await runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
+                        const result = await client.remember(info.url, apiKey, {
+                            content: text,
+                            kind: rememberKindRaw,
+                            scope: typeof flags['scope'] === 'string' ? flags['scope'] : undefined,
+                            owner: typeof flags['owner'] === 'string' ? flags['owner'] : undefined,
+                            artifactRef: typeof flags['artifact-ref'] === 'string' ? flags['artifact-ref'] : undefined,
+                            tags,
+                        });
+                        console.log(`Remembered [${result.id}] (via ${info.url})`);
+                        console.log(`   Kind: ${result.kind} | Tenant: ${result.tenantId}`);
+                    });
+                    if (remembered)
+                        break;
+                }
+            }
             await cmdRemember(hippoRoot, text, flags);
             break;
         }
@@ -4103,7 +4485,16 @@ async function main() {
         case 'dag':
             cmdDag(hippoRoot, flags);
             break;
+        case 'auth':
+            cmdAuth(hippoRoot, args, flags);
+            break;
         case 'audit': {
+            // `audit list` -> A5 audit-log viewer. Other forms (no sub, --fix) keep
+            // the existing memory-quality auditor for backwards compatibility.
+            if (args[0] === 'list') {
+                cmdAuditLog(hippoRoot, args, flags);
+                break;
+            }
             requireInit(hippoRoot);
             const entries = loadAllEntries(hippoRoot);
             const result = auditMemories(entries);
@@ -4167,6 +4558,18 @@ async function main() {
                 console.error('Please provide a memory ID.');
                 process.exit(1);
             }
+            const routed = await runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
+                try {
+                    await client.forget(info.url, apiKey, id);
+                    console.log(`Forgot ${id}`);
+                }
+                catch (err) {
+                    console.error(err.message);
+                    process.exit(1);
+                }
+            });
+            if (routed)
+                break;
             cmdForget(hippoRoot, id);
             break;
         }
@@ -4208,6 +4611,18 @@ async function main() {
                 console.error('Please provide a memory ID.');
                 process.exit(1);
             }
+            const promoted = await runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
+                try {
+                    const result = await client.promote(info.url, apiKey, id);
+                    console.log(`Promoted ${id} to global store as ${result.globalId}`);
+                }
+                catch (err) {
+                    console.error(`Failed to promote: ${err.message}`);
+                    process.exit(1);
+                }
+            });
+            if (promoted)
+                break;
             cmdPromote(hippoRoot, id);
             break;
         }
@@ -4357,12 +4772,35 @@ async function main() {
         case 'wm':
             cmdWm(hippoRoot, args, flags);
             break;
-        case 'mcp':
-            // Start MCP server over stdio - dynamically import to keep main CLI lean
-            await import('./mcp/server.js');
+        case 'mcp': {
+            // Start MCP server over stdio. Dynamic import keeps main CLI lean; the
+            // dispatcher itself is transport-agnostic, so we explicitly attach the
+            // stdio loop here. (HTTP/SSE transport is wired in src/server.ts and
+            // imports the same module without triggering stdin handlers.)
+            const mod = await import('./mcp/server.js');
+            mod.startStdioLoop();
             // Server runs until stdin closes, so we never reach here
             await new Promise(() => { }); // hang forever
             break;
+        }
+        case 'serve': {
+            requireInit(hippoRoot);
+            const portRaw = flags['port'] ?? process.env['HIPPO_PORT'] ?? '6789';
+            const port = Number(portRaw);
+            if (!Number.isFinite(port) || port < 0) {
+                console.error(`Invalid --port: ${String(portRaw)}`);
+                process.exit(1);
+            }
+            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 });
+            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.
+            await new Promise(() => { });
+            break;
+        }
         case 'invalidate': {
             requireInit(hippoRoot);
             const target = args[0];