hippo-memory 1.69.0 → 1.70.0

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

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