@psiclawops/hypermem 0.9.0 → 0.9.1

package/dist/preference-store.js

@@ -1,109 +0,0 @@
-/**
- * hypermem Preference Store
- *
- * Behavioral patterns observed about people, systems, and workflows.
- * Lives in the central library DB.
- * "operator prefers architectural stability" is a preference, not a fact.
- */
-function nowIso() {
-    return new Date().toISOString();
-}
-function parseRow(row) {
-    return {
-        id: row.id,
-        subject: row.subject,
-        domain: row.domain,
-        key: row.key,
-        value: row.value,
-        agentId: row.agent_id,
-        confidence: row.confidence,
-        visibility: row.visibility || 'fleet',
-        sourceType: row.source_type || 'observation',
-        sourceRef: row.source_ref || null,
-        createdAt: row.created_at,
-        updatedAt: row.updated_at,
-    };
-}
-export class PreferenceStore {
-    db;
-    constructor(db) {
-        this.db = db;
-    }
-    /**
-     * Set or update a preference. Upserts on (subject, domain, key).
-     */
-    set(subject, key, value, opts) {
-        const now = nowIso();
-        const domain = opts?.domain || 'general';
-        const result = this.db.prepare(`
-      INSERT INTO preferences (subject, domain, key, value, agent_id, confidence,
-        visibility, source_type, source_ref, created_at, updated_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      ON CONFLICT(subject, domain, key) DO UPDATE SET
-        value = excluded.value,
-        confidence = excluded.confidence,
-        agent_id = excluded.agent_id,
-        source_type = excluded.source_type,
-        source_ref = excluded.source_ref,
-        updated_at = excluded.updated_at
-    `).run(subject, domain, key, value, opts?.agentId || 'system', opts?.confidence || 1.0, opts?.visibility || 'fleet', opts?.sourceType || 'observation', opts?.sourceRef || null, now, now);
-        const id = Number(result.lastInsertRowid);
-        return {
-            id,
-            subject,
-            domain,
-            key,
-            value,
-            agentId: opts?.agentId || 'system',
-            confidence: opts?.confidence || 1.0,
-            visibility: opts?.visibility || 'fleet',
-            sourceType: opts?.sourceType || 'observation',
-            sourceRef: opts?.sourceRef || null,
-            createdAt: now,
-            updatedAt: now,
-        };
-    }
-    /**
-     * Get a specific preference.
-     */
-    get(subject, key, domain = 'general') {
-        const row = this.db.prepare('SELECT * FROM preferences WHERE subject = ? AND domain = ? AND key = ?').get(subject, domain, key);
-        return row ? parseRow(row) : null;
-    }
-    /**
-     * Get all preferences for a subject.
-     */
-    getForSubject(subject, domain) {
-        let sql = 'SELECT * FROM preferences WHERE subject = ?';
-        const params = [subject];
-        if (domain) {
-            sql += ' AND domain = ?';
-            params.push(domain);
-        }
-        sql += ' ORDER BY domain, key';
-        const rows = this.db.prepare(sql).all(...params);
-        return rows.map(parseRow);
-    }
-    /**
-     * Search preferences by value content.
-     */
-    search(query, subject) {
-        let sql = 'SELECT * FROM preferences WHERE (value LIKE ? OR key LIKE ?)';
-        const params = [`%${query}%`, `%${query}%`];
-        if (subject) {
-            sql += ' AND subject = ?';
-            params.push(subject);
-        }
-        sql += ' ORDER BY confidence DESC LIMIT 20';
-        const rows = this.db.prepare(sql).all(...params);
-        return rows.map(parseRow);
-    }
-    /**
-     * Delete a preference.
-     */
-    delete(subject, key, domain = 'general') {
-        const result = this.db.prepare('DELETE FROM preferences WHERE subject = ? AND domain = ? AND key = ?').run(subject, domain, key);
-        return result.changes > 0;
-    }
-}
-//# sourceMappingURL=preference-store.js.map

package/dist/preservation-gate.d.ts

