@psiclawops/hypermem 0.1.0 → 0.5.0

package/dist/compaction-fence.d.ts

@@ -1,89 +0,0 @@
-/**
- * HyperMem Compaction Fence
- *
- * Protects the recent conversation tail from being compacted.
- *
- * The fence is a per-conversation high-water mark (message ID) that divides
- * the message timeline into two zones:
- *
- *   - ABOVE the fence: messages the LLM can currently see (recent tail).
- *     These are off-limits to compaction.
- *   - BELOW the fence: older messages eligible for compaction/summarization.
- *
- * The compositor updates the fence every compose cycle by recording the
- * oldest message ID that was included in the composed context. This means
- * the fence automatically advances as conversations grow.
- *
- * Safety defaults:
- *   - No fence row = no compaction allowed (explicit opt-in)
- *   - Fence never moves backward (monotone progress)
- *   - Fence update is idempotent (same value = no-op)
- *
- * Inspired by the continuity model in openclaw-memory-libravdb, which
- * formally proves that compaction must never touch the recent tail.
- */
-import type { DatabaseSync } from 'node:sqlite';
-export interface CompactionFence {
-    conversationId: number;
-    /** Message ID of the oldest message currently visible to the LLM */
-    fenceMessageId: number;
-    /** Timestamp of the last fence update */
-    updatedAt: string;
-}
-export interface CompactionEligibility {
-    conversationId: number;
-    /** Total messages below the fence (eligible for compaction) */
-    eligibleCount: number;
-    /** Message ID of the oldest eligible message */
-    oldestEligibleId: number | null;
-    /** Message ID of the newest eligible message (just below fence) */
-    newestEligibleId: number | null;
-    /** The fence itself */
-    fence: CompactionFence | null;
-}
-/**
- * Add the compaction_fences table to an existing messages.db.
- * Idempotent — safe to call on every startup.
- */
-export declare function ensureCompactionFenceSchema(db: DatabaseSync): void;
-/**
- * Update the compaction fence for a conversation.
- *
- * Called by the compositor after assembling context, passing the ID of
- * the oldest message that was included in the composed history.
- *
- * The fence only moves forward (monotone progress). If the new fence
- * is lower than the existing one, the update is silently ignored.
- * This prevents a short compose window from accidentally exposing
- * already-compacted messages.
- */
-export declare function updateCompactionFence(db: DatabaseSync, conversationId: number, oldestVisibleMessageId: number): void;
-/**
- * Get the current compaction fence for a conversation.
- * Returns null if no fence has been set (meaning: no compaction allowed).
- */
-export declare function getCompactionFence(db: DatabaseSync, conversationId: number): CompactionFence | null;
-/**
- * Query compaction eligibility for a conversation.
- *
- * Returns the count and range of messages that are below the fence
- * and therefore eligible for compaction. If no fence exists, returns
- * zero eligible (safe default: no fence = no compaction).
- *
- * Excludes messages that are already covered by a summary
- * (via the summary_messages junction table).
- */
-export declare function getCompactionEligibility(db: DatabaseSync, conversationId: number): CompactionEligibility;
-/**
- * Get messages eligible for compaction (below the fence, not yet summarized).
- *
- * Returns messages in chronological order, ready for clustering.
- * Respects the fence boundary and excludes already-summarized messages.
- */
-export declare function getCompactableMessages(db: DatabaseSync, conversationId: number, limit?: number): Array<{
-    id: number;
-    role: string;
-    textContent: string;
-    createdAt: string;
-}>;
-//# sourceMappingURL=compaction-fence.d.ts.map

package/dist/compaction-fence.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"compaction-fence.d.ts","sourceRoot":"","sources":["../src/compaction-fence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,uBAAuB;IACvB,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CAC/B;AAID;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAQlE;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,sBAAsB,EAAE,MAAM,GAC7B,IAAI,CAqBN;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,GACrB,eAAe,GAAG,IAAI,CAYxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,GACrB,qBAAqB,CAwCvB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,KAAK,GAAE,MAAY,GAClB,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CA8B7E"}

package/dist/compaction-fence.js

