hippo-memory 1.61.0 → 1.62.0

package/dist/cli/explain.js

@@ -57,31 +57,39 @@ export async function cmdExplain(hippoRoot, query, flags) {
     const results = dropHeldCopies(rank.results, (r) => r.entry);
     const candidates = rank.localEntries.length + rank.globalEntries.length;
     if (asJson) {
-        const output = results.map((r, rank) => ({
-            rank: rank + 1,
-            id: r.entry.id,
-            layer: r.entry.layer,
-            confidence: confidenceFacets(r.entry).tier,
-            aged_out: confidenceFacets(r.entry).agedOut,
-            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,
-        }));
+        printExplainJson(results, query, modeUsed, candidates);
         return;
     }
     if (results.length === 0) {
         console.log(`No memories matched "${query}" (scanned ${candidates}).`);
         return;
     }
+    printExplainTable(results, query, modeUsed, candidates);
+    results.forEach((r, i) => printExplainBreakdown(r, i));
+    console.log('Note: explain does not mark memories as retrieved (read-only).');
+}
+function printExplainJson(results, query, modeUsed, candidates) {
+    const output = results.map((r, rank) => ({
+        rank: rank + 1,
+        id: r.entry.id,
+        layer: r.entry.layer,
+        confidence: confidenceFacets(r.entry).tier,
+        aged_out: confidenceFacets(r.entry).agedOut,
+        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,
+    }));
+}
+function printExplainTable(results, query, modeUsed, candidates) {
     console.log(`Query: "${query}"`);
     console.log(`Mode:  ${modeUsed}   candidates: ${candidates}   returned: ${results.length}`);
     console.log();
@@ -95,49 +103,47 @@ export async function cmdExplain(hippoRoot, query, flags) {
         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.scopeBoost !== 1)
-                console.log(`    scope:     x${fmt(b.scopeBoost, 2)}  (scope tag ${b.scopeBoost > 1 ? 'match' : 'mismatch'})`);
-            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.churnStaleMultiplier !== 1)
-                console.log(`    churn:     x${fmt(b.churnStaleMultiplier, 2)}  (tagged 'churn-stale')`);
-            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)}`);
-        }
+}
+function printExplainBreakdown(r, 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();
+        return;
     }
-    console.log('Note: explain does not mark memories as retrieved (read-only).');
+    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.scopeBoost !== 1)
+            console.log(`    scope:     x${fmt(b.scopeBoost, 2)}  (scope tag ${b.scopeBoost > 1 ? 'match' : 'mismatch'})`);
+        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.churnStaleMultiplier !== 1)
+            console.log(`    churn:     x${fmt(b.churnStaleMultiplier, 2)}  (tagged 'churn-stale')`);
+        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();
 }
 export async function handleExplain({ hippoRoot, args, flags }) {
     const query = args.join(' ').trim();

package/dist/cli/maintenance.js

@@ -102,34 +102,60 @@ export async function cmdEmbed(hippoRoot, flags) {
     // when no provider key is present (e.g. embedded earlier with a key that was
     // later removed). The provider-availability gate is deferred to the embed path.
     if (flags['reset-physics']) {
-        const entries = loadAllEntries(root);
-        const embIndex = loadEmbeddingIndex(root);
-        const db = openHippoDb(root);
-        try {
-            const count = resetAllPhysicsState(db, entries, embIndex);
-            console.log(`Reset physics state: ${count} particles re-initialized from embeddings.`);
-        }
-        finally {
-            closeHippoDb(db);
-        }
+        resetPhysics(root);
         return;
     }
     if (flags['status']) {
-        const entries = loadAllEntries(root);
-        const embIndex = loadEmbeddingIndex(root);
-        const activeIds = new Set(entries.map((e) => e.id));
-        const activeEmbedded = Object.keys(embIndex).filter((id) => activeIds.has(id)).length;
-        const orphaned = Object.keys(embIndex).length - activeEmbedded;
-        console.log(`Embedding status: ${activeEmbedded}/${entries.length} memories embedded`);
-        if (orphaned > 0) {
-            console.log(`  ${orphaned} orphaned embeddings (run \`hippo embed\` to prune)`);
-        }
-        const missing = entries.filter((e) => !embIndex[e.id]);
-        if (missing.length > 0) {
-            console.log(`  ${missing.length} memories need embedding (run \`hippo embed\` to embed them)`);
-        }
+        printEmbedStatus(root);
+        return;
+    }
+    if (!embedProviderReady(root))
         return;
+    console.log('Embedding all memories (this may take a moment on first run to download model)...');
+    let count;
+    try {
+        count = await embedAll(root, resolveEmbeddingModel(root));
     }
