hippo-memory 0.33.0 → 0.35.0

package/dist/cli.js

@@ -49,11 +49,16 @@ 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';
 import { wmPush, wmRead, wmClear, wmFlush } from './working-memory.js';
 import { multihopSearch } from './multihop.js';
+import { computeSalience } from './salience.js';
+import { computeAmbientState, renderAmbientSummary } from './ambient.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -63,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.');
@@ -401,6 +431,26 @@ async function cmdRemember(hippoRoot, text, flags) {
     // Compute schema fit against existing memories
     const existing = loadAllEntries(targetRoot);
     const schemaFit = computeSchemaFit(text, rawTags, existing);
+    // A3 envelope flags
+    const kindFlagRaw = typeof flags['kind'] === 'string' ? flags['kind'] : undefined;
+    const kindFlag = kindFlagRaw === undefined ? undefined : kindFlagRaw.toLowerCase();
+    // CLI surface intentionally restricted: 'raw' is reserved for ingestion connectors
+    // (E1.x: Slack/Jira/Gmail) that route deletions through archiveRawMemory. Existing
+    // forget/consolidate/conflict-resolve paths abort on kind='raw' via the append-only
+    // trigger, so exposing --kind raw here would create unforgettable memories.
+    // 'archived' is an internal sentinel set only inside archiveRawMemory's transaction.
+    const userVisibleKinds = ['distilled', 'superseded'];
+    if (kindFlag !== undefined && !userVisibleKinds.includes(kindFlag)) {
+        console.error(`Invalid --kind: "${kindFlagRaw}". Must be one of: ${userVisibleKinds.join(', ')}`);
+        console.error(`(kind='raw' is reserved for ingestion connectors; kind='archived' is internal.)`);
+        process.exit(1);
+    }
+    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,
@@ -408,6 +458,11 @@ async function cmdRemember(hippoRoot, text, flags) {
         source: useGlobal ? 'cli-global' : 'cli',
         confidence,
         schema_fit: schemaFit,
+        kind: kindFlag,
+        scope: scopeForEnvelope,
+        owner: ownerFlag,
+        artifact_ref: artifactRefFlag,
+        tenantId,
     });
     // Auto-tag with path context
     const pathTags = extractPathTags(process.cwd());
@@ -423,6 +478,25 @@ async function cmdRemember(hippoRoot, text, flags) {
         if (!entry.tags.includes(scopeTag))
             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,
+            overlapThreshold: rememberConfig.salience.overlapThreshold,
+            minContentLength: rememberConfig.salience.minContentLength,
+            maxRepeatErrors: rememberConfig.salience.maxRepeatErrors,
+        });
+        if (salienceResult.decision === 'skip') {
+            console.log(`Skipped (salience: ${salienceResult.reason}, score ${salienceResult.score.toFixed(2)})`);
+            return;
+        }
+        if (salienceResult.decision === 'start_weak') {
+            entry.strength = salienceResult.score;
+            entry.half_life_days = Math.max(1, entry.half_life_days * 0.5);
+            console.log(`Weakened (salience: ${salienceResult.reason}, strength ${salienceResult.score.toFixed(2)})`);
+        }
+    }
     writeEntry(targetRoot, entry);
     updateStats(targetRoot, { remembered: 1 });
     const prefix = useGlobal ? '[global] ' : '';
@@ -490,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) {
@@ -507,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) => {
@@ -582,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 {
@@ -590,6 +668,155 @@ async function cmdRecall(hippoRoot, query, flags) {
             budget, hippoRoot, mmr: mmrEnabled, mmrLambda, minResults, scope: recallActiveScope,
         });
     }