@@ -1,82 +0,0 @@
-/**
- * hypermem Preservation Gate
- *
- * Verifies that a proposed compaction summary preserves the semantic
- * content of its source messages by measuring geometric fidelity in
- * embedding space.
- *
- * Before a summary replaces raw messages, it must pass two checks:
- *
- *   1. Centroid Alignment — the summary embedding must be close to the
- *      centroid of the source message embeddings (cos similarity).
- *
- *   2. Source Coverage — the summary must have positive cosine similarity
- *      with each individual source message (averaged).
- *
- * If the combined preservation score falls below the threshold, the
- * summary is rejected. The caller should fall back to extractive
- * compaction (concatenation/selection) rather than accepting a
- * semantically drifted summary.
- *
- * This prevents the silent failure mode where a confident summarizer
- * produces fluent text that has drifted away from the original meaning
- * in vector space — making it unretrievable by the very system that
- * will later search for it.
- *
- * Inspired by the Nomic-space preservation gate in openclaw-memory-libravdb
- * (mathematics-v2.md §5.3), adapted for our Ollama + sqlite-vec stack.
- */
-import { type EmbeddingConfig } from './vector-store.js';
-export interface PreservationResult {
-    /** Cosine similarity between summary and source centroid */
-    alignment: number;
-    /** Average positive cosine similarity between summary and each source */
-    coverage: number;
-    /** Combined score: (alignment + coverage) / 2, clamped to [0, 1] */
-    score: number;
-    /** Whether the summary passed the preservation gate */
-    passed: boolean;
-    /** The threshold used for the gate */
-    threshold: number;
-}
-export interface PreservationConfig {
-    /**
-     * Minimum combined preservation score for a summary to be accepted.
-     * Default: 0.65 (same as libravdb's shipped default).
-     *
-     * At 0.65, the summary must be meaningfully close to the source cluster.
-     * Lower values accept more drift; higher values are stricter.
-     * Range: [0, 1].
-     */
-    threshold: number;
-    /** Embedding config for Ollama calls (used by async path only) */
-    embedding?: Partial<EmbeddingConfig>;
-}
-/**
- * Verify that a summary preserves its source content in embedding space.
- *
- * SYNCHRONOUS PATH — for when you already have pre-computed embeddings
- * (e.g., from the background indexer or vector store cache).
- *
- * This is the preferred path: no network calls, no async, deterministic.
- *
- * @param summaryEmbedding - The embedding of the proposed summary
- * @param sourceEmbeddings - Embeddings of the source messages being replaced
- * @param config - Preservation threshold config
- */
-export declare function verifyPreservationFromVectors(summaryEmbedding: Float32Array, sourceEmbeddings: Float32Array[], config?: Partial<PreservationConfig>): PreservationResult;
-/**
- * Verify that a summary preserves its source content in embedding space.
- *
- * ASYNC PATH — generates embeddings via Ollama on demand.
- * Use when pre-computed embeddings aren't available.
- *
- * This makes N+1 embedding calls (1 for summary, N for sources if not cached).
- * For batch compaction, prefer pre-computing embeddings and using the sync path.
- *
- * @param summaryText - The proposed summary text
- * @param sourceTexts - The source message texts being replaced
- * @param config - Preservation threshold and embedding config
- */
-export declare function verifyPreservation(summaryText: string, sourceTexts: string[], config?: Partial<PreservationConfig>): Promise<PreservationResult>;
-//# sourceMappingURL=preservation-gate.d.ts.map

package/dist/preservation-gate.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"preservation-gate.d.ts","sourceRoot":"","sources":["../src/preservation-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAI7E,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,EAAE,OAAO,CAAC;IAChB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;CACtC;AA4DD;;;;;;;;;;;GAWG;AACH,wBAAgB,6BAA6B,CAC3C,gBAAgB,EAAE,YAAY,EAC9B,gBAAgB,EAAE,YAAY,EAAE,EAChC,MAAM,GAAE,OAAO,CAAC,kBAAkB,CAAM,GACvC,kBAAkB,CAmCpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EAAE,EACrB,MAAM,GAAE,OAAO,CAAC,kBAAkB,CAAM,GACvC,OAAO,CAAC,kBAAkB,CAAC,CAqB7B"}

package/dist/preservation-gate.js

