hippo-memory 1.69.0 → 1.71.0

package/dist/cli/status.js

@@ -1,48 +1,53 @@
 // Read-only report verbs: status, inspect, tokens, failures, provenance, correction latency, doctor and support bundle.
-import { envHomeDir } from '../env.js';
-import { evalNow } from '../ablation.js';
+import { envHomeDir } from '../util/env.js';
+import { evalNow } from '../core/ablation.js';
 import * as path from 'path';
 import * as fs from 'fs';
 import * as os from 'os';
 import { fileURLToPath } from 'node:url';
-import { calculateStrength, calculateRewardFactor, resolveConfidence, confidenceFacets, Layer } from '../memory.js';
-import { readEntry, loadAllEntries } from '../store/entry-reads.js';
+import { calculateStrength, calculateRewardFactor, resolveConfidence, Layer } from '../core/memory.js';
+import { loadCorrectionEntries, loadRawEntries } from '../store/report-reads.js';
 import { loadStats } from '../store/index-and-stats.js';
-import { listMemoryConflicts } from '../store/conflicts.js';
-import { loadEmbeddingIndex, embeddingModelRequiresReindex } from '../embeddings.js';
-import { resolveEmbeddingProvider } from '../embedding-provider.js';
-import { loadPhysicsState } from '../physics-state.js';
-import { computeSystemEnergy, vecNorm } from '../physics.js';
-import { loadConfig } from '../config.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
+import { loadStatusCounts } from '../store/candidates.js';
+import { embeddingModelRequiresReindex } from '../store/embeddings/index.js';
+import { resolveEmbeddingProvider } from '../store/embeddings/provider.js';
+import { loadStoredParticles, storedVectorSummary } from '../store/vector-index.js';
+import { computeSystemEnergy, vecNorm } from '../core/physics.js';
+import { loadConfig } from '../core/config.js';
 import { runDoctor, formatDoctor } from '../doctor.js';
 import { buildSupportBundle, TAIL_MAX_LINES } from '../support-bundle.js';
-import { PACKAGE_VERSION } from '../version.js';
-import { FAILURE_LOG_RETENTION_DAYS } from '../failure-log.js';
-import { getGlobalRoot } from '../shared.js';
-import { buildProvenanceCoverage } from '../provenance-coverage.js';
-import { buildCorrectionLatency } from '../correction-latency.js';
-import * as api from '../api.js';
-import { resolveTenantId } from '../tenant.js';
+import { PACKAGE_VERSION } from '../util/version.js';
+import { FAILURE_LOG_RETENTION_DAYS } from '../store/failure-log.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
+import { buildProvenanceCoverage } from './provenance-coverage.js';
+import { buildCorrectionLatency } from './correction-latency.js';
+import * as api from '../api/index.js';
+import { getMemory } from '../api/memories.js';
+import { cliApiContext } from './api-context.js';
+import { errorMessage, log } from '../util/log.js';
 import { printError } from './output.js';
