vektor-slipstream 1.3.5 → 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/README.md

@@ -2,13 +2,18 @@
 
 Hardware-accelerated persistent memory for AI agents. Local-first. No cloud. One-time payment.
 
+[![npm](https://img.shields.io/npm/v/vektor-slipstream)](https://www.npmjs.com/package/vektor-slipstream)
+[![license](https://img.shields.io/badge/license-Commercial-blue)](https://vektormemory.com/product#pricing)
+
 ## Install
+
 ```bash
 npm install vektor-slipstream
 npx vektor setup
 ```
 
 ## Quick Start
+
 ```js
 const { createMemory } = require('vektor-slipstream');
 
@@ -17,36 +22,216 @@ const memory = await createMemory({
   licenceKey: process.env.VEKTOR_LICENCE_KEY,
 });
 
+// Store a memory
 await memory.remember('User prefers TypeScript over JavaScript');
-const results = await memory.recall('coding preferences');
+
+// Recall by semantic similarity — avg 8ms, fully local
+const results = await memory.recall('coding preferences', 5);
 // → [{ content, score, id }]
+
+// Traverse the graph
+const graph = await memory.graph('TypeScript', { hops: 2 });
+
+// What changed in 7 days?
+const delta = await memory.delta('project decisions', 7);
+
+// Morning briefing
+const brief = await memory.briefing();
 ```
 
 ## CLI
+
 ```bash
-npx vektor setup       # First-run wizard
-npx vektor activate    # Activate licence key
-npx vektor test        # Test memory engine
-npx vektor status      # System health check
-npx vektor mcp         # Start Claude MCP server
-npx vektor rem         # Run REM dream cycle
-npx vektor help        # All commands
+npx vektor setup      # First-run wizard — licence, hardware, integrations
+npx vektor activate   # Activate licence key on this machine
+npx vektor test       # Test memory engine with progress bar
+npx vektor status     # System health check
+npx vektor mcp        # Start Claude Desktop MCP server
+npx vektor rem        # Run REM dream cycle
+npx vektor help       # All commands
+```
+
+## CLOAK — Developer Context Layer for Claude Code
+
+CLOAK is a 4-tool MCP layer that gives Claude Code persistent memory of your project.
+Every session starts with full context. Every error is remembered. Every wasted token is tracked.
+
+### What it does
+
+| Tool | Does exactly one thing |
+|---|---|
+| `cloak_cortex` | Scans project files, builds a token-aware anatomy index in Vektor's entity graph |
+| `cloak_axon` | Session boundary handler — loads last context on start, saves MemCell on stop |
+| `cloak_cerebellum` | Pre-write enforcer — checks writes against known error patterns, auto-resolves fixes |
+| `cloak_token` | Token ledger — detects repeated reads and waste, one summary write per session |
+
+### Import
+
+```js
+const { runCortex }        = require('vektor-slipstream/cloak/cortex');
+const { onSessionStart,
+        onSessionStop }    = require('vektor-slipstream/cloak/axon');
+const { checkWrite,
+        recordError }      = require('vektor-slipstream/cloak/cerebellum');
+const { getSessionSummary} = require('vektor-slipstream/cloak/token');
+
+// Clean terminal output (replaces emoji with box-drawing chars)
+const { createMemory }     = require('vektor-slipstream/boot');
+```
+
+### Claude Code setup
+
+Add to `.claude/settings.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "cloak": {
+      "command": "node",
+      "args": ["/path/to/node_modules/vektor-slipstream/index.js"],
+      "env": {
+        "VEKTOR_LICENCE_KEY": "your-licence-key",
+        "CLOAK_PROJECT_PATH": "/path/to/your/project"
+      }
+    }
+  },
+  "hooks": {
+    "SessionStart": [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook SessionStart" }],
+    "Stop":         [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook Stop" }],
+    "PreToolUse":   [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook PreToolUse" }],
+    "PostToolUse":  [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook PostToolUse" }]
+  }
+}
+```
+
+### Usage
+
+```js
+// Scan project files into Vektor entity graph (call once on init)
+await cloak_cortex({})
+
+// Start session — loads last context automatically
+await cloak_axon({ action: 'start' })
+
+// Check before a risky write
+await cloak_cerebellum({
+  action: 'check',
+  content: '...code...',
+  filePath: 'src/auth.ts'
+})
+
+// Record a bug you just hit
+await cloak_cerebellum({
+  action: 'record_error',
+  description: 'Null ref on user.id when DB returns empty',
+  filePath: 'src/auth.ts',
+  errorType: 'null_reference',
+  fix: 'Add guard: if (user && user.id)'
+})
+
+// Save session with intent — the "why" not just the "what"
+await cloak_axon({
+  action: 'stop',
+  narrative: 'Fixed null reference in auth module'
+})
+
+// Check token waste
+await cloak_token({ action: 'summary' })
+```
+
+### Architecture
+
 ```
+Claude Code
+    ↓ hooks + MCP tool calls
+CLOAK (4 tools, ~800 lines Node.js)
+    ↓ memory.remember() / memory.recall()
+Vektor / MAGMA
+    ↓ 4-layer graph (semantic, temporal, causal, entity)
+SQLite-vec (local, no cloud)
+```
+
+### DB growth
+
+CLOAK writes 3-5 nodes per session — not per operation.
+At 1 year of daily use: ~1,000 nodes. Sub-millisecond recall throughout.
+
+> ⚠️ **Concurrency warning**: Use stdio MCP (default). The HTTP mode
+> (`CLOAK_HTTP=1`) does not support concurrent multi-agent sessions.
+
+---
 
 ## What's Included
 
-- **MAGMA graph** — 4-layer associative memory (semantic, causal, temporal, entity)
-- **AUDN curation** — zero contradictions, zero duplicates
-- **REM dream cycle** — 50:1 memory compression
-- **Claude MCP server** — persistent memory for Claude Desktop
-- **Cloak** — stealth browser, AES-256 vault, layout sensor
-- **Mistral bridge** — vektor_memoire tool for Le Chat
-- **LangChain · OpenAI · Gemini · Groq · Ollama** — all supported
-- **Local ONNX embeddings** — $0 embedding cost, no API key
-- **Single SQLite file** — portable, yours forever
+### Memory Core (MAGMA)
+
+- 4-layer associative graph — semantic, causal, temporal, entity
+- AUDN curation loop — zero contradictions, zero duplicates
+- REM dream cycle — up to 50:1 compression
+- Sub-20ms recall — HNSW index, local SQLite
+- Local ONNX embeddings — $0 embedding cost, no API key required
+
+### Integrations
+
+- **Claude MCP** — `vektor_recall`, `vektor_store`, `vektor_graph`, `vektor_delta`
+- **Claude Code** — CLOAK 4-tool developer context layer (see above)
+- **LangChain** — v1 + v2 adapter included
+- **OpenAI Agents SDK** — drop-in integration
+- **Mistral** — `vektor_memoire` HTTP tool, localhost bridge
+- **Gemini · Groq · Ollama** — provider agnostic
+
+### Cloak (Sovereign Identity)
+
+- `cloak_fetch` — stealth headless browser fetch
+- `cloak_render` — computed CSS · post-JS DOM sensor
+- `cloak_passport` — AES-256-GCM credential vault, machine-bound
+- `cloak_diff` — semantic diff since last fetch
+- `tokens_saved` — ROI audit per session
+
+```js
+const { cloak_passport, cloak_fetch, tokens_saved } = require('vektor-slipstream/cloak');
+
+cloak_passport('GITHUB_TOKEN', 'ghp_xxxx');
+const token = cloak_passport('GITHUB_TOKEN');
+
+const { text, tokensSaved } = await cloak_fetch('https://example.com');
+
+const roi = tokens_saved({ raw_tokens: 10000, actual_tokens: 3000 });
+// → { reduction_pct: 70, cost_saved_usd: 0.0175, roi_multiple: 2.3 }
+```
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Recall latency | ~8ms avg (local SQLite) |
+| Embedding cost | $0 — fully local ONNX |
+| Embedding latency | ~10ms GPU / ~25ms CPU |
+| First run | ~2 min (downloads ~25MB model once) |
+| Subsequent boots | <100ms |
+
+## Hardware Auto-Detection
+
+Zero config. VEKTOR detects and uses the best available accelerator:
+
+- **NVIDIA CUDA** — GPU acceleration
+- **Apple Silicon** — CoreML
+- **CPU** — optimised fallback, works everywhere
 
 ## Licence
 
-Commercial licence. One-time payment. 3-machine activation via Polar.  
-Purchase at: https://vektormemory.com/product#pricing  
-Support: hello@vektormemory.com
+Commercial licence. One-time payment of $159. Activates on up to 3 machines.
+Manage at [polar.sh](https://polar.sh).
+
+Purchase: [vektormemory.com/product#pricing](https://vektormemory.com/product#pricing)
+Docs: [vektormemory.com/docs](https://vektormemory.com/docs)
+Support: hello@vektormemory.com
+
+## Research
+
+Built on peer-reviewed research:
+
+- [MAGMA (arxiv:2601.03236)](https://arxiv.org/abs/2601.03236) — Multi-Graph Agentic Memory Architecture
+- [EverMemOS (arxiv:2601.02163)](https://arxiv.org/abs/2601.02163) — Self-Organizing Memory OS
+- [HippoRAG (arxiv:2405.14831)](https://arxiv.org/abs/2405.14831) — Neurobiologically Inspired Long-Term Memory (NeurIPS 2024)
+- [Mem0 (arxiv:2504.19413)](https://arxiv.org/abs/2504.19413) — Production-Ready Agent Memory

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
+ */