+    // ACC EVC-adaptive recall (RESEARCH.md §PFC.ACC). When the initial top-K is
+    // dominated by lexically similar but distinct memories (high pairwise token
+    // overlap = same topic, different facts = conflict), allocate extra retrieval
+    // effort: take a wider candidate pool, drop low-relevance distractors, and
+    // re-rank by recency to surface the most up-to-date item from the cluster.
+    // Default off; opt-in via --evc-adaptive.
+    if (flags['evc-adaptive'] && results.length >= 2) {
+        const sliceSize = Math.min(3, results.length);
+        const slice = results.slice(0, sliceSize);
+        let pairs = 0;
+        let overlapSum = 0;
+        for (let i = 0; i < slice.length; i++) {
+            for (let j = i + 1; j < slice.length; j++) {
+                overlapSum += textOverlap(slice[i].entry.content, slice[j].entry.content);
+                pairs++;
+            }
+        }
+        const avgOverlap = pairs > 0 ? overlapSum / pairs : 0;
+        if (avgOverlap >= 0.4) {
+            const poolSize = Math.min(results.length, Math.max(sliceSize * 3, 9));
+            const pool = results.slice(0, poolSize);
+            const tail = results.slice(poolSize);
+            const maxScore = pool.reduce((m, r) => Math.max(m, r.score), 0);
+            const scoreFloor = maxScore * 0.5;
+            const onTopic = [];
+            const offTopic = [];
+            for (const r of pool) {
+                (r.score >= scoreFloor ? onTopic : offTopic).push(r);
+            }
+            onTopic.sort((a, b) => {
+                const ta = new Date(a.entry.created).getTime();
+                const tb = new Date(b.entry.created).getTime();
+                return tb - ta;
+            });
+            results = [...onTopic, ...offTopic, ...tail];
+        }
+    }
+    // vlPFC interference filter (RESEARCH.md §PFC.vlPFC). Suppress task-irrelevant
+    // memories using *recorded* supersession + conflict structure only. Default
+    // off; opt-in via --filter-conflicts. Two effects, both surgical:
+    //   1. Drop entries with `superseded_by` set. (No-op under default recall,
+    //      which already filters them; matters when `--include-superseded` was
+    //      passed. The flag re-asserts the gate.)
+    //   2. Apply a 0.3x score multiplier to entries whose `conflicts_with` list
+    //      references another entry that ALSO appears in the result set. The
+    //      multiplier is conservative — we never delete on conflict, only
+    //      down-rank, so the user can still surface the loser via --include-*.
+    // We never infer conflicts from lexical overlap. The v1 salience gate did
+    // that and destroyed LoCoMo (0.28 → 0.02). Recorded structure only.
+    if (flags['filter-conflicts']) {
+        results = results.filter((r) => !r.entry.superseded_by);
+        const presentIds = new Set(results.map((r) => r.entry.id));
+        results = results.map((r) => {
+            const peers = r.entry.conflicts_with || [];
+            const hasPeerInResults = peers.some((peerId) => presentIds.has(peerId));
+            return hasPeerInResults ? { ...r, score: r.score * 0.3 } : r;
+        });
+        results.sort((a, b) => b.score - a.score);
+    }
+    // vmPFC continuous value attribution (RESEARCH.md §PFC.vmPFC). Continuous
+    // value scoring per memory based on cumulative outcome attribution. Memories
+    // with positive cumulative outcomes are boosted; those with negative outcomes
+    // are demoted. The multiplier is a tanh-shaped function clamped to [0.7, 1.3]
+    // — wider than the always-on outcomeBoost (which clamps [0.85, 1.15]) so this
+    // flag has additional decisive effect when value attribution should drive
+    // ranking. Default off; opt-in via --value-aware. Reuses outcome_positive /
+    // outcome_negative columns; no schema change.
+    if (flags['value-aware'] && results.length >= 1) {
+        results = results.map((r) => {
+            const pos = r.entry.outcome_positive ?? 0;
+            const neg = r.entry.outcome_negative ?? 0;
+            if (pos === 0 && neg === 0)
+                return r;
+            const raw = 1 + 0.3 * Math.tanh(pos - neg);
+            const valueMult = Math.max(0.7, Math.min(1.3, raw));
+            return { ...r, score: r.score * valueMult };
+        });
+        results.sort((a, b) => b.score - a.score);
+    }
+    // OFC option-value re-ranker MVP (RESEARCH.md §PFC.OFC). Combine relevance,
+    // strength, and integration cost into a single utility score and re-sort.
+    // OFC neurons encode a "common currency" across heterogeneous attributes
+    // (Rangel et al., 2008); this is the simplest demonstration of that mechanism.
+    // Default off; opt-in via --rerank-utility.
+    //
+    //   utility = score * (0.5 + 0.5 * strength) * (1 - cost_factor)
+    //   cost_factor = min(0.3, tokens / 10000)
+    //
+    // The full OFC spec (option_valuation table in RESEARCH.md) decomposes value
+    // into reward / cost / risk / confidence components. The MVP collapses these
+    // to: score (relevance proxy), strength (persistence proxy), tokens (cost).
+    // CAVEAT: cost penalty is monotone with token count; LoCoMo's harder QAs
+    // often live in long evidence-rich memories. Default off — needs LoCoMo
+    // eval before enabling broadly.
+    if (flags['rerank-utility']) {
+        results = results
+            .map((r) => {
+            const strength = typeof r.entry.strength === 'number' ? r.entry.strength : 1.0;
+            const costFactor = Math.min(0.3, (r.tokens || 0) / 10000);
+            const utility = r.score * (0.5 + 0.5 * strength) * (1 - costFactor);
+            return { ...r, score: utility };
+        })
+            .sort((a, b) => b.score - a.score);
+    }
+    // dlPFC goal-conditioned recall MVP (RESEARCH.md §PFC.dlPFC). When --goal
+    // <tag> is set, memories whose `tags` array contains the goal tag receive
+    // a 1.5x score boost and results are re-sorted. The full dlPFC spec
+    // (goal_stack + retrieval_policy tables) maintains a hierarchical task
+    // stack with weighted retrieval policies; this MVP collapses that to a
+    // single-tag boost — the smallest demonstrable goal-conditioning signal.
+    // Default off; opt-in via --goal <tag>. No schema change.
+    const goalTag = flags['goal'] !== undefined ? String(flags['goal']).trim() : '';
+    if (goalTag) {
+        results = results
+            .map((r) => (r.entry.tags?.includes(goalTag) ? { ...r, score: r.score * 1.5 } : r))
+            .sort((a, b) => b.score - a.score);
+    }
+    // Pineal salience MVP (RESEARCH.md §"AI Pineal Gland — Intuition and Awareness
+    // Module"). When --salience-threshold T is set (T > 0), memories whose
+    // retrieval_count is below T are downweighted: score *= max(0.5, count / T).
+    // At or above T, no change. This makes salience emerge from USE — high-recall
+    // memories earn full ranking weight, low-recall memories are softly demoted.
+    //
+    // CRITICAL HISTORY: The v1 salience gate (60% lexical-overlap gate at memory
+    // CREATION time) destroyed LoCoMo recall (0.28 -> 0.02) by dropping same-
+    // session relevant turns at intake. See MEMORY.md "Hippo salience gate
+    // destroys benchmark recall". This v2 is the inverse:
+    //   - retrieval-side only (no creation-time gating)
+    //   - retrieval_count signal only (no lexical overlap, no novelty heuristic)
+    //   - default OFF, opt-in via the flag (no behaviour change without it)
+    //   - 0.5 floor so non-salient entries stay reachable, never dropped
+    // Reuses the existing retrieval_count column; no schema change.
+    const salienceThresholdRaw = flags['salience-threshold'];
+    if (salienceThresholdRaw !== undefined) {
+        const T = Number(salienceThresholdRaw);
+        if (!Number.isFinite(T) || T <= 0) {
+            console.error(`Invalid --salience-threshold: "${salienceThresholdRaw}". Must be a positive number.`);
+            process.exit(1);
+        }
+        results = results
+            .map((r) => {
+            const count = r.entry.retrieval_count ?? 0;
+            if (count >= T)
+                return r;
+            const mult = Math.max(0.5, count / T);
+            return { ...r, score: r.score * mult };
+        })
+            .sort((a, b) => b.score - a.score);
+    }
     // --outcome filter: drop trace entries whose trace_outcome !== target.
     // Non-trace entries pass through unaffected (traces are the only layer with
     // a meaningful outcome; filtering non-traces by outcome would be incoherent).
