vektor-slipstream 1.3.6 → 1.3.7

package/CHANGELOG.md

@@ -0,0 +1,139 @@
+# VEKTOR v1.3.7 — Changelog
+
+Released: 2026-04-05
+
+## New features
+
+### memory.forget(id)
+Hard-deletes a memory and cascades to all graph edges. Throws if memory is pinned — must unpin first.
+```js
+await memory.forget('mem_abc123');
+// → { deleted: true, edgesRemoved: 4 }
+```
+
+### memory.forgetWhere(query, opts)
+Semantic bulk-delete. Preview with `dryRun: true` before committing.
+```js
+await memory.forgetWhere('Project Atlas', { dryRun: true });
+await memory.forgetWhere('Project Atlas', { minScore: 0.9, limit: 5 });
+```
+
+### memory.pin(id) / memory.unpin(id) / memory.listPinned()
+Mark memories as permanent — REM cycle will never compress or delete them.
+```js
+const { id } = await memory.remember('User is allergic to peanuts');
+await memory.pin(id);
+await memory.listPinned(); // → all pinned memories
+```
+
+### memory.inspect()
+Full diagnostic snapshot — no more raw SQLite queries to debug state.
+```js
+const state = memory.inspect();
+state.counts       // → { memories: 247, pinned: 3, edges: 7180 }
+state.rem          // → { totalDreams: 11, compressionRatio: '0.06' }
+state.graph.topNodes  // → 5 most-connected memories
+```
+
+### memory.auditLog(opts) / memory.auditStats()
+Full AUDN decision history. Nothing disappears silently.
+```js
+memory.auditLog({ action: 'DELETE', since: '7d' });
+// → [{ action, memory_id, content, reason, similarity, ran_at }]
+```
+
+### memory.briefing({ since }) — scoped date filtering
+```js
+await memory.briefing({ since: '7d' });
+await memory.briefing({ since: '12h', minImportance: 0.7 });
+await memory.briefing({ since: '2026-01-01', raw: true });
+```
+
+### memory.export() / memory.import()
+Full graph serialisation with checksum integrity.
+```js
+const bundle = memory.export();
+fs.writeFileSync('backup.vektor.json', JSON.stringify(bundle));
+
+memory.import(bundle);
+// → { imported: 244, skipped: 3, edgesAdded: 7100 }
+
+memory.import(bundle, { dryRun: true });    // preview
+memory.import(bundle, { mode: 'replace' }); // wipe and restore
+```
+
+### Namespace support
+Scope all reads/writes to prevent project bleed.
+```js
+const memory = await createMemory({ agentId: 'my-agent', namespace: 'project-atlas' });
+memory.listNamespaces();
+// → [{ namespace: 'project-atlas', memories: 18 }, ...]
+```
+
+### TypeScript types
+Full `.d.ts` declarations for all public API methods. No more flying blind in your IDE.
+Add to `tsconfig.json`: `"types": ["vektor-slipstream"]`
+
+### Structured error codes
+Replace string catch blocks with reliable `VektorError.code` switching.
+```js
+import { VektorError, ERR } from 'vektor-slipstream/errors';
+
+try {
+  await memory.remember(...)
+} catch (e) {
+  if (e instanceof VektorError) {
+    switch (e.code) {
+      case ERR.LICENCE_INVALID: // handle
+      case ERR.EMBED_FAILED:    // retry
+    }
+  }
+}
+```
+
+## Schema changes
+Run `npx vektor migrate` after updating, or migration runs automatically on startup.
+
+New columns:
+- `memories.pinned` INTEGER DEFAULT 0
+- `memories.namespace` TEXT DEFAULT 'default'
+- `memories.updated_at` INTEGER
+
+New tables:
+- `audn_log` — AUDN decision audit trail
+- `rem_log` — REM cycle run history (if not already present)
+- `vektor_meta` — schema version tracking
+
+## Bug fixes
+- REM cycle now skips pinned memories (previously could compress critical facts)
+- AUDN deletions now logged before execution (previously silent)
+- briefing() no longer returns stale summary when no memories exist in window
+
+## Breaking changes
+None. All new methods are additive. Existing code works unchanged.
+Migration is backward-compatible — new columns have safe defaults.
+
+## Gemini security review fixes (round 1 — applied)
+- `briefing.js` — pinned memory query now has LIMIT 50 (context bomb prevention)
+- `briefing.js` — `parseSince()` guards against `Date.now()` ms being passed as unix seconds
+- `forget.js` — `forgetWhere()` selective error catching — infra errors re-thrown, only expected skips swallowed
+- `namespace.js` — O(N) JS delete loop replaced with bulk SQL subquery (2 statements vs N*2)
+- `inspect.js` — all `SUM()` aggregations wrapped in `IFNULL(..., 0)` — no more `null` in charts
+- `migrate-137.js` — `PRAGMA table_info()` replaces brittle error-message string matching
+
+## Gemini security review fixes (round 2 — applied)
+- `export-import.js` — Fix 1: `IN (...memIds)` placeholders replaced with SQL subqueries — no more 32,766 param limit crash on large exports
+- `export-import.js` — Fix 2: O(N) loop in `replace` mode replaced with bulk subquery deletes
+- `export-import.js` — Fix 3: checksum now hashes full memories payload — content/importance tampering now detectable
+- `export-import.js` — Fix 4: dangling edge guard — edges only inserted if both source and target exist in destination (`WHERE EXISTS`)
+- `export-import.js` — `edgesSkipped` added to import return value with console.warn for partial imports
+
+## Gemini security review fixes (round 3 — applied)
+- `forget.js` — pinned edge orphan guard: blocks deleting a memory that shares
+  a graph edge with a pinned memory — prevents silent MAGMA traversal corruption
+- `namespace.js` — SQLITE_BUSY retry loop: 3 attempts × 100ms using
+  `Atomics.wait` (correct sync sleep for better-sqlite3) before propagating error
+- `export-import.js` — confirmed: empty bundle guard (line 103) already sits
+  before checksum computation (line 107) — correct order, no change needed
+
+## Total fixes across 3 Gemini review rounds: 13

