hippo-memory 1.69.0 → 1.71.0

package/dist/audit-prune.d.ts

@@ -1,62 +0,0 @@
-/**
- * Audit log retention pruning.
- *
- * The `audit_log` table grows unbounded by default — every recall, write,
- * outcome, sleep, supersede, promote, forget, archive_raw, auth_revoke,
- * and auth_create emits a row. On a long-running deployment, this can
- * accumulate to millions of rows and slow down both audit queries and
- * incremental SQLite VACUUMs.
- *
- * Regulatory retention floors (HIPAA, SOX, GDPR) are why the prune is opt-in
- * per tenant and emits its own audit trail event.
- *
- * Design notes:
- *   - Per-tenant by default (matches existing audit CLI conventions).
- *   - The prune itself emits an `audit_prune` audit row with metadata
- *     `{cutoff, count, dryRun}`, recursively recording the maintenance op
- *     in the audit trail. Operators investigating "where did old rows go"
- *     have one row left to find regardless of retention floor.
- *   - Dry-run mode returns the count without deleting — first-time
- *     operator safety.
- *   - DELETE is wrapped in a transaction so a mid-operation crash leaves
- *     audit_log in a consistent state.
- *   - The audit_prune row itself is NEVER pruned by the same call (it's
- *     written AFTER the DELETE WHERE ts < cutoff, so ts > cutoff).
- */
-import type { DatabaseSyncLike } from './db.js';
-export interface PruneAuditOpts {
-    /** Cutoff in days. Rows with `ts < (now - N days)` are deleted. */
-    olderThanDays: number;
-    /** Tenant scope. Required: prune is always tenant-scoped. */
-    tenantId: string;
-    /** When true, count matching rows but do NOT delete. Default false. */
-    dryRun?: boolean;
-    /** Actor recording the prune in the audit trail. Default 'cli'. */
-    actor?: string;
-}
-export interface PruneAuditResult {
-    /** ISO timestamp of the cutoff. Rows with ts strictly less than this were deleted. */
-    cutoff: string;
-    /** Number of audit_log rows deleted (or that would be deleted, if dryRun). */
-    count: number;
-    /** Echo back whether this was a dry run. */
-    dryRun: boolean;
-}
-/**
- * Compute the cutoff ISO timestamp for an N-days-ago cutoff. Exported for
- * testability so tests can pin "now" without mocking Date.
- */
-export declare function computeCutoff(days: number, now?: Date): string;
-/**
- * Delete audit_log rows older than `olderThanDays` days for `tenantId`.
- * Emits an `audit_prune` event with metadata `{cutoff, count, dryRun}`.
- *
- * Throws on invalid inputs (non-positive days, missing tenantId).
- */
-export declare function pruneAuditLog(db: DatabaseSyncLike, opts: PruneAuditOpts): PruneAuditResult;
-/**
- * Parse the `--older-than <value>` flag. Accepts either bare integer days
- * (`30`) or integer with `d` suffix (`30d`). Throws on invalid format.
- */
-export declare function parseOlderThanFlag(raw: string): number;
-//# sourceMappingURL=audit-prune.d.ts.map

package/dist/audit-prune.js

