hippo-memory 1.69.0 → 1.71.0

package/dist/cli/maintenance.js

@@ -1,35 +1,39 @@
 // Store upkeep verbs: `hippo refine`, `hippo dedup` and `hippo embed`.
-import { envAnthropicApiKey } from '../env.js';
-import { loadAllEntries } from '../store/entry-reads.js';
-import { deduplicateStore } from '../dedupe.js';
-import { embedAll, loadEmbeddingIndex } from '../embeddings.js';
-import { resolveEmbeddingProvider } from '../embedding-provider.js';
-import { resetAllPhysicsState } from '../physics-state.js';
-import { loadConfig } from '../config.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { resolveTenantId } from '../tenant.js';
-import { refineStore } from '../refine-llm.js';
+import { envAnthropicApiKey } from '../util/env.js';
+import { loadAllEntries, loadAllEntryIds } from '../store/entry-reads.js';
+import { deduplicateStore } from '../consolidate/dedupe.js';
+import { embedAll } from '../store/embeddings/index.js';
+import { resolveEmbeddingProvider } from '../store/embeddings/provider.js';
+import { loadEmbeddingIndex, resetStoredParticles } from '../store/vector-index.js';
+import { loadConfig } from '../core/config.js';
+import { refineStore } from './refine-llm.js';
 import { printError } from './output.js';
+import { boolFlag } from './flag-values.js';
 import { requireInit, resolveAuthRoot } from './shared.js';