+    catch (err) {
+        printError(`Embedding failed: ${err instanceof Error ? err.message : String(err)}`);
+        const partial = loadEmbeddingIndex(root);
+        printError(`Partial progress saved: ${Object.keys(partial).length} embeddings on disk. Re-run \`hippo embed\` to resume.`);
+        process.exitCode = 1;
+        return;
+    }
+    const entriesAfter = loadAllEntries(root);
+    const embIndexAfter = loadEmbeddingIndex(root);
+    console.log(`Done. ${count} new embeddings created. ${Object.keys(embIndexAfter).length}/${entriesAfter.length} total.`);
+}
+function resetPhysics(root) {
+    const entries = loadAllEntries(root);
+    const embIndex = loadEmbeddingIndex(root);
+    const db = openHippoDb(root);
+    try {
+        const count = resetAllPhysicsState(db, entries, embIndex);
+        console.log(`Reset physics state: ${count} particles re-initialized from embeddings.`);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+function printEmbedStatus(root) {
+    const entries = loadAllEntries(root);
+    const embIndex = loadEmbeddingIndex(root);
+    const activeIds = new Set(entries.map((e) => e.id));
+    const activeEmbedded = Object.keys(embIndex).filter((id) => activeIds.has(id)).length;
+    const orphaned = Object.keys(embIndex).length - activeEmbedded;
+    console.log(`Embedding status: ${activeEmbedded}/${entries.length} memories embedded`);
+    if (orphaned > 0) {
+        console.log(`  ${orphaned} orphaned embeddings (run \`hippo embed\` to prune)`);
+    }
+    const missing = entries.filter((e) => !embIndex[e.id]);
+    if (missing.length > 0) {
+        console.log(`  ${missing.length} memories need embedding (run \`hippo embed\` to embed them)`);
+    }
+}
+/** False, after saying why, when no usable provider exists. */
+function embedProviderReady(root) {
     // Embedding (unlike status/reset) needs an available provider.
     const embedProvider = (() => {
         try {
@@ -142,38 +168,23 @@ export async function cmdEmbed(hippoRoot, flags) {
     })();
     if (!embedProvider) {
         process.exitCode = 1;
-        return;
+        return false;
     }
-    if (!embedProvider.isAvailable()) {
-        if (loadConfig(root).embeddings.enabled === false) {
-            console.log('Embeddings are disabled in config (embeddings.enabled = false). Set it to true or "auto" to enable.');
-            return;
-        }
-        if (embedProvider.kind === 'local') {
-            console.log('Embeddings not available. Install @huggingface/transformers to enable:');
-            console.log('  npm install @huggingface/transformers');
-        }
-        else {
-            printError(`Embedding provider '${embedProvider.kind}' is configured but ${embedProvider.keyEnv} is not set.`);
-            printError(`Export ${embedProvider.keyEnv}, or set config.embeddings.provider back to 'local'.`);
-            process.exitCode = 1;
-        }
-        return;
+    if (embedProvider.isAvailable())
+        return true;
+    if (loadConfig(root).embeddings.enabled === false) {
+        console.log('Embeddings are disabled in config (embeddings.enabled = false). Set it to true or "auto" to enable.');
+        return false;
     }
-    console.log('Embedding all memories (this may take a moment on first run to download model)...');
-    let count;
-    try {
-        count = await embedAll(root, resolveEmbeddingModel(root));
+    if (embedProvider.kind === 'local') {
+        console.log('Embeddings not available. Install @huggingface/transformers to enable:');
+        console.log('  npm install @huggingface/transformers');
     }
-    catch (err) {
-        printError(`Embedding failed: ${err instanceof Error ? err.message : String(err)}`);
-        const partial = loadEmbeddingIndex(root);
-        printError(`Partial progress saved: ${Object.keys(partial).length} embeddings on disk. Re-run \`hippo embed\` to resume.`);
+    else {
+        printError(`Embedding provider '${embedProvider.kind}' is configured but ${embedProvider.keyEnv} is not set.`);
+        printError(`Export ${embedProvider.keyEnv}, or set config.embeddings.provider back to 'local'.`);
         process.exitCode = 1;
-        return;
     }
-    const entriesAfter = loadAllEntries(root);
-    const embIndexAfter = loadEmbeddingIndex(root);
-    console.log(`Done. ${count} new embeddings created. ${Object.keys(embIndexAfter).length}/${entriesAfter.length} total.`);
+    return false;
 }
 //# sourceMappingURL=maintenance.js.map