@@ -1,107 +0,0 @@
-/**
- * Audit log retention pruning.
- *
- * The `audit_log` table grows unbounded by default — every recall, write,
- * outcome, sleep, supersede, promote, forget, archive_raw, auth_revoke,
- * and auth_create emits a row. On a long-running deployment, this can
- * accumulate to millions of rows and slow down both audit queries and
- * incremental SQLite VACUUMs.
- *
- * Regulatory retention floors (HIPAA, SOX, GDPR) are why the prune is opt-in
- * per tenant and emits its own audit trail event.
- *
- * Design notes:
- *   - Per-tenant by default (matches existing audit CLI conventions).
- *   - The prune itself emits an `audit_prune` audit row with metadata
- *     `{cutoff, count, dryRun}`, recursively recording the maintenance op
- *     in the audit trail. Operators investigating "where did old rows go"
- *     have one row left to find regardless of retention floor.
- *   - Dry-run mode returns the count without deleting — first-time
- *     operator safety.
- *   - DELETE is wrapped in a transaction so a mid-operation crash leaves
- *     audit_log in a consistent state.
- *   - The audit_prune row itself is NEVER pruned by the same call (it's
- *     written AFTER the DELETE WHERE ts < cutoff, so ts > cutoff).
- */
-import { appendAuditEvent } from './audit.js';
-/**
- * Compute the cutoff ISO timestamp for an N-days-ago cutoff. Exported for
- * testability so tests can pin "now" without mocking Date.
- */
-export function computeCutoff(days, now = new Date()) {
-    const cutoff = new Date(now.getTime() - days * 24 * 60 * 60 * 1000);
-    return cutoff.toISOString();
-}
-function isTenantIdString(value) {
-    return typeof value === 'string';
-}
-/**
- * Delete audit_log rows older than `olderThanDays` days for `tenantId`.
- * Emits an `audit_prune` event with metadata `{cutoff, count, dryRun}`.
- *
- * Throws on invalid inputs (non-positive days, missing tenantId).
- */
-export function pruneAuditLog(db, opts) {
-    if (!Number.isFinite(opts.olderThanDays) || opts.olderThanDays <= 0) {
-        throw new Error(`pruneAuditLog: olderThanDays must be a positive number, got ${opts.olderThanDays}`);
-    }
-    if (!opts.tenantId || !isTenantIdString(opts.tenantId)) {
-        throw new Error('pruneAuditLog: tenantId is required');
-    }
-    const dryRun = opts.dryRun === true;
-    const actor = opts.actor ?? 'cli';
-    const cutoff = computeCutoff(opts.olderThanDays);
-    let count = 0;
-    if (dryRun) {
-        // Dry-run: just count, no DELETE.
-        // SAFETY: row comes from `SELECT COUNT(*) AS c` above; COUNT(*) always
-        // yields exactly one row with a numeric `c` column (number or bigint
-        // depending on the node:sqlite driver's integer handling).
-        const row = db
-            .prepare(`SELECT COUNT(*) AS c FROM audit_log WHERE tenant_id = ? AND ts < ?`)
-            .get(opts.tenantId, cutoff);
-        count = Number(row.c);
-    }
-    else {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const result = db
-                .prepare(`DELETE FROM audit_log WHERE tenant_id = ? AND ts < ?`)
-                .run(opts.tenantId, cutoff);
-            count = Number(result.changes ?? 0);
-            // Record the prune itself in the audit trail. This row has ts = now,
-            // so it's not eligible for the cutoff that was just applied.
-            appendAuditEvent(db, {
-                tenantId: opts.tenantId,
-                actor,
-                op: 'audit_prune',
-                metadata: { cutoff, count, dryRun: false, olderThanDays: opts.olderThanDays },
-            });
-            db.exec('COMMIT');
-        }
-        catch (e) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back; keep the original error */ }
-            throw e;
-        }
-    }
-    return { cutoff, count, dryRun };
-}
-/**
- * Parse the `--older-than <value>` flag. Accepts either bare integer days
- * (`30`) or integer with `d` suffix (`30d`). Throws on invalid format.
- */
-export function parseOlderThanFlag(raw) {
-    const m = raw.match(/^(\d+)(d)?$/i);
-    if (!m) {
-        throw new Error(`Invalid --older-than value: "${raw}". Expected integer days (e.g. "30") or with d suffix ("30d").`);
-    }
-    const n = parseInt(m[1], 10);
-    if (!Number.isFinite(n) || n <= 0) {
-        throw new Error(`Invalid --older-than value: "${raw}". Must be a positive integer.`);
-    }
-    return n;
-}
-//# sourceMappingURL=audit-prune.js.map

package/dist/autolearn.d.ts