-export async function cmdRefine(hippoRoot, flags) {
+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 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 = Boolean(flags['dry-run']);
-    const all = Boolean(flags['all']);
+    const dryRun = boolFlag(flags, 'dry-run');
+    const all = boolFlag(flags, 'all');
     const limit = flags['limit'] !== undefined ? parseInt(String(flags['limit']), 10) : undefined;
     const model = flags['model'] ? String(flags['model']) : undefined;
-    const asJson = Boolean(flags['json']);
+    const asJson = boolFlag(flags, 'json');
     const result = await refineStore(hippoRoot, {
         apiKey,
         model,
         limit,
         dryRun,
         all,
-        tenantId: resolveTenantId({}),
+        tenantId,
     });
     if (asJson) {
         console.log(JSON.stringify(result, null, 2));
@@ -41,14 +45,14 @@ export async function cmdRefine(hippoRoot, flags) {
     console.log(`Failed:   ${result.failed}`);
     if (result.failed > 0) {
         console.log('\nFailures:');
-        for (const d of result.details.filter((x) => x.status === 'failed').slice(0, 5)) {
+        for (const d of result.details.filter((x) => x.status === 'failed').slice(0, MAX_FAILED_SHOWN)) {
             console.log(`  ${d.id}: ${d.reason}`);
         }
     }
 }
-export function cmdDedup(hippoRoot, flags) {
+export function handleDedup({ hippoRoot, flags }) {
     requireInit(hippoRoot);
-    const dryRun = Boolean(flags['dry-run']);
+    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.');
     }
@@ -59,6 +63,10 @@ export function cmdDedup(hippoRoot, flags) {
         console.log('No duplicates found.');
         return;
     }
+    printDedupGroups(result, dryRun);
+    printDedupPairs(result, dryRun);
+}
+function printDedupGroups(result, dryRun) {
     // Group by reason
     const sameLayerSem = result.pairs.filter(p => p.keptLayer === 'semantic' && p.removedLayer === 'semantic');
     const sameLayerEpi = result.pairs.filter(p => p.keptLayer === 'episodic' && p.removedLayer === 'episodic');
@@ -73,33 +81,31 @@ export function cmdDedup(hippoRoot, flags) {
     if (crossLayer.length > 0) {
         console.log(`  ${crossLayer.length} cross-layer duplicates (episodic content already consolidated into semantic)`);
     }
+}
+function printDedupPairs(result, dryRun) {
     // Show detailed pairs
     console.log('');
-    const shown = result.pairs.slice(0, 15);
+    const shown = result.pairs.slice(0, MAX_PAIRS_SHOWN);
     for (const pair of shown) {
         const simPct = (pair.similarity * 100).toFixed(0);
         const action = dryRun ? 'Would remove' : 'Removed';
         console.log(`  ${simPct}% similar | kept [${pair.keptLayer}] strength=${pair.keptStrength.toFixed(2)}`);
-        console.log(`    ${pair.keptContent.slice(0, 90)}`);
+        console.log(`    ${pair.keptContent.slice(0, PAIR_PREVIEW_CHARS)}`);
         console.log(`  ${action} [${pair.removedLayer}] strength=${pair.removedStrength.toFixed(2)}`);
-        console.log(`    ${pair.removedContent.slice(0, 90)}`);
+        console.log(`    ${pair.removedContent.slice(0, PAIR_PREVIEW_CHARS)}`);
         console.log('');
     }
     if (result.pairs.length > 15) {
         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, 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.
+    // --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);
         return;
@@ -117,7 +123,7 @@ export async function cmdEmbed(hippoRoot, flags, given) {
         count = await embedAll(root, undefined, provider);
     }
     catch (err) {
-        printError(`Embedding failed: ${err instanceof Error ? err.message : String(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.`);
         process.exitCode = 1;
@@ -133,16 +139,9 @@ export async function cmdEmbed(hippoRoot, flags, given) {
     }
 }
 function resetPhysics(root) {
-    const entries = loadAllEntries(root);
     const embIndex = loadEmbeddingIndex(root);
-    const db = openHippoDb(root);
-    try {
-        const count = resetAllPhysicsState(db, entries, embIndex);
-        console.log(`Reset physics state: ${count} particles re-initialized from embeddings.`);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    const count = resetStoredParticles(root, loadAllEntryIds(root), embIndex);
+    console.log(`Reset physics state: ${count} particles re-initialized from embeddings.`);
 }
 function printEmbedStatus(root) {
     const entries = loadAllEntries(root);
@@ -167,7 +166,7 @@ function readyEmbedProvider(root, given) {
             return resolveEmbeddingProvider(root);
         }
         catch (err) {
-            printError(err instanceof Error ? err.message : String(err));
+            printError(errorMessage(err));
             return null;
         }
     })();

package/dist/cli/object-verbs.d.ts

@@ -0,0 +1,40 @@
+import { type CliFlags } from './flag-values.js';
+/** The member of `states` named by `status`, or exit 1 with the message that lists every allowed value. */
+export declare function requireStatus<S extends string>(status: string, states: ReadonlySet<S>): S;
+/** `--status` checked against the kind's states; undefined when absent or `all`. */
+export declare function statusFilter<S extends string>(flags: CliFlags, states: ReadonlySet<S>): S | undefined;
+export interface ObjectListSpec<O, S extends string> {
+    readonly plural: string;
+    readonly states: ReadonlySet<S>;
+    readonly load: (opts: {
+        status?: S;
+        limit: number;
+    }) => readonly O[];
+    readonly printRow: (o: O) => void;
+}
+export declare function listObjects<O, S extends string>(flags: CliFlags, spec: ObjectListSpec<O, S>): void;
+/** The `<id>` after the subcommand; prints `usage` and exits 1 when it is missing. */
+export declare function idArgOrExit(args: string[], usage: string, label: string, parseId?: (raw: string, label: string) => number): number;
+export declare function foundOrExit<O>(found: O | null | undefined, noun: string, id: number): O;
+/** How a kind is named in usage lines (`cmd`), in messages (`noun`) and in the invalid-id error (`idLabel`). */
+export interface ObjectNames {
+    readonly cmd: string;
+    readonly noun: string;
+    readonly idLabel: string;
+}
+/** `hippo <cmd> close <id>` for a kind whose close call returns the closed row. */
+export declare function closeObject(args: string[], names: ObjectNames, close: (id: number) => {
+    id: number;
+}, parseId?: (raw: string, label: string) => number): void;
+interface LifecycleTail {
+    readonly changeSummary?: string | null;
+    readonly supersededBy: number | null;
+    readonly supersededAt?: string | null;
+    readonly closedAt?: string | null;
+    readonly memoryId?: string | null;
+    readonly createdAt: string;
+}
+/** The detail lines every `get` ends with. */
+export declare function printLifecycleTail(o: LifecycleTail): void;
+export {};
+//# sourceMappingURL=object-verbs.d.ts.map

package/dist/cli/object-verbs.js

@@ -0,0 +1,66 @@
+// 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(' | ')}.`);
+        throw new CliExit(1);
+    }
+    return found;
+}
+/** `--status` checked against the kind's states; undefined when absent or `all`. */
+export function statusFilter(flags, states) {
+    const status = stringFlag(flags, 'status')?.trim() ?? 'all';
+    return status === 'all' ? undefined : requireStatus(status, states);
+}
+export function listObjects(flags, spec) {
+    const limit = parseListLimit(flags);
+    const status = statusFilter(flags, spec.states);
+    const results = spec.load(status === undefined ? { limit } : { status, limit });
+    if (results.length === 0) {
+        console.log(`No ${spec.plural}.`);
+        return;
+    }
+    console.log(`Found ${results.length} ${spec.plural}:\n`);
+    for (const o of results)
+        spec.printRow(o);
+}
+/** The `<id>` after the subcommand; prints `usage` and exits 1 when it is missing. */
+export function idArgOrExit(args, usage, label, parseId = parsePositiveId) {
+    const idRaw = args[1];
+    if (!idRaw) {
+        printError(usage);
+        throw new CliExit(1);
+    }
+    return parseId(idRaw, label);
+}
+export function foundOrExit(found, noun, id) {
+    if (!found) {
+        printError(`${noun} ${id} not found.`);
+        throw new CliExit(1);
+    }
+    return found;
+}
+/** `hippo <cmd> close <id>` for a kind whose close call returns the closed row. */
+export function closeObject(args, names, close, parseId = parsePositiveId) {
+    const id = idArgOrExit(args, `Usage: hippo ${names.cmd} close <id>`, names.idLabel, parseId);
+    console.log(`${names.noun} #${close(id).id} closed.`);
+}
+/** The detail lines every `get` ends with. */
+export function printLifecycleTail(o) {
+    if (o.changeSummary)
+        console.log(`  change_summary: ${o.changeSummary}`);
+    if (o.supersededBy !== null)
+        console.log(`  superseded_by: #${o.supersededBy}`);
+    if (o.supersededAt)
+        console.log(`  superseded_at: ${o.supersededAt}`);
+    if (o.closedAt)
+        console.log(`  closed_at: ${o.closedAt}`);
+    if (o.memoryId)
+        console.log(`  memory: ${o.memoryId}`);
+    console.log(`  created: ${o.createdAt}`);
+}
+//# sourceMappingURL=object-verbs.js.map

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

@@ -0,0 +1,18 @@
+/** --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;
+    /** The owner string as the caller should now use it. undefined when no owner was supplied. */
+    value: string | undefined;
+    /** Human-readable message (warn or error). Empty when ok = true. */
+    message: string;
+}
+/** 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;
+/** True when strict-owner enforcement is enabled via env var. */
+export declare function isStrictOwnerEnv(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=owner-validation.d.ts.map

package/dist/cli/owner-validation.js

@@ -0,0 +1,33 @@
+/** --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. */
+import { processEnv } from '../util/env.js';
+const OWNER_RE = /^(user|agent):[A-Za-z0-9_-]+$/;
+export const OWNER_CONTRACT_HINT = 'Must match ^(user|agent):[A-Za-z0-9_-]+$ (e.g. user:alice, agent:capture-bot).';
+/** 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 function validateOwner(owner, opts = {}) {
+    if (owner === undefined || owner === null || owner === '') {
+        return { ok: true, value: undefined, message: '' };
+    }
+    if (OWNER_RE.test(owner)) {
+        return { ok: true, value: owner, message: '' };
+    }
+    if (opts.strict) {
+        return {
+            ok: false,
+            value: owner,
+            message: `Invalid --owner "${owner}". ${OWNER_CONTRACT_HINT}`,
+        };
+    }
+    return {
+        ok: true,
+        value: owner,
+        message: `[warn] --owner "${owner}" does not match the contract. ${OWNER_CONTRACT_HINT} ` +
+            `Accepting for back-compat; set HIPPO_STRICT_OWNER=1 to reject.`,
+    };
+}
+/** True when strict-owner enforcement is enabled via env var. */
+export function isStrictOwnerEnv(env = processEnv()) {
+    return env.HIPPO_STRICT_OWNER === '1';
+}
+//# sourceMappingURL=owner-validation.js.map

package/dist/cli/playbooks.d.ts

@@ -1,4 +1,5 @@
-export declare function cmdProcess(hippoRoot: string, args: string[], flags: Record<string, string | boolean | string[]>): void;
-export declare function cmdPolicy(hippoRoot: string, args: string[], flags: Record<string, string | boolean | string[]>): void;
-export declare function cmdSkill(hippoRoot: string, args: string[], flags: Record<string, string | boolean | string[]>): void;
+import { type CommandContext } from './flag-values.js';
+export declare function handleProcess({ hippoRoot, tenantId, args, flags }: CommandContext): void;
+export declare function handlePolicy({ hippoRoot, tenantId, args, flags }: CommandContext): void;
+export declare function handleSkill({ hippoRoot, tenantId, args, flags }: CommandContext): void;
 //# sourceMappingURL=playbooks.d.ts.map