hippo-memory 0.24.2 → 0.27.0

package/dist/cli.js

@@ -46,6 +46,8 @@ 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 { runEval, bootstrapCorpus } from './eval.js';
 import { wmPush, wmRead, wmClear, wmFlush } from './working-memory.js';
 // ---------------------------------------------------------------------------
 // Helpers
@@ -438,6 +440,11 @@ async function cmdRecall(hippoRoot, query, flags) {
     const config = loadConfig(hippoRoot);
     const usePhysics = forcePhysics
         || (!forceClassic && config.physics.enabled !== false);
+    const noMmr = Boolean(flags['no-mmr']);
+    const mmrLambda = flags['mmr-lambda'] !== undefined
+        ? parseFloat(String(flags['mmr-lambda']))
+        : config.mmr.lambda;
+    const mmrEnabled = !noMmr && config.mmr.enabled;
     let results;
     if (usePhysics && !hasGlobal) {
         results = await physicsSearch(query, localEntries, {
@@ -448,10 +455,14 @@ async function cmdRecall(hippoRoot, query, flags) {
     }
     else if (hasGlobal) {
         // Use searchBothHybrid for merged results with embedding support
-        results = await searchBothHybrid(query, hippoRoot, globalRoot, { budget });
+        results = await searchBothHybrid(query, hippoRoot, globalRoot, {
+            budget, mmr: mmrEnabled, mmrLambda,
+        });
     }
     else {
-        results = await hybridSearch(query, localEntries, { budget, hippoRoot });
+        results = await hybridSearch(query, localEntries, {
+            budget, hippoRoot, mmr: mmrEnabled, mmrLambda,
+        });
     }
     if (limit < results.length) {
         results = results.slice(0, limit);
@@ -523,6 +534,326 @@ async function cmdRecall(hippoRoot, query, flags) {
         console.log();
     }
 }
+async function cmdExplain(hippoRoot, query, flags) {
+    requireInit(hippoRoot);
+    const budget = parseInt(String(flags['budget'] ?? '4000'), 10);
+    const limit = parseLimitFlag(flags['limit']);
+    const asJson = Boolean(flags['json']);
+    const forcePhysics = Boolean(flags['physics']);
+    const forceClassic = Boolean(flags['classic']);
+    const globalRoot = getGlobalRoot();
+    const localEntries = loadSearchEntries(hippoRoot, query);
+    const globalEntries = isInitialized(globalRoot) ? loadSearchEntries(globalRoot, query) : [];
+    const hasGlobal = globalEntries.length > 0;
+    const config = loadConfig(hippoRoot);
+    const usePhysics = forcePhysics
+        || (!forceClassic && config.physics.enabled !== false);
+    const noMmr = Boolean(flags['no-mmr']);
+    const mmrLambda = flags['mmr-lambda'] !== undefined
+        ? parseFloat(String(flags['mmr-lambda']))
+        : config.mmr.lambda;
+    const mmrEnabled = !noMmr && config.mmr.enabled;
+    let results;
+    let modeUsed;
+    if (usePhysics && !hasGlobal) {
+        results = await physicsSearch(query, localEntries, {
+            budget,
+            hippoRoot,
+            physicsConfig: config.physics,
+            explain: true,
+        });
+        modeUsed = 'physics';
+    }
+    else if (hasGlobal) {
+        results = await searchBothHybrid(query, hippoRoot, globalRoot, {
+            budget, explain: true, mmr: mmrEnabled, mmrLambda,
+        });
+        modeUsed = 'searchBothHybrid';
+    }
+    else {
+        results = await hybridSearch(query, localEntries, {
+            budget, hippoRoot, explain: true, mmr: mmrEnabled, mmrLambda,
+        });
+        modeUsed = 'hybrid';
+    }
+    if (limit < results.length) {
+        results = results.slice(0, limit);
+    }
+    const candidates = localEntries.length + globalEntries.length;
+    if (asJson) {
+        const output = results.map((r, rank) => ({
+            rank: rank + 1,
+            id: r.entry.id,
+            layer: r.entry.layer,
+            confidence: resolveConfidence(r.entry),
+            score: r.score,
+            tokens: r.tokens,
+            tags: r.entry.tags,
+            content: r.entry.content,
+            breakdown: r.breakdown,
+        }));
+        console.log(JSON.stringify({
+            query,
+            mode: modeUsed,
+            candidates,
+            returned: output.length,
+            results: output,
+        }));
+        return;
+    }
+    if (results.length === 0) {
+        console.log(`No memories matched "${query}" (scanned ${candidates}).`);
+        return;
+    }
+    console.log(`Query: "${query}"`);
+    console.log(`Mode:  ${modeUsed}   candidates: ${candidates}   returned: ${results.length}`);
+    console.log();
+    console.log('Rank  Score   Strength  Age    Layer      ID                Preview');
+    console.log('----- ------- --------- ------ ---------- ----------------- ---------------------------------');
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        const b = r.breakdown;
+        const preview = r.entry.content.replace(/\s+/g, ' ').slice(0, 48);
+        const ageStr = b ? `${b.ageDays}d` : '?';
+        console.log(`${String(i + 1).padEnd(5)} ${fmt(r.score, 3).padEnd(7)} ${fmt(r.entry.strength).padEnd(9)} ${ageStr.padEnd(6)} ${r.entry.layer.padEnd(10)} ${r.entry.id.padEnd(17)} ${preview}`);
+    }
+    console.log();
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        const b = r.breakdown;
+        console.log(`[${i + 1}] ${r.entry.id}   composite=${fmt(r.score, 4)}`);
+        if (!b) {
+            console.log('    (no breakdown available)');
+            console.log();
+            continue;
+        }
+        if (b.mode === 'physics') {
+            console.log(`    mode:      physics-gravity`);
+            console.log(`    cosine:    ${fmt(b.cosine, 3)}  (pre-amp baseline)`);
+            console.log(`    final:     ${fmt(b.final, 4)}  (post-amp, from physics scorer)`);
+        }
+        else {
+            const matched = b.matchedTerms.length > 0 ? b.matchedTerms.join(', ') : '(none)';
+            console.log(`    mode:      ${b.mode}${b.mode === 'hybrid-no-vec' ? '  (no cached doc vector — run `hippo embed`)' : ''}`);
+            console.log(`    BM25:      raw=${fmt(r.bm25, 3)}  normalized=${fmt(b.normBm25, 3)}  weight=${fmt(b.bm25Weight, 2)}  matched=[${matched}]`);
+            console.log(`    embedding: cosine=${fmt(b.cosine, 3)}  weight=${fmt(b.embeddingWeight, 2)}`);
+            console.log(`    base:      ${fmt(b.bm25Weight, 2)}*${fmt(b.normBm25, 3)} + ${fmt(b.embeddingWeight, 2)}*${fmt(b.cosine, 3)} = ${fmt(b.base, 4)}`);
+            console.log(`    strength:  x${fmt(b.strengthMultiplier, 3)}  (strength=${fmt(r.entry.strength, 3)})`);
+            console.log(`    recency:   x${fmt(b.recencyMultiplier, 3)}  (age=${b.ageDays}d)`);
+            if (b.decisionBoost !== 1)
+                console.log(`    decision:  x${fmt(b.decisionBoost, 2)}  (tagged 'decision')`);
+            if (b.pathBoost !== 1)
+                console.log(`    path:      x${fmt(b.pathBoost, 3)}  (cwd path tag overlap)`);
+            if (b.sourceBump !== 1)
+                console.log(`    source:    x${fmt(b.sourceBump, 2)}  (local priority bump over global)`);
+            if (b.outcomeBoost !== 1)
+                console.log(`    outcome:   x${fmt(b.outcomeBoost, 3)}  (user feedback: pos-neg = ${(r.entry.outcome_positive ?? 0) - (r.entry.outcome_negative ?? 0)})`);
+            if (b.preMmrRank !== undefined && b.postMmrRank !== undefined && b.preMmrRank !== b.postMmrRank) {
+                const arrow = b.postMmrRank < b.preMmrRank ? 'up' : 'down';
+                console.log(`    mmr:       rank ${b.preMmrRank} -> ${b.postMmrRank}  (diversity ${arrow})`);
+            }
+            console.log(`    final:     ${fmt(b.final, 4)}`);
+        }
+        console.log();
+    }
+    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']);
+    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);
+    // Bootstrap mode: emit a synthetic corpus and exit.
+    if (flags['bootstrap']) {
+        const outPath = flags['out'] ? String(flags['out']) : null;
+        const max = flags['max-cases'] !== undefined ? parseInt(String(flags['max-cases']), 10) : 50;
+        const corpus = bootstrapCorpus(entries, max);
+        const payload = JSON.stringify({ cases: corpus }, null, 2);
+        if (outPath) {
+            fs.mkdirSync(path.dirname(outPath), { recursive: true });
+            fs.writeFileSync(outPath, payload, 'utf8');
+            console.log(`Wrote ${corpus.length} bootstrap cases to ${outPath}`);
+        }
+        else {
+            console.log(payload);
+        }
+        return;
+    }
+    if (!corpusPath) {
+        console.error('Usage: hippo eval <corpus.json>  OR  hippo eval --bootstrap [--out <path>]');
+        process.exit(1);
+    }
+    if (!fs.existsSync(corpusPath)) {
+        console.error(`Corpus file not found: ${corpusPath}`);
+        process.exit(1);
+    }
+    let cases;
+    try {
+        const raw = JSON.parse(fs.readFileSync(corpusPath, 'utf8'));
+        cases = Array.isArray(raw) ? raw : raw.cases;
+        if (!Array.isArray(cases))
+            throw new Error('Corpus JSON must be an array or { cases: [...] }');
+    }
+    catch (err) {
+        console.error(`Failed to read corpus: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+    const summary = await runEval(cases, entries, {
+        hippoRoot,
+        mmr: !noMmr,
+        mmrLambda,
+        embeddingWeight,
+    });
+    if (asJson) {
+        console.log(JSON.stringify(summary, null, 2));
+    }
+    else {
+        console.log(`Eval: ${summary.cases.length} cases, ${summary.durationMs}ms`);
+        console.log();
+        console.log(`MRR:          ${fmt(summary.meanMrr, 4)}`);
+        console.log(`Recall@5:     ${fmt(summary.meanRecallAt5, 4)}`);
+        console.log(`Recall@10:    ${fmt(summary.meanRecallAt10, 4)}`);
+        console.log(`NDCG@10:      ${fmt(summary.meanNdcgAt10, 4)}`);
+        if (showCases) {
+            console.log();
+            console.log('Case details:');
+            for (const c of summary.cases) {
+                const exp = c.case.expectedIds.length;
+                const expectedSet = new Set(c.case.expectedIds);
+                const hitTop10 = c.returnedIds.slice(0, 10).filter((id) => expectedSet.has(id));
+                const missed = c.case.expectedIds.filter((id) => !c.returnedIds.slice(0, 10).includes(id));
+                console.log();
+                console.log(`[${c.case.id}] R@10=${fmt(c.recallAt10, 2)}  MRR=${fmt(c.mrr, 2)}  expected=${exp}  hit=${hitTop10.length}`);
+                console.log(`  query: ${c.case.query}`);
+                console.log(`  top 3: ${c.returnedIds.slice(0, 3).join(', ') || '(none)'}`);
+                if (missed.length > 0) {
+                    const shown = missed.slice(0, 4);
+                    const more = missed.length > shown.length ? ` +${missed.length - shown.length} more` : '';
+                    console.log(`  missed: ${shown.join(', ')}${more}`);
+                }
+            }
+        }
+        console.log();
+        const failing = summary.cases.filter((c) => c.mrr === 0);
+        if (failing.length > 0) {
+            console.log(`${failing.length} case(s) returned zero relevant results:`);
+            for (const f of failing.slice(0, 10)) {
+                console.log(`  [${f.case.id}] "${f.case.query.slice(0, 60)}"`);
+            }
+            if (failing.length > 10)
+                console.log(`  ...and ${failing.length - 10} more`);
+        }
+    }
+    if (minMrr !== null && summary.meanMrr < minMrr) {
+        console.error(`MRR ${fmt(summary.meanMrr, 4)} below threshold ${minMrr}`);
+        process.exit(1);
+    }
+}
+function cmdTrace(hippoRoot, id, flags) {
+    requireInit(hippoRoot);
+    const asJson = Boolean(flags['json']);
+    // Look in local store first, then global.
+    let entry = readEntry(hippoRoot, id);
+    let sourceLabel = 'local';
+    const globalRoot = getGlobalRoot();
+    if (!entry && isInitialized(globalRoot)) {
+        entry = readEntry(globalRoot, id);
+        sourceLabel = 'global';
+    }
+    if (!entry) {
+        console.error(`Memory not found: ${id}`);
+        process.exit(1);
+    }
+    const now = new Date();
+    const strength = calculateStrength(entry, now);
+    const halfLife = deriveHalfLife(7, entry);
+    const rewardFactor = calculateRewardFactor(entry);
+    const effHalfLife = halfLife * rewardFactor;
+    const createdMs = new Date(entry.created).getTime();
+    const ageDays = (now.getTime() - createdMs) / 86_400_000;
+    const lastMs = new Date(entry.last_retrieved).getTime();
+    const sinceLast = (now.getTime() - lastMs) / 86_400_000;
+    const conf = resolveConfidence(entry, now);
+    // Projected strength: same decay curve, just push `now` out.
+    const projectedAt = (days) => calculateStrength(entry, new Date(now.getTime() + days * 86_400_000));
+    // Parents (consolidation lineage) — schema v9 field.
+    const parents = Array.isArray(entry.parents) ? entry.parents : [];
+    const parentPreviews = parents.map((pid) => {
+        const p = readEntry(hippoRoot, pid) ?? (isInitialized(globalRoot) ? readEntry(globalRoot, pid) : null);
+        return { id: pid, content: p ? p.content.replace(/\s+/g, ' ').slice(0, 70) : '(not found)' };
+    });
+    // Open conflicts involving this memory.
+    const allConflicts = [
+        ...listMemoryConflicts(hippoRoot, 'open'),
+        ...(isInitialized(globalRoot) ? listMemoryConflicts(globalRoot, 'open') : []),
+    ];
+    const myConflicts = allConflicts.filter((c) => c.memory_a_id === id || c.memory_b_id === id);
+    if (asJson) {
+        console.log(JSON.stringify({
+            id: entry.id,
+            source: sourceLabel,
+            layer: entry.layer,
+            confidence: conf,
+            pinned: entry.pinned,
+            starred: entry.starred,
+            tags: entry.tags,
+            content: entry.content,
+            created: entry.created,
+            age_days: ageDays,
+            last_retrieved: entry.last_retrieved,
+            days_since_last_retrieval: sinceLast,
+            retrieval_count: entry.retrieval_count,
+            strength_now: strength,
+            half_life_days: halfLife,
+            reward_factor: rewardFactor,
+            effective_half_life_days: effHalfLife,
+            projected_strength_30d: projectedAt(30),
+            projected_strength_90d: projectedAt(90),
+            outcome_positive: entry.outcome_positive,
+            outcome_negative: entry.outcome_negative,
+            parents: parentPreviews,
+            open_conflicts: myConflicts,
+        }, null, 2));
+        return;
+    }
+    console.log(`Memory: ${entry.id}  [${sourceLabel}]`);
+    console.log('='.repeat(50));
+    console.log(`Content:   ${entry.content.replace(/\s+/g, ' ').slice(0, 160)}${entry.content.length > 160 ? '...' : ''}`);
+    console.log(`Layer:     ${entry.layer.padEnd(10)} Confidence: ${conf.padEnd(10)} Pinned: ${entry.pinned ? 'yes' : 'no'}${entry.starred ? '  Starred: yes' : ''}`);
+    console.log(`Tags:      ${entry.tags.join(', ') || '(none)'}`);
+    console.log(`Created:   ${entry.created}  (${fmt(ageDays, 1)} days ago)`);
+    console.log();
+    console.log(`Strength trajectory:`);
+    console.log(`  now:        ${fmt(strength, 3)}`);
+    console.log(`  in 30 days: ${fmt(projectedAt(30), 3)}`);
+    console.log(`  in 90 days: ${fmt(projectedAt(90), 3)}`);
+    console.log(`  half-life:  ${fmt(halfLife, 1)}d (base) x ${fmt(rewardFactor, 2)} reward = ${fmt(effHalfLife, 1)}d effective`);
+    console.log();
+    console.log(`Retrieval:`);
+    console.log(`  count:      ${entry.retrieval_count}`);
+    console.log(`  last:       ${entry.last_retrieved}  (${fmt(sinceLast, 1)} days ago)`);
+    console.log();
+    console.log(`Outcomes:   +${entry.outcome_positive} / -${entry.outcome_negative}`);
+    if (parentPreviews.length > 0) {
+        console.log();
+        console.log(`Parents (consolidation lineage):`);
+        for (const p of parentPreviews) {
+            console.log(`  - ${p.id}: ${p.content}`);
+        }
+    }
+    if (myConflicts.length > 0) {
+        console.log();
+        console.log(`Open conflicts: ${myConflicts.length}`);
+        for (const c of myConflicts) {
+            const other = c.memory_a_id === id ? c.memory_b_id : c.memory_a_id;
+            console.log(`  - with ${other}: ${c.reason} (score=${fmt(c.score, 2)})`);
+        }
+    }
+}
 /**
  * Scan for Claude Code MEMORY.md files and import new entries into hippo.
  * Looks in ~/.claude/projects/<project>/memory/ for .md files with YAML frontmatter.
@@ -767,6 +1098,24 @@ function cmdSleepCore(hippoRoot, flags) {
             console.log(`\nDeduped ${dedupResult.removed} duplicates (${parts.join(', ')}). Kept stronger copies.`);
         }
     }
+    // Quality audit — remove junk, report warnings
+    if (!dryRun) {
+        const allEntries = loadAllEntries(hippoRoot);
+        const audit = auditMemories(allEntries);
+        if (audit.issues.length > 0) {
+            const errors = audit.issues.filter(i => i.severity === 'error');
+            const warnings = audit.issues.filter(i => i.severity === 'warning');
+            if (errors.length > 0) {
+                for (const issue of errors) {
+                    deleteEntry(hippoRoot, issue.memoryId);
+                }
+                console.log(`\nAudit: removed ${errors.length} junk memories (too short/empty).`);
+            }
+            if (warnings.length > 0) {
+                console.log(`Audit: ${warnings.length} low-quality memories detected (run \`hippo audit\` for details).`);
+            }
+        }
+    }
     // Auto-share high-transfer-score memories to global (unless --no-share or dry-run)
     if (!dryRun && !flags['no-share']) {
         const sleepConfig = loadConfig(hippoRoot);
@@ -2150,7 +2499,7 @@ hippo capture --stdin <<< '<decisions, errors, lessons — 2-5 bullets>'
     'codex': {
         file: 'AGENTS.md',
         description: 'OpenAI Codex',
-        content: `
+        content: `
 ## Project Memory (Hippo)
 
 At the start of every task, run:
@@ -2169,8 +2518,8 @@ On task completion:
 hippo outcome --good
 \`\`\`
 
-When Hippo's Codex wrapper is installed, session-end capture runs automatically.
-If the wrapper is not installed, capture a brief summary manually:
+When Hippo's Codex wrapper is installed, session-end capture runs automatically.
+If the wrapper is not installed, capture a brief summary manually:
 \`\`\`bash
 hippo capture --stdin <<< '<decisions, errors, lessons — 2-5 bullets>'
 \`\`\`
@@ -2602,13 +2951,13 @@ Hippo - biologically-inspired memory system for AI agents
 Usage: hippo <command> [options]
 
 Commands:
-  init                     Create .hippo/ structure in current directory
-    --scan [dir]           Find all git repos under dir (default: ~) and init each
-    --days <n>             Days of git history to seed (default: 365 for --scan, 30 for single)
-    --global               Init the global store ($HIPPO_HOME or ~/.hippo/)
-    --no-hooks             Skip auto-detecting and installing agent hooks
-    --no-schedule          Skip auto-creating the machine-level daily runner
-    --no-learn             Skip seeding memories from git history
+  init                     Create .hippo/ structure in current directory
+    --scan [dir]           Find all git repos under dir (default: ~) and init each
+    --days <n>             Days of git history to seed (default: 365 for --scan, 30 for single)
+    --global               Init the global store ($HIPPO_HOME or ~/.hippo/)
+    --no-hooks             Skip auto-detecting and installing agent hooks
+    --no-schedule          Skip auto-creating the machine-level daily runner
+    --no-learn             Skip seeding memories from git history
   remember <text>          Store a memory
     --tag <tag>            Add a tag (repeatable)
     --error                Tag as error (boosts retention)
@@ -2621,20 +2970,43 @@ Commands:
     --budget <n>           Token budget (default: 4000)
     --json                 Output as JSON
     --why                  Show match reasons and source annotations
-  context                  Smart context injection for AI agents
+    --no-mmr               Disable MMR diversity re-ranking
+    --mmr-lambda <f>       MMR balance 0..1 (default: 0.7, 1.0 = pure relevance)
+  explain <query>          Show full score breakdown for each retrieved memory
+    --budget <n>           Token budget (default: 4000)
+    --limit <n>            Cap the number of results displayed
+    --json                 Output as JSON
+    --physics | --classic  Force search mode (default: from config)
+    --no-mmr               Disable MMR diversity re-ranking
+    --mmr-lambda <f>       MMR balance 0..1 (default: 0.7, 1.0 = pure relevance)
+  trace <id>               Memory dossier: content, decay trajectory, retrievals,
+                           outcomes, consolidation parents, open conflicts
+    --json                 Output as JSON
+  eval [<corpus.json>]     Measure recall quality against a test corpus
+    --bootstrap            Generate a synthetic corpus from current memories
+    --out <path>           With --bootstrap, write to file instead of stdout
+    --max-cases <n>        With --bootstrap, cap case count (default: 50)
+    --show-cases           Print per-case details (query, R@10, missed, top 3)
+    --no-mmr               Disable MMR for this eval run
+    --mmr-lambda <f>       Override MMR lambda for this run
+    --embedding-weight <f> Override cosine weight (default: 0.6)
+    --min-mrr <f>          Exit non-zero if mean MRR falls below this
+    --json                 Output full summary as JSON
+  context                  Smart context injection for AI agents
     --auto                 Auto-detect task from git state
     --budget <n>           Token budget (default: 1500)
     --format <fmt>         Output format: markdown (default) or json
     --framing <mode>       Framing: observe (default), suggest, assert
-  sleep                    Run consolidation pass (auto-learns + dedup + auto-shares)
-    --dry-run              Preview without writing
-    --no-learn             Skip auto git-learn before consolidation
-    --no-share             Skip auto-sharing to global store
-  daily-runner             Sweep registered workspaces and run daily learn+sleep
-  dedup                    Remove duplicate memories (keeps stronger copy)
+  sleep                    Run consolidation pass (auto-learns + dedup + auto-shares)
+    --dry-run              Preview without writing
+    --no-learn             Skip auto git-learn before consolidation
+    --no-share             Skip auto-sharing to global store
+  daily-runner             Sweep registered workspaces and run daily learn+sleep
+  dedup                    Remove duplicate memories (keeps stronger copy)
     --dry-run              Preview without removing
     --threshold <n>        Overlap threshold 0-1 (default: 0.7)
   status                   Show memory health stats
+  audit [--fix]            Check memory quality (--fix removes junk)
   outcome                  Apply feedback to last recall
     --good                 Memories were helpful
     --bad                  Memories were irrelevant
@@ -2723,20 +3095,20 @@ Commands:
     --log-file <path>      Tee output to a log file (paired with 'hippo last-sleep')
     --dry-run              Preview without writing
     --global               Write to global store ($HIPPO_HOME or ~/.hippo/)
-  setup                    One-shot: detect installed AI tools and install all
-                           available SessionEnd+SessionStart hooks
-    --all                  Install for every JSON-hook tool, even if not detected
-    --dry-run              Show what would be installed without writing
-    --no-schedule          Skip installing or repairing the daily runner
-  last-sleep               Print the last 'hippo sleep --log-file' output and clear it
-    --path <p>             Log path (default: ~/.hippo/logs/last-sleep.log)
-    --keep                 Print without clearing
-  codex-run [-- ...args]   Launch real Codex behind Hippo's session-end wrapper
-  hook <sub> [target]      Manage framework integrations
-    hook list              Show available hooks
-    hook install <target>  Install hook (claude-code|codex|cursor|openclaw|opencode|pi)
-                           claude-code/opencode install SessionEnd+SessionStart;
-                           codex wraps the detected launcher in place
+  setup                    One-shot: detect installed AI tools and install all
+                           available SessionEnd+SessionStart hooks
+    --all                  Install for every JSON-hook tool, even if not detected
+    --dry-run              Show what would be installed without writing
+    --no-schedule          Skip installing or repairing the daily runner
+  last-sleep               Print the last 'hippo sleep --log-file' output and clear it
+    --path <p>             Log path (default: ~/.hippo/logs/last-sleep.log)
+    --keep                 Print without clearing
+  codex-run [-- ...args]   Launch real Codex behind Hippo's session-end wrapper
+  hook <sub> [target]      Manage framework integrations
+    hook list              Show available hooks
+    hook install <target>  Install hook (claude-code|codex|cursor|openclaw|opencode|pi)
+                           claude-code/opencode install SessionEnd+SessionStart;
+                           codex wraps the detected launcher in place
     hook uninstall <target> Remove hook
   decide "<decision>"      Record an architectural decision (90-day half-life)
     --context "<why>"      Why this decision was made
@@ -2805,8 +3177,8 @@ async function main() {
             break;
         case 'remember': {
             const text = args.join(' ').trim();
-            if (!text) {
-                console.error('Please provide text to remember.');
+            if (!text || text.length < 3) {
+                console.error('Memory content too short (minimum 3 characters).');
                 process.exit(1);
             }
             cmdRemember(hippoRoot, text, flags);
@@ -2821,6 +3193,29 @@ async function main() {
             await cmdRecall(hippoRoot, query, flags);
             break;
         }
+        case 'explain': {
+            const query = args.join(' ').trim();
+            if (!query) {
+                console.error('Please provide a search query.');
+                process.exit(1);
+            }
+            await cmdExplain(hippoRoot, query, flags);
+            break;
+        }
+        case 'eval': {
+            const corpusPath = args[0] ? String(args[0]) : null;
+            await cmdEval(hippoRoot, corpusPath, flags);
+            break;
+        }
+        case 'trace': {
+            const id = args[0] ? String(args[0]) : null;
+            if (!id) {
+                console.error('Usage: hippo trace <memory-id>');
+                process.exit(1);
+            }
+            cmdTrace(hippoRoot, id, flags);
+            break;
+        }
         case 'sleep':
             cmdSleep(hippoRoot, flags);
             break;
@@ -2842,6 +3237,40 @@ async function main() {
         case 'dedup':
             cmdDedup(hippoRoot, flags);
             break;
+        case 'audit': {
+            requireInit(hippoRoot);
+            const entries = loadAllEntries(hippoRoot);
+            const result = auditMemories(entries);
+            const shouldFix = Boolean(flags['fix']);
+            if (result.issues.length === 0) {
+                console.log(`All ${result.total} memories passed quality checks.`);
+            }
+            else {
+                console.log(`Audited ${result.total} memories: ${result.clean} clean, ${result.issues.length} issues\n`);
+                for (const issue of result.issues) {
+                    const icon = issue.severity === 'error' ? 'ERR' : 'WARN';
+                    console.log(`  [${icon}] ${issue.memoryId}: ${issue.reason}`);
+                    console.log(`         "${issue.content.slice(0, 80)}${issue.content.length > 80 ? '...' : ''}"`);
+                }
+                if (shouldFix) {
+                    const errorIds = result.issues.filter(i => i.severity === 'error').map(i => i.memoryId);
+                    if (errorIds.length > 0) {
+                        for (const id of errorIds) {
+                            deleteEntry(hippoRoot, id);
+                        }
+                        console.log(`\nRemoved ${errorIds.length} error-severity memories.`);
+                        console.log(`${result.issues.length - errorIds.length} warnings remain (review manually).`);
+                    }
+                    else {
+                        console.log(`\nNo error-severity issues. Warnings require manual review.`);
+                    }
+                }
+                else {
+                    console.log(`\nRun with --fix to auto-remove error-severity issues.`);
+                }
+            }
+            break;
+        }
         case 'status':
             cmdStatus(hippoRoot);
             break;