@@ -1,56 +0,0 @@
-/**
- * Auto-learn from errors and git history.
- * Agents learn from failures without explicit hippo remember calls.
- */
-import { MemoryEntry } from './memory.js';
-/** A memory of a failed command, "Command '<cmd>' failed: <truncated stderr>"; no store is in reach, so `hippo watch` re-derives its half-life from the store's config. */
-export declare function captureError(exitCode: number, stderr: string, command: string, tenantId?: string): MemoryEntry;
-/**
- * Parse git log output for actionable lessons.
- * Looks for fix:, revert:, bug:, error:, hotfix: commit messages.
- */
-export declare function extractLessons(gitLog: string, customPatterns?: string[]): string[];
-/**
- * Split parsed lessons into ones worth storing and low-information ones.
- *
- * `extractLessons` is a published API surface (exported from src/index.ts)
- * and does one job: parse a git log into candidate lesson strings. Adding a
- * quality check inside it would break that contract and silently change
- * what external callers get back. So parsing and admission are separate
- * steps: this function is the write-path gate, called by each caller that
- * actually stores a lesson, not by the parser itself.
- *
- * Order is preserved in both output arrays; both hold lessons with secret shapes redacted.
- */
-export declare function partitionLessons(lessons: string[]): {
-    kept: string[];
-    dropped: string[];
-};
-/**
- * Check if a substantially similar memory already exists.
- * Returns true if overlap > threshold (default 0.7).
- *
- * `tenantId` is opt-in. Only takes effect when the first argument is a
- * root string (string-overload path). When the first argument is a
- * pre-loaded MemoryEntry[], the caller has already scoped — tenantId is
- * ignored on that path.
- */
-export declare function deduplicateLesson(hippoRootOrEntries: string | MemoryEntry[], lesson: string, threshold?: number, tenantId?: string): boolean;
-/**
- * Run a command, streaming stdout/stderr to the terminal in real time.
- * Returns: { exitCode, stderr }.
- */
-export declare function runWatched(command: string): Promise<{
-    exitCode: number;
-    stderr: string;
-}>;
-/**
- * Check whether a directory is a git work tree.
- */
-export declare function isGitRepo(cwd: string): boolean;
-/**
- * Fetch recent git log lines (subject lines only).
- * days: how many days of history to include.
- */
-export declare function fetchGitLog(cwd: string, days: number): string;
-//# sourceMappingURL=autolearn.d.ts.map

package/dist/client.d.ts

@@ -1,48 +0,0 @@
-/**
- * HTTP client wrapper for `hippo serve`.
- *
- * Only the writes the CLI routes (remember, forget, archive, promote), which are
- * also all HIPPO_REQUIRE_SERVER covers; every other command opens the store
- * directly. Each call returns the same shape that api.ts would.
- *
- * Errors from the server (4xx/5xx) are mapped back into thrown Errors with
- * the server's `error` message preserved verbatim so existing CLI handlers
- * that match on substrings (e.g. "not found", "already superseded") still
- * work unchanged.
- *
- * Network errors (ECONNREFUSED on a stale pidfile, etc.) propagate as the
- * native fetch failure so the caller can detect them and self-heal.
- */
-import type { RememberOpts, RememberResult } from './api.js';
-/** An error the server answered with, not one the transport raised. The
- *  refused-connection classifier sniffs message text, and a server message
- *  quotes the caller's own id or content back verbatim. */
-export declare class HttpResponseError extends Error {
-    readonly status: number;
-    constructor(message: string, status: number);
-}
-export declare function remember(serverUrl: string, apiKey: string | undefined, opts: RememberOpts): Promise<RememberResult>;
-export declare function forget(serverUrl: string, apiKey: string | undefined, id: string): Promise<{
-    ok: true;
-    id: string;
-}>;
-export declare function promote(serverUrl: string, apiKey: string | undefined, id: string): Promise<{
-    ok: true;
-    sourceId: string;
-    globalId: string;
-}>;
-export declare function archiveRaw(serverUrl: string, apiKey: string | undefined, id: string, reason: string): Promise<{
-    ok: true;
-    archivedAt: string;
-}>;
-/**
- * How far a request got before the transport failed.
- *
- * 'never-sent' means the connection never opened, so the caller may safely
- * replay the call locally. 'delivery-unknown' means the socket broke with the
- * request already on the wire: the server may have committed it, so replaying a
- * write would store it twice. 'none' means this was not a transport failure.
- */
-export type TransportFailure = 'none' | 'never-sent' | 'delivery-unknown';
-export declare function classifyTransportFailure(err: unknown): TransportFailure;
-//# sourceMappingURL=client.d.ts.map

