hippo-memory 2.0.0 → 2.1.0

package/dist/cli/remember.js

@@ -4,7 +4,7 @@ import { evalNow, strengthAblation } from '../core/ablation.js';
 import * as fs from 'fs';
 import { calculateStrength, calculateRewardFactor, confidenceFacets, confidenceLabel, Layer, } from '../core/memory.js';
 import * as api from '../api/index.js';
-import { getMemory } from '../api/memories.js';
+import { getMemory } from '../api/memories/memories.js';
 import { ConflictError, NotFoundError } from '../core/api-errors.js';
 import { isInitialized } from '../core/project-identity.js';
 import { RejectedValueError } from '../core/api-errors.js';
@@ -20,10 +20,10 @@ import { validateOwner, isStrictOwnerEnv } from './owner-validation.js';
 import { printError } from './output.js';
 import { requireInit, runViaServerIfAvailable } from './shared.js';
 import { fmt } from './print.js';
-import { boolFlag, flagIsTrue, isOneOf, stringFlag, stringListFlag } from './flag-values.js';
+import { boolFlag, flagIsTrue, isOneOf, stringFlag, stringFlagOrExit, stringListFlag, } from './flag-values.js';
 import { DAY_MS } from '../util/time.js';
 import { errorMessage } from '../util/log.js';
-import { CliExit } from './exit.js';
+import { CliExit, fail } from './exit.js';
 const PARENT_PREVIEW_CHARS = 70;
 const DETAIL_CONTENT_CHARS = 160;
 // Shared by the direct write and the routed request so both store the same tags.
@@ -36,7 +36,7 @@ function rememberTags(flags, cwd) {
         if (!all.includes(pt))
             all.push(pt);
     }