@@ -619,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 }));
@@ -665,6 +906,9 @@ async function cmdRecall(hippoRoot, query, flags) {
                 base.reason = explanation.reason;
                 base.bm25 = r.bm25;
                 base.cosine = r.cosine;
+                if (explanation.envelope) {
+                    base.envelope = explanation.envelope;
+                }
             }
             return base;
         });
@@ -688,6 +932,19 @@ async function cmdRecall(hippoRoot, query, flags) {
             const explanation = explainMatch(query, r);
             console.log(`    source:${sourceMark} | layer: [${e.layer}] | confidence: [${conf}]`);
             console.log(`    reason: ${explanation.reason}`);
+            if (explanation.envelope) {
+                const env = explanation.envelope;
+                console.log(`    kind: ${env.kind}`);
+                if (env.scope)
+                    console.log(`    scope: ${env.scope}`);
+                if (env.owner)
+                    console.log(`    owner: ${env.owner}`);
+                if (env.artifact_ref)
+                    console.log(`    artifact_ref: ${env.artifact_ref}`);
+                if (env.session_id)
+                    console.log(`    session_id: ${env.session_id}`);
+                console.log(`    confidence: ${env.confidence}`);
+            }
         }
         console.log();
         console.log(e.content);
@@ -708,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) => {
@@ -769,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';
     }
