hippo-memory 0.34.0 → 0.35.0

package/dist/cli.js

@@ -49,7 +49,9 @@ import { getGlobalRoot, initGlobal, promoteToGlobal, shareMemory, listPeers, aut
 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, queryAuditEvents, } from './audit.js';
+import { createApiKey, listApiKeys, revokeApiKey } from './auth.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,6 +68,31 @@ 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.');
@@ -421,6 +448,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 +462,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 +564,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 +582,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 +660,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 +846,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 +965,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 +1028,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';
     }
@@ -2621,11 +2672,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 +2768,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 +2792,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);
@@ -3172,6 +3240,11 @@ function cmdPromote(hippoRoot, id) {
     }
     try {
         const globalEntry = promoteToGlobal(hippoRoot, id);
+        // Emit audit on the global store (where the promoted memory now lives).
+        // The writeEntry inside promoteToGlobal already fires a 'remember' on the
+        // global db; we add a separate 'promote' event so the audit trail keeps
+        // the user-facing intent distinct from the underlying upsert.
+        emitCliAudit(getGlobalRoot(), 'promote', globalEntry.id, { sourceId: id });
         console.log(`Promoted ${id} to global store as ${globalEntry.id}`);
         console.log(`   Global store: ${getGlobalRoot()}`);
     }
@@ -3725,6 +3798,235 @@ 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 tenantId = tenantFlag ?? resolveTenantId({});
+    const asJson = Boolean(flags['json']);
+    const db = openHippoDb(root);
+    let result;
+    try {
+        result = createApiKey(db, { tenantId, label: labelFlag });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    if (asJson) {
+        console.log(JSON.stringify({
+            keyId: result.keyId,
+            plaintext: result.plaintext,
+            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 db = openHippoDb(root);
+    let events;
+    try {
+        events = queryAuditEvents(db, { tenantId, op, since, limit });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    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 +4263,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
@@ -4103,7 +4426,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);