package/dist/compare.d.ts

@@ -1,86 +0,0 @@
-/**
- * Deterministic tie-break comparators for recall ranking.
- *
- * A true LEAF module: imports NOTHING from any sort-site module (search.ts,
- * physics.ts, api.ts, cli.ts, shared.ts, goals.ts, graph-recall.ts,
- * multihop.ts, rerankers/*). Every comparator here takes a structural param
- * type instead of an imported one, on purpose — a type-only import back to
- * search.ts would still create the search.ts <-> physics.ts ESM import
- * cycle this module exists to avoid.
- *
- * Mirrors the deliberate-determinism comment style already established in
- * graph-stream.ts:88, :165-168, :233-236 — a sort with a documented,
- * reproducible tiebreak instead of leaving ties to array/scan order.
- */
-/** Minimal shape needed to break a tie deterministically across fresh
- *  ingests of the same content into different stores. The metadata keys are
- *  optional so existing `{ content, id }` callers (tests, benchmarks) still fit;
- *  a full MemoryEntry satisfies it structurally and gets the metadata order. */
-export interface EntryIdentity {
-    content: string;
-    id: string;
-    layer?: string;
-    tags?: readonly string[];
-    source?: string;
-}
-/**
- * content asc -> layer rank asc -> distinct tag count desc -> sorted tags asc
- * -> source asc -> id asc (all string compares are UTF-16 code-unit order).
- *
- * `content` is the cross-ingest-stable key: identical text ingested into two
- * independently-created stores (different directory name, different insert
- * order of everything else on disk) sorts identically. The metadata keys make
- * byte-identical twins order by what they carry instead of by `id`
- * (`crypto.randomUUID()`), which is per-instance random and would make the
- * dedupe survivor arbitrary. `id` stays the terminal key so the order is
- * total within one store.
- *
- * Layer rank puts semantic first: semantic rows are consolidation output, so
- * keeping that copy preserves the promotion instead of demoting the memory.
- * Unknown or missing layers rank last and then compare as raw strings.
- * Tags prefer the copy with more distinct labels (fewer labels are lost on
- * dedupe); source is an arbitrary but stable key.
- *
- * Plain `<`/`>`, NOT `localeCompare`: `localeCompare` is locale- and
- * ICU-version-dependent (a determinism leak in its own right) and needlessly
- * slow for a tiebreak that only needs a total order. The metadata keys are
- * only computed on a content tie, which is rare, so the per-compare Set/sort
- * cost never lands on the hot path.
- */
-export declare function compareEntryIdentity(a: EntryIdentity, b: EntryIdentity): number;
-/** Minimal shape for score-primary sort sites (SearchResult and friends
- *  that carry `{ score, entry: { content, id } }`). */
-export interface ScoredEntryLike {
-    score: number;
-    entry: EntryIdentity;
-}
-/**
- * score descending -> `compareEntryIdentity`. The shared ordering rule for
- * every score-primary recall sort site (search.ts, shared.ts, goals.ts,
- * api.ts, cli.ts, graph-recall.ts, multihop.ts, rerankers/cross-encoder.ts).
- * Sites delegate wholesale to this (via a thin arrow where the element
- * shape's score field is named something other than `score`, e.g.
- * `rerankScore`) rather than reimplementing `b.score - a.score` locally, so
- * the tiebreak can't silently drift between call sites.
- */
-export declare function compareScoredResults(a: ScoredEntryLike, b: ScoredEntryLike): number;
-/**
- * Build a score-desc -> tie-key comparator for the physics layer.
- *
- * `ScoredPhysicsResult` (physics.ts) carries `{ memoryId, baseScore,
- * clusterAmplification, finalScore }` -- NO `entry`/`content` in scope at
- * that layer, so `compareEntryIdentity` cannot apply directly. With only the
- * default memoryId key this is PER-INSTANCE-ONLY determinism; callers that need
- * CROSS-INGEST stability supply `tieKeyOf` mapping the result to its memory
- * CONTENT, because the baseScore tie order selects the cluster_top_k
- * amplification set, which MUTATES scores before the content-aware merge sort.
- *
- * A factory (not a fixed-field comparator) because physics.ts re-sorts the
- * same result array by two different score fields in sequence (`baseScore`
- * for top-K selection, then `finalScore` after cluster amplification) — one
- * shared tiebreak rule, parameterised by which field is primary this pass.
- */
-export declare function comparePhysicsResultsBy<T extends {
-    memoryId: string;
-}>(scoreOf: (r: T) => number, tieKeyOf?: (r: T) => string): (a: T, b: T) => number;
-//# sourceMappingURL=compare.d.ts.map

