hippo-memory 1.19.0 → 1.21.0

package/dist/src/cli.js

@@ -66,6 +66,7 @@ import * as skillsModule from './skills.js';
 import * as briefsModule from './project-briefs.js';
 import * as customerNotesModule from './customer-notes.js';
 import { extractGraph } from './graph-extract.js';
+import { buildGraphModel, renderGraphHtml, renderGraphCanvas, DEFAULT_VIEW_LIMIT } from './graph-view.js';
 import { createHash } from 'node:crypto';
 import { detectAnchoring, hashQueryText, buildSessionKey, getOrCreateRing, appendRecall, snapshotRing, } from './recall-history.js';
 import { detectAvailabilityBias } from './availability.js';
@@ -100,6 +101,7 @@ import { refineStore } from './refine-llm.js';
 import { wmPush, wmRead, wmClear, wmFlush } from './working-memory.js';
 import { multihopSearch } from './multihop.js';
 import { graphExpandRecall, MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from './graph-recall.js';
+import { DEFAULT_GRAPH_STREAM_WEIGHT } from './graph-stream.js';
 import { getReranker } from './rerankers/index.js';
 import { computeSalience } from './salience.js';
 import { computeAmbientState, renderAmbientSummary } from './ambient.js';
@@ -779,8 +781,59 @@ async function cmdRecall(hippoRoot, query, flags) {
     const recallExplicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
     const recallActiveScope = recallExplicitScope || detectScope();
     const useMultihop = flags['multihop'] === true || config.multihop.enabled;
+    // L1 — graph-retrieval stream. `--graph-stream` forces rrf fusion + the graph stream
+    // (see src/graph-stream.ts). NOTE: it implies `scoring:'rrf'` (production default is
+    // 'blend'), so the flag bundles two behaviours by design. CLI surface is local-store
+    // only for now; the library API supports a globalRoot for callers who need it.
+    const useGraphStream = flags['graph-stream'] === true;
+    let graphStreamHops;
+    if (useGraphStream && flags['graph-hops'] !== undefined) {
+        if (typeof flags['graph-hops'] === 'boolean') {
+            console.error(`--graph-hops requires an integer value 1..${MAX_HOPS} (e.g. --graph-hops 2).`);
+            process.exit(1);
+        }
+        const h = Number(flags['graph-hops']);
+        if (!Number.isInteger(h) || h < 1 || h > MAX_HOPS) {
+            console.error(`Invalid --graph-hops: "${String(flags['graph-hops'])}". Must be an integer 1..${MAX_HOPS}.`);
+            process.exit(1);
+        }
+        graphStreamHops = h;
+    }
+    let graphStreamSeeds;
+    if (useGraphStream && flags['graph-seeds'] !== undefined) {
+        if (typeof flags['graph-seeds'] === 'boolean') {
+            console.error('--graph-seeds requires a positive integer value (e.g. --graph-seeds 10).');
+            process.exit(1);
+        }
+        const s = Number(flags['graph-seeds']);
+        if (!Number.isInteger(s) || s < 1) {
+            console.error(`Invalid --graph-seeds: "${String(flags['graph-seeds'])}". Must be a positive integer.`);
+            process.exit(1);
+        }
+        graphStreamSeeds = s;
+    }
     let results;
-    if (useMultihop) {
+    if (useGraphStream) {
+        if (!isEmbeddingAvailable()) {
+            // The graph stream fuses inside the rrf path, which only runs with embeddings; without
+            // them hybridSearch falls back to BM25-only and the stream is inert. Say so plainly
+            // rather than silently no-op.
+            console.error('[note] --graph-stream needs embeddings (rrf fusion); none available, so the graph stream is inert. Run `hippo embed` first.');
+        }
+        if (hasGlobal) {
+            console.error('[note] --graph-stream searches the local store only; global graph fusion is a follow-up.');
+        }
+        // The stream anchors on the top-`seedCount` lexical hits and re-ranks the rank>seedCount
+        // tail; on a pool with <= seedCount candidates EVERY candidate is a seed and the stream
+        // is inert (it degrades to the 2-list fusion). Tune the anchor count with --graph-seeds.
+        results = await hybridSearch(query, localEntries, {
+            budget, hippoRoot, mmr: mmrEnabled, mmrLambda, minResults, scope: recallActiveScope,
+            includeSuperseded, asOf,
+            scoring: 'rrf',
+            graphStream: { weight: DEFAULT_GRAPH_STREAM_WEIGHT, tenantId, hops: graphStreamHops, seedCount: graphStreamSeeds },
+        });
+    }
+    else if (useMultihop) {
         const allEntries = [...localEntries, ...globalEntries];
         results = multihopSearch(query, allEntries, {
             budget,
@@ -4522,7 +4575,7 @@ function noteUsage() {
     console.error('       hippo note supersede <id> --text "<note>" [--change "<summary>"]');
     console.error('       hippo note close <id>');
 }
-function cmdGraph(hippoRoot, args, _flags) {
+function cmdGraph(hippoRoot, args, flags) {
     requireInit(hippoRoot);
     const tenantId = resolveTenantId({});
     const subcommand = args[0] ?? '';
@@ -4538,7 +4591,75 @@ function cmdGraph(hippoRoot, args, _flags) {
         }
         return;
     }
-    console.error('Usage: hippo graph extract   (rebuild the entity/relation graph from consolidated decisions/policies/customer-notes/project-briefs)');
+    const entity = typeof flags['entity'] === 'string' ? flags['entity'] : undefined;
+    if (subcommand === 'show') {
+        const model = buildGraphModel(hippoRoot, tenantId, { entity, limit: DEFAULT_VIEW_LIMIT });
+        if (flags['json']) {
+            console.log(JSON.stringify(model, null, 2));
+            return;
+        }
+        if (model.nodes.length === 0) {
+            console.log(entity ? `No entity named "${entity}".` : 'Graph is empty. Run `hippo graph extract` first.');
+            return;
+        }
+        console.log(`Graph: ${model.nodes.length} entities, ${model.edges.length} relations${model.truncated ? ' (truncated)' : ''}`);
+        const byType = new Map();
+        for (const n of model.nodes) {
+            const arr = byType.get(n.type) ?? [];
+            arr.push({ id: n.id, name: n.name });
+            byType.set(n.type, arr);
+        }
+        for (const [type, ns] of byType) {
+            console.log(`\n${type} (${ns.length}):`);
+            for (const n of ns)
+                console.log(`  [${n.id}] ${n.name}`);
+        }
+        if (model.edges.length > 0) {
+            const nameById = new Map(model.nodes.map((n) => [n.id, n.name]));
+            console.log('\nrelations:');
+            for (const e of model.edges) {
+                console.log(`  ${nameById.get(e.from)} --${e.relType}--> ${nameById.get(e.to)}`);
+            }
+        }
+        return;
+    }
+    if (subcommand === 'view') {
+        const format = typeof flags['format'] === 'string' ? flags['format'] : 'html';
+        if (format !== 'html' && format !== 'canvas') {
+            console.error("graph view: --format must be 'html' or 'canvas'");
+            process.exit(1);
+        }
+        const model = buildGraphModel(hippoRoot, tenantId, { entity, limit: DEFAULT_VIEW_LIMIT });
+        const content = format === 'canvas' ? renderGraphCanvas(model) : renderGraphHtml(model);
+        const defaultOut = format === 'canvas' ? 'hippo-graph.canvas' : 'hippo-graph.html';
+        const out = typeof flags['out'] === 'string' ? flags['out'] : defaultOut;
+        fs.writeFileSync(out, content, 'utf8');
+        console.log(`Wrote ${model.nodes.length} entities + ${model.edges.length} relations to ${out}${model.truncated ? ' (truncated)' : ''}`);
+        if (flags['open'] && format === 'html') {
+            // Best-effort browser launch; never fail the command if it doesn't work.
+            try {
+                const [cmd, cmdArgs] = process.platform === 'win32'
+                    ? ['cmd', ['/c', 'start', '', out]]
+                    : process.platform === 'darwin'
+                        ? ['open', [out]]
+                        : ['xdg-open', [out]];
+                const child = spawn(cmd, cmdArgs, { detached: true, stdio: 'ignore' });
+                // A missing launcher (e.g. xdg-open absent) emits 'error' asynchronously;
+                // an unhandled 'error' event would throw, so swallow it — the file is
+                // already written and its path printed above.
+                child.on('error', () => { });
+                child.unref();
+            }
+            catch {
+                /* ignore — the file is written; the path is printed above */
+            }
+        }
+        return;
+    }
+    console.error('Usage:\n' +
+        '  hippo graph extract                     Rebuild the entity/relation graph from consolidated objects\n' +
+        '  hippo graph show [--entity NAME] [--json]   Inspect entities + their edges (text or JSON)\n' +
+        '  hippo graph view [--out FILE] [--open] [--format html|canvas] [--entity NAME]   Generate an interactive node-link diagram');
     process.exit(1);
 }
 function cmdCustomerNote(hippoRoot, args, flags) {
@@ -6675,6 +6796,15 @@ Commands:
                            graph holds supersedes edges (E3.1); cross-object edges
                            light up the same traversal once extracted.
     --max-neighbors <n>    Per-hop fanout cap for --hops (1..200, default 25).
+    --graph-stream         L1: fuse a graph-retrieval stream into RRF, re-ranking
+                           in-pool results by graph proximity to the strong lexical
+                           seeds. Implies rrf scoring (default is blend). Local store
+                           only. Distinct from --hops (which injects out-of-pool
+                           neighbours); this re-ranks within the candidate pool.
+    --graph-hops <n>       Hops for --graph-stream (1..3, default 2).
+    --graph-seeds <n>      Lexical anchors for --graph-stream (default 10). The stream
+                           re-ranks the rank>seeds tail; on a pool with <= n candidates
+                           every candidate is a seed and the stream is inert.
     --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