@@ -865,7 +1124,6 @@ async function cmdExplain(hippoRoot, query, flags) {
     console.log('Note: explain does not mark memories as retrieved (read-only).');
 }
 async function cmdEval(hippoRoot, corpusPath, flags) {
-    requireInit(hippoRoot);
     const asJson = Boolean(flags['json']);
     const minMrr = flags['min-mrr'] !== undefined ? parseFloat(String(flags['min-mrr'])) : null;
     const showCases = Boolean(flags['show-cases']);
@@ -873,7 +1131,14 @@ async function cmdEval(hippoRoot, corpusPath, flags) {
     const noMmr = Boolean(flags['no-mmr']);
     const mmrLambda = flags['mmr-lambda'] !== undefined ? parseFloat(String(flags['mmr-lambda'])) : undefined;
     const embeddingWeight = flags['embedding-weight'] !== undefined ? parseFloat(String(flags['embedding-weight'])) : undefined;
-    const entries = loadAllEntries(hippoRoot);
+    // Suite mode doesn't need an initialized store
+    if (flags['suite']) {
+        // handled below after bootstrap check
+    }
+    else {
+        requireInit(hippoRoot);
+    }
+    const entries = flags['suite'] ? [] : loadAllEntries(hippoRoot);
     // Bootstrap mode: emit a synthetic corpus and exit.
     if (flags['bootstrap']) {
         const outPath = flags['out'] ? String(flags['out']) : null;
@@ -890,8 +1155,41 @@ async function cmdEval(hippoRoot, corpusPath, flags) {
         }
         return;
     }
+    // Suite mode: run built-in feature eval (no corpus file needed, no init needed)
+    if (flags['suite']) {
+        const pkg = JSON.parse(fs.readFileSync(path.join(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1')), '..', 'package.json'), 'utf8'));
+        const version = pkg.version || 'unknown';
+        const baselinePath = flags['baseline'] ? String(flags['baseline']) : path.join(hippoRoot, 'eval-baseline.json');
+        let baseline;
+        if (fs.existsSync(baselinePath)) {
+            try {
+                baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+            }
+            catch { }
+        }
+        const result = await runFeatureEval(version);
+        if (asJson) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(formatResult(result, baseline));
+        }
+        if (flags['save-baseline']) {
+            const newBaseline = resultToBaseline(result);
+            fs.mkdirSync(path.dirname(baselinePath), { recursive: true });
+            fs.writeFileSync(baselinePath, JSON.stringify(newBaseline, null, 2), 'utf8');
+            console.log(`\nBaseline saved to ${baselinePath}`);
+        }
+        if (baseline) {
+            const report = detectRegressions(baseline, result);
+            if (report.verdict === 'REGRESSION' && minMrr === null) {
+                process.exit(1);
+            }
+        }
+        return;
+    }
     if (!corpusPath) {
-        console.error('Usage: hippo eval <corpus.json>  OR  hippo eval --bootstrap [--out <path>]');
+        console.error('Usage: hippo eval <corpus.json>  OR  hippo eval --suite [--save-baseline]  OR  hippo eval --bootstrap');
         process.exit(1);
     }
     if (!fs.existsSync(corpusPath)) {
@@ -1459,6 +1757,17 @@ async function cmdSleepCore(hippoRoot, flags) {
             }
         }
     }
+    // Post-sleep ambient state summary
+    if (!dryRun) {
+        const postSleepConfig = loadConfig(hippoRoot);
+        if (postSleepConfig.ambient.enabled) {
+            const postSleepEntries = loadAllEntries(hippoRoot).filter(e => !e.superseded_by);
+            if (postSleepEntries.length > 0) {
+                const ambientState = computeAmbientState(postSleepEntries);
+                console.log(`\n${renderAmbientSummary(ambientState)}`);
+            }
+        }
+    }
 }
 /**
  * Print the contents of the SessionEnd sleep log to stdout, then clear it.
@@ -2363,25 +2672,31 @@ 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);
-    const allEntries = [...localEntries];
-    if (allEntries.length === 0 && globalEntries.length === 0)
-        return; // no memories, zero output
     let selectedItems = [];
     let totalTokens = 0;
     // Task snapshots / session events live in the local store. Skip when
     // local isn't initialized — loading would auto-create .hippo in the cwd.
     const activeSnapshot = hasLocal ? loadActiveTaskSnapshot(hippoRoot) : null;
+    const sessionHandoff = hasLocal && activeSnapshot?.session_id
+        ? loadLatestHandoff(hippoRoot, activeSnapshot.session_id)
+        : null;
     const recentSessionEvents = hasLocal && activeSnapshot?.session_id
         ? listSessionEvents(hippoRoot, { session_id: activeSnapshot.session_id, limit: 5 })
         : [];
+    if (localEntries.length === 0 && globalEntries.length === 0 && !activeSnapshot && !sessionHandoff && recentSessionEvents.length === 0) {
+        return;
+    }
     // --pinned-only: restrict to pinned entries only. Used by the Claude Code
     // UserPromptSubmit hook so invariants stay in context every turn.
     // (pinnedOnly and hasLocal are declared at the top of this function.)
@@ -2453,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,
@@ -2477,12 +2792,26 @@ 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);
         totalTokens = selectedItems.reduce((sum, r) => sum + r.tokens, 0);
     }
-    if (selectedItems.length === 0 && !activeSnapshot && recentSessionEvents.length === 0)
+    if (selectedItems.length === 0 && !activeSnapshot && !sessionHandoff && recentSessionEvents.length === 0)
         return;
     // --pinned-only is called by the UserPromptSubmit hook every turn. Treat it
     // as read-only so pinned memories don't inflate retrieval_count or extend
@@ -2516,7 +2845,7 @@ async function cmdContext(hippoRoot, args, flags) {
             content: r.entry.content,
             global: r.isGlobal ?? false,
         }));
-        console.log(JSON.stringify({ query, activeSnapshot, recentSessionEvents, memories: output, tokens: totalTokens }));
+        console.log(JSON.stringify({ query, activeSnapshot, sessionHandoff, recentSessionEvents, memories: output, tokens: totalTokens }));
     }
     else if (format === 'additional-context') {
         // Claude Code UserPromptSubmit hook JSON shape. Capture the markdown that
@@ -2527,14 +2856,18 @@ async function cmdContext(hippoRoot, args, flags) {
         try {
             if (activeSnapshot)
                 printActiveTaskSnapshot(activeSnapshot);
+            if (sessionHandoff)
+                printHandoff(sessionHandoff);
             if (recentSessionEvents.length > 0)
                 printSessionEvents(recentSessionEvents);
-            printContextMarkdown(selectedItems.map((r) => ({
-                entry: updatedEntries.find((u) => u.id === r.entry.id) ?? r.entry,
-                score: r.score,
-                tokens: r.tokens,
-                isGlobal: r.isGlobal ?? false,
-            })), totalTokens, framing);
+            if (selectedItems.length > 0) {
+                printContextMarkdown(selectedItems.map((r) => ({
+                    entry: updatedEntries.find((u) => u.id === r.entry.id) ?? r.entry,
+                    score: r.score,
+                    tokens: r.tokens,
+                    isGlobal: r.isGlobal ?? false,
+                })), totalTokens, framing);
+            }
         }
         finally {
             console.log = realLog;
@@ -2554,15 +2887,29 @@ async function cmdContext(hippoRoot, args, flags) {
         if (activeSnapshot) {
             printActiveTaskSnapshot(activeSnapshot);
         }
+        if (sessionHandoff) {
+            printHandoff(sessionHandoff);
+        }
         if (recentSessionEvents.length > 0) {
             printSessionEvents(recentSessionEvents);
         }
-        printContextMarkdown(selectedItems.map((r) => ({
-            entry: updatedEntries.find((u) => u.id === r.entry.id) ?? r.entry,
-            score: r.score,
-            tokens: r.tokens,
-            isGlobal: r.isGlobal ?? false,
-        })), totalTokens, framing);
+        if (selectedItems.length > 0) {
+            printContextMarkdown(selectedItems.map((r) => ({
+                entry: updatedEntries.find((u) => u.id === r.entry.id) ?? r.entry,
+                score: r.score,
+                tokens: r.tokens,
+                isGlobal: r.isGlobal ?? false,
+            })), totalTokens, framing);
+        }
+        // Ambient state summary (one-line landscape overview)
+        const ambientConfig = loadConfig(hippoRoot);
+        if (ambientConfig.ambient.enabled && !pinnedOnly) {
+            const allForAmbient = [...localEntries, ...globalEntries];
+            if (allForAmbient.length > 0) {
+                const ambientState = computeAmbientState(allForAmbient);
+                console.log(`\n${renderAmbientSummary(ambientState)}`);
+            }
+        }
     }
 }
 function printContextMarkdown(items, totalTokens, framing = 'observe') {
@@ -2893,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()}`);
     }
@@ -3446,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
@@ -3475,6 +4056,38 @@ Commands:
     --why                  Show match reasons and source annotations
     --no-mmr               Disable MMR diversity re-ranking
     --mmr-lambda <f>       MMR balance 0..1 (default: 0.7, 1.0 = pure relevance)
+    --evc-adaptive         ACC-style: when top-K shows high inter-item overlap
+                           (= conflict cluster), expand pool and re-rank by
+                           recency. Default off. RESEARCH.md §PFC.ACC.
+    --filter-conflicts     vlPFC interference filter: drop superseded entries
+                           and 0.3x-downweight entries flagged in an open
+                           conflict with a peer in the same result set.
+                           Uses recorded supersession + conflicts only — never
+                           lexical inference. Default off. RESEARCH.md §PFC.vlPFC.
+    --value-aware          vmPFC value attribution: boost memories with positive
+                           cumulative outcomes and demote those with negative
+                           outcomes during ranking. Multiplier
+                           clip(1 + 0.3*tanh(pos - neg), 0.7, 1.3). Reuses
+                           outcome_positive / outcome_negative; no schema
+                           change. Default off. RESEARCH.md §PFC.vmPFC.
+    --rerank-utility       OFC option-value re-ranker: combine relevance,
+                           strength, and integration cost into a single utility
+                           = score * (0.5 + 0.5 * strength) * (1 - cost_factor)
+                           where cost_factor = min(0.3, tokens / 10000). Re-sorts
+                           results by utility. Default off. RESEARCH.md §PFC.OFC.
+    --goal <tag>           dlPFC goal-conditioned recall: memories tagged with
+                           the goal tag get a 1.5x score boost and results are
+                           re-sorted. Default off. RESEARCH.md §PFC.dlPFC.
+    --salience-threshold <n>
+                           Pineal salience: down-weight memories whose
+                           retrieval_count is below n. score *= max(0.5,
+                           retrieval_count / n) for entries with count < n;
+                           entries at or above n are unchanged. Salience emerges
+                           from USE, not from lexical overlap. Default off.
+                           RESEARCH.md §"AI Pineal Gland". (v1's creation-time
+                           lexical gate destroyed LoCoMo 0.28 -> 0.02; this v2
+                           is retrieval-side, opt-in only — see MEMORY.md
+                           "Hippo salience gate destroys benchmark recall".)
   explain <query>          Show full score breakdown for each retrieved memory
     --budget <n>           Token budget (default: 4000)
     --limit <n>            Cap the number of results displayed
@@ -3650,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
@@ -3705,7 +4339,13 @@ async function main() {
             cmdInit(hippoRoot, flags);
             break;
         case 'remember': {
-            const text = args.join(' ').trim();
+            let text;
+            if (args.length === 1 && args[0] === '-') {
+                text = fs.readFileSync(0, 'utf-8').trim();
+            }
+            else {
+                text = args.join(' ').trim();
+            }
             if (!text || text.length < 3) {
                 console.error('Memory content too short (minimum 3 characters).');
                 process.exit(1);
@@ -3786,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);