hippo-memory 1.70.0 → 1.72.0

package/dist/cli/init.js

@@ -8,18 +8,23 @@ import { writeFileAtomic } from '../util/atomic-write.js';
 import { isCodexPresent } from '../hooks/shared.js';
 import { isCodexWrapperInstalled } from '../hooks/codex-wrapper.js';
 import { installOpencodePlugin } from '../hooks/opencode.js';
-import { isInitialized, initStore } from '../store/open.js';
-import { loadAllEntries } from '../store/entry-reads.js';
+import { initMemoryStore } from '../api/store-init.js';
+import { isInitialized } from '../core/project-identity.js';
+import { listMemories } from '../api/memories.js';
+import { cliApiContext } from './api-context.js';
 import { isGitRepo } from '../learn/autolearn.js';
 import { currentMachine, importForStore, importProjectMemories, importUserMemories } from '../agent-memories/sync.js';
 import { emptyReport, mergeReports } from '../agent-memories/report.js';
-import { getGlobalRoot, initGlobal } from '../sharing/shared.js';
+import { getGlobalRoot, initGlobal } from '../sharing/global-store.js';
 import { registerWorkspace } from './scheduler.js';
-import { stringFlag } from './flag-values.js';
+import { numberFlag, stringFlag } from './flag-values.js';
 import { printAgentImport } from './print.js';
+import { errorCode, errorMessage, log } from '../util/log.js';
 import { installCodexMemoryHooks, setupDailySchedule, warnClaudeSettingsUnusable } from './install-steps.js';
 import { learnFromRepo, skipLearnOnSharedStore } from './shared.js';
 import { HOOK_MARKERS, HOOKS, hippoBlock } from '../hooks/hook-blocks.js';
+// An unreadable or vanished folder is expected while scanning; any other failure is worth a line.
+const QUIET_SCAN_ERRORS = new Set(['EACCES', 'EPERM', 'ENOENT', 'ENOTDIR']);
 function scanForGitRepos(rootDir, maxDepth = 2) {
     const repos = [];
     function walk(dir, depth) {
@@ -40,7 +45,11 @@ function scanForGitRepos(rootDir, maxDepth = 2) {
                     walk(full, depth + 1);
             }
         }
-        catch { /* permission denied, etc */ }
+        catch (err) {
+            const code = errorCode(err);
+            if (!QUIET_SCAN_ERRORS.has(code))
+                log.warn(`repo scan skipped ${dir}`, { code: code || 'unknown', reason: errorMessage(err) });
+        }
     }
     // Check if rootDir itself is a git repo
     if (fs.existsSync(path.join(rootDir, '.git')))
@@ -49,22 +58,22 @@ function scanForGitRepos(rootDir, maxDepth = 2) {
     return repos;
 }
 /** Creates the repo's store when absent and registers it; returns whether it already existed. */
