hippo-memory 1.68.0 → 1.70.0

package/dist/decisions.js

@@ -1,326 +0,0 @@
-/**
- * Decision first-class object.
- *
- * `hippo decide` used to write only a tagged memory (tags ['decision'], source
- * 'decision') with a 90-day half-life, so an in-force decision decayed out of
- * recall even though it was never reversed. The `decisions` table is now the
- * source of truth: a decision stays `active` regardless of memory decay, and
- * `hippo decide list --status active` is authoritative. A memory row still
- * mirrors the decision for recall surfaces but is NOT canonical — memory_id is
- * NULLABLE with ON DELETE SET NULL so forget/consolidate/archive gracefully
- * orphans the decision row.
- *
- * Lifecycle: active -> superseded (a newer decision replaces it; superseded_by
- * points to the successor) or active -> closed (retired with no successor).
- *
- * Tenant scoping: every helper requires tenantId. BEFORE INSERT/UPDATE triggers
- * enforce decisions.tenant_id == the referenced memory's tenant_id, and a
- * superseded_by same-tenant trigger makes cross-tenant supersession
- * unrepresentable. Mirrors the predictions pattern (src/predictions.ts).
- *
- * Dual-write atomicity: `saveDecision` writes the memory + decisions row (and,
- * when superseding, the old row's UPDATE) inside writeEntry's SAVEPOINT
- * 'write_entry' (store/entry-writes.ts) via the afterWrite hook, so a failure in any
- * step rolls all of them back. Pattern matches savePrediction (predictions.ts).
- */
-import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
-import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry } from './store/entry-writes.js';
-import { assertTenantId } from './tenant.js';
-import { markGraphDirty, removeGraphEntitiesForObject } from './graph/write.js';
-import { createMemory, Layer } from './memory.js';
-import { appendAuditEvent } from './audit.js';
-import { objectHalfLifeDays } from './half-life-migration.js';
-import { keysetAfter } from './keyset.js';
-export const VALID_DECISION_STATES = new Set([
-    'active',
-    'superseded',
-    'closed',
-]);
-function rowToDecision(row) {
-    return {
-        id: row.id,
-        memoryId: row.memory_id,
-        tenantId: row.tenant_id,
-        decisionText: row.decision_text,
-        context: row.context,
-        // SAFETY: status is DB-constrained to VALID_DECISION_STATES; this module
-        // is the only writer and always inserts one of those literal strings.
-        status: row.status,
-        supersededBy: row.superseded_by,
-        supersededAt: row.superseded_at,
-        closedAt: row.closed_at,
-        createdAt: row.created_at,
-    };
-}
-const DECISION_COLS = `
-  id, memory_id, tenant_id, decision_text, context, status,
-  superseded_by, superseded_at, closed_at, created_at
-`;
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/** The legacy `hippo decide` memory mirror for a decision. */
-function buildDecisionMemory(hippoRoot, tenantId, opts) {
-    const content = opts.context
-        ? `${opts.decisionText}\n\nContext: ${opts.context}`
-        : opts.decisionText;
-    const tags = ['decision', ...(opts.extraTags ?? [])];
-    return createMemory(content, {
-        tags,
-        layer: Layer.Semantic,
-        confidence: 'verified',
-        source: 'decision',
-        baseHalfLifeDays: objectHalfLifeDays(hippoRoot),
-        tenantId,
-    });
-}
-// Preflight the supersede target BEFORE inserting the new row. The new
-// row's autoincrement id could otherwise collide with a non-existent
-// supersedesDecisionId (e.g. superseding id 1 on an empty store, where the
-// INSERT below would itself become id 1), making the row supersede itself.
-// Validating first means the new row is never a candidate for its own
-// supersede UPDATE.
-function preflightDecisionSupersede(db, tenantId, supersedesId) {
-    // SAFETY: row shape matches the single `status` column named in the SELECT below.
-    const pred = db.prepare(`SELECT status FROM decisions WHERE id = ? AND tenant_id = ?`).get(supersedesId, tenantId);
-    if (!pred) {
-        throw new NotFoundError(`saveDecision: decision ${supersedesId} to supersede not found for tenant ${tenantId}`);
-    }
-    if (pred.status !== 'active') {
-        throw new ConflictError(`saveDecision: decision ${supersedesId} is not active (status='${pred.status}'); only active decisions can be superseded.`);
-    }
-}
-function insertDecisionRow(db, memoryId, tenantId, opts, now) {
-    const result = db.prepare(`
-    INSERT INTO decisions(
-      memory_id, tenant_id, decision_text, context,
-      status, superseded_by, superseded_at, closed_at, created_at
-    ) VALUES (?, ?, ?, ?, 'active', NULL, NULL, NULL, ?)
-  `).run(memoryId, tenantId, opts.decisionText, opts.context ?? null, now);
-    return Number(result.lastInsertRowid ?? 0);
-}
-// Supersede the (preflight-validated) prior active decision in the SAME
-// SAVEPOINT, atomic with the new row. The `id != decisionId` exclusion is
-// defense-in-depth against the self-match described above; combined with
-// the preflight, a 0-change here is unreachable in the single-writer txn.
-function supersedeDecisionRow(db, tenantId, actor, supersedesId, decisionId, now) {
-    const sup = db.prepare(`
-    UPDATE decisions
-    SET status = 'superseded', superseded_by = ?, superseded_at = ?
-    WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
-  `).run(decisionId, now, supersedesId, tenantId, decisionId);
-    if (sup.changes === 0) {
-        throw new ConflictError(`saveDecision: decision ${supersedesId} could not be superseded (no longer active or self-reference).`);
-    }
-    appendAuditEvent(db, {
-        tenantId,
-        actor,
-        op: 'decision_supersede',
-        targetId: String(supersedesId),
-        metadata: {
-            decision_id: supersedesId,
-            superseded_by: decisionId,
-        },
-    });
-}
-/** The afterWrite body: preflight, INSERT, supersede, reload, create audit, all in one SAVEPOINT. */
-function writeDecisionRow(db, memoryId, tenantId, opts, actor, now) {
-    if (opts.supersedesDecisionId !== undefined) {
-        preflightDecisionSupersede(db, tenantId, opts.supersedesDecisionId);
-    }
-    const decisionId = insertDecisionRow(db, memoryId, tenantId, opts, now);
-    if (opts.supersedesDecisionId !== undefined) {
-        supersedeDecisionRow(db, tenantId, actor, opts.supersedesDecisionId, decisionId, now);
-    }
-    // SAFETY: row's shape matches the columns named in DECISION_COLS above.
-    const row = db.prepare(`SELECT ${DECISION_COLS} FROM decisions WHERE id = ?`)
-        .get(decisionId);
-    if (!row)
-        throw new Error('saveDecision: failed to reload saved decision row');
-    // GDPR-light metadata: id + flag only, no decision_text.
-    appendAuditEvent(db, {
-        tenantId,
-        actor,
-        op: 'decision_create',
-        targetId: String(decisionId),
-        metadata: {
-            decision_id: decisionId,
-            has_context: opts.context !== undefined && opts.context !== null && opts.context !== '',
-        },
-    });
-    return row;
-}
-/**
- * Create a decision. Writes the memory mirror + the decisions row atomically
- * inside writeEntry's SAVEPOINT 'write_entry'. When supersedesDecisionId is
- * given, the referenced ACTIVE row is UPDATEd -> superseded in the SAME
- * SAVEPOINT (CAS: WHERE status='active'; throws on changes===0 so a duplicate
- * supersede aborts the whole write rather than orphaning a successor).
- *
- * The memory mirror preserves the legacy `hippo decide` shape: tags
- * ['decision', ...extraTags], source 'decision', confidence 'verified',
- * the half-life objectHalfLifeDays picks, content = "<text>\n\nContext: <context>"
- * when context is given (so existing recall output is unchanged).
- */
-export function saveDecision(hippoRoot, tenantId, opts, actor = 'cli') {
-    assertTenantId('saveDecision', tenantId);
-    if (!opts.decisionText)
-        throw new BadRequestError('saveDecision: decisionText is required');
-    const now = new Date().toISOString();
-    const mem = buildDecisionMemory(hippoRoot, tenantId, opts);
-    // Populated inside afterWrite so the INSERT, the supersede UPDATE, and the
-    // memory write all share one SAVEPOINT.
-    let savedRow;
-    writeEntry(hippoRoot, mem, {
-        actor,
-        afterWrite: (db, memoryId) => {
-            savedRow = writeDecisionRow(db, memoryId, tenantId, opts, actor, now);
-        },
-        // Post-commit hook: mark the tenant's graph dirty AFTER the DB row commits
-        // but BEFORE the markdown mirrors are written, so a mirror-write failure can
-        // never leave a committed save unflagged. markGraphDirty is fail-soft.
-        afterCommit: () => markGraphDirty(hippoRoot, tenantId, mem.id),
-    });
-    if (!savedRow) {
-        // Unreachable unless afterWrite threw first; defensive.
-        throw new Error('saveDecision: afterWrite did not populate the row');
-    }
-    return rowToDecision(savedRow);
-}
-/**
- * Close (retire) an active decision with no successor. Updates the decisions
- * row only; the memory mirror is not mutated. CAS guard mirrors closePrediction
- * (predictions.ts): WHERE status='active'; 0 changes distinguishes not-found
- * from not-active so callers surface the right error.
- */
-export function closeDecision(hippoRoot, tenantId, id, actor = 'cli') {
-    assertTenantId('closeDecision', tenantId);
-    const now = new Date().toISOString();
-    const db = openHippoDb(hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const updateResult = db.prepare(`
-        UPDATE decisions
-        SET status = 'closed', closed_at = ?
-        WHERE id = ? AND tenant_id = ? AND status = 'active'
-      `).run(now, id, tenantId);
-            if (updateResult.changes === 0) {
-                // SAFETY: row shape matches the single `status` column named in the SELECT above.
-                const existing = db.prepare(`SELECT status FROM decisions WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
-                if (!existing) {
-                    throw new NotFoundError(`closeDecision: decision ${id} not found for tenant ${tenantId}`);
-                }
-                throw new ConflictError(`closeDecision: decision ${id} is not active (status='${existing.status}'); only active decisions can be closed.`);
-            }
-            // SAFETY: row's shape matches the columns named in DECISION_COLS above.
-            const row = db.prepare(`SELECT ${DECISION_COLS} FROM decisions WHERE id = ? AND tenant_id = ?`)
-                .get(id, tenantId);
-            if (!row)
-                throw new NotFoundError(`closeDecision: decision ${id} not found after UPDATE`);
-            appendAuditEvent(db, {
-                tenantId,
-                actor,
-                op: 'decision_close',
-                targetId: String(id),
-                metadata: { decision_id: id },
-            });
-            db.exec('COMMIT');
-            const closed = rowToDecision(row);
-            // After COMMIT (write lock released), before the finally closes `db`.
-            // Closing removes the object from the graph. Remove its rows DIRECTLY (deterministic),
-            // not only via an enqueued rebuild whose queue item is lost if the mirror is later
-            // forgotten (the queue row cascade-deletes with the memory), which would leave the closed
-            // object stale and could block that forget. Still enqueue when a mirror exists
-            // so a concurrent rebuild re-derives consistently (harmless if it also runs).
-            removeGraphEntitiesForObject(hippoRoot, tenantId, 'decision', closed.id);
-            if (closed.memoryId) {
-                markGraphDirty(hippoRoot, tenantId, closed.memoryId);
-            }
-            return closed;
-        }
-        catch (e) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch {
-                // Ignore rollback failures — the throw below is what matters.
-            }
-            throw e;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadDecisionById(hippoRoot, tenantId, id) {
-    assertTenantId('loadDecisionById', tenantId);
-    const db = openHippoDb(hippoRoot);
-    try {
-        // SAFETY: row's shape matches the columns named in DECISION_COLS above.
-        const row = db.prepare(`SELECT ${DECISION_COLS} FROM decisions WHERE id = ? AND tenant_id = ?`)
-            .get(id, tenantId);
-        return row ? rowToDecision(row) : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadDecisions(hippoRoot, tenantId, opts = {}) {
-    assertTenantId('loadDecisions', tenantId);
-    const limit = opts.limit ?? 100;
-    const after = keysetAfter('created_at', 'id', opts.after);
-    const db = openHippoDb(hippoRoot);
-    try {
-        let rows;
-        if (opts.status) {
-            if (!VALID_DECISION_STATES.has(opts.status)) {
-                throw new BadRequestError(`loadDecisions: status must be one of ${Array.from(VALID_DECISION_STATES).join('|')}; got ${opts.status}`);
-            }
-            // SAFETY: rows' shape matches the columns named in DECISION_COLS above.
-            rows = db.prepare(`
-        SELECT ${DECISION_COLS} FROM decisions
-        WHERE tenant_id = ? AND status = ?${after.sql}
-        ORDER BY created_at DESC, id DESC
-        LIMIT ?
-      `).all(tenantId, opts.status, ...after.params, limit);
-        }
-        else {
-            // SAFETY: rows' shape matches the columns named in DECISION_COLS above.
-            rows = db.prepare(`
-        SELECT ${DECISION_COLS} FROM decisions
-        WHERE tenant_id = ?${after.sql}
-        ORDER BY created_at DESC, id DESC
-        LIMIT ?
-      `).all(tenantId, ...after.params, limit);
-        }
-        return rows.map(rowToDecision);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadActiveDecisions(hippoRoot, tenantId, opts = {}) {
-    return loadDecisions(hippoRoot, tenantId, { status: 'active', limit: opts.limit });
-}
-/**
- * Resolve a `--supersedes <memory-id>` (the legacy CLI contract) to the table id
- * of the ACTIVE decision backed by that memory, or null when the memory has no
- * active decision row (a legacy pre-episode decision-tagged memory). Extracted
- * so the CLI's backward-compat path is unit-testable at the store layer without
- * exporting cmdDecide.
- */
-export function resolveActiveDecisionIdByMemory(hippoRoot, tenantId, memoryId) {
-    assertTenantId('resolveActiveDecisionIdByMemory', tenantId);
-    const db = openHippoDb(hippoRoot);
-    try {
-        // SAFETY: row shape matches the single `id` column named in the SELECT above.
-        const row = db.prepare(`SELECT id FROM decisions WHERE memory_id = ? AND tenant_id = ? AND status = 'active' ORDER BY id DESC LIMIT 1`).get(memoryId, tenantId);
-        return row ? row.id : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-//# sourceMappingURL=decisions.js.map

package/dist/extract.js

@@ -1,133 +0,0 @@
-import { Layer, createMemory } from './memory.js';
-import { writeEntry } from './store/entry-writes.js';
-import { loadConfig } from './config.js';
-import { RejectedValueError } from './rejection.js';
-import { redactSecretsStrict } from './secret-detect.js';
-import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
-import { neverAutoShareTags } from './shared.js';
-import { log } from './log.js';
-import { isJsonString } from './json.js';
-import { certainDefect } from './memory-quality.js';
-const EXTRACTION_PROMPT = `You are extracting factual statements from a conversation or memory entry. Extract 1-8 standalone factual statements that would be useful to remember later.
-
-Rules:
-- Each fact must be a complete, standalone sentence
-- Include the speaker's name in every fact (e.g. "Alice prefers..." not "She prefers...")
-- Preserve specific details: names, numbers, dates, paths, IDs
-- Return a JSON array of objects with: content (string), tags (array of "speaker:X" and "topic:Y" strings), valence ("neutral", "positive", "negative", or "critical")
-- Return an empty array [] for small talk with no extractable facts
-- Output ONLY the JSON array, no preamble or explanation
-
-Input text:
-`;
-export async function extractFacts(text, opts) {
-    const model = opts.model ?? 'claude-sonnet-4-6';
-    const fetchFn = opts.fetcher ?? fetch;
-    let res;
-    try {
-        res = await fetchWithRetry('https://api.anthropic.com/v1/messages', {
-            method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                'x-api-key': opts.apiKey,
-                'anthropic-version': '2023-06-01',
-            },
-            body: JSON.stringify({
-                model,
-                max_tokens: 1200,
-                messages: [{ role: 'user', content: EXTRACTION_PROMPT + redactSecretsStrict(text) }],
-            }),
-        }, { timeoutMs: llmTimeoutMs(), fetchFn });
-    }
-    catch (err) {
-        opts.onError?.(`request failed: ${err instanceof Error ? err.message : String(err)}`);
-        return [];
-    }
-    if (!res.ok) {
-        opts.onError?.(`HTTP ${res.status}`);
-        return [];
-    }
-    try {
-        const data = await res.json();
-        const raw = data.content?.[0]?.text?.trim() ?? '';
-        if (!raw)
-            return [];
-        const parsed = JSON.parse(raw);
-        if (!Array.isArray(parsed))
-            return [];
-        const validValences = new Set(['neutral', 'positive', 'negative', 'critical']);
-        const facts = [];
-        for (const item of parsed) {
-            if (facts.length >= 8)
-                break;
-            if (!item ||
-                !isJsonString(item.content) ||
-                item.content.length < 3)
-                continue;
-            const itemTags = item.tags;
-            const tags = Array.isArray(itemTags)
-                ? itemTags.filter((t) => isJsonString(t))
-                : [];
-            // SAFETY: validValences.has(item.valence) above confirms item.valence is one of the four literal strings of EmotionalValence.
-            const valence = validValences.has(item.valence)
-                ? item.valence
-                : 'neutral';
-            facts.push({ content: item.content, tags, valence });
-        }
-        return facts;
-    }
-    catch (err) {
-        opts.onError?.(`unparseable response: ${err instanceof Error ? err.message : String(err)}`);
-        return [];
-    }
-}
-const INHERITABLE_PREFIXES = ['conv:', 'session:', 'scope:', 'path:'];
-export function storeExtractedFacts(hippoRoot, source, facts) {
-    const inheritedTags = [
-        ...source.tags.filter((t) => INHERITABLE_PREFIXES.some((p) => t.startsWith(p))),
-        ...neverAutoShareTags([source]),
-    ];
-    const entries = [];
-    let rejected = 0;
-    const baseHalfLifeDays = loadConfig(hippoRoot).defaultHalfLifeDays;
-    for (const fact of facts) {
-        const defect = certainDefect(fact.content);
-        if (defect !== null) {
-            log.warn(`storeExtractedFacts: skipped automatic quality defect (${defect})`);
-            continue;
-        }
-        const tags = ['extracted', ...inheritedTags, ...fact.tags];
-        const entry = { ...createMemory(fact.content, {
-                layer: Layer.Semantic,
-                tags,
-                emotional_valence: fact.valence,
-                confidence: 'inferred',
-                source: source.source,
-                extracted_from: source.id,
-                scope: source.scope,
-                // Without it createMemory stamps 'default', and extracted facts leave
-                // the tenant of the episodic memory they were extracted from.
-                tenantId: source.tenantId,
-                baseHalfLifeDays,
-            }), origin_project: source.origin_project };
-        // A refusal is per-VALUE: one rejected fact must not
-        // drop the rest of this batch. writeEntry has already audited the
-        // refusal (reject_refusal) before rethrowing, so skip-and-count here.
-        try {
-            writeEntry(hippoRoot, entry);
-        }
-        catch (err) {
-            if (err instanceof RejectedValueError) {
-                rejected++;
-                continue;
-            }
-            throw err;
-        }
-        entries.push(entry);
-    }
-    if (rejected > 0) {
-        log.warn(`storeExtractedFacts: skipped ${rejected} rejected value(s)`);
-    }
-    return entries;
-}
-//# sourceMappingURL=extract.js.map

package/dist/graph/rows.d.ts

@@ -1,45 +0,0 @@
-import type { Entity, Relation, GraphQueueItem } from './types.js';
-export interface EntityRow {
-    id: number;
-    tenant_id: string;
-    entity_type: string;
-    name: string;
-    memory_id: string | null;
-    source_kind: string;
-    source_object_type: string | null;
-    source_object_id: number | null;
-    created_at: string;
-}
-export interface RelationRow {
-    id: number;
-    tenant_id: string;
-    from_entity_id: number;
-    to_entity_id: number;
-    rel_type: string;
-    memory_id: string | null;
-    source_kind: string;
-    source_object_type: string | null;
-    source_object_id: number | null;
-    created_at: string;
-}
-export interface QueueRow {
-    id: number;
-    tenant_id: string;
-    memory_id: string;
-    kind: string;
-    status: string;
-    enqueued_at: string;
-    processed_at: string | null;
-}
-export declare function rowToEntity(row: EntityRow): Entity;
-export declare function rowToRelation(row: RelationRow): Relation;
-export declare function rowToQueueItem(row: QueueRow): GraphQueueItem;
-export declare const ENTITY_COLS = "id, tenant_id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id, created_at";
-export declare const RELATION_COLS = "id, tenant_id, from_entity_id, to_entity_id, rel_type, memory_id, source_kind, source_object_type, source_object_id, created_at";
-export declare const QUEUE_COLS = "id, tenant_id, memory_id, kind, status, enqueued_at, processed_at";
-export interface DbLike {
-    prepare(sql: string): {
-        get<T>(...params: unknown[]): T;
-    };
-}
-//# sourceMappingURL=rows.d.ts.map

package/dist/graph/types.js

@@ -1,11 +0,0 @@
-export const GRAPH_ENTITY_TYPES = new Set([
-    'person', 'project', 'customer', 'system', 'policy', 'decision',
-]);
-export const GRAPH_RELATION_TYPES = new Set([
-    'owns', 'supersedes', 'depends-on', 'blocked-by', 'references',
-]);
-export const VALID_QUEUE_STATES = new Set([
-    'pending', 'processed', 'skipped',
-]);
-export const MAX_ENTITY_NAME_LEN = 512;
-//# sourceMappingURL=types.js.map