hippo-memory 0.8.1 → 0.9.0

package/dist/working-memory.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Working Memory — bounded buffer for current-state notes.
+ *
+ * Separate from long-term semantic memory. Entries are scoped,
+ * importance-ranked, and automatically evicted when the buffer
+ * exceeds WM_MAX_ENTRIES per scope.
+ */
+export declare const WM_MAX_ENTRIES = 20;
+export interface WorkingMemoryItem {
+    id: number;
+    scope: string;
+    sessionId: string | null;
+    taskId: string | null;
+    importance: number;
+    content: string;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Push a new entry into working memory.
+ * If the scope exceeds WM_MAX_ENTRIES, the lowest-importance entry
+ * is evicted (ties broken by oldest created_at).
+ * Returns the new row ID.
+ */
+export declare function wmPush(hippoRoot: string, opts: {
+    scope: string;
+    content: string;
+    importance?: number;
+    sessionId?: string;
+    taskId?: string;
+    metadata?: Record<string, unknown>;
+}): number;
+/**
+ * Read working memory entries, sorted by importance DESC.
+ */
+export declare function wmRead(hippoRoot: string, opts?: {
+    scope?: string;
+    sessionId?: string;
+    limit?: number;
+}): WorkingMemoryItem[];
+/**
+ * Clear (delete) working memory entries. Returns the count deleted.
+ */
+export declare function wmClear(hippoRoot: string, opts?: {
+    scope?: string;
+    sessionId?: string;
+}): number;
+/**
+ * Flush working memory — delete entries after session end.
+ * Functionally identical to wmClear but semantically distinct:
+ * used at session boundaries to discard ephemeral state.
+ * Returns the count flushed.
+ */
+export declare function wmFlush(hippoRoot: string, opts?: {
+    scope?: string;
+    sessionId?: string;
+}): number;
+//# sourceMappingURL=working-memory.d.ts.map

package/dist/working-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"working-memory.d.ts","sourceRoot":"","sources":["../src/working-memory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAkCD;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GAAG,MAAM,CAqDT;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,iBAAiB,EAAE,CAgCtB;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAsBT;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAET"}

package/dist/working-memory.js

@@ -0,0 +1,149 @@
+/**
+ * Working Memory — bounded buffer for current-state notes.
+ *
+ * Separate from long-term semantic memory. Entries are scoped,
+ * importance-ranked, and automatically evicted when the buffer
+ * exceeds WM_MAX_ENTRIES per scope.
+ */
+import { openHippoDb, closeHippoDb } from './db.js';
+import { initStore } from './store.js';
+export const WM_MAX_ENTRIES = 20;
+function rowToItem(row) {
+    let metadata = {};
+    try {
+        metadata = JSON.parse(row.metadata_json);
+    }
+    catch {
+        // malformed JSON — default to empty
+    }
+    return {
+        id: row.id,
+        scope: row.scope,
+        sessionId: row.session_id,
+        taskId: row.task_id,
+        importance: Number(row.importance),
+        content: row.content,
+        metadata,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+/**
+ * Push a new entry into working memory.
+ * If the scope exceeds WM_MAX_ENTRIES, the lowest-importance entry
+ * is evicted (ties broken by oldest created_at).
+ * Returns the new row ID.
+ */
+export function wmPush(hippoRoot, opts) {
+    initStore(hippoRoot);
+    const db = openHippoDb(hippoRoot);
+    try {
+        const now = new Date().toISOString();
+        const importance = opts.importance ?? 0;
+        db.exec('BEGIN');
+        try {
+            const result = db.prepare(`
+        INSERT INTO working_memory(scope, session_id, task_id, importance, content, metadata_json, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(opts.scope, opts.sessionId ?? null, opts.taskId ?? null, importance, opts.content, JSON.stringify(opts.metadata ?? {}), now, now);
+            const id = Number(result.lastInsertRowid ?? 0);
+            // Evict if over capacity for this scope
+            const countRow = db.prepare(`
+        SELECT COUNT(*) AS cnt FROM working_memory WHERE scope = ?
+      `).get(opts.scope);
+            const count = Number(countRow?.cnt ?? 0);
+            if (count > WM_MAX_ENTRIES) {
+                const excess = count - WM_MAX_ENTRIES;
+                db.prepare(`
+          DELETE FROM working_memory
+          WHERE id IN (
+            SELECT id FROM working_memory
+            WHERE scope = ?
+            ORDER BY importance ASC, created_at ASC
+            LIMIT ?
+          )
+        `).run(opts.scope, excess);
+            }
+            db.exec('COMMIT');
+            return id;
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* ignore */ }
+            throw error;
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Read working memory entries, sorted by importance DESC.
+ */
+export function wmRead(hippoRoot, opts) {
+    initStore(hippoRoot);
+    const db = openHippoDb(hippoRoot);
+    try {
+        const clauses = [];
+        const params = [];
+        if (opts?.scope) {
+            clauses.push('scope = ?');
+            params.push(opts.scope);
+        }
+        if (opts?.sessionId) {
+            clauses.push('session_id = ?');
+            params.push(opts.sessionId);
+        }
+        const limit = Math.max(1, Math.trunc(opts?.limit ?? WM_MAX_ENTRIES));
+        params.push(limit);
+        const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
+        const rows = db.prepare(`
+      SELECT id, scope, session_id, task_id, importance, content, metadata_json, created_at, updated_at
+      FROM working_memory
+      ${where}
+      ORDER BY importance DESC, created_at DESC
+      LIMIT ?
+    `).all(...params);
+        return rows.map(rowToItem);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Clear (delete) working memory entries. Returns the count deleted.
+ */
+export function wmClear(hippoRoot, opts) {
+    initStore(hippoRoot);
+    const db = openHippoDb(hippoRoot);
+    try {
+        const clauses = [];
+        const params = [];
+        if (opts?.scope) {
+            clauses.push('scope = ?');
+            params.push(opts.scope);
+        }
+        if (opts?.sessionId) {
+            clauses.push('session_id = ?');
+            params.push(opts.sessionId);
+        }
+        const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
+        const result = db.prepare(`DELETE FROM working_memory ${where}`).run(...params);
+        return Number(result.changes ?? 0);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Flush working memory — delete entries after session end.
+ * Functionally identical to wmClear but semantically distinct:
+ * used at session boundaries to discard ephemeral state.
+ * Returns the count flushed.
+ */
+export function wmFlush(hippoRoot, opts) {
+    return wmClear(hippoRoot, opts);
+}
+//# sourceMappingURL=working-memory.js.map

package/dist/working-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"working-memory.js","sourceRoot":"","sources":["../src/working-memory.ts"],"names":[],"mappings":"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"}