hippo-memory 1.68.0 → 1.70.0

package/dist/{refine-llm.js → cli/refine-llm.js}

@@ -12,13 +12,18 @@
  * - Uses fetch directly so no SDK dependency.
  * - On failure (API error, bad response), the original memory is untouched.
  */
-import { Layer } from './memory.js';
-import { writeEntry } from './store/entry-writes.js';
-import { loadAllEntries, readEntry } from './store/entry-reads.js';
-import { redactSecretsStrict } from './secret-detect.js';
-import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
-import { log } from './log.js';
+import { Layer } from '../core/memory.js';
+import { writeEntry } from '../store/entry-writes.js';
+import { loadAllEntries, readEntry } from '../store/entry-reads.js';
+import { redactSecretsStrict } from '../util/secret-detect.js';
+import { sendAnthropicMessage } from '../util/anthropic-messages.js';
+import { log } from '../util/log.js';
+const MAX_REFINE_SOURCES = 8;
+const REFINE_SOURCE_CHARS = 400;
 const REFINED_TAG = 'llm-refined';
+// Output budget for one refined memory, and the shortest reply kept as a refinement.
+const REFINE_MAX_TOKENS = 800;
+const REFINE_MIN_CHARS = 10;
 const CONSOLIDATED_MARKERS = [
     '[Consolidated from',
     '[Consolidated pattern from',
@@ -29,11 +34,9 @@ const CONSOLIDATED_MARKERS = [
  * `null` when the API call failed.
  */
 export async function refineSemanticMemory(merged, sources, opts) {
-    const model = opts.model ?? 'claude-sonnet-4-6';
-    const fetchFn = opts.fetcher ?? fetch;
     const sourceBlock = sources
-        .slice(0, 8)
-        .map((s, i) => `[source ${i + 1}] ${redactSecretsStrict(s.content).slice(0, 400)}`)
+        .slice(0, MAX_REFINE_SOURCES)
+        .map((s, i) => `[source ${i + 1}] ${redactSecretsStrict(s.content).slice(0, REFINE_SOURCE_CHARS)}`)
         .join('\n\n');
     const prompt = `You are refining a semantic memory in an agent's memory store. The rule-based consolidator merged several related episodic memories into one, but the output is clumsy. Produce a single coherent semantic memory that captures the underlying principle.
 
@@ -49,47 +52,29 @@ ${redactSecretsStrict(merged)}
 
 Source memories (up to 8 shown):
 ${sourceBlock}`;
-    let res;
-    try {
-        res = await fetchWithRetry('https://api.anthropic.com/v1/messages', {
-            method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                'x-api-key': opts.apiKey,
-                'anthropic-version': '2023-06-01',
-            },
-            body: JSON.stringify({
-                model,
-                max_tokens: 800,
-                messages: [{ role: 'user', content: prompt }],
-            }),
-        }, { timeoutMs: llmTimeoutMs(), fetchFn });
-    }
-    catch (err) {
-        log.warn(`refine: request failed: ${err instanceof Error ? err.message : String(err)}`);
-        return null;
-    }
-    if (!res.ok) {
-        log.warn(`refine: API answered HTTP ${res.status}`);
-        return null;
-    }
-    let text;
-    try {
-        // SAFETY: data is the Anthropic Messages API response body; the
-        // documented response shape is `{ content: [{ type, text, ... }] }`
-        // for a text-generating request like this one.
-        const data = await res.json();
-        text = data.content?.[0]?.text?.trim() ?? '';
-    }
-    catch (err) {
-        log.warn(`refine: unreadable response: ${err instanceof Error ? err.message : String(err)}`);
+    const reply = await sendAnthropicMessage({
+        apiKey: opts.apiKey,
+        model: opts.model,
+        maxTokens: REFINE_MAX_TOKENS,
+        prompt,
+        fetcher: opts.fetcher,
+    });
+    if (!reply.ok) {
+        log.warn(describeRefineFailure(reply.failure));
         return null;
     }
-    if (text.length < 10) {
+    if (reply.text.length < REFINE_MIN_CHARS) {
         log.warn('refine: response was empty or too short to use');
         return null;
     }
-    return text;
+    return reply.text;
+}
+function describeRefineFailure(failure) {
+    switch (failure.kind) {
+        case 'request': return `refine: request failed: ${failure.message}`;
+        case 'http': return `refine: API answered HTTP ${failure.status}`;
+        case 'unreadable': return `refine: unreadable response: ${failure.message}`;
+    }
 }
 function isConsolidated(entry) {
     if (entry.layer !== Layer.Semantic)
@@ -125,43 +110,46 @@ export async function refineStore(hippoRoot, opts) {
         if (opts.limit !== undefined && processed >= opts.limit)
             break;
         processed++;
-        // Best-effort: walk parents_json (schema v9) to fetch originals. When
-        // parents aren't recorded we still refine using just the merged content.
-        const sources = [];
-        const parentIds = Array.isArray(entry.parents) ? entry.parents : [];
-        for (const pid of parentIds) {
-            // Parent lookup scoped by opts.tenantId when provided.
-            // Cross-tenant parents return null and are silently skipped — refine
-            // still produces output from the merged content alone (graceful
-            // degradation rather than refuse-to-refine).
-            const p = readEntry(hippoRoot, pid, opts.tenantId);
-            if (p)
-                sources.push(p);
-        }
-        const refined = await refineSemanticMemory(entry.content, sources, {
-            apiKey: opts.apiKey,
-            model: opts.model,
-            fetcher: opts.fetcher,
-        });
-        if (refined === null) {
-            result.failed++;
-            result.details.push({ id: entry.id, status: 'failed', reason: 'api error or empty response' });
-            continue;
-        }
-        if (opts.dryRun) {
-            result.refined++;
-            result.details.push({ id: entry.id, status: 'refined', reason: 'dry-run (no write)' });
-            continue;
-        }
-        const updated = {
-            ...entry,
-            content: refined,
-            tags: entry.tags.includes(REFINED_TAG) ? entry.tags : [...entry.tags, REFINED_TAG],
-        };
-        writeEntry(hippoRoot, updated);
-        result.refined++;
-        result.details.push({ id: entry.id, status: 'refined' });
+        await refineOneEntry(hippoRoot, entry, opts, result);
     }
     return result;
 }
+async function refineOneEntry(hippoRoot, entry, opts, result) {
+    // Best-effort: walk parents_json (schema v9) to fetch originals. When
+    // parents aren't recorded we still refine using just the merged content.
+    const sources = [];
+    const parentIds = Array.isArray(entry.parents) ? entry.parents : [];
+    for (const pid of parentIds) {
+        // Parent lookup scoped by opts.tenantId when provided.
+        // Cross-tenant parents return null and are silently skipped — refine
+        // still produces output from the merged content alone (graceful
+        // degradation rather than refuse-to-refine).
+        const p = readEntry(hippoRoot, pid, opts.tenantId);
+        if (p)
+            sources.push(p);
+    }
+    const refined = await refineSemanticMemory(entry.content, sources, {
+        apiKey: opts.apiKey,
+        model: opts.model,
+        fetcher: opts.fetcher,
+    });
+    if (refined === null) {
+        result.failed++;
+        result.details.push({ id: entry.id, status: 'failed', reason: 'api error or empty response' });
+        return;
+    }
+    if (opts.dryRun) {
+        result.refined++;
+        result.details.push({ id: entry.id, status: 'refined', reason: 'dry-run (no write)' });
+        return;
+    }
+    const updated = {
+        ...entry,
+        content: refined,
+        tags: entry.tags.includes(REFINED_TAG) ? entry.tags : [...entry.tags, REFINED_TAG],
+    };
+    writeEntry(hippoRoot, updated);
+    result.refined++;
+    result.details.push({ id: entry.id, status: 'refined' });
+}
 //# sourceMappingURL=refine-llm.js.map

package/dist/cli/remember.d.ts

@@ -1,6 +1,4 @@
-import { type CommandContext } from './shared.js';
-/** @internal Exported so tests/remember-origin-parity.test.ts runs the real direct write; not a stable public API. */
-export declare function cmdRemember(hippoRoot: string, text: string, flags: Record<string, string | boolean | string[]>): Promise<void>;
+import { type CommandContext } from './flag-values.js';
 export declare function handleRemember({ hippoRoot, args, flags }: CommandContext): Promise<void>;
 export declare function handleSupersede({ hippoRoot, args, flags }: CommandContext): void;
 export declare function handleTrace({ hippoRoot, args, flags }: CommandContext): void;

package/dist/cli/remember.js

@@ -1,28 +1,35 @@
 // The write verbs: `hippo remember`, `hippo supersede` and `hippo trace`.
-import { envAnthropicApiKey } from '../env.js';
-import { evalNow } from '../ablation.js';
+import { envAnthropicApiKey } from '../util/env.js';
+import { evalNow } from '../core/ablation.js';
 import * as fs from 'fs';
-import { createMemory, createSuccessor, calculateStrength, calculateRewardFactor, confidenceFacets, confidenceLabel, computeSchemaFit, Layer, } from '../memory.js';
+import { createMemory, createSuccessor, calculateStrength, calculateRewardFactor, confidenceFacets, confidenceLabel, Layer, } from '../core/memory.js';
 import { isInitialized } from '../store/open.js';
 import { writeEntry } from '../store/entry-writes.js';
 import { readEntry, loadAllEntries } from '../store/entry-reads.js';
+import { loadNewestEntries, schemaFitInStore } from '../store/candidates.js';
 import { updateStats } from '../store/index-and-stats.js';
 import { listMemoryConflicts } from '../store/conflicts.js';
-import { RejectedValueError } from '../rejection.js';
-import { renderTraceContent, parseSteps } from '../trace.js';
-import { embedMemory } from '../embeddings.js';
-import { loadConfig } from '../config.js';
-import { extractPathTags } from '../path-context.js';
-import { detectScope } from '../scope.js';
-import { assertClientScope } from '../recall-scope.js';
-import { getGlobalRoot, initGlobal } from '../shared.js';
-import { vetSecrets } from '../secret-detect.js';
-import * as client from '../client.js';
-import { resolveTenantId } from '../tenant.js';
-import { computeSalience } from '../salience.js';
-import { validateOwner, isStrictOwnerEnv } from '../owner-validation.js';
+import { RejectedValueError } from '../store/rejection.js';
+import { renderTraceContent, parseSteps } from '../consolidate/trace.js';
+import { embedMemory } from '../store/embeddings/index.js';
+import { loadConfig } from '../core/config.js';
+import { extractPathTags } from '../search/path-context.js';
+import { detectScope } from '../sharing/scope.js';
+import { assertClientScope } from '../store/recall-scope.js';
+import { getGlobalRoot, initGlobal } from '../sharing/shared.js';
+import { vetSecrets } from '../util/secret-detect.js';
+import * as client from './client.js';
+import { resolveTenantId } from '../store/tenant.js';
+import { computeSalience } from '../core/salience.js';
+import { validateOwner, isStrictOwnerEnv } from './owner-validation.js';
 import { printError } from './output.js';
-import { emitCliAudit, requireInit, runViaServerIfAvailable, fmt } from './shared.js';
+import { emitCliAudit, requireInit, runViaServerIfAvailable } from './shared.js';
+import { fmt } from './print.js';
+import { boolFlag, flagIsTrue, stringFlag } from './flag-values.js';
+import { DAY_MS } from '../util/time.js';
+import { errorMessage } from '../util/log.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.
 function rememberTags(flags, cwd) {
     const requested = Array.isArray(flags['tag']) ? [...flags['tag']] : [];
@@ -54,7 +61,7 @@ function rememberConfidence(flags) {
     return confidence;
 }
 function parseKindFlag(flags) {
-    const kindFlagRaw = typeof flags['kind'] === 'string' ? flags['kind'] : undefined;
+    const kindFlagRaw = stringFlag(flags, 'kind');
     const kindFlag = kindFlagRaw === undefined ? undefined : kindFlagRaw.toLowerCase();
     // CLI surface intentionally restricted: 'raw' is reserved for ingestion connectors
     // that route deletions through archiveRawMemory. Existing
@@ -71,7 +78,7 @@ function parseKindFlag(flags) {
 }
 function parseRememberEnvelope(flags) {
     const kind = parseKindFlag(flags);
-    const ownerRaw = typeof flags['owner'] === 'string' ? flags['owner'] : null;
+    const ownerRaw = stringFlag(flags, 'owner') ?? null;
     const ownerCheck = validateOwner(ownerRaw, { strict: isStrictOwnerEnv() });
     if (!ownerCheck.ok) {
         printError(ownerCheck.message);
@@ -80,14 +87,13 @@ function parseRememberEnvelope(flags) {
     if (ownerCheck.message)
         printError(ownerCheck.message);
     const owner = ownerCheck.value ?? null;
-    const artifactRef = typeof flags['artifact-ref'] === 'string' ? flags['artifact-ref'] : null;
-    const scope = typeof flags['scope'] === 'string' ? flags['scope'].trim() || null : null;
+    const artifactRef = stringFlag(flags, 'artifact-ref') ?? null;
+    const scope = stringFlag(flags, 'scope')?.trim() || null;
     assertClientScope(scope);
     return { kind, owner, artifactRef, scope };
 }
-/** @internal Exported so tests/remember-origin-parity.test.ts runs the real direct write; not a stable public API. */
-export async function cmdRemember(hippoRoot, text, flags) {
-    const useGlobal = Boolean(flags['global']);
+async function cmdRemember(hippoRoot, text, flags) {
+    const useGlobal = boolFlag(flags, 'global');
     const targetRoot = useGlobal ? getGlobalRoot() : hippoRoot;
     if (useGlobal) {
         initGlobal();
@@ -98,8 +104,7 @@ export async function cmdRemember(hippoRoot, text, flags) {
     const { requested: requestedTags, all: allTags } = rememberTags(flags, process.cwd());
     const confidence = rememberConfidence(flags);
     // Schema fit needs the store, which the routed request has no access to, so it stays here.
-    const existing = loadAllEntries(targetRoot, resolveTenantId({}));
-    const schemaFit = computeSchemaFit(text, requestedTags, existing);
+    const schemaFit = schemaFitInStore(targetRoot, resolveTenantId({}), text, requestedTags);
     const envelope = parseRememberEnvelope(flags);
     // Stamp tenant_id from env (HIPPO_TENANT) so recall isolation can filter on this row; unauthenticated CLI gets 'default'.
     const tenantId = resolveTenantId({});
@@ -107,7 +112,7 @@ export async function cmdRemember(hippoRoot, text, flags) {
     const entry = createMemory(text, {
         layer: Layer.Episodic,
         tags: allTags,
-        pinned: Boolean(flags['pin']),
+        pinned: boolFlag(flags, 'pin'),
         source: useGlobal ? 'cli-global' : 'cli',
         confidence,
         schema_fit: schemaFit,
@@ -118,7 +123,7 @@ export async function cmdRemember(hippoRoot, text, flags) {
         tenantId,
         baseHalfLifeDays: rememberConfig.defaultHalfLifeDays,
     });
-    if (!passesSalienceGate(entry, text, existing, rememberConfig, flags))
+    if (!passesSalienceGate(entry, text, targetRoot, rememberConfig, flags))
         return;
     writeEntry(targetRoot, entry);
     updateStats(targetRoot, { remembered: 1 });
@@ -127,10 +132,15 @@ export async function cmdRemember(hippoRoot, text, flags) {
     await extractRememberFacts(targetRoot, entry, flags);
 }
 /** False when the gate skips the write; a start_weak verdict weakens `entry` in place. */
-function passesSalienceGate(entry, text, existing, rememberConfig, flags) {
-    if (!rememberConfig.salience.enabled || Boolean(flags['pin']) || Boolean(flags['force']))
+function passesSalienceGate(entry, text, targetRoot, rememberConfig, flags) {
+    if (!rememberConfig.salience.enabled || boolFlag(flags, 'pin') || boolFlag(flags, 'force'))
         return true;
-    const salienceResult = computeSalience(text, entry.tags, existing, {
+    // computeSalience compares against the last `recentWindow` rows only; below 1 its slice takes every row, so that case still loads them all.
+    const window = Math.trunc(rememberConfig.salience.recentWindow);
+    const recent = Number.isSafeInteger(window) && window >= 1
+        ? loadNewestEntries(targetRoot, entry.tenantId, window)
+        : loadAllEntries(targetRoot, entry.tenantId);
+    const salienceResult = computeSalience(text, entry.tags, recent, {
         recentWindow: rememberConfig.salience.recentWindow,
         overlapThreshold: rememberConfig.salience.overlapThreshold,
         minContentLength: rememberConfig.salience.minContentLength,
@@ -164,7 +174,7 @@ async function extractRememberFacts(targetRoot, entry, flags) {
     const apiKey = envAnthropicApiKey() ?? '';
     if (shouldExtract && apiKey) {
         try {
-            const { extractFacts, storeExtractedFacts } = await import('../extract.js');
+            const { extractFacts, storeExtractedFacts } = await import('../learn/extract.js');
             const facts = await extractFacts(entry.content, {
                 apiKey,
                 model: config.extraction.model,
@@ -177,13 +187,33 @@ async function extractRememberFacts(targetRoot, entry, flags) {
         }
         catch (err) {
             // Extraction is best-effort: report it, never block remember.
-            printError(`  (extraction failed: ${err instanceof Error ? err.message : String(err)})`);
+            printError(`  (extraction failed: ${errorMessage(err)})`);
         }
     }
     else if (shouldExtract && !apiKey) {
         printError('  (extraction skipped: ANTHROPIC_API_KEY not set)');
     }
 }
+function supersedeTags(flags) {
+    const rawTags = flags['tag'];
+    return Array.isArray(rawTags)
+        ? rawTags.map((t) => String(t))
+        : typeof rawTags === 'string'
+            ? rawTags.split(',').map((t) => t.trim()).filter(Boolean)
+            : undefined;
+}
+function writeSuccessor(hippoRoot, newEntry) {
+    try {
+        writeEntry(hippoRoot, newEntry);
+    }
+    catch (err) {
+        if (err instanceof RejectedValueError) {
+            printError(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        throw err;
+    }
+}
 function cmdSupersede(hippoRoot, oldId, newContent, flags) {
     requireInit(hippoRoot);
     const old = readEntry(hippoRoot, oldId, resolveTenantId({}));
@@ -195,14 +225,9 @@ function cmdSupersede(hippoRoot, oldId, newContent, flags) {
         printError(`Error: memory ${oldId} is already superseded by ${old.superseded_by}. Supersede that one instead.`);
         process.exit(1);
     }
-    const layer = typeof flags['layer'] === 'string' ? flags['layer'] : undefined;
-    const rawTags = flags['tag'];
-    const tags = Array.isArray(rawTags)
-        ? rawTags.map((t) => String(t))
-        : typeof rawTags === 'string'
-            ? rawTags.split(',').map((t) => t.trim()).filter(Boolean)
-            : undefined;
-    const pinned = flags['pin'] === true || old.pinned;
+    const layer = stringFlag(flags, 'layer');
+    const tags = supersedeTags(flags);
+    const pinned = flagIsTrue(flags, 'pin') || old.pinned;
     const newEntry = createSuccessor(old, newContent, {
         tenantId: old.tenantId,
         baseHalfLifeDays: loadConfig(hippoRoot).defaultHalfLifeDays,
@@ -212,21 +237,29 @@ function cmdSupersede(hippoRoot, oldId, newContent, flags) {
     });
     // Write the SUCCESSOR first: a rejection-guard refusal then mutates nothing, and an old-row failure leaves an
     // orphan successor rather than a dangling pointer. Unlike api.supersede this path is two non-atomic writes.
-    try {
-        writeEntry(hippoRoot, newEntry);
-    }
-    catch (err) {
-        if (err instanceof RejectedValueError) {
-            printError(`Error: ${err.message}`);
-            process.exit(1);
-        }
-        throw err;
-    }
+    writeSuccessor(hippoRoot, newEntry);
     old.superseded_by = newEntry.id;
     writeEntry(hippoRoot, old);
     emitCliAudit(hippoRoot, 'supersede', oldId, { newId: newEntry.id });
     console.log(`Superseded ${oldId} → ${newEntry.id}`);
 }
+function parseStepsOrExit(stepsJson) {
+    try {
+        return parseSteps(stepsJson);
+    }
+    catch (err) {
+        printError(errorMessage(err));
+        process.exit(1);
+    }
+}
+function traceTags(flags) {
+    const rawTags = flags['tag'];
+    return Array.isArray(rawTags)
+        ? rawTags.map((t) => String(t))
+        : rawTags !== undefined
+            ? [String(rawTags)]
+            : [];
+}
 function cmdTraceRecord(hippoRoot, flags) {
     requireInit(hippoRoot);
     const task = String(flags['task'] ?? '').trim();
@@ -241,21 +274,9 @@ function cmdTraceRecord(hippoRoot, flags) {
         printError(`Invalid outcome: "${outcome}". Must be one of: ${validOutcomes.join(', ')}.`);
         process.exit(1);
     }
-    let steps;
-    try {
-        steps = parseSteps(stepsJson);
-    }
-    catch (err) {
-        printError(String(err instanceof Error ? err.message : err));
-        process.exit(1);
-    }
+    const steps = parseStepsOrExit(stepsJson);
     const sessionId = String(flags['session'] ?? '').trim() || null;
-    const rawTags = flags['tag'];
-    const tags = Array.isArray(rawTags)
-        ? rawTags.map((t) => String(t))
-        : rawTags !== undefined
-            ? [String(rawTags)]
-            : [];
+    const tags = traceTags(flags);
     const content = renderTraceContent({
         task,
         steps,
@@ -275,7 +296,7 @@ function cmdTraceRecord(hippoRoot, flags) {
 }
 function cmdTrace(hippoRoot, id, flags) {
     requireInit(hippoRoot);
-    const asJson = Boolean(flags['json']);
+    const asJson = boolFlag(flags, 'json');
     const tenantId = resolveTenantId({});
     // Look in local store first, then global.
     let entry = readEntry(hippoRoot, id, tenantId);
@@ -307,13 +328,13 @@ function traceStats(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 ageDays = (now.getTime() - createdMs) / DAY_MS;
     const lastMs = new Date(entry.last_retrieved).getTime();
-    const sinceLast = (now.getTime() - lastMs) / 86_400_000;
+    const sinceLast = (now.getTime() - lastMs) / DAY_MS;
     const facets = confidenceFacets(entry, now);
     const conf = confidenceLabel(entry, now).text;
     // Projected strength: same decay curve, just push `now` out.
-    const projectedAt = (days) => calculateStrength(entry, new Date(now.getTime() + days * 86_400_000));
+    const projectedAt = (days) => calculateStrength(entry, new Date(now.getTime() + days * DAY_MS));
     return { strength, halfLife, rewardFactor, effHalfLife, ageDays, sinceLast, facets, conf, projectedAt };
 }
 function traceLineage(hippoRoot, globalRoot, entry, id, tenantId) {
@@ -321,7 +342,7 @@ function traceLineage(hippoRoot, globalRoot, entry, id, tenantId) {
     const parents = Array.isArray(entry.parents) ? entry.parents : [];
     const parentPreviews = parents.map((pid) => {
         const p = readEntry(hippoRoot, pid, tenantId) ?? (isInitialized(globalRoot) ? readEntry(globalRoot, pid, tenantId) : null);
-        return { id: pid, content: p ? p.content.replace(/\s+/g, ' ').slice(0, 70) : '(not found)' };
+        return { id: pid, content: p ? p.content.replace(/\s+/g, ' ').slice(0, PARENT_PREVIEW_CHARS) : '(not found)' };
     });
     // Open conflicts involving this memory.
     const allConflicts = [
@@ -365,7 +386,7 @@ function printTraceText(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, 160)}${entry.content.length > 160 ? '...' : ''}`);
+    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' : ''}`);
     console.log(`Tags:      ${entry.tags.join(', ') || '(none)'}`);
     console.log(`Created:   ${entry.created}  (${fmt(ageDays, 1)} days ago)`);
@@ -418,40 +439,40 @@ export async function handleRemember({ hippoRoot, args, flags }) {
     const richFlag = flags['pin'] || flags['global'] || flags['extract'] || flags['force'] ||
         flags['observed'] || flags['inferred'] || flags['verified'] ||
         flags['layer'] !== undefined;
-    if (!richFlag) {
-        const rememberKindRaw = typeof flags['kind'] === 'string' ? flags['kind'].toLowerCase() : undefined;
-        const rememberKindAllowed = ['distilled', 'superseded'];
-        if (rememberKindRaw === undefined || rememberKindAllowed.includes(rememberKindRaw)) {
-            const tags = rememberTags(flags, process.cwd()).all;
-            // Validate --owner on the thin-client path too, so validation is the same whether or not a server is up.
-            const thinOwnerRaw = typeof flags['owner'] === 'string' ? flags['owner'] : undefined;
-            const thinOwnerCheck = validateOwner(thinOwnerRaw, { strict: isStrictOwnerEnv() });
-            if (!thinOwnerCheck.ok) {
-                printError(thinOwnerCheck.message);
-                process.exit(1);
-            }
-            if (thinOwnerCheck.message)
-                printError(thinOwnerCheck.message);
-            const remembered = await runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
-                const result = await client.remember(info.url, apiKey, {
-                    content: text,
-                    kind: rememberKindRaw,
-                    scope: typeof flags['scope'] === 'string' ? flags['scope'] : undefined,
-                    owner: thinOwnerCheck.value,
-                    artifactRef: typeof flags['artifact-ref'] === 'string' ? flags['artifact-ref'] : undefined,
-                    tags,
-                });
-                console.log(`Remembered [${result.id}] (via ${info.url})`);
-                console.log(`   Kind: ${result.kind} | Tenant: ${result.tenantId}`);
-                for (const w of result.warnings ?? [])
-                    printError(`Warning: ${w}`);
-            });
-            if (remembered)
-                return;
-        }
-    }
+    if (!richFlag && await rememberViaThinClient(hippoRoot, text, flags))
+        return;
     await cmdRemember(hippoRoot, text, flags);
 }
+async function rememberViaThinClient(hippoRoot, text, flags) {
+    const rememberKindRaw = stringFlag(flags, 'kind')?.toLowerCase();
+    const rememberKindAllowed = ['distilled', 'superseded'];
+    if (rememberKindRaw !== undefined && !rememberKindAllowed.includes(rememberKindRaw))
+        return false;
+    const tags = rememberTags(flags, process.cwd()).all;
+    // Validate --owner on the thin-client path too, so validation is the same whether or not a server is up.
+    const thinOwnerRaw = stringFlag(flags, 'owner');
+    const thinOwnerCheck = validateOwner(thinOwnerRaw, { strict: isStrictOwnerEnv() });
+    if (!thinOwnerCheck.ok) {
+        printError(thinOwnerCheck.message);
+        process.exit(1);
+    }
+    if (thinOwnerCheck.message)
+        printError(thinOwnerCheck.message);
+    return runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
+        const result = await client.remember(info.url, apiKey, {
+            content: text,
+            kind: rememberKindRaw,
+            scope: stringFlag(flags, 'scope'),
+            owner: thinOwnerCheck.value,
+            artifactRef: stringFlag(flags, 'artifact-ref'),
+            tags,
+        });
+        console.log(`Remembered [${result.id}] (via ${info.url})`);
+        console.log(`   Kind: ${result.kind} | Tenant: ${result.tenantId}`);
+        for (const w of result.warnings ?? [])
+            printError(`Warning: ${w}`);
+    });
+}
 export function handleSupersede({ hippoRoot, args, flags }) {
     const oldId = args[0];
     const newContent = args.slice(1).join(' ').trim();

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

@@ -15,7 +15,7 @@ export interface SchedulerFsDeps {
     existsSync: typeof fs.existsSync;
     readFileSync: typeof fs.readFileSync;
     mkdirSync: typeof fs.mkdirSync;
-    writeFileSync: typeof fs.writeFileSync;
+    writeFile: (file: string, text: string) => void;
     renameSync: typeof fs.renameSync;
 }
 /** Test-only override. Not part of this module's public API surface. */
@@ -28,6 +28,8 @@ export declare function listRegisteredWorkspaces(globalRoot: string): string[];
 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. */
+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[];
 export declare function runDailyMaintenance(workspaces: readonly string[], runCommand: (cwd: string, args: string[]) => void): void;

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

@@ -1,12 +1,14 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { log } from './log.js';
+import { errorMessage, log } from '../util/log.js';
+import { writeFileAtomic } from '../util/atomic-write.js';
 export const DAILY_TASK_NAME = 'hippo-daily-runner';
 let fsDeps = {
     existsSync: fs.existsSync,
     readFileSync: fs.readFileSync,
     mkdirSync: fs.mkdirSync,
-    writeFileSync: fs.writeFileSync,
+    // One rename, so a crash mid-save cannot leave a truncated registry that reads as corrupt.
+    writeFile: writeFileAtomic,
     renameSync: fs.renameSync,
 };
 /** Test-only override. Not part of this module's public API surface. */
@@ -34,7 +36,7 @@ export function loadWorkspaceRegistry(globalRoot) {
         text = fsDeps.readFileSync(registryPath, 'utf8');
     }
     catch (err) {
-        log.warn(`workspace registry ${registryPath} could not be read (${err instanceof Error ? err.message : String(err)}); starting with no workspaces`);
+        log.warn(`workspace registry ${registryPath} could not be read (${errorMessage(err)}); starting with no workspaces`);
         return defaultRegistry();
     }
     try {
@@ -54,22 +56,22 @@ export function loadWorkspaceRegistry(globalRoot) {
     }
 }
 function setAsideCorruptRegistry(registryPath, err) {
-    const reason = err instanceof Error ? err.message : String(err);
+    const reason = errorMessage(err);
     const aside = `${registryPath}.corrupt-${new Date().toISOString().replace(/[:.]/g, '-')}`;
     try {
         fsDeps.renameSync(registryPath, aside);
         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 (${renameErr instanceof Error ? renameErr.message : String(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`);
     }
 }
 export function saveWorkspaceRegistry(globalRoot, registry) {
     fsDeps.mkdirSync(globalRoot, { recursive: true, mode: 0o700 });
-    fsDeps.writeFileSync(workspaceRegistryPath(globalRoot), JSON.stringify({
+    fsDeps.writeFile(workspaceRegistryPath(globalRoot), JSON.stringify({
         version: 1,
         workspaces: [...new Set(registry.workspaces.map(normalizeWorkspace))].sort(),
-    }, null, 2) + '\n', 'utf8');
+    }, null, 2) + '\n');
 }
 export function registerWorkspace(globalRoot, projectDir) {
     const registry = loadWorkspaceRegistry(globalRoot);
@@ -92,6 +94,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. */
+export function quoteInsideWindowsArg(text) {
+    return text.replace(/(\\*)"/g, '$1$1\\"').replace(/\\+$/, '$&$&');
+}
 /** Argv for `schtasks`, passed without a shell: through cmd.exe the `&&` in /tr split the command. */
 export function buildSchtasksCreateArgs(taskName, cmd) {
     return ['/create', '/tn', taskName, '/tr', buildWindowsTaskRun(cmd), '/sc', 'daily', '/st', '06:15', '/f'];

package/dist/cli/serve.d.ts

@@ -1,4 +1,4 @@
-import { type CommandContext } from './shared.js';
+import { type CommandContext } from './flag-values.js';
 export declare function handleDashboard({ hippoRoot, flags }: CommandContext): Promise<void>;
 export declare function handleMcp(): Promise<void>;
 export declare function handleServe({ hippoRoot, flags }: CommandContext): Promise<void>;