-import { parseCountFlag, requireInit, fmt, cardStringFlag, hookStoreRoot, resolveAuthRoot, } from './shared.js';
-export function cmdStatus(hippoRoot) {
+import { parseCountFlag, stringFlagOrExit, flagIsTrue } from './flag-values.js';
+import { requireInit, resolveAuthRoot } from './shared.js';
+import { fmt } from './print.js';
+import { isJsonObject } from '../util/json.js';
+import { hookStoreRoot } from './hook-runtime.js';
+import { DAY_MS } from '../util/time.js';
+import { CliExit } from './exit.js';
+export function handleStatus({ hippoRoot }) {
     requireInit(hippoRoot);
-    const entries = loadAllEntries(hippoRoot);
     const stats = loadStats(hippoRoot);
-    const now = evalNow();
-    const { byLayer, byConfidence, pinned, atRisk, agedOut, avgStrength } = tallyStatus(entries, now);
+    const counts = loadStatusCounts(hippoRoot, evalNow(), 0.2);
+    const { byLayer, byConfidence, pinned, atRisk, agedOut, avgStrength } = counts;
     console.log('Hippo Status');
     console.log('---------------------------');
-    console.log(`Total memories:    ${entries.length}`);
+    console.log(`Total memories:    ${counts.total}`);
     console.log(`  Buffer:          ${byLayer[Layer.Buffer]}`);
     console.log(`  Episodic:        ${byLayer[Layer.Episodic]}`);
     console.log(`  Semantic:        ${byLayer[Layer.Semantic]}`);
     console.log(`  Trace:           ${byLayer[Layer.Trace]}`);
-    const conflictCount = listMemoryConflicts(hippoRoot).length;
     console.log(`Pinned:            ${pinned}`);
     console.log(`At risk (<0.2):    ${atRisk}`);
-    console.log(`Open conflicts:    ${conflictCount}`);
+    console.log(`Open conflicts:    ${counts.openConflicts}`);
     console.log(`Avg strength:      ${fmt(avgStrength)}`);
     console.log('');
     console.log('Confidence breakdown:');
@@ -52,55 +57,22 @@ export function cmdStatus(hippoRoot) {
     console.log(`  Stale:           ${byConfidence['stale'] ?? 0}`);
     console.log(`  Aged out:        ${agedOut}  (of the above; excludes pinned, verified)`);
     console.log('');
-    console.log(`Total remembered:  ${stats['total_remembered'] ?? 0}`);
-    console.log(`Total recalled:    ${stats['total_recalled'] ?? 0}`);
-    console.log(`Total forgotten:   ${stats['total_forgotten'] ?? 0}`);
-    const runs = stats['consolidation_runs'] ?? [];
+    console.log(`Total remembered:  ${stats.total_remembered ?? 0}`);
+    console.log(`Total recalled:    ${stats.total_recalled ?? 0}`);
+    console.log(`Total forgotten:   ${stats.total_forgotten ?? 0}`);
+    const runs = stats.consolidation_runs ?? [];
     if (Array.isArray(runs) && runs.length > 0) {
         const last = runs[runs.length - 1];
-        console.log(`Last sleep:        ${last['timestamp']}`);
+        console.log(`Last sleep:        ${isJsonObject(last) ? last['timestamp'] : undefined}`);
     }
     else {
         console.log(`Last sleep:        never`);
     }
-    printEmbeddingStatus(hippoRoot, entries);
+    printEmbeddingStatus(hippoRoot, counts);
     printPhysicsStatus(hippoRoot);
 }
-function tallyStatus(entries, now) {
-    const byLayer = {
-        [Layer.Buffer]: 0,
-        [Layer.Episodic]: 0,
-        [Layer.Semantic]: 0,
-        [Layer.Trace]: 0,
-    };
-    const byConfidence = {
-        verified: 0,
-        observed: 0,
-        inferred: 0,
-        stale: 0,
-    };
-    let totalStrength = 0;
-    let pinned = 0;
-    let atRisk = 0; // strength < 0.2
-    let agedOut = 0;
-    for (const e of entries) {
-        const s = calculateStrength(e, now);
-        byLayer[e.layer] = (byLayer[e.layer] ?? 0) + 1;
-        totalStrength += s;
-        if (e.pinned)
-            pinned++;
-        if (s < 0.2)
-            atRisk++;
-        const facets = confidenceFacets(e, now);
-        byConfidence[facets.tier] = (byConfidence[facets.tier] ?? 0) + 1;
-        if (facets.agedOut)
-            agedOut++;
-    }
-    const avgStrength = entries.length > 0 ? totalStrength / entries.length : 0;
-    return { byLayer, byConfidence, pinned, atRisk, agedOut, avgStrength };
-}
 // Embedding status (provider-aware)
-function printEmbeddingStatus(hippoRoot, entries) {
+function printEmbeddingStatus(hippoRoot, counts) {
     const embedProvider = (() => {
         try {
             return resolveEmbeddingProvider(hippoRoot);
@@ -131,62 +103,60 @@ function printEmbeddingStatus(hippoRoot, entries) {
     }
     // Show cached counts whenever vectors exist on disk (even when disabled or
     // the key was removed), so the user still sees what is already indexed.
-    const embIndex = loadEmbeddingIndex(hippoRoot);
-    if (!embAvail && Object.keys(embIndex).length === 0)
+    const { ids: embeddedIds, dims } = storedVectorSummary(hippoRoot);
+    if (!embAvail && embeddedIds.size === 0)
         return;
-    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;
-    const dims = Object.values(embIndex)[0]?.length;
-    let line = `Embedded:          ${activeEmbedded}/${entries.length} memories`;
+    const orphaned = embeddedIds.size - counts.embedded;
+    let line = `Embedded:          ${counts.embedded}/${counts.total} memories`;
     if (dims)
         line += ` (${dims}-dim)`;
     if (orphaned > 0)
         line += ` (${orphaned} orphaned, run \`hippo embed\` to prune)`;
     console.log(line);
-    if (embeddingModelRequiresReindex(hippoRoot, embedProvider.id, embIndex)) {
+    // No index argument: the check then asks SQLite whether any vector exists instead of loading them.
+    if (embeddingModelRequiresReindex(hippoRoot, embedProvider.id)) {
         console.log(`                   model changed, run \`hippo embed\` to reindex`);
     }
 }
+// The all-pairs energy sum is quadratic, so a large particle set skips it.
+const PHYSICS_ENERGY_STATUS_MAX = 2000;
 // Physics status
 function printPhysicsStatus(hippoRoot) {
     try {
-        const db = openHippoDb(hippoRoot);
-        try {
-            const physicsMap = loadPhysicsState(db);
-            if (physicsMap.size > 0) {
-                const particles = Array.from(physicsMap.values());
-                const physConfig = loadConfig(hippoRoot);
-                const energy = computeSystemEnergy(particles, physConfig.physics.G_memory);
-                let sumVelMag = 0;
-                for (const p of particles)
-                    sumVelMag += vecNorm(p.velocity);
-                const avgVelMag = sumVelMag / particles.length;
-                console.log('');
-                console.log(`Physics: ${particles.length} particles, energy: ${fmt(energy.total, 4)} (KE: ${fmt(energy.kinetic, 4)}, PE: ${fmt(energy.potential, 4)}), avg vel: ${fmt(avgVelMag, 4)}`);
-            }
-        }
-        finally {
-            closeHippoDb(db);
+        const particles = loadStoredParticles(hippoRoot);
+        if (particles.length > 0) {
+            let sumVelMag = 0;
+            for (const p of particles)
+                sumVelMag += vecNorm(p.velocity);
+            const avgVelMag = sumVelMag / particles.length;
+            console.log('');
+            console.log(`Physics: ${particles.length} particles, ${physicsEnergyText(particles, loadConfig(hippoRoot).physics.G_memory)}, avg vel: ${fmt(avgVelMag, 4)}`);
         }
     }
-    catch {
-        // Physics table may not exist yet — degrade gracefully
+    catch (err) {
+        // The physics table may not exist yet, so status prints without that line.
+        log.debug(`physics status skipped: ${errorMessage(err)}`);
     }
 }
-function cmdInspect(hippoRoot, id) {
+export function physicsEnergyText(particles, gMemory) {
+    if (particles.length > PHYSICS_ENERGY_STATUS_MAX)
+        return `energy: skipped (${particles.length} particles)`;
+    const energy = computeSystemEnergy(particles, gMemory);
+    return `energy: ${fmt(energy.total, 4)} (KE: ${fmt(energy.kinetic, 4)}, PE: ${fmt(energy.potential, 4)})`;
+}
+async function cmdInspect(hippoRoot, tenantId, id) {
     requireInit(hippoRoot);
-    const entry = readEntry(hippoRoot, id, resolveTenantId({}));
+    const entry = await getMemory(cliApiContext(hippoRoot, tenantId), id);
     if (!entry) {
         printError(`Memory not found: ${id}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const now = evalNow();
     const currentStrength = calculateStrength(entry, now);
     const lastRetrieved = new Date(entry.last_retrieved);
     const created = new Date(entry.created);
-    const ageDays = (now.getTime() - created.getTime()) / (1000 * 60 * 60 * 24);
-    const daysSince = (now.getTime() - lastRetrieved.getTime()) / (1000 * 60 * 60 * 24);
+    const ageDays = (now.getTime() - created.getTime()) / DAY_MS;
+    const daysSince = (now.getTime() - lastRetrieved.getTime()) / DAY_MS;
     const effectiveConfidence = resolveConfidence(entry, now);
     console.log(`Memory: ${entry.id}`);
     console.log('---------------------------');
@@ -216,20 +186,11 @@ function cmdInspect(hippoRoot, id) {
     console.log('-'.repeat(40));
     console.log(entry.content);
 }
-/**
- * `hippo tokens [--days <n>] [--json] [--global]`: the token ledger.
- * Tokens of memory text handed to agents per surface, blocks
- * the per-prompt hook skipped as unchanged and the tokens that saved,
- * and the hook blocks' tokens later model calls re-read, counted when each session ends.
- * Counts are estimates (characters / 4), the same estimate every budget uses.
- */
-export function cmdTokens(hippoRoot, flags) {
+/** `hippo tokens [--days <n>] [--json] [--global]`: the token ledger per surface, tokens saved by skipped unchanged blocks, and re-read hook tokens.
+ * Counts are estimates (characters / 4), the same estimate every budget uses. */
+export function handleTokens({ hippoRoot, tenantId, flags }) {
     const root = resolveAuthRoot(hippoRoot, flags);
-    const ctx = {
-        hippoRoot: root,
-        tenantId: resolveTenantId({}),
-        actor: api.adminActor('cli'),
-    };
+    const ctx = cliApiContext(root, tenantId);
     const days = parseCountFlag(flags['days']);
     const summary = api.tokenSummary(ctx, { days: days > 0 ? days : undefined });
     if (flags['json']) {
@@ -259,15 +220,11 @@ export function cmdTokens(hippoRoot, flags) {
     console.log("  Re-reads usually bill at the provider's cached-input rate, a fraction of the full input price.");
 }
 /** `hippo failures [--days <n>] [--json] [--global]`: failed tool calls by outcome, and repeats across sessions. */
-export function cmdFailures(hippoRoot, flags) {
+export function handleFailures({ hippoRoot, tenantId, flags }) {
     // The store the capture-error hook writes to; a report never creates one.
     const root = flags['global'] ? getGlobalRoot() : hookStoreRoot(hippoRoot);
     requireInit(root);
-    const ctx = {
-        hippoRoot: root,
-        tenantId: resolveTenantId({}),
-        actor: api.adminActor('cli'),
-    };
+    const ctx = cliApiContext(root, tenantId);
     const days = parseCountFlag(flags['days']);
     const summary = api.failureSummary(ctx, { days: days > 0 ? days : undefined });
     if (flags['json']) {
@@ -302,8 +259,7 @@ export function cmdFailures(hippoRoot, flags) {
 }
 export function handleCorrectionLatency({ hippoRoot, flags }) {
     requireInit(hippoRoot);
-    const entries = loadAllEntries(hippoRoot);
-    const report = buildCorrectionLatency(entries);
+    const report = buildCorrectionLatency(loadCorrectionEntries(hippoRoot));
     if (flags['json']) {
         console.log(JSON.stringify(report, null, 2));
     }
@@ -332,8 +288,7 @@ export function handleCorrectionLatency({ hippoRoot, flags }) {
 }
 export function handleProvenance({ hippoRoot, flags }) {
     requireInit(hippoRoot);
-    const entries = loadAllEntries(hippoRoot);
-    const coverage = buildProvenanceCoverage(entries);
+    const coverage = buildProvenanceCoverage(loadRawEntries(hippoRoot));
     if (flags['json']) {
         console.log(JSON.stringify(coverage, null, 2));
     }
@@ -351,7 +306,7 @@ export function handleProvenance({ hippoRoot, flags }) {
         }
     }
     if (flags['strict'] && coverage.coverage < 1) {
-        process.exit(1);
+        throw new CliExit(1);
     }
 }
 export function handleDoctor({ flags }) {
@@ -360,15 +315,15 @@ export function handleDoctor({ flags }) {
     const report = runDoctor({ version: pkg.version });
     console.log(flags['json'] ? JSON.stringify(report, null, 2) : formatDoctor(report));
     if (!report.ok)
-        process.exit(1);
+        throw new CliExit(1);
 }
 export function handleSupportBundle({ flags }) {
-    const outFlag = cardStringFlag(flags, 'out');
+    const outFlag = stringFlagOrExit(flags, 'out');
     if (outFlag === '') {
         printError('--out requires a file path.');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const includeLogs = flags['include-logs'] === true;
+    const includeLogs = flagIsTrue(flags, 'include-logs');
     const home = envHomeDir() || os.homedir();
     const now = new Date();
     const bundle = buildSupportBundle({ cwd: process.cwd(), home, version: PACKAGE_VERSION, includeLogs, now });
@@ -383,9 +338,9 @@ export function handleSupportBundle({ flags }) {
             printError(`${file} already exists; pass --out to choose another file. Nothing was written.`);
         }
         else {
-            printError(err instanceof Error ? err.message : String(err));
+            printError(errorMessage(err));
         }
-        process.exit(1);
+        throw new CliExit(1);
     }
     const kb = Math.round(Buffer.byteLength(json) / 1024);
     console.log(`Wrote ${file} (${kb} KB).`);
@@ -393,12 +348,12 @@ export function handleSupportBundle({ flags }) {
         ? `It holds versions, doctor checks, config with secrets removed, store counts, and the last ${TAIL_MAX_LINES} lines of each hippo log with known secret shapes removed. Those log lines can quote memory text. Read it before you attach it to a ticket.`
         : 'It holds versions, doctor checks, config with secrets removed, store counts and log file names. It never holds memory text. Read it before you attach it to a ticket.');
 }
-export function handleInspect({ hippoRoot, args }) {
+export async function handleInspect({ hippoRoot, tenantId, args }) {
     const id = args[0];
     if (!id) {
         printError('Please provide a memory ID.');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    cmdInspect(hippoRoot, id);
+    await cmdInspect(hippoRoot, tenantId, id);
 }
 //# sourceMappingURL=status.js.map

package/dist/{stdin.d.ts → cli/stdin.d.ts}

@@ -1,13 +1,11 @@
-/** `timedOut` means the window closed with stdin still open, so absent
- * `text` is "unknown", not "none", and present `text` may be truncated.
- * Treating absence as a manual run is only safe when it is false. */
+/** `timedOut` means the window closed with stdin still open, so absent `text` is "unknown", not "none", and present `text` may be truncated;
+ * treating absence as a manual run is only safe when it is false. */
 export interface BoundedStdin {
     text?: string;
     timedOut: boolean;
 }
-/** Never blocks: a TTY resolves at once, otherwise waits up to `waitMs` of
- * idle (default 1000ms, or `HIPPO_STDIN_WAIT_MS`), refreshed on each chunk
- * so a slow but real write is not cut off, and capped at `waitMs * 10`. */
+/** Never blocks: a TTY resolves at once, otherwise waits up to `waitMs` of idle (default 1000ms, or `HIPPO_STDIN_WAIT_MS`),
+ * refreshed on each chunk so a slow real write is not cut off, capped at `waitMs * 10`. */
 export declare function readStdinBounded(waitMs?: number): Promise<BoundedStdin>;
 /** A hook payload with Copilot's camelCase fields copied to the snake_case keys hippo reads. The camelCase keys stay,
  * so the sessionStart reply can follow the sender's casing; text that needs no change comes back exactly as sent. */

package/dist/{stdin.js → cli/stdin.js}

@@ -1,12 +1,11 @@
-import { envStdinWaitMs } from './env.js';
-import { isJsonObject } from './hooks/shared.js';
-import { isJsonString } from './json.js';
+import { envStdinWaitMs } from '../util/env.js';
+import { isJsonString, isJsonObjectLiteral } from '../util/json.js';
+const DEFAULT_STDIN_WAIT_MS = 1000;
 function defaultWaitMs() {
-    return envStdinWaitMs() ?? 1000;
+    return envStdinWaitMs() ?? DEFAULT_STDIN_WAIT_MS;
 }
-/** Never blocks: a TTY resolves at once, otherwise waits up to `waitMs` of
- * idle (default 1000ms, or `HIPPO_STDIN_WAIT_MS`), refreshed on each chunk
- * so a slow but real write is not cut off, and capped at `waitMs * 10`. */
+/** Never blocks: a TTY resolves at once, otherwise waits up to `waitMs` of idle (default 1000ms, or `HIPPO_STDIN_WAIT_MS`),
+ * refreshed on each chunk so a slow real write is not cut off, capped at `waitMs * 10`. */
 export function readStdinBounded(waitMs = defaultWaitMs()) {
     let stdin;
     try {
@@ -73,7 +72,7 @@ function snakeCaseFields(payload) {
         added.tool_input = parsedToolArgs(payload.toolArgs);
     const error = payload.error;
     // An error object gives its message, so readers that expect the documented string still get one.
-    if (isJsonObject(error) && isJsonString(error.message))
+    if (isJsonObjectLiteral(error) && isJsonString(error.message))
         added.error = error.message;
     return added;
 }
@@ -91,7 +90,7 @@ export function normaliseHookPayload(text) {
         // Not JSON: each reader already treats that as a malformed payload, so it passes through untouched.
         return text;
     }
-    if (!isJsonObject(payload))
+    if (!isJsonObjectLiteral(payload))
         return text;
     const added = snakeCaseFields(payload);
     return Object.keys(added).length === 0 ? text : JSON.stringify({ ...payload, ...added });

package/dist/cli/transfer.d.ts

@@ -1,10 +1,10 @@
-import { type CommandContext } from './shared.js';
-export declare function cmdLearn(hippoRoot: string, flags: Record<string, string | boolean | string[]>): void;
-export declare function cmdImport(hippoRoot: string, args: string[], flags: Record<string, string | boolean | string[]>): void;
-export declare function cmdSync(hippoRoot: string, flags?: Record<string, string | boolean | string[]>): void;
-export declare function handleWatch({ hippoRoot, args }: CommandContext): Promise<void>;
-export declare function handlePromote({ hippoRoot, args }: CommandContext): Promise<void>;
-export declare function handleShare({ hippoRoot, args, flags }: CommandContext): void;
-export declare function handlePeers({ flags }: CommandContext): void;
-export declare function handleExport({ hippoRoot, args, flags }: CommandContext): void;
+import { type CommandContext } from './flag-values.js';
+export declare function handleLearn({ hippoRoot, flags }: CommandContext): void;
+export declare function handleImport({ hippoRoot, tenantId, args, flags }: CommandContext): void;
+export declare function handleSync({ hippoRoot, flags }: CommandContext): void;
+export declare function handleWatch({ hippoRoot, tenantId, args }: CommandContext): Promise<void>;
+export declare function handlePromote({ hippoRoot, tenantId, args }: CommandContext): Promise<void>;
+export declare function handleShare({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
+export declare function handlePeers({ tenantId, flags }: CommandContext): void;
+export declare function handleExport({ hippoRoot, tenantId, args, flags }: CommandContext): void;
 //# sourceMappingURL=transfer.d.ts.map