@@ -1,150 +0,0 @@
-/**
- * hypermem Preservation Gate
- *
- * Verifies that a proposed compaction summary preserves the semantic
- * content of its source messages by measuring geometric fidelity in
- * embedding space.
- *
- * Before a summary replaces raw messages, it must pass two checks:
- *
- *   1. Centroid Alignment — the summary embedding must be close to the
- *      centroid of the source message embeddings (cos similarity).
- *
- *   2. Source Coverage — the summary must have positive cosine similarity
- *      with each individual source message (averaged).
- *
- * If the combined preservation score falls below the threshold, the
- * summary is rejected. The caller should fall back to extractive
- * compaction (concatenation/selection) rather than accepting a
- * semantically drifted summary.
- *
- * This prevents the silent failure mode where a confident summarizer
- * produces fluent text that has drifted away from the original meaning
- * in vector space — making it unretrievable by the very system that
- * will later search for it.
- *
- * Inspired by the Nomic-space preservation gate in openclaw-memory-libravdb
- * (mathematics-v2.md §5.3), adapted for our Ollama + sqlite-vec stack.
- */
-import { generateEmbeddings } from './vector-store.js';
-const DEFAULT_PRESERVATION_CONFIG = {
-    threshold: 0.65,
-};
-// ─── Math Utilities ─────────────────────────────────────────────
-/**
- * Cosine similarity between two Float32Arrays.
- * Returns value in [-1, 1]. Handles zero-norm vectors gracefully (returns 0).
- */
-function cosineSimilarity(a, b) {
-    if (a.length !== b.length) {
-        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
-    }
-    let dot = 0;
-    let normA = 0;
-    let normB = 0;
-    for (let i = 0; i < a.length; i++) {
-        dot += a[i] * b[i];
-        normA += a[i] * a[i];
-        normB += b[i] * b[i];
-    }
-    const denom = Math.sqrt(normA) * Math.sqrt(normB);
-    if (denom === 0)
-        return 0;
-    return dot / denom;
-}
-/**
- * Compute the centroid (element-wise mean) of an array of vectors.
- */
-function computeCentroid(vectors) {
-    if (vectors.length === 0) {
-        throw new Error('Cannot compute centroid of empty vector set');
-    }
-    const dim = vectors[0].length;
-    const centroid = new Float32Array(dim);
-    for (const vec of vectors) {
-        for (let i = 0; i < dim; i++) {
-            centroid[i] += vec[i];
-        }
-    }
-    const n = vectors.length;
-    for (let i = 0; i < dim; i++) {
-        centroid[i] /= n;
-    }
-    return centroid;
-}
-// ─── Preservation Gate ──────────────────────────────────────────
-/**
- * Verify that a summary preserves its source content in embedding space.
- *
- * SYNCHRONOUS PATH — for when you already have pre-computed embeddings
- * (e.g., from the background indexer or vector store cache).
- *
- * This is the preferred path: no network calls, no async, deterministic.
- *
- * @param summaryEmbedding - The embedding of the proposed summary
- * @param sourceEmbeddings - Embeddings of the source messages being replaced
- * @param config - Preservation threshold config
- */
-export function verifyPreservationFromVectors(summaryEmbedding, sourceEmbeddings, config = {}) {
-    const threshold = config.threshold ?? DEFAULT_PRESERVATION_CONFIG.threshold;
-    if (sourceEmbeddings.length === 0) {
-        return {
-            alignment: 0,
-            coverage: 0,
-            score: 0,
-            passed: false,
-            threshold,
-        };
-    }
-    // 1. Centroid alignment
-    const centroid = computeCentroid(sourceEmbeddings);
-    const alignment = cosineSimilarity(summaryEmbedding, centroid);
-    // 2. Source coverage (average positive cosine similarity)
-    let coverageSum = 0;
-    for (const src of sourceEmbeddings) {
-        coverageSum += Math.max(0, cosineSimilarity(summaryEmbedding, src));
-    }
-    const coverage = coverageSum / sourceEmbeddings.length;
-    // 3. Combined score, clamped to [0, 1]
-    const rawScore = (alignment + coverage) / 2;
-    const score = Math.max(0, Math.min(1, rawScore));
-    return {
-        alignment,
-        coverage,
-        score,
-        passed: score >= threshold,
-        threshold,
-    };
-}
-/**
- * Verify that a summary preserves its source content in embedding space.
- *
- * ASYNC PATH — generates embeddings via Ollama on demand.
- * Use when pre-computed embeddings aren't available.
- *
- * This makes N+1 embedding calls (1 for summary, N for sources if not cached).
- * For batch compaction, prefer pre-computing embeddings and using the sync path.
- *
- * @param summaryText - The proposed summary text
- * @param sourceTexts - The source message texts being replaced
- * @param config - Preservation threshold and embedding config
- */
-export async function verifyPreservation(summaryText, sourceTexts, config = {}) {
-    const threshold = config.threshold ?? DEFAULT_PRESERVATION_CONFIG.threshold;
-    if (sourceTexts.length === 0) {
-        return {
-            alignment: 0,
-            coverage: 0,
-            score: 0,
-            passed: false,
-            threshold,
-        };
-    }
-    // Batch all texts into one embedding call for efficiency
-    const allTexts = [summaryText, ...sourceTexts];
-    const allEmbeddings = await generateEmbeddings(allTexts, config.embedding);
-    const summaryEmbedding = allEmbeddings[0];
-    const sourceEmbeddings = allEmbeddings.slice(1);
-    return verifyPreservationFromVectors(summaryEmbedding, sourceEmbeddings, config);
-}
-//# sourceMappingURL=preservation-gate.js.map