package/dist/compare.js

@@ -1,117 +0,0 @@
-/**
- * Deterministic tie-break comparators for recall ranking.
- *
- * A true LEAF module: imports NOTHING from any sort-site module (search.ts,
- * physics.ts, api.ts, cli.ts, shared.ts, goals.ts, graph-recall.ts,
- * multihop.ts, rerankers/*). Every comparator here takes a structural param
- * type instead of an imported one, on purpose — a type-only import back to
- * search.ts would still create the search.ts <-> physics.ts ESM import
- * cycle this module exists to avoid.
- *
- * Mirrors the deliberate-determinism comment style already established in
- * graph-stream.ts:88, :165-168, :233-236 — a sort with a documented,
- * reproducible tiebreak instead of leaving ties to array/scan order.
- */
-/**
- * content asc -> layer rank asc -> distinct tag count desc -> sorted tags asc
- * -> source asc -> id asc (all string compares are UTF-16 code-unit order).
- *
- * `content` is the cross-ingest-stable key: identical text ingested into two
- * independently-created stores (different directory name, different insert
- * order of everything else on disk) sorts identically. The metadata keys make
- * byte-identical twins order by what they carry instead of by `id`
- * (`crypto.randomUUID()`), which is per-instance random and would make the
- * dedupe survivor arbitrary. `id` stays the terminal key so the order is
- * total within one store.
- *
- * Layer rank puts semantic first: semantic rows are consolidation output, so
- * keeping that copy preserves the promotion instead of demoting the memory.
- * Unknown or missing layers rank last and then compare as raw strings.
- * Tags prefer the copy with more distinct labels (fewer labels are lost on
- * dedupe); source is an arbitrary but stable key.
- *
- * Plain `<`/`>`, NOT `localeCompare`: `localeCompare` is locale- and
- * ICU-version-dependent (a determinism leak in its own right) and needlessly
- * slow for a tiebreak that only needs a total order. The metadata keys are
- * only computed on a content tie, which is rare, so the per-compare Set/sort
- * cost never lands on the hot path.
- */
-export function compareEntryIdentity(a, b) {
-    return (compareStrings(a.content, b.content) ||
-        layerRank(a.layer) - layerRank(b.layer) ||
-        compareStrings(a.layer ?? '', b.layer ?? '') ||
-        compareTags(a.tags, b.tags) ||
-        compareStrings(a.source ?? '', b.source ?? '') ||
-        compareStrings(a.id, b.id));
-}
-const LAYER_RANK = new Map([
-    ['semantic', 0],
-    ['episodic', 1],
-    ['trace', 2],
-    ['buffer', 3],
-]);
-function layerRank(layer) {
-    return LAYER_RANK.get(layer ?? '') ?? LAYER_RANK.size;
-}
-function compareStrings(a, b) {
-    return a < b ? -1 : a > b ? 1 : 0;
-}
-function compareTags(a, b) {
-    const ua = [...new Set(a ?? [])].sort();
-    const ub = [...new Set(b ?? [])].sort();
-    if (ua.length !== ub.length)
-        return ub.length - ua.length;
-    // element-wise, not a joined string: a separator inside a tag would collide
-    for (let i = 0; i < ua.length; i++) {
-        const c = compareStrings(ua[i], ub[i]);
-        if (c !== 0)
-            return c;
-    }
-    return 0;
-}
-/**
- * score descending -> `compareEntryIdentity`. The shared ordering rule for
- * every score-primary recall sort site (search.ts, shared.ts, goals.ts,
- * api.ts, cli.ts, graph-recall.ts, multihop.ts, rerankers/cross-encoder.ts).
- * Sites delegate wholesale to this (via a thin arrow where the element
- * shape's score field is named something other than `score`, e.g.
- * `rerankScore`) rather than reimplementing `b.score - a.score` locally, so
- * the tiebreak can't silently drift between call sites.
- */
-export function compareScoredResults(a, b) {
-    const d = b.score - a.score;
-    return d !== 0 ? d : compareEntryIdentity(a.entry, b.entry);
-}
-/**
- * Build a score-desc -> tie-key comparator for the physics layer.
- *
- * `ScoredPhysicsResult` (physics.ts) carries `{ memoryId, baseScore,
- * clusterAmplification, finalScore }` -- NO `entry`/`content` in scope at
- * that layer, so `compareEntryIdentity` cannot apply directly. With only the
- * default memoryId key this is PER-INSTANCE-ONLY determinism; callers that need
- * CROSS-INGEST stability supply `tieKeyOf` mapping the result to its memory
- * CONTENT, because the baseScore tie order selects the cluster_top_k
- * amplification set, which MUTATES scores before the content-aware merge sort.
- *
- * A factory (not a fixed-field comparator) because physics.ts re-sorts the
- * same result array by two different score fields in sequence (`baseScore`
- * for top-K selection, then `finalScore` after cluster amplification) — one
- * shared tiebreak rule, parameterised by which field is primary this pass.
- */
-export function comparePhysicsResultsBy(scoreOf, tieKeyOf) {
-    return (a, b) => {
-        const d = scoreOf(b) - scoreOf(a);
-        if (d !== 0)
-            return d;
-        const ai = tieKeyOf ? tieKeyOf(a) : a.memoryId;
-        const bi = tieKeyOf ? tieKeyOf(b) : b.memoryId;
-        if (ai < bi)
-            return -1;
-        if (ai > bi)
-            return 1;
-        // Tie-key collision (e.g. duplicate content): fall through to memoryId
-        // so the comparator still yields a total order within one store.
-        return a.memoryId < b.memoryId ? -1 : a.memoryId > b.memoryId ? 1 : 0;
-    };
-}
-//# sourceMappingURL=compare.js.map