package/audn-log.js

@@ -0,0 +1,143 @@
+/**
+ * VEKTOR AUDN audit log — v1.3.7
+ * Records every ADD/UPDATE/DELETE/NO_OP decision AUDN makes
+ * before acting on it. Full transparency — nothing disappears silently.
+ *
+ * Schema additions required:
+ *   CREATE TABLE IF NOT EXISTS audn_log (
+ *     id          INTEGER PRIMARY KEY AUTOINCREMENT,
+ *     agent_id    TEXT NOT NULL,
+ *     namespace   TEXT NOT NULL,
+ *     action      TEXT NOT NULL,  -- ADD | UPDATE | DELETE | NO_OP
+ *     memory_id   TEXT,           -- affected memory id (null for ADD before insert)
+ *     content     TEXT,           -- snapshot of content at time of action
+ *     reason      TEXT,           -- why AUDN made this decision
+ *     similarity  REAL,           -- similarity score that triggered the decision
+ *     ran_at      INTEGER DEFAULT (unixepoch())
+ *   );
+ *   CREATE INDEX IF NOT EXISTS idx_audn_log_agent ON audn_log(agent_id, namespace, ran_at);
+ */
+
+/**
+ * logAudn — call this inside AUDN before executing each decision
+ *
+ * @param {object} db
+ * @param {string} agentId
+ * @param {string} namespace
+ * @param {object} entry
+ * @param {string} entry.action      - ADD | UPDATE | DELETE | NO_OP
+ * @param {string} entry.memoryId    - memory id (if known)
+ * @param {string} entry.content     - content snapshot
+ * @param {string} entry.reason      - human-readable reason
+ * @param {number} entry.similarity  - cosine score that triggered this
+ */
+export function logAudn(db, agentId, namespace, entry) {
+  db.prepare(`
+    INSERT INTO audn_log (agent_id, namespace, action, memory_id, content, reason, similarity)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    agentId,
+    namespace,
+    entry.action,
+    entry.memoryId || null,
+    entry.content ? entry.content.slice(0, 500) : null,
+    entry.reason || null,
+    entry.similarity || null
+  );
+}
+
+/**
+ * auditLog(opts) — retrieve AUDN decision history
+ *
+ * @param {object} db
+ * @param {string} agentId
+ * @param {string} namespace
+ * @param {object} opts
+ * @param {number}  opts.limit   - max rows (default 50)
+ * @param {string}  opts.action  - filter to specific action (ADD|UPDATE|DELETE|NO_OP)
+ * @param {string}  opts.since   - time filter — '7d', '24h', ISO date
+ * @returns {object[]}
+ */
+export function auditLog(db, agentId, namespace, opts = {}) {
+  const { limit = 50, action = null, since = null } = opts;
+
+  let sinceTs = null;
+  if (since) {
+    const rel = String(since).match(/^(\d+)(d|h|m)$/);
+    if (rel) {
+      const n = parseInt(rel[1]);
+      const unit = rel[2];
+      const seconds = unit === 'd' ? n * 86400 : unit === 'h' ? n * 3600 : n * 60;
+      sinceTs = Math.floor(Date.now() / 1000) - seconds;
+    } else {
+      sinceTs = Math.floor(Date.parse(since) / 1000);
+    }
+  }
+
+  const actionClause = action ? `AND action = '${action.toUpperCase()}'` : '';
+  const sinceClause = sinceTs ? `AND ran_at >= ${sinceTs}` : '';
+
+  return db.prepare(`
+    SELECT id, action, memory_id, content, reason, similarity, ran_at
+    FROM audn_log
+    WHERE agent_id = ? AND namespace = ?
+    ${actionClause}
+    ${sinceClause}
+    ORDER BY ran_at DESC
+    LIMIT ?
+  `).all(agentId, namespace, limit);
+}
+
+/**
+ * auditStats() — summary counts by action type
+ */
+export function auditStats(db, agentId, namespace) {
+  return db.prepare(`
+    SELECT
+      action,
+      COUNT(*) as count,
+      MAX(ran_at) as last_at
+    FROM audn_log
+    WHERE agent_id = ? AND namespace = ?
+    GROUP BY action
+    ORDER BY count DESC
+  `).all(agentId, namespace);
+}
+
+/**
+ * pruneAuditLog(days) — keep log from growing forever
+ * Call from REM cycle or a scheduled job
+ */
+export function pruneAuditLog(db, agentId, namespace, keepDays = 30) {
+  const cutoff = Math.floor(Date.now() / 1000) - keepDays * 86400;
+  const result = db.prepare(
+    `DELETE FROM audn_log WHERE agent_id = ? AND namespace = ? AND ran_at < ?`
+  ).run(agentId, namespace, cutoff);
+  return { pruned: result.changes };
+}
+
+/**
+ * Integration into Memory class / AUDN loop:
+ *
+ * // Inside AUDN decision logic:
+ * logAudn(this.db, this.agentId, this.namespace, {
+ *   action: 'DELETE',
+ *   memoryId: existing.id,
+ *   content: existing.content,
+ *   reason: 'Contradicts newer memory with score 0.94',
+ *   similarity: 0.94
+ * });
+ * // then execute the delete
+ *
+ * // Expose on Memory class:
+ * auditLog(opts = {}) {
+ *   return auditLog(this.db, this.agentId, this.namespace, opts);
+ * }
+ *
+ * Usage:
+ *   memory.auditLog({ action: 'DELETE', since: '7d' });
+ *   // → [{ id, action:'DELETE', content:'...', reason:'...', ran_at }]
+ *
+ *   memory.auditLog({ limit: 100 });
+ *   // → last 100 AUDN decisions
+ */

package/briefing.js

@@ -0,0 +1,150 @@
+/**
+ * VEKTOR briefing() date scoping — v1.3.7
+ * Adds `since` param to briefing() — filter to last N days/hours
+ * or an explicit ISO timestamp.
+ *
+ * Drop-in replacement for existing briefing() implementation.
+ */
+
+import { VektorError, ERR } from './errors.js';
+
+/**
+ * Parse a `since` value into a Unix timestamp (seconds).
+ * Accepts:
+ *   '1d'   → last 1 day
+ *   '7d'   → last 7 days
+ *   '12h'  → last 12 hours
+ *   '30m'  → last 30 minutes
+ *   '2026-01-01T00:00:00Z'  → explicit ISO date
+ *   1735689600  → raw unix timestamp
+ */
+export function parseSince(since) {
+  if (!since) return null;
+
+  // Raw unix timestamp — guard against Date.now() (ms) being passed accidentally
+  // If number > 9999999999 it's milliseconds (year ~2001 in seconds) — convert it
+  if (typeof since === 'number') {
+    return since > 9_999_999_999 ? Math.floor(since / 1000) : since;
+  }
+
+  // Relative shorthand: 7d, 12h, 30m
+  const rel = String(since).match(/^(\d+)(d|h|m)$/);
+  if (rel) {
+    const n = parseInt(rel[1]);
+    const unit = rel[2];
+    const seconds = unit === 'd' ? n * 86400 : unit === 'h' ? n * 3600 : n * 60;
+    return Math.floor(Date.now() / 1000) - seconds;
+  }
+
+  // ISO date string
+  const ts = Date.parse(since);
+  if (!isNaN(ts)) return Math.floor(ts / 1000);
+
+  throw new VektorError(
+    ERR.MEMORY_READ_FAILED,
+    `Invalid since value: "${since}". Use "7d", "12h", "30m", ISO date, or unix timestamp.`
+  );
+}
+
+/**
+ * briefing({ since, limit, minImportance })
+ * Returns a structured summary of recent memories for agent context injection.
+ *
+ * @param {object} db
+ * @param {string} agentId
+ * @param {string} namespace
+ * @param {Function} summariseFn  - LLM summarise function (existing REM summariser)
+ * @param {object} opts
+ * @param {string|number} opts.since         - time filter (default: '1d')
+ * @param {number}        opts.limit         - max memories (default: 20)
+ * @param {number}        opts.minImportance - filter by importance score (default: 0)
+ * @param {boolean}       opts.raw           - return raw memories, skip LLM summary
+ * @returns {object}  { period, memoryCount, pinned, summary, memories }
+ */
+export async function briefing(db, agentId, namespace, summariseFn, opts = {}) {
+  const {
+    since = '1d',
+    limit = 20,
+    minImportance = 0,
+    raw = false
+  } = opts;
+
+  const sinceTs = parseSince(since);
+  const sinceClause = sinceTs ? `AND created_at >= ${sinceTs}` : '';
+  const importanceClause = minImportance > 0 ? `AND importance >= ${minImportance}` : '';
+
+  // Fetch scoped memories
+  const memories = db.prepare(`
+    SELECT id, content, summary, importance, pinned, created_at
+    FROM memories
+    WHERE agent_id = ? AND namespace = ?
+    ${sinceClause}
+    ${importanceClause}
+    ORDER BY importance DESC, created_at DESC
+    LIMIT ?
+  `).all(agentId, namespace, limit);
+
+  // Always fetch pinned regardless of time window — hard cap 50 to prevent context bomb
+  // (an agent running for months could accumulate hundreds of pinned memories)
+  const pinnedLimit = 50;
+  const pinned = db.prepare(`
+    SELECT id, content, summary, importance, created_at
+    FROM memories
+    WHERE agent_id = ? AND namespace = ? AND pinned = 1
+    ORDER BY importance DESC
+    LIMIT ${pinnedLimit}
+  `).all(agentId, namespace);
+
+  if (raw) {
+    return {
+      period: since,
+      memoryCount: memories.length,
+      pinned,
+      memories
+    };
+  }
+
+  // Build prompt context for LLM summary
+  const context = [
+    pinned.length > 0
+      ? `PINNED (permanent):\n${pinned.map(m => `- ${m.summary || m.content}`).join('\n')}`
+      : null,
+    memories.length > 0
+      ? `RECENT (${since}):\n${memories.map(m => `- [${m.importance?.toFixed(2)}] ${m.summary || m.content}`).join('\n')}`
+      : 'No recent memories in this period.'
+  ].filter(Boolean).join('\n\n');
+
+  const summary = await summariseFn(
+    `Produce a concise agent briefing from these memories. Lead with pinned facts, then recent activity.\n\n${context}`
+  );
+
+  return {
+    period: since,
+    memoryCount: memories.length,
+    pinnedCount: pinned.length,
+    pinned,
+    memories,
+    summary
+  };
+}
+
+/**
+ * Integration into Memory class:
+ *
+ * async briefing(opts = {}) {
+ *   return briefing(this.db, this.agentId, this.namespace, this._summarise.bind(this), opts);
+ * }
+ *
+ * Usage:
+ *   await memory.briefing();
+ *   // → last 24h summary (default)
+ *
+ *   await memory.briefing({ since: '7d' });
+ *   // → last 7 days
+ *
+ *   await memory.briefing({ since: '2026-01-01', minImportance: 0.7 });
+ *   // → since Jan 1st, high importance only
+ *
+ *   await memory.briefing({ raw: true, since: '1h' });
+ *   // → raw memory objects, no LLM call
+ */