@@ -1,153 +0,0 @@
-/**
- * HyperMem Compaction Fence
- *
- * Protects the recent conversation tail from being compacted.
- *
- * The fence is a per-conversation high-water mark (message ID) that divides
- * the message timeline into two zones:
- *
- *   - ABOVE the fence: messages the LLM can currently see (recent tail).
- *     These are off-limits to compaction.
- *   - BELOW the fence: older messages eligible for compaction/summarization.
- *
- * The compositor updates the fence every compose cycle by recording the
- * oldest message ID that was included in the composed context. This means
- * the fence automatically advances as conversations grow.
- *
- * Safety defaults:
- *   - No fence row = no compaction allowed (explicit opt-in)
- *   - Fence never moves backward (monotone progress)
- *   - Fence update is idempotent (same value = no-op)
- *
- * Inspired by the continuity model in openclaw-memory-libravdb, which
- * formally proves that compaction must never touch the recent tail.
- */
-// ─── Schema ─────────────────────────────────────────────────────
-/**
- * Add the compaction_fences table to an existing messages.db.
- * Idempotent — safe to call on every startup.
- */
-export function ensureCompactionFenceSchema(db) {
-    db.exec(`
-    CREATE TABLE IF NOT EXISTS compaction_fences (
-      conversation_id INTEGER PRIMARY KEY REFERENCES conversations(id),
-      fence_message_id INTEGER NOT NULL,
-      updated_at TEXT NOT NULL
-    )
-  `);
-}
-// ─── Fence Operations ───────────────────────────────────────────
-/**
- * Update the compaction fence for a conversation.
- *
- * Called by the compositor after assembling context, passing the ID of
- * the oldest message that was included in the composed history.
- *
- * The fence only moves forward (monotone progress). If the new fence
- * is lower than the existing one, the update is silently ignored.
- * This prevents a short compose window from accidentally exposing
- * already-compacted messages.
- */
-export function updateCompactionFence(db, conversationId, oldestVisibleMessageId) {
-    const now = new Date().toISOString();
-    const existing = db.prepare('SELECT fence_message_id FROM compaction_fences WHERE conversation_id = ?').get(conversationId);
-    if (!existing) {
-        // First fence for this conversation
-        db.prepare('INSERT INTO compaction_fences (conversation_id, fence_message_id, updated_at) VALUES (?, ?, ?)').run(conversationId, oldestVisibleMessageId, now);
-        return;
-    }
-    // Monotone progress: fence only moves forward
-    if (oldestVisibleMessageId > existing.fence_message_id) {
-        db.prepare('UPDATE compaction_fences SET fence_message_id = ?, updated_at = ? WHERE conversation_id = ?').run(oldestVisibleMessageId, now, conversationId);
-    }
-}
-/**
- * Get the current compaction fence for a conversation.
- * Returns null if no fence has been set (meaning: no compaction allowed).
- */
-export function getCompactionFence(db, conversationId) {
-    const row = db.prepare('SELECT conversation_id, fence_message_id, updated_at FROM compaction_fences WHERE conversation_id = ?').get(conversationId);
-    if (!row)
-        return null;
-    return {
-        conversationId: row.conversation_id,
-        fenceMessageId: row.fence_message_id,
-        updatedAt: row.updated_at,
-    };
-}
-/**
- * Query compaction eligibility for a conversation.
- *
- * Returns the count and range of messages that are below the fence
- * and therefore eligible for compaction. If no fence exists, returns
- * zero eligible (safe default: no fence = no compaction).
- *
- * Excludes messages that are already covered by a summary
- * (via the summary_messages junction table).
- */
-export function getCompactionEligibility(db, conversationId) {
-    const fence = getCompactionFence(db, conversationId);
-    if (!fence) {
-        return {
-            conversationId,
-            eligibleCount: 0,
-            oldestEligibleId: null,
-            newestEligibleId: null,
-            fence: null,
-        };
-    }
-    // Messages below the fence that haven't been summarized yet
-    const stats = db.prepare(`
-    SELECT
-      COUNT(*) AS cnt,
-      MIN(m.id) AS oldest_id,
-      MAX(m.id) AS newest_id
-    FROM messages m
-    WHERE m.conversation_id = ?
-      AND m.id < ?
-      AND m.id NOT IN (
-        SELECT sm.message_id FROM summary_messages sm
-        JOIN summaries s ON sm.summary_id = s.id
-        WHERE s.conversation_id = ?
-      )
-  `).get(conversationId, fence.fenceMessageId, conversationId);
-    return {
-        conversationId,
-        eligibleCount: stats.cnt,
-        oldestEligibleId: stats.oldest_id,
-        newestEligibleId: stats.newest_id,
-        fence,
-    };
-}
-/**
- * Get messages eligible for compaction (below the fence, not yet summarized).
- *
- * Returns messages in chronological order, ready for clustering.
- * Respects the fence boundary and excludes already-summarized messages.
- */
-export function getCompactableMessages(db, conversationId, limit = 100) {
-    const fence = getCompactionFence(db, conversationId);
-    if (!fence)
-        return [];
-    const rows = db.prepare(`
-    SELECT m.id, m.role, m.text_content, m.created_at
-    FROM messages m
-    WHERE m.conversation_id = ?
-      AND m.id < ?
-      AND m.text_content IS NOT NULL
-      AND m.id NOT IN (
-        SELECT sm.message_id FROM summary_messages sm
-        JOIN summaries s ON sm.summary_id = s.id
-        WHERE s.conversation_id = ?
-      )
-    ORDER BY m.id ASC
-    LIMIT ?
-  `).all(conversationId, fence.fenceMessageId, conversationId, limit);
-    return rows.map(r => ({
-        id: r.id,
-        role: r.role,
-        textContent: r.text_content,
-        createdAt: r.created_at,
-    }));
-}
-//# sourceMappingURL=compaction-fence.js.map