package/dist/connectors/github/cli-impl.d.ts

@@ -1,25 +0,0 @@
-/**
- * Implementation of `hippo github` CLI subcommands. Extracted from the main
- * cli.ts so unit tests can import these functions directly without triggering
- * the cli.ts main() side effects. The cli.ts dispatcher re-exports the
- * top-level cmdGithub.
- *
- * Subcommands mirror the Slack connector shape (cli.ts §Slack subcommands):
- *   - hippo github backfill --repo <owner/name> [--since ISO] [--max <N>]
- *   - hippo github dlq list
- *   - hippo github dlq replay <id> [--force]
- */
-import { type GitHubFetcher } from './octokit-client.js';
-type FlagValue = string | boolean | string[];
-type Flags = Record<string, FlagValue>;
-export declare function printGithubBackfillUsage(): void;
-/**
- * `hippo github backfill`. The fetcher is injectable so tests can drive the
- * code path without hitting the network. Defaults to `realGitHubFetcher`.
- */
-export declare function cmdGithubBackfill(hippoRoot: string, flags: Flags, fetcher?: GitHubFetcher): Promise<void>;
-export declare function cmdGithubDlqList(hippoRoot: string, _flags: Flags): void;
-export declare function cmdGithubDlqReplay(hippoRoot: string, args: string[], flags: Flags): Promise<void>;
-export declare function cmdGithub(hippoRoot: string, args: string[], flags: Flags): Promise<void>;
-export {};
-//# sourceMappingURL=cli-impl.d.ts.map