hippo-memory 1.69.0 → 1.71.0

package/dist/skills.js

@@ -1,367 +0,0 @@
-/**
- * Skills as a first-class, versioned object.
- *
- * A `skill` is a reusable, agent-followable capability: an `instructions` body
- * plus an optional `trigger` ("when to apply"), evolving via the supersede delta
- * lifecycle. "Executable" is scoped to an agent-followable INSTRUCTION that, once
- * exported into the agent's in-force rules (AGENTS.md / CLAUDE.md) via
- * `exportSkills`, is executed by the agent reading it. Literal code/command
- * execution is deferred (security; a future sandbox). The distinguishing
- * capability is therefore the EXPORT renderer, not a runtime.
- *
- * Reuses the process/decision supersede machinery verbatim (superseded_by self-FK
- * + CAS + INSERT-preflight + server-derived version + change_summary + supersede
- * tenant-match trigger). It DROPS process's `steps` (a skill's content is a single
- * `instructions` body) and ADDS `trigger` (stored in the `trigger_text` column -
- * `trigger` is a SQLite reserved keyword).
- *
- * The `skills` table is the source of truth (survives memory decay); the memory
- * mirror is for recall. memory_id is NULLABLE with ON DELETE SET NULL.
- *
- * Lifecycle: active -> superseded (a newer version replaces it) or active ->
- * closed (retired). Export renders ACTIVE skills only.
- */
-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 { 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_SKILL_STATES = new Set([
-    'active',
-    'superseded',
-    'closed',
-]);
-/** Field caps (untrusted at the HTTP/SDK boundary). instructions is a body, so a
- *  larger cap than the 4096 short-field convention. */
-export const MAX_SKILL_NAME_LEN = 256;
-export const MAX_SKILL_INSTRUCTIONS_LEN = 8192;
-export const MAX_SKILL_TRIGGER_LEN = 1024;
-/** Aggregate bound on a single export render so the export body is never unbounded.
- *  Realistic active-skill counts are tens; 1000 is a generous bound. */
-export const MAX_EXPORT_SKILLS = 1000;
-/**
- * Validate + normalise skill fields. skill_name is trimmed and MUST be a single
- * line (no newlines) so it cannot break the H2 header in the export render.
- * instructions are kept verbatim (operator content) but capped.
- * Returns the normalised name + trigger (null when absent/empty).
- */
-function validateSkillFields(skillName, instructions, trigger) {
-    const name = (skillName ?? '').trim();
-    if (name.length === 0)
-        throw new BadRequestError('saveSkill: skillName is required');
-    if (/[\r\n]/.test(name))
-        throw new BadRequestError('saveSkill: skillName must be a single line (no newlines)');
-    if (name.length > MAX_SKILL_NAME_LEN) {
-        throw new BadRequestError(`saveSkill: skillName exceeds the ${MAX_SKILL_NAME_LEN}-char cap`);
-    }
-    if (!instructions || instructions.trim().length === 0) {
-        throw new BadRequestError('saveSkill: instructions are required');
-    }
-    if (instructions.length > MAX_SKILL_INSTRUCTIONS_LEN) {
-        throw new BadRequestError(`saveSkill: instructions exceed the ${MAX_SKILL_INSTRUCTIONS_LEN}-char cap`);
-    }
-    let triggerVal = null;
-    if (trigger !== undefined && trigger !== null && trigger.trim().length > 0) {
-        if (trigger.length > MAX_SKILL_TRIGGER_LEN) {
-            throw new BadRequestError(`saveSkill: trigger exceeds the ${MAX_SKILL_TRIGGER_LEN}-char cap`);
-        }
-        // Single-line, like skill_name: a trigger is a short "when to apply" phrase,
-        // and a newline would let it forge a heading inside the export **When:** line.
-        // Reject rather than emit a multi-line trigger.
-        if (/[\r\n]/.test(trigger)) {
-            throw new BadRequestError('saveSkill: trigger must be a single line (no newlines)');
-        }
-        triggerVal = trigger;
-    }
-    return { name, trigger: triggerVal };
-}
-function rowToSkill(row) {
-    return {
-        id: row.id,
-        memoryId: row.memory_id,
-        tenantId: row.tenant_id,
-        skillName: row.skill_name,
-        instructions: row.instructions,
-        trigger: row.trigger_text,
-        version: row.version,
-        // SAFETY: status is DB-constrained to VALID_SKILL_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,
-        changeSummary: row.change_summary,
-        closedAt: row.closed_at,
-        createdAt: row.created_at,
-    };
-}
-const SKILL_COLS = `
-  id, memory_id, tenant_id, skill_name, instructions, trigger_text, version, status,
-  superseded_by, superseded_at, change_summary, closed_at, created_at
-`;
-/** Recall-surface content for the memory mirror: name + optional trigger +
- *  instructions. Named (mirrors buildProcessContent) so the recall surface is
- *  deterministic + unit-testable. */
-function buildSkillContent(skillName, instructions, trigger) {
-    let content = skillName;
-    if (trigger)
-        content += `\n\nWhen: ${trigger}`;
-    content += `\n\n${instructions}`;
-    return content;
-}
-// Preflight the supersede target BEFORE inserting the new row (so the new
-// autoincrement id can never be its own supersede target); read the
-// predecessor version in the same SELECT for server-derived versioning.
-// Mirrors saveProcess / savePolicy.
-function preflightSkillSupersede(db, tenantId, supersedesId) {
-    // SAFETY: row shape matches the `status, version` columns named in the SELECT below.
-    const pred = db.prepare(`SELECT status, version FROM skills WHERE id = ? AND tenant_id = ?`).get(supersedesId, tenantId);
-    if (!pred) {
-        throw new NotFoundError(`saveSkill: skill ${supersedesId} to supersede not found for tenant ${tenantId}`);
-    }
-    if (pred.status !== 'active') {
-        throw new ConflictError(`saveSkill: skill ${supersedesId} is not active (status='${pred.status}'); only active skills can be superseded.`);
-    }
-    return pred.version + 1;
-}
-function insertSkillRow(db, memoryId, w, version) {
-    const result = db.prepare(`
-    INSERT INTO skills(
-      memory_id, tenant_id, skill_name, instructions, trigger_text, version,
-      status, superseded_by, superseded_at, change_summary, closed_at, created_at
-    ) VALUES (?, ?, ?, ?, ?, ?, 'active', NULL, NULL, ?, NULL, ?)
-  `).run(memoryId, w.tenantId, w.name, w.instructions, w.trigger, version, w.changeSummary, w.now);
-    return Number(result.lastInsertRowid ?? 0);
-}
-function supersedeSkillRow(db, w, supersedesId, skillId, version) {
-    const sup = db.prepare(`
-    UPDATE skills
-    SET status = 'superseded', superseded_by = ?, superseded_at = ?
-    WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
-  `).run(skillId, w.now, supersedesId, w.tenantId, skillId);
-    if (sup.changes === 0) {
-        throw new ConflictError(`saveSkill: skill ${supersedesId} could not be superseded (no longer active or self-reference).`);
-    }
-    appendAuditEvent(db, {
-        tenantId: w.tenantId,
-        actor: w.actor,
-        op: 'skill_supersede',
-        targetId: String(supersedesId),
-        metadata: {
-            skill_id: supersedesId,
-            superseded_by: skillId,
-            new_version: version,
-        },
-    });
-}
-/** The afterWrite body: preflight, INSERT, supersede, reload, create audit, all in one SAVEPOINT. */
-function writeSkillRow(db, memoryId, w) {
-    const version = w.supersedesId !== undefined ? preflightSkillSupersede(db, w.tenantId, w.supersedesId) : 1;
-    const skillId = insertSkillRow(db, memoryId, w, version);
-    if (w.supersedesId !== undefined)
-        supersedeSkillRow(db, w, w.supersedesId, skillId, version);
-    // SAFETY: row's shape matches the columns named in SKILL_COLS above.
-    const row = db.prepare(`SELECT ${SKILL_COLS} FROM skills WHERE id = ?`)
-        .get(skillId);
-    if (!row)
-        throw new Error('saveSkill: failed to reload saved skill row');
-    // GDPR-light metadata: ids + flags only, no skill text.
-    appendAuditEvent(db, {
-        tenantId: w.tenantId,
-        actor: w.actor,
-        op: 'skill_create',
-        targetId: String(skillId),
-        metadata: {
-            skill_id: skillId,
-            version,
-            has_trigger: w.trigger !== null,
-        },
-    });
-    return row;
-}
-/**
- * Create a skill (or a new version that supersedes an existing one). Writes the
- * memory mirror + the skills row atomically inside writeEntry's SAVEPOINT. When
- * supersedesSkillId is given, the referenced ACTIVE row is preflighted (status +
- * version) BEFORE the INSERT, then CAS-UPDATEd -> superseded in the same SAVEPOINT;
- * the new version = predecessor.version + 1 (server-derived).
- */
-export function saveSkill(hippoRoot, tenantId, opts, actor = 'cli') {
-    assertTenantId('saveSkill', tenantId);
-    const { name, trigger } = validateSkillFields(opts.skillName, opts.instructions, opts.trigger);
-    const isSupersede = opts.supersedesSkillId !== undefined;
-    const changeSummary = isSupersede ? (opts.changeSummary ?? null) : null;
-    const now = new Date().toISOString();
-    const content = buildSkillContent(name, opts.instructions, trigger);
-    const tags = ['skill', ...(opts.extraTags ?? [])];
-    const mem = createMemory(content, {
-        tags,
-        layer: Layer.Semantic,
-        confidence: 'verified',
-        source: 'skill',
-        baseHalfLifeDays: objectHalfLifeDays(hippoRoot),
-        tenantId,
-    });
-    const w = {
-        tenantId,
-        actor,
-        name,
-        instructions: opts.instructions,
-        trigger,
-        changeSummary,
-        supersedesId: opts.supersedesSkillId,
-        now,
-    };
-    let savedRow;
-    writeEntry(hippoRoot, mem, {
-        actor,
-        afterWrite: (db, memoryId) => {
-            savedRow = writeSkillRow(db, memoryId, w);
-        },
-    });
-    if (!savedRow) {
-        throw new Error('saveSkill: afterWrite did not populate the row');
-    }
-    return rowToSkill(savedRow);
-}
-/**
- * Close (retire) an active skill. CAS guard WHERE status='active'; 0 changes
- * distinguishes not-found from not-active. A superseded row is terminal.
- */
-export function closeSkill(hippoRoot, tenantId, id, actor = 'cli') {
-    assertTenantId('closeSkill', tenantId);
-    const now = new Date().toISOString();
-    const db = openHippoDb(hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const updateResult = db.prepare(`
-        UPDATE skills
-        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 skills WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
-                if (!existing) {
-                    throw new NotFoundError(`closeSkill: skill ${id} not found for tenant ${tenantId}`);
-                }
-                throw new ConflictError(`closeSkill: skill ${id} is not active (status='${existing.status}'); only active skills can be closed.`);
-            }
-            // SAFETY: row's shape matches the columns named in SKILL_COLS above.
-            const row = db.prepare(`SELECT ${SKILL_COLS} FROM skills WHERE id = ? AND tenant_id = ?`)
-                .get(id, tenantId);
-            if (!row)
-                throw new NotFoundError(`closeSkill: skill ${id} not found after UPDATE`);
-            appendAuditEvent(db, {
-                tenantId,
-                actor,
-                op: 'skill_close',
-                targetId: String(id),
-                metadata: { skill_id: id },
-            });
-            db.exec('COMMIT');
-            return rowToSkill(row);
-        }
-        catch (e) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch {
-                // Ignore rollback failures — the throw below is what matters.
-            }
-            throw e;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadSkillById(hippoRoot, tenantId, id) {
-    assertTenantId('loadSkillById', tenantId);
-    const db = openHippoDb(hippoRoot);
-    try {
-        // SAFETY: row's shape matches the columns named in SKILL_COLS above.
-        const row = db.prepare(`SELECT ${SKILL_COLS} FROM skills WHERE id = ? AND tenant_id = ?`)
-            .get(id, tenantId);
-        return row ? rowToSkill(row) : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadSkills(hippoRoot, tenantId, opts = {}) {
-    assertTenantId('loadSkills', 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_SKILL_STATES.has(opts.status)) {
-                throw new BadRequestError(`loadSkills: status must be one of ${Array.from(VALID_SKILL_STATES).join('|')}; got ${opts.status}`);
-            }
-            // SAFETY: rows' shape matches the columns named in SKILL_COLS above.
-            rows = db.prepare(`
-        SELECT ${SKILL_COLS} FROM skills
-        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 SKILL_COLS above.
-            rows = db.prepare(`
-        SELECT ${SKILL_COLS} FROM skills
-        WHERE tenant_id = ?${after.sql}
-        ORDER BY created_at DESC, id DESC
-        LIMIT ?
-      `).all(tenantId, ...after.params, limit);
-        }
-        return rows.map(rowToSkill);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function loadActiveSkills(hippoRoot, tenantId, opts = {}) {
-    return loadSkills(hippoRoot, tenantId, { status: 'active', limit: opts.limit });
-}
-/**
- * Render the tenant's ACTIVE skills into ONE AGENTS.md / CLAUDE.md-style markdown
- * block (one H2 per skill, ordered by skill_name ASC for determinism), and RETURN
- * the string. Does NOT write any file. Returns '' when there are no active skills.
- *
- * skill_name is single-line (validated on save) so it cannot break the H2 header;
- * instructions are emitted verbatim (operator content). Bounded by MAX_EXPORT_SKILLS
- * active rows; each field is capped on save, so the rendered string is bounded.
- */
-export function exportSkills(hippoRoot, tenantId) {
-    assertTenantId('exportSkills', tenantId);
-    const db = openHippoDb(hippoRoot);
-    try {
-        // SAFETY: rows' shape matches the columns named in SKILL_COLS above.
-        const rows = db.prepare(`
-      SELECT ${SKILL_COLS} FROM skills
-      WHERE tenant_id = ? AND status = 'active'
-      ORDER BY skill_name ASC, id ASC
-      LIMIT ?
-    `).all(tenantId, MAX_EXPORT_SKILLS);
-        return rows
-            .map(rowToSkill)
-            .map((s) => {
-            let block = `## ${s.skillName}`;
-            if (s.trigger)
-                block += `\n\n**When:** ${s.trigger}`;
-            block += `\n\n${s.instructions}`;
-            return block;
-        })
-            .join('\n\n');
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-//# sourceMappingURL=skills.js.map

package/dist/store/entry-writes-group.d.ts

@@ -1,9 +0,0 @@
-import { type DatabaseSyncLike } from '../db.js';
-import type { EntryWrites, SupersedeWrite } from '../store-port.js';
-/** Each call on its own handle; mirrors and the forgotten counter follow the commit, so a rolled-back write leaves neither. */
-export declare function sqliteEntryWrites(hippoRoot: string): EntryWrites;
-/** Reach, the CAS on the old row, the successor's insert and the supersede row in one BEGIN IMMEDIATE transaction. Two racing supersedes: one CAS wins. */
-export declare function commitSupersede(db: DatabaseSyncLike, write: SupersedeWrite): void;
-/** A mirror left on disk would bring the archived row back on the next import; on failure the reaper retries, as mirror_cleaned_at stays NULL. */
-export declare function cleanArchivedMirrors(db: DatabaseSyncLike, hippoRoot: string, id: string): void;
-//# sourceMappingURL=entry-writes-group.d.ts.map

package/dist/store/vector-writes.d.ts

@@ -1,6 +0,0 @@
-import { type DatabaseSyncLike } from '../db.js';
-import type { MemoryEntry } from '../memory.js';
-import type { VectorBackfillQuery, VectorWrite, VectorWriteResult } from '../store-port.js';
-export declare function entriesWithoutVectorAt(db: DatabaseSyncLike, query: VectorBackfillQuery): MemoryEntry[];
-export declare function writeVectorsAt(db: DatabaseSyncLike, write: VectorWrite): VectorWriteResult;
-//# sourceMappingURL=vector-writes.d.ts.map

package/dist/store/vector-writes.js

@@ -1,59 +0,0 @@
-// hippo.db's half of the VectorWrites store group.
-import { setMeta, withWriteScope } from '../db.js';
-import { embeddingIndexStateOn, replacesIndex } from '../embeddings.js';
-import { float32ToBuffer } from '../physics-state.js';
-import { EMBEDDING_MODEL_META_KEY, upsertVectors } from '../vector-store.js';
-import { chunked } from './entry-reads.js';
-import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
-const MAX_BACKFILL_PAGE = 500;
-export function entriesWithoutVectorAt(db, query) {
-    if (!Number.isInteger(query.limit))
-        throw new RangeError('limit must be an integer');
-    const limit = Math.max(1, Math.min(query.limit, MAX_BACKFILL_PAGE));
-    const tenantClause = query.tenantId === undefined ? '' : ' AND tenant_id = ?';
-    const tenantArgs = query.tenantId === undefined ? [] : [query.tenantId];
-    // SAFETY: selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
-    const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id > ?${tenantClause}
-       AND NOT EXISTS (SELECT 1 FROM memory_vectors v WHERE v.memory_id = memories.id AND v.model = ?)
-     ORDER BY id LIMIT ?`).all(query.afterId ?? '', ...tenantArgs, query.model, limit);
-    return rows.map(rowToEntry);
-}
-function ownedIds(db, ids, tenantId) {
-    const owned = new Set();
-    for (const chunk of chunked([...new Set(ids)])) {
-        // SAFETY: the SELECT names one column, id.
-        const rows = db.prepare(`SELECT id FROM memories WHERE tenant_id = ? AND id IN (${chunk.map(() => '?').join(', ')})`).all(tenantId, ...chunk);
-        for (const row of rows)
-            owned.add(row.id);
-    }
-    return owned;
-}
-// savePhysicsState opens its own transaction and overwrites, so the first particle for a memory is inserted here instead.
-function insertNewParticles(db, rows) {
-    const stmt = db.prepare(`
-    INSERT INTO memory_physics (memory_id, position_blob, velocity_blob, mass, charge, temperature, last_simulation)
-    VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(memory_id) DO NOTHING
-  `);
-    for (const { memoryId, particle: p } of rows) {
-        if (p)
-            stmt.run(memoryId, float32ToBuffer(p.position), float32ToBuffer(p.velocity), p.mass, p.charge, p.temperature, p.lastSimulation);
-    }
-}
-export function writeVectorsAt(db, write) {
-    return withWriteScope(db, 'write_vectors', () => {
-        const replaces = replacesIndex(embeddingIndexStateOn(db), write.model);
-        if (replaces && !write.replaceIndex)
-            return { written: 0, modelMismatch: true };
-        const owned = ownedIds(db, write.rows.map((r) => r.memoryId), write.tenantId);
-        const rows = write.rows.filter((r) => owned.has(r.memoryId) && r.vector.length > 0 && r.vector.every(Number.isFinite));
-        if (rows.length === 0)
-            return { written: 0, modelMismatch: false };
-        if (replaces)
-            db.exec('DELETE FROM memory_vectors; DELETE FROM memory_physics;');
-        const written = upsertVectors(db, rows.map((r) => [r.memoryId, r.vector]), write.model);
-        insertNewParticles(db, rows);
-        setMeta(db, EMBEDDING_MODEL_META_KEY, write.model);
-        return { written, modelMismatch: false };
-    });
-}
-//# sourceMappingURL=vector-writes.js.map