package/dist/compositor.d.ts

@@ -1,139 +0,0 @@
-/**
- * HyperMem Compositor
- *
- * Assembles context for LLM calls by orchestrating all four memory layers:
- *   L1 Redis    — hot session working memory (system, identity, recent msgs)
- *   L2 Messages — conversation history from messages.db
- *   L3 Vectors  — semantic search across all indexed content
- *   L4 Library  — structured knowledge (facts, preferences, knowledge, episodes)
- *
- * Token-budgeted: never exceeds the budget, prioritizes by configured order.
- * Provider-neutral internally, translates at the output boundary.
- */
-import type { DatabaseSync } from 'node:sqlite';
-import type { ComposeRequest, ComposeResult, CompositorConfig } from './types.js';
-import { RedisLayer } from './redis.js';
-import { VectorStore } from './vector-store.js';
-/**
- * A trigger definition maps a collection to the conversation signals that
- * indicate it should be queried. When any keyword matches the user's latest
- * message, the compositor fetches relevant chunks from that collection.
- *
- * Centralizing trigger logic here (not in workspace stubs) means:
- * - One update propagates to all agents
- * - Stubs become documentation, not code
- * - Trigger logic can be tested independently
- */
-export interface CollectionTrigger {
-    /** Collection path: governance/policy, identity/job, etc. */
-    collection: string;
-    /** Keywords that trigger this collection (case-insensitive) */
-    keywords: string[];
-    /** Max tokens to inject from this collection */
-    maxTokens?: number;
-    /** Max chunks to retrieve */
-    maxChunks?: number;
-}
-/**
- * Default trigger registry for standard ACA collections.
- * Covers the core ACA offload use case from Anvil's spec.
- */
-export declare const DEFAULT_TRIGGERS: CollectionTrigger[];
-export interface CompositorDeps {
-    redis: RedisLayer;
-    vectorStore?: VectorStore | null;
-    libraryDb?: DatabaseSync | null;
-    /** Custom trigger registry; defaults to DEFAULT_TRIGGERS if not provided */
-    triggerRegistry?: CollectionTrigger[];
-}
-export declare class Compositor {
-    private readonly config;
-    private readonly redis;
-    private vectorStore;
-    private readonly libraryDb;
-    private readonly triggerRegistry;
-    constructor(deps: CompositorDeps | RedisLayer, config?: Partial<CompositorConfig>);
-    /**
-     * Set or replace the vector store after construction.
-     * Called by HyperMem.create() once sqlite-vec is confirmed available.
-     */
-    setVectorStore(vs: VectorStore): void;
-    /**
-     * Compose a complete message array for sending to an LLM.
-     *
-     * Orchestrates all four memory layers:
-     *   1. System prompt + identity (never truncated)
-     *   2. Conversation history (L1 Redis → L2 messages.db)
-     *   3. Active facts from library (L4)
-     *   4. Knowledge entries relevant to conversation (L4)
-     *   5. User preferences (L4)
-     *   6. Semantic recall via vector search (L3)
-     *   7. Cross-session context (L2)
-     *
-     * Each slot respects the remaining token budget.
-     */
-    compose(request: ComposeRequest, db: DatabaseSync, libraryDb?: DatabaseSync): Promise<ComposeResult>;
-    /**
-     * Warm a session from SQLite into Redis.
-     * Called on session start or Redis cache miss.
-     */
-    warmSession(agentId: string, sessionKey: string, db: DatabaseSync, opts?: {
-        systemPrompt?: string;
-        identity?: string;
-        libraryDb?: DatabaseSync;
-    }): Promise<void>;
-    /**
-     * Get slot content: try Redis first, fall back to SQLite.
-     */
-    private getSlotContent;
-    /**
-     * Get conversation history: try Redis first, fall back to SQLite.
-     */
-    private getHistory;
-    /**
-     * Build facts content from library DB.
-     */
-    private buildFactsFromDb;
-    /**
-     * Build knowledge content from library DB.
-     * Prioritizes high-confidence, non-superseded entries.
-     */
-    private buildKnowledgeFromDb;
-    /**
-     * Build preferences content from library DB.
-     * Shows user/operator preferences relevant to this agent.
-     */
-    private buildPreferencesFromDb;
-    /**
-     * Build semantic recall content using hybrid FTS5+KNN retrieval.
-     *
-     * Uses Reciprocal Rank Fusion to merge keyword and vector results.
-     * Gracefully degrades: FTS5-only when no vector store, KNN-only
-     * when FTS query is empty (all stop words), both when available.
-     */
-    private buildSemanticRecall;
-    /**
-     * Format a hybrid search result for injection into context.
-     * Shows retrieval source(s) and relevance score.
-     */
-    private formatHybridResult;
-    /**
-     * Format a vector-only search result (legacy fallback).
-     */
-    private formatVectorResult;
-    /**
-     * Build cross-session context by finding recent activity
-     * in other sessions for this agent.
-     */
-    private buildCrossSessionContext;
-    /**
-     * Extract the last user message text from the composed messages.
-     */
-    private getLastUserMessage;
-    /**
-     * Truncate text to approximately fit within a token budget.
-     * Truncates at line boundaries when possible.
-     */
-    private truncateToTokens;
-}
-//# sourceMappingURL=compositor.d.ts.map

package/dist/compositor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"compositor.d.ts","sourceRoot":"","sources":["../src/compositor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAKb,gBAAgB,EAGjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EAAE,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AAiBzE;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAAiB,EAkE/C,CAAC;AA6KF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,UAAU,CAAC;IAClB,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC,SAAS,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAChC,4EAA4E;IAC5E,eAAe,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACvC;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsB;gBAGpD,IAAI,EAAE,cAAc,GAAG,UAAU,EACjC,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC;IAkBpC;;;OAGG;IACH,cAAc,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI;IAIrC;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAqjB1G;;;OAGG;IACG,WAAW,CACf,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,YAAY,EAChB,IAAI,CAAC,EAAE;QACL,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,YAAY,CAAC;KAC1B,GACA,OAAO,CAAC,IAAI,CAAC;IA8DhB;;OAEG;YACW,cAAc;IAoB5B;;OAEG;YACW,UAAU;IAoBxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA+BxB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAyC5B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IA4C9B;;;;;;OAMG;YACW,mBAAmB;IA6DjC;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAiB1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IA6ChC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;CAezB"}