-function initScannedRepo(repo, globalRoot) {
+function initScannedRepo(repo, tenantId, globalRoot) {
     const repoHippo = path.join(repo, '.hippo');
     const alreadyExists = isInitialized(repoHippo);
     if (!alreadyExists) {
-        initStore(repoHippo);
+        initMemoryStore(cliApiContext(repoHippo, tenantId));
     }
     registerWorkspace(globalRoot, repo);
     return alreadyExists;
 }
 /** Seeds one scanned repo from git history and its agents' notes, unless --no-learn. */
-function learnScannedRepo(repo, seedDays, learn, machine, agentImport) {
+function learnScannedRepo(repo, tenantId, seedDays, learn, machine, agentImport) {
     const repoHippo = path.join(repo, '.hippo');
     let added = 0;
     let lowInfo = 0;
     if (learn && isGitRepo(repo)) {
-        const result = learnFromRepo(repoHippo, repo, seedDays, path.basename(repo));
+        const result = learnFromRepo(repoHippo, tenantId, repo, seedDays, path.basename(repo));
         added = result.added;
         lowInfo = result.lowInfo;
     }
@@ -93,7 +102,7 @@ function printScanSummary(repoCount, totalLessons, totalLowInfo) {
         (totalLowInfo > 0 ? `, ${totalLowInfo} low-information subject(s) dropped` : '') +
         '.');
 }
-function cmdInitScan(scanDir, flags) {
+function cmdInitScan(scanDir, tenantId, flags) {
     const resolved = path.resolve(scanDir);
     console.log(`Scanning ${resolved} for git repositories...\n`);
     const repos = scanForGitRepos(resolved);
@@ -104,22 +113,19 @@ function cmdInitScan(scanDir, flags) {
     console.log(`Found ${repos.length} repositories:\n`);
     const globalRoot = initGlobalFirst();
     let totalLessons = 0;
-    // Rolled up so the cross-repo summary reports the gate too. Each repo
-    // already prints its own count inside learnFromRepo, but the aggregate
-    // line showed only what was ADDED - and the point of this change is
-    // that a dropped subject is never invisible.
+    // Rolled up so the cross-repo summary reports the gate too: a dropped subject is never invisible.
     let totalLowInfo = 0;
-    const seedDays = parseInt(String(flags['days'] ?? '365'), 10);
+    const seedDays = numberFlag(flags, 'days') ?? 365;
     const machine = currentMachine();
     const agentImport = emptyReport();
     const learn = !flags['no-learn'];
     for (const repo of repos) {
-        const alreadyExists = initScannedRepo(repo, globalRoot);
-        const { added, lowInfo } = learnScannedRepo(repo, seedDays, learn, machine, agentImport);
+        const alreadyExists = initScannedRepo(repo, tenantId, globalRoot);
+        const { added, lowInfo } = learnScannedRepo(repo, tenantId, seedDays, learn, machine, agentImport);
         totalLessons += added;
         totalLowInfo += lowInfo;
         const status = alreadyExists ? 'existing' : 'new';
-        const entries = loadAllEntries(path.join(repo, '.hippo'));
+        const entries = listMemories(cliApiContext(path.join(repo, '.hippo'), tenantId), { everyTenant: true });
         console.log(`  ${path.basename(repo).padEnd(25)} ${status.padEnd(10)} ${entries.length} memories${added > 0 ? ` (+${added} from git)` : ''}`);
     }
     printScanSummary(repos.length, totalLessons, totalLowInfo);
@@ -147,12 +153,12 @@ function initGlobalOnly(flags) {
     if (!flags['no-learn'])
         printAgentImport(importUserMemories(globalRoot, { machine: currentMachine() }));
 }
-function seedFromGitHistory(hippoRoot) {
+function seedFromGitHistory(hippoRoot, tenantId) {
     if (!isGitRepo(process.cwd()))
         return;
     const seedDays = 30;
     console.log(`\n   Seeding memories from last ${seedDays} days of git history...`);
-    const { added, skipped } = learnFromRepo(hippoRoot, process.cwd(), seedDays);
+    const { added, skipped } = learnFromRepo(hippoRoot, tenantId, process.cwd(), seedDays);
     if (added > 0) {
         console.log(`   Learned ${added} lessons from git (${skipped} duplicates skipped).`);
     }
@@ -160,11 +166,11 @@ function seedFromGitHistory(hippoRoot) {
         console.log(`   No matching commits found in git history.`);
     }
 }
-export function cmdInit(hippoRoot, flags) {
+export function handleInit({ hippoRoot, tenantId, flags }) {
     // Handle --scan mode
     if (flags['scan']) {
         const scanDir = stringFlag(flags, 'scan') ?? os.homedir();
-        cmdInitScan(scanDir, flags);
+        cmdInitScan(scanDir, tenantId, flags);
         return;
     }
     if (flags['global']) {
@@ -176,7 +182,7 @@ export function cmdInit(hippoRoot, flags) {
         console.log('Already initialized at', hippoRoot);
     }
     else {
-        initStore(hippoRoot);
+        initMemoryStore(cliApiContext(hippoRoot, tenantId));
         console.log('Initialized Hippo at', hippoRoot);
         console.log('   Directories: buffer/ episodic/ semantic/ conflicts/');
         console.log('   Files: hippo.db stats.json');
@@ -193,7 +199,7 @@ export function cmdInit(hippoRoot, flags) {
     const learn = !flags['no-learn'] && !skipLearnOnSharedStore(hippoRoot);
     // Seed with git history on first init (unless --no-learn)
     if (!alreadyExists && learn && !flags['global'])
-        seedFromGitHistory(hippoRoot);
+        seedFromGitHistory(hippoRoot, tenantId);
     // Every run, not only the first: an agent's notes change between inits.
     if (learn)
         printAgentImport(importForStore(hippoRoot, { machine: currentMachine() }));
@@ -304,9 +310,7 @@ function installClaudeCodeSettingsHooks(hook) {
     }
 }
 function installOpencodeUserPlugin() {
-    // opencode uses a TS plugin, not Claude Code's JSON-hook schema.
-    // See OPENCODE_PLUGIN_SOURCE in src/hooks.ts for the plugin file
-    // content + design rationale.
+    // opencode uses a TS plugin, not Claude Code's JSON-hook schema (see OPENCODE_PLUGIN_SOURCE in src/hooks/opencode.ts).
     const result = installOpencodePlugin();
     if (result.installed) {
         console.log(`   Auto-installed hippo opencode plugin -> ${result.pluginPath}`);
@@ -328,9 +332,8 @@ function installUserLevelHooks(agents, codexHint) {
         // Checked first so init never creates ~/.codex on a machine without Codex.
         if (hook === 'codex' && isCodexPresent())
             installCodexMemoryHooks('   ');
-        // For Claude Code, also install SessionEnd+SessionStart entries in its
-        // settings.json. Keeps `hippo init` in lockstep with `hippo hook install
-        // claude-code` and `hippo setup`.
+        // For Claude Code, also install SessionEnd+SessionStart entries in settings.json, keeping `hippo init` in lockstep with
+        // `hippo hook install claude-code` and `hippo setup`.
         if (hook === 'claude-code')
             installClaudeCodeSettingsHooks(hook);
         else if (hook === 'opencode')

package/dist/cli/install-steps.d.ts

@@ -1,7 +1,8 @@
 import { type InstallResult } from '../hooks/json-hooks.js';
 /** Adds hippo's two Codex hooks and says what changed; each install ends on the trust reminder, since Codex skips an untrusted hook. */
 export declare function installCodexMemoryHooks(indent: string): void;
-/** The one line init, hook install, hook uninstall and setup print when Claude Code's settings.json is not JSON hippo can edit and so was left unchanged; true when it printed. */
+/** The one line init, hook install, hook uninstall and setup print when Claude Code's settings.json is not JSON hippo can edit and so was
+ * left unchanged; true when it printed. */
 export declare function warnClaudeSettingsUnusable(result: Pick<InstallResult, 'settingsPath' | 'invalidJson'>, indent: string, action?: 'install' | 'uninstall'): boolean;
 export declare function setupDailySchedule(globalRoot: string): void;
 //# sourceMappingURL=install-steps.d.ts.map

package/dist/cli/install-steps.js

@@ -3,7 +3,8 @@ import * as path from 'path';
 import { execFileSync, execSync } from 'child_process';
 import { installJsonHooks } from '../hooks/json-hooks.js';
 import { CODEX_TRUST_LINE } from '../hooks/shared.js';
-import { DAILY_TASK_NAME, buildDailyRunnerCommand, buildSchtasksCreateArgs, buildWindowsTaskRun, quoteInsideWindowsArg } from './scheduler.js';
+import { envSkipSchedule } from '../util/env.js';
+import { DAILY_TASK_NAME, buildDailyRunnerCommand, hasUnsafeRunnerPathChars, buildSchtasksCreateArgs, buildWindowsTaskRun, quoteInsideWindowsArg, } from './scheduler.js';
 /** Adds hippo's two Codex hooks and says what changed; each install ends on the trust reminder, since Codex skips an untrusted hook. */
 export function installCodexMemoryHooks(indent) {
     const result = installJsonHooks('codex');
@@ -20,20 +21,16 @@ export function installCodexMemoryHooks(indent) {
         : `${indent}hippo's Codex memory hooks already in ${result.settingsPath}`);
     console.log(`${indent}${CODEX_TRUST_LINE}`);
 }
-/** The one line init, hook install, hook uninstall and setup print when Claude Code's settings.json is not JSON hippo can edit and so was left unchanged; true when it printed. */
+/** The one line init, hook install, hook uninstall and setup print when Claude Code's settings.json is not JSON hippo can edit and so was
+ * left unchanged; true when it printed. */
 export function warnClaudeSettingsUnusable(result, indent, action = 'install') {
     if (!result.invalidJson)
         return false;
-    console.log(`${indent}WARNING: ${result.settingsPath} is not a JSON object hippo can merge into, so it was left unchanged; fix it, then run \`hippo hook ${action} claude-code\`.`);
+    console.log(`${indent}WARNING: ${result.settingsPath} is not a JSON object hippo can merge into, so it was left unchanged; ` +
+        `fix it, then run \`hippo hook ${action} claude-code\`.`);
     return true;
 }
-/**
- * Set up a machine-level daily runner that sweeps all registered Hippo
- * workspaces.
- * Linux/macOS: writes to user crontab.
- * Windows: creates a scheduled task.
- * Skips if already installed.
- */
+/** Machine-level daily runner sweeping all registered workspaces: user crontab on Linux/macOS, a scheduled task on Windows; skips if installed. */
 /** Bound on each schtasks and crontab call, so a scheduler that never answers cannot hang `hippo init` or `hippo setup`. */
 const SCHEDULER_CALL_TIMEOUT_MS = 30_000;
 /** Node kills a child at its timeout and reports ETIMEDOUT; every other failure here means the scheduler refused or is missing. */
@@ -44,11 +41,13 @@ function warnSchedulerTimedOut(command) {
     console.log(`   ${command} did not answer within ${SCHEDULER_CALL_TIMEOUT_MS / 1000} s and was stopped, so the daily runner is not scheduled.`);
 }
 export function setupDailySchedule(globalRoot) {
+    // Checked here, not per caller, so init, init --scan and setup all honour it.
+    if (envSkipSchedule()) {
+        console.log('   HIPPO_SKIP_SCHEDULE=1, so the machine-level daily runner was not scheduled.');
+        return;
+    }
     const runnerDir = path.resolve(globalRoot);
-    // Reject paths with characters that could break shell/crontab quoting
-    // (backslash is normal on Windows, only dangerous in Unix shell/crontab)
-    const unsafeChars = process.platform === 'win32' ? /["`$%\n\r]/ : /["`$\n\r\\]/;
-    if (unsafeChars.test(runnerDir)) {
+    if (hasUnsafeRunnerPathChars(runnerDir, process.platform)) {
         console.log(`   Skipping schedule: runner path contains unsafe characters.`);
         return;
     }

package/dist/cli/last-sleep.d.ts

@@ -1,7 +1,8 @@
-import { type CliFlags } from './flag-values.js';
+import { type CliFlags, type CommandContext } from './flag-values.js';
 /** The line the user sees when the last sleep failed, a spool step hit an unexpected error, or the spool holds `.bad` files; null when none did. */
 export declare function sleepProblems(logText: string, bad: number): string | null;
 /** Prints the SessionEnd sleep log on stderr, then clears it. In a hook, stdout carries only `systemMessage`,
  *  because Claude Code shows that to the user and adds any other SessionStart stdout to the model's context. */
 export declare function cmdLastSleep(hippoRoot: string, flags: CliFlags, out?: 'hook' | 'terminal'): void;
+export declare function handleLastSleep({ hippoRoot, flags }: CommandContext): void;
 //# sourceMappingURL=last-sleep.d.ts.map

package/dist/cli/last-sleep.js

@@ -1,7 +1,7 @@
 // `hippo last-sleep`: the previous session's sleep log for the debug log, and one problems line for the user.
 import * as fs from 'fs';
 import { isStringValue } from '../core/capture-contract.js';
-import { REPLAY_AFTER_MS } from '../capture/compaction-record.js';
+import { REPLAY_AFTER_MS } from '../core/compaction-timing.js';
 import { SPOOL_PROBLEM, spoolCounts } from '../capture/compaction-spool.js';
 import { defaultSleepLogPath } from '../hooks/shared.js';
 import { errorMessage, log } from '../util/log.js';
@@ -67,4 +67,7 @@ export function cmdLastSleep(hippoRoot, flags, out = process.stdout.isTTY ? 'ter
         }
     }
 }
+export function handleLastSleep({ hippoRoot, flags }) {
+    return cmdLastSleep(hippoRoot, flags);
+}
 //# sourceMappingURL=last-sleep.js.map

package/dist/cli/lenient-id.d.ts

@@ -0,0 +1,2 @@
+export declare function parseObjectId(idRaw: string, noun: string): number;
+//# sourceMappingURL=lenient-id.d.ts.map

package/dist/cli/lenient-id.js

@@ -0,0 +1,13 @@
+// The id parser the predict and decide verbs share.
+import { printError } from './output.js';
+import { CliExit } from './exit.js';
+// Lenient on purpose (parseInt reads "1abc" as 1) until the next major version; the other object verbs use the strict parser.
+export function parseObjectId(idRaw, noun) {
+    const id = parseInt(String(idRaw), 10);
+    if (!Number.isFinite(id) || id <= 0) {
+        printError(`Invalid ${noun} id: "${idRaw}"`);
+        throw new CliExit(1);
+    }
+    return id;
+}
+//# sourceMappingURL=lenient-id.js.map

package/dist/cli/maintenance.d.ts

@@ -1,6 +1,6 @@
-import { type EmbeddingProvider } from '../store/embeddings/provider.js';
-import { type CliFlags } from './flag-values.js';
-export declare function cmdRefine(hippoRoot: string, flags: CliFlags): Promise<void>;
-export declare function cmdDedup(hippoRoot: string, flags: CliFlags): void;
-export declare function cmdEmbed(hippoRoot: string, flags: CliFlags, given?: EmbeddingProvider): Promise<void>;
+import { type EmbeddingProvider } from '../embeddings/provider.js';
+import { type CommandContext } from './flag-values.js';
+export declare function handleRefine({ hippoRoot, tenantId, flags }: CommandContext): Promise<void>;
+export declare function handleDedup({ hippoRoot, tenantId, flags }: CommandContext): void;
+export declare function handleEmbed({ hippoRoot, tenantId, flags }: CommandContext, given?: EmbeddingProvider): Promise<void>;
 //# sourceMappingURL=maintenance.d.ts.map

package/dist/cli/maintenance.js

@@ -1,30 +1,30 @@
 // Store upkeep verbs: `hippo refine`, `hippo dedup` and `hippo embed`.
 import { envAnthropicApiKey } from '../util/env.js';
-import { loadAllEntries } from '../store/entry-reads.js';
 import { deduplicateStore } from '../consolidate/dedupe.js';
-import { embedAll, loadEmbeddingIndex } from '../store/embeddings/index.js';
-import { resolveEmbeddingProvider } from '../store/embeddings/provider.js';
-import { resetStoredParticles } from '../store/vector-writes.js';
+import { resolveEmbeddingProvider } from '../embeddings/provider.js';
+import { embedCoverage, embedMissingMemories, resetPhysicsFromVectors, storedVectorCount } from '../api/embeddings.js';
+import { countAllMemories } from '../api/memories.js';
+import { cliApiContext } from './api-context.js';
 import { loadConfig } from '../core/config.js';
-import { resolveTenantId } from '../store/tenant.js';
 import { refineStore } from './refine-llm.js';
 import { printError } from './output.js';
-import { boolFlag } from './flag-values.js';
+import { boolFlag, numberFlag } from './flag-values.js';
 import { requireInit, resolveAuthRoot } from './shared.js';
 import { errorMessage } from '../util/log.js';
+import { CliExit } from './exit.js';
 const MAX_FAILED_SHOWN = 5;
 const MAX_PAIRS_SHOWN = 15;
 const PAIR_PREVIEW_CHARS = 90;
-export async function cmdRefine(hippoRoot, flags) {
+export async function handleRefine({ hippoRoot, tenantId, flags }) {
     requireInit(hippoRoot);
     const apiKey = envAnthropicApiKey();
     if (!apiKey) {
         printError('hippo refine needs ANTHROPIC_API_KEY in the environment.');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const dryRun = boolFlag(flags, 'dry-run');
     const all = boolFlag(flags, 'all');
-    const limit = flags['limit'] !== undefined ? parseInt(String(flags['limit']), 10) : undefined;
+    const limit = numberFlag(flags, 'limit');
     const model = flags['model'] ? String(flags['model']) : undefined;
     const asJson = boolFlag(flags, 'json');
     const result = await refineStore(hippoRoot, {
@@ -33,7 +33,7 @@ export async function cmdRefine(hippoRoot, flags) {
         limit,
         dryRun,
         all,
-        tenantId: resolveTenantId({}),
+        tenantId,
     });
     if (asJson) {
         console.log(JSON.stringify(result, null, 2));
@@ -50,14 +50,14 @@ export async function cmdRefine(hippoRoot, flags) {
         }
     }
 }
-export function cmdDedup(hippoRoot, flags) {
+export function handleDedup({ hippoRoot, tenantId, flags }) {
     requireInit(hippoRoot);
     const dryRun = boolFlag(flags, 'dry-run');
     if (flags['threshold'] !== undefined) {
         printError('hippo dedup: --threshold is ignored; a duplicate is the same text apart from spacing.');
     }
-    const entries = loadAllEntries(hippoRoot);
-    console.log(`Scanning ${entries.length} memories for duplicates (same text apart from spacing)${dryRun ? ' (dry run)' : ''}...\n`);
+    const total = countAllMemories(cliApiContext(hippoRoot, tenantId));
+    console.log(`Scanning ${total} memories for duplicates (same text apart from spacing)${dryRun ? ' (dry run)' : ''}...\n`);
     const result = deduplicateStore(hippoRoot, { dryRun });
     if (result.removed === 0) {
         console.log('No duplicates found.');
@@ -99,23 +99,20 @@ function printDedupPairs(result, dryRun) {
         console.log(`  ... and ${result.pairs.length - 15} more (run with --dry-run to see all)`);
     }
 }
-// ---------------------------------------------------------------------------
 // Embed command
-// ---------------------------------------------------------------------------
-export async function cmdEmbed(hippoRoot, flags, given) {
-    // --global mirrors resolveAuthRoot (cli.ts:6900): initGlobal() + the global
-    // root, skipping the local requireInit entirely, so this is the healing
-    // path for pre-1.27.0 global stores from a directory with no local .hippo.
+export async function handleEmbed({ hippoRoot, tenantId, flags }, given) {
+    // --global mirrors resolveAuthRoot: initGlobal() + the global root, skipping the local requireInit,
+    // so it heals pre-1.27.0 global stores from a directory with no local .hippo.
     const root = resolveAuthRoot(hippoRoot, flags);
-    // --status and --reset-physics only read cached state, so they must work even
-    // 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.
+    const ctx = cliApiContext(root, tenantId);
+    // --status and --reset-physics only read cached state, so they must work with no provider key (e.g. removed after an earlier embed);
+    // the provider-availability gate is deferred to the embed path.
     if (flags['reset-physics']) {
-        resetPhysics(root);
+        resetPhysics(ctx);
         return;
     }
     if (flags['status']) {
-        printEmbedStatus(root);
+        printEmbedStatus(ctx);
         return;
     }
     const provider = readyEmbedProvider(root, given);
@@ -124,41 +121,38 @@ export async function cmdEmbed(hippoRoot, flags, given) {
     console.log('Embedding all memories (this may take a moment on first run to download model)...');
     let count;
     try {
-        count = await embedAll(root, undefined, provider);
+        count = await embedMissingMemories(ctx, provider);
     }
     catch (err) {
         printError(`Embedding failed: ${errorMessage(err)}`);
-        const partial = loadEmbeddingIndex(root);
-        printError(`Partial progress saved: ${Object.keys(partial).length} embeddings on disk. Re-run \`hippo embed\` to resume.`);
+        printError(`Partial progress saved: ${storedVectorCount(ctx)} 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.`);
-    const unembedded = entriesAfter.filter((e) => !embIndexAfter[e.id]).length;
+    const after = embedCoverage(ctx);
+    console.log(`Done. ${count} new embeddings created. ${after.vectorIds.length}/${after.memoryIds.length} total.`);
+    const embeddedAfter = new Set(after.vectorIds);
+    const unembedded = after.memoryIds.filter((id) => !embeddedAfter.has(id)).length;
     if (unembedded > 0) {
         printError(`${unembedded} memories are still not embedded (the warnings above name them). Re-run \`hippo embed\` to retry.`);
         process.exitCode = 1;
     }
 }
-function resetPhysics(root) {
-    const entries = loadAllEntries(root);
-    const embIndex = loadEmbeddingIndex(root);
-    const count = resetStoredParticles(root, entries, embIndex);
+function resetPhysics(ctx) {
+    const count = resetPhysicsFromVectors(ctx);
     console.log(`Reset physics state: ${count} particles re-initialized from embeddings.`);
 }
-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`);
+function printEmbedStatus(ctx) {
+    const { memoryIds, vectorIds } = embedCoverage(ctx);
+    const activeIds = new Set(memoryIds);
+    const activeEmbedded = vectorIds.filter((id) => activeIds.has(id)).length;
+    const orphaned = vectorIds.length - activeEmbedded;
+    console.log(`Embedding status: ${activeEmbedded}/${memoryIds.length} memories embedded`);
     if (orphaned > 0) {
         console.log(`  ${orphaned} orphaned embeddings (run \`hippo embed\` to prune)`);
     }
-    const missing = entries.filter((e) => !embIndex[e.id]);
+    const embedded = new Set(vectorIds);
+    const missing = memoryIds.filter((id) => !embedded.has(id));
     if (missing.length > 0) {
         console.log(`  ${missing.length} memories need embedding (run \`hippo embed\` to embed them)`);
     }

package/dist/cli/notes.d.ts

@@ -0,0 +1,2 @@
+export declare const handleCustomerNote: (ctx: import("./flag-values.js").CommandContext) => void;
+//# sourceMappingURL=notes.d.ts.map

package/dist/cli/notes.js

@@ -0,0 +1,41 @@
+// The customer note verbs: one account's note, versioned by supersession.
+import * as customerNotesModule from '../objects/customer-notes.js';
+import { stringFlag } from './flag-values.js';
+import { requiredText, versionedVerbs } from './versioned-verbs.js';
+function printNoteRow(n) {
+    console.log(`#${n.id} [${n.status}] v${n.version} customer="${n.customer}" memory=${n.memoryId ?? '-'}`);
+    if (n.changeSummary)
+        console.log(`    change: ${n.changeSummary}`);
+}
+const noteKind = (hippoRoot, tenantId) => ({
+    names: { cmd: 'note', noun: 'Customer note', idLabel: 'note' },
+    plural: 'customer notes',
+    states: customerNotesModule.VALID_NOTE_STATES,
+    usage: [
+        'Usage: hippo note new "<customer>" --text "<note>"',
+        '       hippo note list [--status active|superseded|closed|all] [--customer "<id>"] [--limit N]',
+        '       hippo note get <id>',
+        '       hippo note supersede <id> --text "<note>" [--change "<summary>"]',
+        '       hippo note close <id>',
+    ],
+    supersedeUsage: 'Usage: hippo note supersede <id> --text "<note>" [--change "<summary>"]',
+    bodyRequired: '--text "<note>"',
+    body: (flags) => requiredText(flags, 'text'),
+    keyOf: (n) => n.customer,
+    save: (customer, note, extraTags, from) => customerNotesModule.saveCustomerNote(hippoRoot, tenantId, {
+        customer, note, extraTags, changeSummary: from?.changeSummary, supersedesNoteId: from?.id,
+    }),
+    recorded: (n) => `Customer note recorded: #${n.id} (v${n.version}) for customer "${n.customer}"`,
+    list: (opts, flags) => customerNotesModule.loadCustomerNotes(hippoRoot, tenantId, { ...opts, customer: stringFlag(flags, 'customer')?.trim() || undefined }),
+    loadById: (id) => customerNotesModule.loadCustomerNoteById(hippoRoot, tenantId, id),
+    close: (id) => customerNotesModule.closeCustomerNote(hippoRoot, tenantId, id),
+    printRow: printNoteRow,
+    printDetail: (n) => {
+        console.log(`  customer: ${n.customer}`);
+        console.log(`  status: ${n.status}`);
+        console.log(`  version: ${n.version}`);
+        console.log(`  note: ${n.note}`);
+    },
+});
+export const handleCustomerNote = versionedVerbs(noteKind);
+//# sourceMappingURL=notes.js.map

package/dist/cli/object-verbs.js

@@ -1,12 +1,13 @@
 // The status, list, id and not-found paths the typed-object verbs (process, policy, skill, brief, note, decide, incident, predict) share.
 import { printError } from './output.js';
 import { parseListLimit, parsePositiveId, stringFlag } from './flag-values.js';
+import { CliExit } from './exit.js';
 /** The member of `states` named by `status`, or exit 1 with the message that lists every allowed value. */
 export function requireStatus(status, states) {
     const found = [...states].find((s) => s === status);
     if (found === undefined) {
         printError(`Invalid --status: "${status}". Must be one of: ${[...states, 'all'].join(' | ')}.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return found;
 }
@@ -32,14 +33,14 @@ export function idArgOrExit(args, usage, label, parseId = parsePositiveId) {
     const idRaw = args[1];
     if (!idRaw) {
         printError(usage);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return parseId(idRaw, label);
 }
 export function foundOrExit(found, noun, id) {
     if (!found) {
         printError(`${noun} ${id} not found.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return found;
 }

package/dist/cli/open-browser.d.ts

@@ -0,0 +1,14 @@
+/** The part of a child process the launch reads. */
+interface Launched {
+    on(event: 'error', listener: (err: Error) => void): void;
+    unref(): void;
+}
+type Launcher = (cmd: string, args: string[], opts: {
+    detached: boolean;
+    stdio: 'ignore';
+    windowsHide: boolean;
+}) => Launched;
+/** `launch` is the process starter; tests hand in a stand-in. */
+export declare function openInBrowser(out: string, launch?: Launcher): void;
+export {};
+//# sourceMappingURL=open-browser.d.ts.map

package/dist/cli/open-browser.js

@@ -0,0 +1,26 @@
+// Best-effort browser launch for CLI verbs that write a file.
+import { spawn } from 'child_process';
+import { errorMessage, log } from '../util/log.js';
+/** `launch` is the process starter; tests hand in a stand-in. */
+export function openInBrowser(out, launch = spawn) {
+    // 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 = launch(cmd, cmdArgs, { detached: true, stdio: 'ignore', windowsHide: true });
+        // A missing launcher (e.g. xdg-open absent) emits 'error' asynchronously; unhandled, it would throw.
+        child.on('error', (err) => {
+            log.warn(`graph view: could not open the browser: ${errorMessage(err)}`);
+            process.exitCode = 1;
+        });
+        child.unref();
+    }
+    catch (err) {
+        // The file is written and its path printed above, so a browser that will not start costs nothing.
+        log.debug(`browser not opened: ${errorMessage(err)}`);
+    }
+}
+//# sourceMappingURL=open-browser.js.map

package/dist/cli/owner-validation.d.ts

@@ -1,14 +1,5 @@
-/**
- * --owner format validation.
- *
- * Documented MEMORY_ENVELOPE.md contract: owner = `user:<id>` | `agent:<id>`
- * with id ∈ `[A-Za-z0-9_-]+`.
- *
- * Default: WARN-ONLY (log + accept) to preserve back-compat with existing
- * scripted callers passing legacy owner strings. Set `HIPPO_STRICT_OWNER=1`
- * to reject + exit. Strict mode will become the default once real auth replaces
- * the stub (see `TODOS.md` for the migration path).
- */
+/** --owner validation per MEMORY_ENVELOPE.md: `user:<id>` | `agent:<id>`, id in `[A-Za-z0-9_-]+`.
+ * Warn-only by default for legacy scripted callers; `HIPPO_STRICT_OWNER=1` rejects and exits. */
 export declare const OWNER_CONTRACT_HINT = "Must match ^(user|agent):[A-Za-z0-9_-]+$ (e.g. user:alice, agent:capture-bot).";
 export interface OwnerValidation {
     ok: boolean;
@@ -17,25 +8,11 @@ export interface OwnerValidation {
     /** Human-readable message (warn or error). Empty when ok = true. */
     message: string;
 }
-/**
- * Pure validator. Returns `{ ok, value, message }`. Does NOT print or
- * `process.exit`. The CLI wrapper below handles side effects so this is
- * unit-testable.
- *
- * Behaviour:
- *   - owner undefined → ok=true, value=undefined, no message.
- *   - owner matches OWNER_RE → ok=true, value=owner.
- *   - owner doesn't match + strict=false → ok=true, value=owner (accept),
- *     message contains the warning text.
- *   - owner doesn't match + strict=true → ok=false, value=owner (echoed),
- *     message contains the error text.
- */
+/** Pure validator returning `{ ok, value, message }`; never prints or exits, so it is unit-testable.
+ * A non-matching owner is accepted with a warning unless strict, where ok=false with an error message. */
 export declare function validateOwner(owner: string | null | undefined, opts?: {
     strict?: boolean;
 }): OwnerValidation;
-/**
- * Returns true when strict-owner enforcement is enabled via env var.
- * Centralised here so any future bump to default-strict is one edit.
- */
+/** True when strict-owner enforcement is enabled via env var. */
 export declare function isStrictOwnerEnv(env?: NodeJS.ProcessEnv): boolean;
 //# sourceMappingURL=owner-validation.d.ts.map