-    const explicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
+    const explicitScope = stringFlagOrExit(flags, 'scope') ?? null;
     const activeScope = explicitScope || detectScope();
     if (activeScope) {
         const scopeTag = `scope:${activeScope}`;
@@ -60,12 +60,12 @@ const USER_VISIBLE_KINDS = ['distilled', 'superseded'];
 function parseKindFlag(flags) {
     const kindFlagRaw = stringFlag(flags, 'kind');
     const kindFlag = kindFlagRaw === undefined ? undefined : kindFlagRaw.toLowerCase();
-    // 'raw' is reserved for ingestion connectors (deletions go through archiveRawMemory); the append-only trigger aborts forget/consolidate on raw rows,
-    // so exposing --kind raw would create unforgettable memories. 'archived' is an internal sentinel set only in that transaction.
+    // 'raw' is reserved for ingestion connectors (deletions go through archiveRawMemory); the append-only trigger aborts
+    // forget/consolidate on raw rows, so exposing --kind raw would create unforgettable memories. 'archived' is an
+    // internal sentinel set only in that transaction.
     if (kindFlag !== undefined && !isOneOf(USER_VISIBLE_KINDS, kindFlag)) {
         printError(`Invalid --kind: "${kindFlagRaw}". Must be one of: ${USER_VISIBLE_KINDS.join(', ')}`);
-        printError(`(kind='raw' is reserved for ingestion connectors; kind='archived' is internal.)`);
-        throw new CliExit(1);
+        fail(`(kind='raw' is reserved for ingestion connectors; kind='archived' is internal.)`);
     }
     return kindFlag;
 }
@@ -74,8 +74,7 @@ function parseRememberEnvelope(flags) {
     const ownerRaw = stringFlag(flags, 'owner') ?? null;
     const ownerCheck = validateOwner(ownerRaw, { strict: isStrictOwnerEnv() });
     if (!ownerCheck.ok) {
-        printError(ownerCheck.message);
-        throw new CliExit(1);
+        fail(ownerCheck.message);
     }
     if (ownerCheck.message)
         printError(ownerCheck.message);
@@ -126,7 +125,8 @@ async function cmdRemember(hippoRoot, tenantId, text, flags) {
 function printRemembered(entry, useGlobal) {
     const prefix = useGlobal ? '[global] ' : '';
     console.log(`${prefix}Remembered [${entry.id}]`);
-    console.log(`   Layer: ${entry.layer} | Strength: ${fmt(entry.strength)} | Half-life: ${entry.half_life_days}d | Confidence: ${entry.confidence}`);
+    console.log(`   Layer: ${entry.layer} | Strength: ${fmt(entry.strength)} | Half-life: ${entry.half_life_days}d | ` +
+        `Confidence: ${entry.confidence}`);
     if (entry.tags.length > 0)
         console.log(`   Tags: ${entry.tags.join(', ')}`);
     if (entry.pinned)
@@ -150,7 +150,9 @@ function supersedeTags(flags) {
 /** The api's conflict text differs by which writer lost; the row itself names its successor either way. */
 async function alreadySupersededLine(hippoRoot, oldId, tenantId, conflict) {
     const by = (await getMemory(cliApiContext(hippoRoot, tenantId), oldId))?.superseded_by;
-    return by ? `Error: memory ${oldId} is already superseded by ${by}. Supersede that one instead.` : `Error: ${conflict.message}`;
+    return by
+        ? `Error: memory ${oldId} is already superseded by ${by}. Supersede that one instead.`
+        : `Error: ${conflict.message}`;
 }
 function parseLayerFlag(flags) {
     const raw = stringFlag(flags, 'layer');
@@ -158,8 +160,7 @@ function parseLayerFlag(flags) {
         return undefined;
     const layer = Object.values(Layer).find((l) => l === raw);
     if (layer === undefined) {
-        printError(`Invalid --layer: "${raw}". Must be one of: ${Object.values(Layer).join(', ')}`);
-        throw new CliExit(1);
+        fail(`Invalid --layer: "${raw}". Must be one of: ${Object.values(Layer).join(', ')}`);
     }
     return layer;
 }
@@ -193,34 +194,27 @@ function parseStepsOrExit(stepsJson) {
         return parseSteps(stepsJson);
     }
     catch (err) {
-        printError(errorMessage(err));
-        throw new CliExit(1);
+        fail(errorMessage(err));
     }
 }
 function traceTags(flags) {
-    const rawTags = flags['tag'];
-    return Array.isArray(rawTags)
-        ? rawTags.map((t) => String(t))
-        : rawTags !== undefined
-            ? [String(rawTags)]
-            : [];
+    return stringListFlag(flags, 'tag') ?? [];
 }
 async function cmdTraceRecord(hippoRoot, tenantId, flags) {
     requireInit(hippoRoot);
-    const task = String(flags['task'] ?? '').trim();
-    const stepsJson = String(flags['steps'] ?? '').trim();
-    const outcome = String(flags['outcome'] ?? '').trim();
+    const task = stringFlagOrExit(flags, 'task') ?? '';
+    const stepsJson = stringFlagOrExit(flags, 'steps') ?? '';
+    const outcome = stringFlagOrExit(flags, 'outcome') ?? '';
     const validOutcomes = ['success', 'failure', 'partial'];
     if (!task || !stepsJson || !outcome) {
-        printError('Usage: hippo trace record --task <t> --steps <json> --outcome <success|failure|partial> [--session <id>] [--tag <t>]');
-        throw new CliExit(1);
+        fail('Usage: hippo trace record --task <t> --steps <json> --outcome <success|failure|partial> ' +
+            '[--session <id>] [--tag <t>]');
     }
     if (!isOneOf(validOutcomes, outcome)) {
-        printError(`Invalid outcome: "${outcome}". Must be one of: ${validOutcomes.join(', ')}.`);
-        throw new CliExit(1);
+        fail(`Invalid outcome: "${outcome}". Must be one of: ${validOutcomes.join(', ')}.`);
     }
     const steps = parseStepsOrExit(stepsJson);
-    const sessionId = String(flags['session'] ?? '').trim() || null;
+    const sessionId = stringFlagOrExit(flags, 'session') || null;
     const tags = traceTags(flags);
     const content = renderTraceContent({
         task,
@@ -232,7 +226,7 @@ async function cmdTraceRecord(hippoRoot, tenantId, flags) {
         tags,
         local: {
             layer: Layer.Trace,
-            source: String(flags['source'] ?? 'cli'),
+            source: stringFlagOrExit(flags, 'source') ?? 'cli',
             traceOutcome: outcome,
             sourceSessionId: sessionId,
         },
@@ -251,8 +245,7 @@ async function cmdTrace(hippoRoot, tenantId, id, flags) {
         sourceLabel = 'global';
     }
     if (!entry) {
-        printError(`Memory not found: ${id}`);
-        throw new CliExit(1);
+        fail(`Memory not found: ${id}`);
     }
     const t = {
         entry, id, sourceLabel,
@@ -288,12 +281,15 @@ async function traceLineage(hippoRoot, globalRoot, entry, id, tenantId) {
     for (const pid of parents) {
         const p = (await getMemory(cliApiContext(hippoRoot, tenantId), pid))
             ?? (isInitialized(globalRoot) ? await getMemory(cliApiContext(globalRoot, tenantId), pid) : null);
-        parentPreviews.push({ id: pid, content: p ? p.content.replace(/\s+/g, ' ').slice(0, PARENT_PREVIEW_CHARS) : '(not found)' });
+        parentPreviews.push({
+            id: pid,
+            content: p ? p.content.replace(/\s+/g, ' ').slice(0, PARENT_PREVIEW_CHARS) : '(not found)',
+        });
     }
     // Open conflicts involving this memory.
     const allConflicts = [
-        ...api.listConflicts(cliApiContext(hippoRoot, tenantId), 'open'),
-        ...(isInitialized(globalRoot) ? api.listConflicts(cliApiContext(globalRoot, tenantId), 'open') : []),
+        ...(await api.listConflicts(cliApiContext(hippoRoot, tenantId), 'open')),
+        ...(isInitialized(globalRoot) ? await api.listConflicts(cliApiContext(globalRoot, tenantId), 'open') : []),
     ];
     const myConflicts = allConflicts.filter((c) => c.memory_a_id === id || c.memory_b_id === id);
     return { parentPreviews, myConflicts };
@@ -328,13 +324,16 @@ function printTraceJson(t) {
     }, null, 2));
 }
 function printTraceText(t) {
-    const { entry, id, sourceLabel, conf, ageDays, strength, projectedAt, halfLife, rewardFactor, effHalfLife, sinceLast } = t;
+    const { entry, id, sourceLabel, conf, ageDays, strength, projectedAt } = t;
+    const { halfLife, rewardFactor, effHalfLife, sinceLast } = t;
     const { parentPreviews, myConflicts } = t;
     console.log(`Memory: ${entry.id}  [${sourceLabel}]`);
     console.log('='.repeat(50));
-    console.log(`Content:   ${entry.content.replace(/\s+/g, ' ').slice(0, DETAIL_CONTENT_CHARS)}${entry.content.length > DETAIL_CONTENT_CHARS ? '...' : ''}`);
-    console.log(`Layer:     ${entry.layer.padEnd(10)} Confidence: ${conf.padEnd(14)} Pinned: ${entry.pinned ? 'yes' : 'no'}${entry.starred ? '  Starred: ' +
-        'yes' : ''}`);
+    const ellipsis = entry.content.length > DETAIL_CONTENT_CHARS ? '...' : '';
+    console.log(`Content:   ${entry.content.replace(/\s+/g, ' ').slice(0, DETAIL_CONTENT_CHARS)}${ellipsis}`);
+    const starred = entry.starred ? '  Starred: ' + 'yes' : '';
+    const pinned = entry.pinned ? 'yes' : 'no';
+    console.log(`Layer:     ${entry.layer.padEnd(10)} Confidence: ${conf.padEnd(14)} Pinned: ${pinned}${starred}`);
     console.log(`Tags:      ${entry.tags.join(', ') || '(none)'}`);
     console.log(`Created:   ${entry.created}  (${fmt(ageDays, 1)} days ago)`);
     console.log();
@@ -374,11 +373,11 @@ export async function handleRemember({ hippoRoot, tenantId, args, flags }) {
         text = args.join(' ').trim();
     }
     if (!text || text.length < 3) {
-        printError('Memory content too short (minimum 3 characters).');
-        throw new CliExit(1);
+        fail('Memory content too short (minimum 3 characters).');
     }
-    // Thin-client routing: simple `remember` calls go over HTTP so the daemon stays the single writer; rich flags need the direct path.
-    // The salience gate is not in richFlag and the route does not apply it, so a routed remember stores what a direct one would skip.
+    // Thin-client routing: simple `remember` calls go over HTTP so the daemon stays the single writer; rich flags need
+    // the direct path. The salience gate is not in richFlag and the route does not apply it, so a routed remember stores
+    // what a direct one would skip.
     const richFlag = flags['pin'] || flags['global'] || flags['extract'] || flags['force'] ||
         flags['observed'] || flags['inferred'] || flags['verified'] ||
         flags['layer'] !== undefined;
@@ -395,8 +394,7 @@ async function rememberViaThinClient(hippoRoot, text, flags) {
     const thinOwnerRaw = stringFlag(flags, 'owner');
     const thinOwnerCheck = validateOwner(thinOwnerRaw, { strict: isStrictOwnerEnv() });
     if (!thinOwnerCheck.ok) {
-        printError(thinOwnerCheck.message);
-        throw new CliExit(1);
+        fail(thinOwnerCheck.message);
     }
     if (thinOwnerCheck.message)
         printError(thinOwnerCheck.message);
@@ -419,8 +417,7 @@ export async function handleSupersede({ hippoRoot, tenantId, args, flags }) {
     const oldId = args[0];
     const newContent = args.slice(1).join(' ').trim();
     if (!oldId || !newContent) {
-        printError('Usage: hippo supersede <old-id> "<new content>" [--layer L] [--tag T] [--pin]');
-        throw new CliExit(1);
+        fail('Usage: hippo supersede <old-id> "<new content>" [--layer L] [--tag T] [--pin]');
     }
     await cmdSupersede(hippoRoot, tenantId, oldId, newContent, flags);
 }
@@ -431,8 +428,7 @@ export async function handleTrace({ hippoRoot, tenantId, args, flags }) {
         return;
     }
     if (!sub) {
-        printError('Usage: hippo trace <memory-id> | hippo trace record --task <t> --steps <json> --outcome <o>');
-        throw new CliExit(1);
+        fail('Usage: hippo trace <memory-id> | hippo trace record --task <t> --steps <json> --outcome <o>');
     }
     await cmdTrace(hippoRoot, tenantId, sub, flags);
 }

package/dist/cli/scheduler.d.ts

@@ -13,7 +13,10 @@ export declare function hasUnsafeRunnerPathChars(runnerDir: string, platform: No
 export declare function buildDailyRunnerCommand(projectDir: string, platform?: NodeJS.Platform): string;
 /** What the Windows task runs. A plain `cmd /c` task opens a visible console every morning. */
 export declare function buildWindowsTaskRun(cmd: string): string;
-/** `text` for the inside of one double-quoted Windows argument: a backslash run before a quote or the end doubles, so no quote ends the argument early. */
+/**
+ * `text` for the inside of one double-quoted Windows argument: a backslash run before a quote or the end doubles, so no
+ * quote ends the argument early.
+ */
 export declare function quoteInsideWindowsArg(text: string): string;
 /** Argv for `schtasks`, passed without a shell: through cmd.exe the `&&` in /tr split the command. */
 export declare function buildSchtasksCreateArgs(taskName: string, cmd: string): string[];

package/dist/cli/scheduler.js

@@ -1,6 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { errorMessage, log } from '../util/log.js';
+import { errorMessage, log, errorFields } from '../util/log.js';
 import { writeFileAtomic } from '../util/atomic-write.js';
 export const DAILY_TASK_NAME = 'hippo-daily-runner';
 function defaultRegistry() {
@@ -24,7 +24,7 @@ export function loadWorkspaceRegistry(globalRoot) {
         text = fs.readFileSync(registryPath, 'utf8');
     }
     catch (err) {
-        log.warn(`workspace registry ${registryPath} could not be read (${errorMessage(err)}); starting with no workspaces`);
+        log.warn(`workspace registry ${registryPath} could not be read (${errorMessage(err)}); starting with no workspaces`, errorFields(err));
         return defaultRegistry();
     }
     try {
@@ -51,8 +51,9 @@ function setAsideCorruptRegistry(registryPath, err) {
         log.warn(`workspace registry ${registryPath} is corrupt (${reason}); moved it to ${aside} and starting with no workspaces`);
     }
     catch (renameErr) {
-        log.warn(`workspace registry ${registryPath} is corrupt (${reason}) and could not be moved aside (${errorMessage(renameErr)}); ` +
-            `starting with no workspaces`);
+        log.warn(`workspace registry ${registryPath} is corrupt (${reason}) and could not be moved aside ` +
+            `(${errorMessage(renameErr)}); ` +
+            `starting with no workspaces`, errorFields(renameErr));
     }
 }
 export function saveWorkspaceRegistry(globalRoot, registry) {
@@ -89,7 +90,10 @@ export function buildDailyRunnerCommand(projectDir, platform = process.platform)
 export function buildWindowsTaskRun(cmd) {
     return `conhost.exe --headless cmd /c ${cmd}`;
 }
-/** `text` for the inside of one double-quoted Windows argument: a backslash run before a quote or the end doubles, so no quote ends the argument early. */
+/**
+ * `text` for the inside of one double-quoted Windows argument: a backslash run before a quote or the end doubles, so no
+ * quote ends the argument early.
+ */
 export function quoteInsideWindowsArg(text) {
     return text.replace(/(\\*)"/g, '$1$1\\"').replace(/\\+$/, '$&$&');
 }

package/dist/cli/serve.js

@@ -1,20 +1,21 @@
 // Long-running verbs: `hippo dashboard`, `hippo mcp` and `hippo serve`.
 import { installCrashHandlers } from '../util/crash-handlers.js';
-import { envAllowKeylessLocal, envKeylessLocalRole, envPort, envRequireAuth, envTlsCert, envTlsKey } from '../util/env.js';
+import { envAllowKeylessLocal, envKeylessLocalRole, envPort, envRequireAuth, envTlsCert, envTlsKey, } from '../util/env.js';
 import * as fs from 'fs';
 import * as path from 'path';
-import { printError } from './output.js';
 import { flagIsTrue, stringFlagOrExit, stringFlag, numberFlag } from './flag-values.js';
 import { requireInit } from './shared.js';
 import { errorMessage } from '../util/log.js';
-import { CliExit } from './exit.js';
+import { fail } from './exit.js';
+import { cliStdioHost } from './api-context.js';
 import { DEFAULT_DASHBOARD_PORT, DEFAULT_SERVER_HOST, DEFAULT_SERVER_PORT } from '../server/defaults.js';
 export async function handleDashboard({ hippoRoot, flags }) {
     requireInit(hippoRoot);
     const port = numberFlag(flags, 'port') ?? DEFAULT_DASHBOARD_PORT;
     const { serveDashboard } = await import('../dashboard/dashboard.js');
     serveDashboard(hippoRoot, port, undefined, { handleSignals: true });
-    // A later throw ends in one log line and exit 1, as it does for serve and mcp; a busy port is reported by the dashboard itself.
+    // A later throw ends in one log line and exit 1, as it does for serve and mcp; a busy port is reported by the
+    // dashboard itself.
     installCrashHandlers('dashboard');
     await new Promise(() => { }); // run until Ctrl+C
 }
@@ -24,11 +25,12 @@ export async function handleMcp() {
     // stdio loop here. (HTTP/SSE transport is wired in src/server.ts and
     // imports the same module without triggering stdin handlers.)
     const mod = await import('../mcp/server.js');
-    mod.startStdioLoop();
+    mod.startStdioLoop(cliStdioHost);
     // Server runs until stdin closes, so we never reach here
     await new Promise(() => { }); // hang forever
 }
-/** The certificate and key for HTTPS, from --tls-cert and --tls-key or HIPPO_TLS_CERT and HIPPO_TLS_KEY; undefined when neither is set. */
+/** The certificate and key for HTTPS, from --tls-cert and --tls-key or HIPPO_TLS_CERT and HIPPO_TLS_KEY; undefined when
+ * neither is set. */
 function readTlsFiles(flags) {
     // A flag with no value exits here; falling back to cleartext would hide the mistake.
     const certPath = stringFlagOrExit(flags, 'tls-cert') ?? envTlsCert();
@@ -36,37 +38,40 @@ function readTlsFiles(flags) {
     if (certPath === undefined && keyPath === undefined)
         return undefined;
     if (certPath === undefined || keyPath === undefined) {
-        printError('hippo serve: TLS needs both a certificate and a key: --tls-cert and --tls-key, or HIPPO_TLS_CERT and HIPPO_TLS_KEY.');
-        throw new CliExit(1);
+        fail('hippo serve: TLS needs both a certificate and a key: --tls-cert and --tls-key, ' +
+            'or HIPPO_TLS_CERT and HIPPO_TLS_KEY.');
     }
     try {
         return { cert: fs.readFileSync(certPath), key: fs.readFileSync(keyPath) };
     }
     catch (err) {
-        printError(`hippo serve: cannot read the TLS files: ${errorMessage(err)}`);
-        throw new CliExit(1);
+        fail(`hippo serve: cannot read the TLS files: ${errorMessage(err)}`);
     }
 }
-/** Said at every start, so the key rule is a choice an operator sees, and an upgrade that changed it explains itself. */
+/** Said at every start, so the key rule is a choice an operator sees, and an upgrade that changed it explains
+ * itself. */
 function keyRuleLine() {
     if (envRequireAuth())
         return 'every request needs an API key (HIPPO_REQUIRE_AUTH=1)';
     if (envAllowKeylessLocal()) {
         const role = envKeylessLocalRole() === 'admin'
             ? 'act as host admin (HIPPO_ALLOW_KEYLESS_LOCAL=1, HIPPO_KEYLESS_LOCAL_ROLE=admin)'
-            : 'act as a member (HIPPO_ALLOW_KEYLESS_LOCAL=1; HIPPO_KEYLESS_LOCAL_ROLE=admin opens sleep and the quarantine routes)';
-        return `requests from this machine need no API key and ${role}; unset HIPPO_ALLOW_KEYLESS_LOCAL to require a key on every request`;
+            : 'act as a member (HIPPO_ALLOW_KEYLESS_LOCAL=1; ' +
+                'HIPPO_KEYLESS_LOCAL_ROLE=admin opens sleep and the quarantine routes)';
+        return `requests from this machine need no API key and ${role}; ` +
+            'unset HIPPO_ALLOW_KEYLESS_LOCAL to require a key on every request';
     }
-    return 'every request needs an API key: mint one with `hippo auth create` and send it as "Authorization: Bearer <key>" ' +
-        '(the hippo CLI reads HIPPO_API_KEY). To let requests from this machine in without a key, start with HIPPO_ALLOW_KEYLESS_LOCAL=1';
+    return 'every request needs an API key: mint one with `hippo auth create` and send it as ' +
+        '"Authorization: Bearer <key>" ' +
+        '(the hippo CLI reads HIPPO_API_KEY). To let requests from this machine in without a key, ' +
+        'start with HIPPO_ALLOW_KEYLESS_LOCAL=1';
 }
 export async function handleServe({ hippoRoot, flags }) {
     requireInit(hippoRoot);
     const portRaw = flags['port'] ?? envPort() ?? DEFAULT_SERVER_PORT;
     const port = Number(portRaw);
     if (!Number.isFinite(port) || port < 0) {
-        printError(`Invalid --port: ${String(portRaw)}`);
-        throw new CliExit(1);
+        fail(`Invalid --port: ${String(portRaw)}`);
     }
     const host = stringFlag(flags, 'host') ?? DEFAULT_SERVER_HOST;
     const tls = readTlsFiles(flags);

package/dist/cli/session-hooks.d.ts

@@ -1,6 +1,6 @@
 import { type CliFlags, type CommandContext } from './flag-values.js';
-/** SessionEnd entry: TUI teardown kills children still running, so read stdin inline, spawn a detached child that runs sleep then capture, and exit.
- * The child logs to a file that the next SessionStart reads via `hippo last-sleep`. */
+/** SessionEnd entry: TUI teardown kills children still running, so read stdin inline, spawn a detached child that runs
+ * sleep then capture, and exit. The child logs to a file that the next SessionStart reads via `hippo last-sleep`. */
 export declare function handleSessionEnd({ hippoRoot, tenantId, flags }: CommandContext): Promise<void>;
 export declare function handleSessionEndWorker({ hippoRoot, tenantId, flags }: CommandContext): Promise<void>;
 export declare function handleCodexRun({ hippoRoot, tenantId, args }: CommandContext): void;