hippo-memory 1.69.0 → 1.71.0

package/dist/half-life-migration.js

@@ -1,182 +0,0 @@
-/**
- * Moving a store's memories to a new default half-life.
- *
- * Each memory stores its own `half_life_days`, set at write from the
- * default base and a few write-time multipliers (`deriveHalfLife`). Changing
- * the default therefore reaches only new memories; without this migration a
- * store would mix old-base and new-base memories, a state the decay
- * evaluation never tested. The rule, declared before any run:
- *
- * - only a memory still on the old base is rescaled: its half-life is
- *   `deriveHalfLife(from, entry)` plus its recall bonus. A memory hippo shortened since
- *   (invalidated, superseded, a merge source, marked bad) or one with its own
- *   fixed half-life (decisions, incidents, customer notes) keeps its value;
- * - every rescale is written to the audit log with the ids, so it can be
- *   undone, and the store records the base it is on (`meta`), so the
- *   migration runs once.
- *
- * `hippo sleep` runs it before its decay pass, from the base the store is on
- * (7 days when never recorded) to the configured `defaultHalfLifeDays`. Once per store it also
- * moves memories of live decisions, incidents and other objects off the flat 90 days they used to get.
- */
-import { deriveHalfLife } from './memory.js';
-import { openStore, HALF_LIFE_BASE_META_KEY, TYPED_HALF_LIFE_META_KEY } from './store/open.js';
-import { selectAllEntries } from './store/entry-reads.js';
-import { openHippoDb, closeHippoDb, getMeta, setMeta } from './db.js';
-import { appendAuditEvent } from './audit.js';
-import { loadConfig } from './config.js';
-/** The base every store used before the base was recorded. */
-export const LEGACY_HALF_LIFE_BASE = 7;
-/** The flat half-life the decision, incident and other object writers gave their memories before they took the default. */
-export const LEGACY_TYPED_HALF_LIFE = 90;
-const TYPED_SOURCES = new Set(['decision', 'incident', 'process', 'policy', 'skill', 'project_brief', 'customer_note']);
-const OBJECT_TABLES = ['decisions', 'incidents', 'processes', 'policies', 'skills', 'project_briefs', 'customer_notes'];
-export { HALF_LIFE_BASE_META_KEY };
-/** Recall bonus over `written`, the half-life `entry` got at write, or null when off it; each recall added 2 days. */
-export function halfLifeRecallBonus(entry, written) {
-    if (entry.superseded_by || entry.tags.includes('invalidated') || entry.tags.includes('superseded'))
-        return null;
-    const bonus = entry.half_life_days - written;
-    const k = Math.round(bonus / 2);
-    return Math.abs(bonus - 2 * k) < 1e-9 && k >= 0 && k <= entry.retrieval_count ? bonus : null;
-}
-/** The entries to rescale from `from` to `to`, as copies that keep their recall bonus. Pure. */
-export function planHalfLifeMigration(entries, from, to) {
-    if (from === to)
-        return [];
-    return entries.flatMap((e) => {
-        const bonus = halfLifeRecallBonus(e, deriveHalfLife(from, e));
-        return bonus === null ? [] : [{ ...e, half_life_days: deriveHalfLife(to, e) + bonus }];
-    });
-}
-/** Memories of decisions, incidents and other objects still on the flat 90 days, as copies on `to` that keep their recall bonus. Pure. */
-export function planTypedHalfLifeMigration(entries, to) {
-    return entries.flatMap((e) => {
-        const bonus = TYPED_SOURCES.has(e.source) ? halfLifeRecallBonus(e, LEGACY_TYPED_HALF_LIFE) : null;
-        const next = bonus === null ? e.half_life_days : deriveHalfLife(to, e) + bonus;
-        return next === e.half_life_days ? [] : [{ ...e, half_life_days: next }];
-    });
-}
-/** The base this store's memories are on. */
-export function storeHalfLifeBase(hippoRoot) {
-    const db = openHippoDb(hippoRoot);
-    try {
-        return readBase(db);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-function readBase(db) {
-    const raw = Number(getMeta(db, HALF_LIFE_BASE_META_KEY, String(LEGACY_HALF_LIFE_BASE)));
-    return Number.isFinite(raw) && raw > 0 ? raw : LEGACY_HALF_LIFE_BASE;
-}
-/** The base an object writer gives its memory: the flat 90 days until this store's typed migration has run, which then moves them, and the default after. */
-export function objectHalfLifeDays(hippoRoot) {
-    // SHORTCUT: read outside the write's transaction, so a write racing the typed migration keeps 90; read inside writeEntry if that ever matters.
-    const db = openStore(hippoRoot);
-    try {
-        return getMeta(db, TYPED_HALF_LIFE_META_KEY, '') === '' ? LEGACY_TYPED_HALF_LIFE : loadConfig(hippoRoot).defaultHalfLifeDays;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * Move the store's memories from the base they are on, and those of objects from
- * the old flat 90 days, to `to`, once. Under `dryRun` nothing is written, the recorded
- * base included.
- */
-export function migrateDefaultHalfLife(hippoRoot, to, opts = {}) {
-    const dryRun = opts.dryRun ?? false;
-    const noop = (from) => ({ from, to, rescaled: 0, typed: 0, kept: 0, dryRun, halfLives: new Map() });
-    const db = openStore(hippoRoot);
-    try {
-        // Plan, write, audit and record the base under one write lock, so a concurrent write or sleep cannot interleave.
-        if (!dryRun)
-            db.exec('BEGIN IMMEDIATE');
-        try {
-            const from = readBase(db);
-            const typedPending = getMeta(db, TYPED_HALF_LIFE_META_KEY, '') === '';
-            if (!(Number.isFinite(to) && to > 0) || (from === to && !typedPending)) {
-                if (!dryRun)
-                    db.exec('COMMIT');
-                return noop(from);
-            }
-            const all = selectAllEntries(db);
-            const objects = typedPending ? objectMemoryIds(db) : { all: new Set(), retired: new Set() };
-            const losers = typedPending ? conflictLosers(db) : new Set();
-            const copies = new Set(all.flatMap((e) => (e.superseded_by ? [e.superseded_by] : [])));
-            // Provenance before shape: an object's memory came from its writer, a supersede copy from the base (it keeps the source). Shape decides the rest.
-            const objectWritten = (e) => objects.all.has(e.id) || (!copies.has(e.id) && TYPED_SOURCES.has(e.source) && halfLifeRecallBonus(e, LEGACY_TYPED_HALF_LIFE) !== null);
-            const typedPlan = typedPending ? planTypedHalfLifeMigration(all.filter((e) => objectWritten(e) && !objects.retired.has(e.id) && !losers.has(e.id)), to) : [];
-            const basePlan = planHalfLifeMigration(typedPending ? all.filter((e) => !objectWritten(e)) : all, from, to);
-            const plan = [...basePlan, ...typedPlan];
-            const halfLives = new Map(plan.map((e) => [e.id, e.half_life_days]));
-            const result = { from, to, rescaled: basePlan.length, typed: typedPlan.length, kept: all.length - plan.length, dryRun, halfLives };
-            if (dryRun)
-                return result;
-            const old = new Map(all.map((e) => [e.id, e.half_life_days]));
-            const actor = opts.actor ?? 'system';
-            writePlan(db, basePlan, old, { from, to, actor });
-            writePlan(db, typedPlan, old, { from: LEGACY_TYPED_HALF_LIFE, to, actor });
-            setMeta(db, HALF_LIFE_BASE_META_KEY, String(to));
-            setMeta(db, TYPED_HALF_LIFE_META_KEY, '1');
-            db.exec('COMMIT');
-            return result;
-        }
-        catch (err) {
-            if (!dryRun)
-                db.exec('ROLLBACK');
-            throw err;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** Memories behind every object, and those behind a superseded or closed one. Retiring an object leaves its memory untouched, so only its table knows. */
-function objectMemoryIds(db) {
-    const all = new Set();
-    const retired = new Set();
-    for (const table of OBJECT_TABLES) {
-        // SAFETY: SELECT of two TEXT columns, filtered to a non-null memory_id.
-        const rows = db.prepare(`SELECT memory_id, status FROM ${table} WHERE memory_id IS NOT NULL`).all();
-        for (const r of rows) {
-            all.add(r.memory_id);
-            if (r.status === 'superseded' || r.status === 'closed')
-                retired.add(r.memory_id);
-        }
-    }
-    return { all, retired };
-}
-/** Memories that lost a conflict, which resolveConflict halved untagged. A resolved conflict with no audit row (resolved before resolves were audited, or found stale) names no winner, so both sides count. */
-function conflictLosers(db) {
-    // SAFETY: SELECT of two fields every conflict_resolve audit row carries (ConflictResolveMeta in store.ts).
-    const audited = db.prepare(`SELECT json_extract(metadata_json, '$.conflictId') AS conflictId, json_extract(metadata_json, '$.loserId') AS loserId FROM audit_log WHERE op = 'conflict_resolve'`).all();
-    const losers = new Set(audited.map((a) => a.loserId));
-    const named = new Set(audited.map((a) => a.conflictId));
-    // SAFETY: SELECT of three columns of resolved conflicts.
-    const resolved = db.prepare(`SELECT id, memory_a_id, memory_b_id FROM memory_conflicts WHERE status = 'resolved'`).all();
-    for (const c of resolved)
-        if (!named.has(c.id))
-            losers.add(c.memory_a_id).add(c.memory_b_id);
-    return losers;
-}
-/** Writes `plan`, then one audit event per tenant with each id's old half-life, so the move can be undone. */
-function writePlan(db, plan, old, move) {
-    const update = db.prepare('UPDATE memories SET half_life_days = ? WHERE id = ?');
-    const byTenant = new Map();
-    for (const e of plan) {
-        update.run(e.half_life_days, e.id);
-        // One record per tenant, filled in place: copying it per row made the write grow with the square of the store.
-        let record = byTenant.get(e.tenantId);
-        if (!record)
-            byTenant.set(e.tenantId, (record = {}));
-        record[e.id] = old.get(e.id);
-    }
-    for (const [tenantId, oldHalfLives] of byTenant) {
-        appendAuditEvent(db, { tenantId, actor: move.actor, op: 'half_life_migrate', metadata: { from: move.from, to: move.to, ids: Object.keys(oldHalfLives), oldHalfLives } });
-    }
-}
-//# sourceMappingURL=half-life-migration.js.map

package/dist/handoff.js

@@ -1,68 +0,0 @@
-/**
- * Session handoff types and helpers.
- *
- * A handoff captures the state of a session so that a successor
- * session (or a different agent) can pick up where the previous
- * one left off.
- */
-/** Narrows an unvalidated value (e.g. CLI input or event content) to a HandoffOutcome. */
-export function isHandoffOutcome(v) {
-    return v === 'success' || v === 'failure' || v === 'partial';
-}
-/** Renders evidence as one line shared by every renderer (CLI, MCP, token accounting). */
-export function formatHandoffEvidenceLine(evidence) {
-    const gitRef = evidence.gitRef ?? 'unknown';
-    const tree = evidence.dirtyTree === true ? 'dirty' : evidence.dirtyTree === false ? 'clean' : 'unknown';
-    const tests = evidence.testStatus ?? 'unknown';
-    return `git ${gitRef}, tree ${tree}, tests ${tests}`;
-}
-export function rowToSessionHandoff(row) {
-    let artifacts = [];
-    try {
-        const parsed = JSON.parse(row.artifacts_json);
-        if (Array.isArray(parsed)) {
-            artifacts = parsed.map((item) => String(item));
-        }
-    }
-    catch {
-        // A corrupt column degrades to empty instead of hiding the whole handoff.
-        artifacts = [];
-    }
-    let constraints = [];
-    try {
-        const parsed = row.constraints_json ? JSON.parse(row.constraints_json) : [];
-        if (Array.isArray(parsed)) {
-            constraints = parsed.map((item) => String(item));
-        }
-    }
-    catch {
-        // Same degrade-to-empty rule as artifacts.
-        constraints = [];
-    }
-    let evidence = null;
-    try {
-        // SAFETY: catch below falls back to null on malformed JSON, so a wrong shape never escapes.
-        evidence = row.evidence_json ? JSON.parse(row.evidence_json) : null;
-    }
-    catch {
-        // Same degrade rule as artifacts: bad evidence reads as none.
-        evidence = null;
-    }
-    return {
-        version: 1,
-        sessionId: row.session_id,
-        repoRoot: row.repo_root ?? undefined,
-        taskId: row.task_id ?? undefined,
-        summary: row.summary,
-        nextAction: row.next_action ?? undefined,
-        artifacts,
-        scope: row.scope ?? null,
-        updatedAt: row.created_at,
-        constraints,
-        evidence,
-        outcome: isHandoffOutcome(row.outcome) ? row.outcome : null,
-        targetRuntime: row.target_runtime ?? null,
-        cardId: row.card_id ?? null,
-    };
-}
-//# sourceMappingURL=handoff.js.map

package/dist/home-path.js

@@ -1,24 +0,0 @@
-// Home-directory paths name their user, so text bound for a shared store tests or masks them here; no imports keep it light.
-// VS Code writes file links URL-encoded, so a separator may be %5C or %2F.
-const WIN_SEP = String.raw `(?:[\\/]|%5C|%2F)`;
-const WIN_CHAR = String.raw `(?:(?!%5C|%2F)[^\\/:*?"<>|\s])`;
-// A Windows name never holds a quote, so JSON stops it; one with spaces runs to a separator, quote, closing mark or line end, leaving the mark, as stopping at its first word leaks the surname.
-const WIN_USER = String.raw `(?:${WIN_CHAR}+(?: ${WIN_CHAR}+){0,3}(?=${WIN_SEP}|["'\`)\]>,;]|\.(?=\s|$)|(?<!\.)(?:[^\S ]|$))(?<![\`)\],;'])|${WIN_CHAR}+)`;
-/** One pattern per path shape that carries a user name: Windows, Git Bash and WSL mounts, extended-length, UNC home shares, Linux, macOS and 8.3 short names. */
-export const USER_SEGMENT = [
-    new RegExp(String.raw `[A-Za-z](?::|%3A)${WIN_SEP}+(?:Users|Documents and Settings)${WIN_SEP}+${WIN_USER}`, 'i'),
-    new RegExp(String.raw `(?<![\w.])(?:\/mnt)?\/[A-Za-z]\/Users\/${WIN_USER}`, 'i'),
-    /\\\\\?\\/,
-    new RegExp(String.raw `\\\\[^\\/\s]+\\+(?:homes?|users|profiles?)\$?\\+${WIN_USER}`, 'i'),
-    /(?<![\w.~-])(?:\/var)?\/home\/[^/\s]+/,
-    /(?<![\w.~-])(?:\/var)?\/root(?![\w.-])/,
-    /(?<![\w.~-])\/Users\/[^/\s]+/,
-    /[\\/][A-Z0-9_$]{1,6}~\d{1,6}(?:\.[A-Z0-9]{1,3})?(?![\w~])|\b[A-Z0-9_$]{1,6}~\d{1,6}(?:\.[A-Z0-9]{1,3})?[\\/]/,
-];
-// Global copies, so the shared test patterns keep their lastIndex at 0.
-const USER_SEGMENT_ALL = USER_SEGMENT.map((re) => new RegExp(re.source, `${re.flags}g`));
-/** `text` with each home-directory segment replaced by `[home]`. */
-export function maskHomePaths(text) {
-    return USER_SEGMENT_ALL.reduce((out, re) => out.replace(re, '[home]'), text);
-}
-//# sourceMappingURL=home-path.js.map

package/dist/http-retry.js

@@ -1,51 +0,0 @@
-/** One retry policy for outbound HTTP: a timeout on every attempt, and backoff on 429 and 5xx only. */
-import { envLlmTimeoutMs } from './env.js';
-const DEFAULT_ATTEMPTS = 3;
-const DEFAULT_BASE_DELAY_MS = 250;
-const DEFAULT_MAX_DELAY_MS = 8_000;
-const DEFAULT_LLM_TIMEOUT_MS = 60_000;
-/** LLM calls (consolidation refine, DAG summaries, fact extraction) share one budget; `HIPPO_LLM_TIMEOUT_MS` overrides it. */
-export function llmTimeoutMs() {
-    return envLlmTimeoutMs() ?? DEFAULT_LLM_TIMEOUT_MS;
-}
-export function isRetryableStatus(status) {
-    return status === 429 || (status >= 500 && status <= 599);
-}
-/** Retry-After as milliseconds: delta-seconds or an HTTP date; null when absent or unreadable. */
-export function parseRetryAfterMs(header, now = Date.now()) {
-    if (header === null || header.trim() === '')
-        return null;
-    const seconds = Number(header);
-    if (Number.isFinite(seconds))
-        return Math.max(0, seconds * 1000);
-    const at = Date.parse(header);
-    return Number.isNaN(at) ? null : Math.max(0, at - now);
-}
-const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-/** `fetch` with a per-attempt timeout and up to `attempts` tries on 429 and 5xx; the last response comes back as is and transport errors throw at once. */
-export async function fetchWithRetry(url, init, policy) {
-    const fetchFn = policy.fetchFn ?? fetch;
-    const attempts = Math.max(1, policy.attempts ?? DEFAULT_ATTEMPTS);
-    const baseDelayMs = policy.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
-    const maxDelayMs = policy.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
-    const sleep = policy.sleep ?? realSleep;
-    const random = policy.random ?? Math.random;
-    const retryOn = policy.retryOn ?? ((res) => isRetryableStatus(res.status));
-    for (let attempt = 1;; attempt++) {
-        const timeout = AbortSignal.timeout(policy.timeoutMs);
-        const signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
-        const res = await fetchFn(url, { ...init, signal });
-        if (!retryOn(res) || attempt >= attempts)
-            return res;
-        const retryAfter = parseRetryAfterMs(res.headers.get('retry-after'));
-        if (retryAfter !== null && retryAfter > maxDelayMs)
-            return res;
-        // Jitter over the upper half keeps parallel callers from retrying in lockstep.
-        const ceiling = Math.min(maxDelayMs, baseDelayMs * 2 ** (attempt - 1));
-        const delay = retryAfter ?? ceiling / 2 + random() * (ceiling / 2);
-        // Frees the pooled socket before the next attempt.
-        await res.body?.cancel();
-        await sleep(delay);
-    }
-}
-//# sourceMappingURL=http-retry.js.map

package/dist/incidents.d.ts

@@ -1,103 +0,0 @@
-/**
- * Incident first-class object.
- *
- * An incident is a postmortem capsule: a recorded operational event with a
- * lifecycle and optional linked receipts (the memories that are its evidence).
- * The `incidents` table is the source of truth: an incident stays `open`
- * regardless of memory decay. A memory row still mirrors the incident for
- * recall surfaces but is NOT canonical — memory_id is NULLABLE with ON DELETE
- * SET NULL so forget/consolidate/archive gracefully orphans the incident row.
- *
- * Lifecycle: open -> resolved (a resolution was recorded; the incident stays on
- * record with resolution_text + resolved_at) or open|resolved -> closed
- * (retired with closed_at). This is NOT decision's supersede: there is no
- * superseded_by self-FK, no supersede CAS, and no supersede trigger.
- *
- * Tenant scoping: every helper requires tenantId. BEFORE INSERT/UPDATE triggers
- * enforce incidents.tenant_id == the referenced memory's tenant_id. Mirrors the
- * v30 decisions pattern (src/decisions.ts).
- *
- * Dual-write atomicity: `saveIncident` writes the memory + incidents row inside
- * writeEntry's SAVEPOINT 'write_entry' (store.ts) via the afterWrite hook, so a
- * failure in any step rolls all of them back. Pattern matches saveDecision.
- *
- * linked_memory_ids ("linked receipts"): a JSON-encoded array of memory ids on
- * the row, default `[]`. On save, every id must exist in the SAME tenant; a
- * cross-tenant or nonexistent id is rejected (throw) before the insert.
- */
-import { type KeysetPosition } from './keyset.js';
-export type IncidentStatus = 'open' | 'resolved' | 'closed';
-export declare const VALID_INCIDENT_STATES: ReadonlySet<IncidentStatus>;
-export interface Incident {
-    id: number;
-    /** Nullable: ON DELETE SET NULL lets memory deletion (forget / consolidate /
-     *  archive) proceed without breaking the incident row. */
-    memoryId: string | null;
-    tenantId: string;
-    incidentText: string;
-    context: string | null;
-    status: IncidentStatus;
-    /** Set only when status === 'resolved'. */
-    resolutionText: string | null;
-    resolvedAt: string | null;
-    closedAt: string | null;
-    /** Linked receipts: memory ids that are this incident's evidence. */
-    linkedMemoryIds: string[];
-    createdAt: string;
-}
-export interface SaveIncidentOpts {
-    incidentText: string;
-    context?: string;
-    /** Memory ids (linked receipts) that are this incident's evidence. Each must
-     *  exist in the same tenant; cross-tenant/nonexistent ids are rejected. */
-    linkedMemoryIds?: string[];
-    /** Extra memory tags merged after ['incident'] (the CLI passes path-context
-     *  tags; HTTP/SDK pass none). */
-    extraTags?: string[];
-}
-export interface ListIncidentsOpts {
-    status?: IncidentStatus;
-    limit?: number;
-    /** Resume after this row: the position the previous page ended on. */
-    after?: KeysetPosition;
-}
-/**
- * Create an incident. Writes the memory mirror + the incidents row atomically
- * inside writeEntry's SAVEPOINT 'write_entry'.
- *
- * The memory mirror: tags ['incident', ...extraTags], source 'incident',
- * confidence 'verified', the half-life objectHalfLifeDays picks, content =
- * "<text>\n\nContext: <context>" when context is given.
- *
- * linked_memory_ids are validated BEFORE insert: each must exist in the SAME
- * tenant. A cross-tenant or nonexistent id throws and rolls back the whole
- * write. The validated ids are stored as JSON.stringify(validated).
- */
-export declare function saveIncident(hippoRoot: string, tenantId: string, opts: SaveIncidentOpts, actor?: string): Incident;
-/**
- * Resolve an open incident (open -> resolved). Records resolution_text +
- * resolved_at; the incident stays on record. CAS guard: WHERE status='open';
- * 0 changes distinguishes not-found from not-open so callers surface the right
- * error. Emits incident_resolve.
- */
-export declare function resolveIncident(hippoRoot: string, tenantId: string, id: number, resolutionText: string, actor?: string): Incident;
-/**
- * Close (retire) an incident from open or resolved (open|resolved -> closed).
- * Updates closed_at only; the memory mirror is not mutated. CAS guard: WHERE
- * status IN ('open','resolved'); 0 changes distinguishes not-found from
- * wrong-state. Emits incident_close.
- */
-export declare function closeIncident(hippoRoot: string, tenantId: string, id: number, actor?: string): Incident;
-export declare function loadIncidentById(hippoRoot: string, tenantId: string, id: number): Incident | null;
-export declare function loadIncidents(hippoRoot: string, tenantId: string, opts?: ListIncidentsOpts): Incident[];
-export declare function loadOpenIncidents(hippoRoot: string, tenantId: string, opts?: {
-    limit?: number;
-}): Incident[];
-/**
- * Resolve a memory id to the table id of the OPEN incident backed by that
- * memory, or null when the memory has no open incident row. Extracted so a
- * memory-id-based lookup is unit-testable at the store layer (mirror of
- * resolveActiveDecisionIdByMemory).
- */
-export declare function resolveActiveIncidentIdByMemory(hippoRoot: string, tenantId: string, memoryId: string): number | null;
-//# sourceMappingURL=incidents.d.ts.map