package/dist/proactive-pass.d.ts

@@ -1,63 +0,0 @@
-/**
- * hypermem Proactive Passes
- *
- * Background maintenance passes that run between indexer ticks to keep
- * message storage lean. Two passes:
- *
- *   1. Noise Sweep — deletes low/zero-signal messages outside the recent
- *      window (heartbeats, acks, empty strings, control tokens).
- *
- *   2. Tool Decay — truncates oversized tool_results outside the recent
- *      window in-place, preserving JSON structure but collapsing large
- *      content blobs into a byte-count placeholder.
- *
- * Both passes are:
- *   - Synchronous (DatabaseSync, no async)
- *   - Wrapped in transactions (atomic)
- *   - Best-effort: catch all errors, log, and return a zero-change result
- *
- * Ported and adapted from ClawText proactive-pass.ts.
- * hypermem schema differences vs ClawText:
- *   - No content_type column — we classify on the fly via classifyContentType()
- *   - No external payload store — we truncate content inline in tool_results JSON
- *   - No ClawText-specific dependencies (payload-store, tool-tracker, etc.)
- */
-import type { DatabaseSync } from 'node:sqlite';
-export interface NoiseSweepResult {
-    messagesDeleted: number;
-    passType: 'noise_sweep';
-}
-export interface ToolDecayResult {
-    messagesUpdated: number;
-    bytesFreed: number;
-    passType: 'tool_decay';
-}
-/**
- * Delete noise and heartbeat messages outside the recent window.
- *
- * "Outside the recent window" means message_index < maxIndex - recentWindowSize.
- * Messages inside the window are never deleted, even if they are noise —
- * the model may still reference them in the current turn.
- *
- * Deletions are wrapped in a single transaction. The FTS5 trigger handles
- * index cleanup automatically (msg_fts_ad fires on DELETE).
- */
-export declare function runNoiseSweep(db: DatabaseSync, conversationId: number, recentWindowSize?: number, maxCandidates?: number): NoiseSweepResult;
-/**
- * Truncate oversized tool_results outside the recent window.
- *
- * Strategy:
- *   1. Find messages whose tool_results JSON string is > 2000 chars total,
- *      outside the recent window.
- *   2. Parse the JSON array.
- *   3. For each result entry where the `content` field exceeds 500 chars,
- *      replace `content` with `[tool result truncated — N bytes]`.
- *   4. Re-serialize and write back.
- *
- * The JSON structure is preserved (array of result objects). Only the
- * oversized `content` values are collapsed.
- *
- * Mutations are committed in a single transaction.
- */
-export declare function runToolDecay(db: DatabaseSync, conversationId: number, recentWindowSize?: number, maxCandidates?: number): ToolDecayResult;
-//# sourceMappingURL=proactive-pass.d.ts.map

package/dist/proactive-pass.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"proactive-pass.d.ts","sourceRoot":"","sources":["../src/proactive-pass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAwFD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,gBAAgB,GAAE,MAAW,EAC7B,aAAa,GAAE,MAAiB,GAC/B,gBAAgB,CAwFlB;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,gBAAgB,GAAE,MAAW,EAC7B,aAAa,GAAE,MAAiB,GAC/B,eAAe,CAgHjB"}