agent-working-memory 0.4.2 → 0.5.0

package/src/storage/sqlite.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * SQLite storage layer — persistence for engrams, associations, and eval events.
  *
@@ -10,10 +12,18 @@ import { randomUUID } from 'node:crypto';
 import type {
   Engram, EngramCreate, EngramStage, Association, AssociationType,
   SearchQuery, SalienceFeatures, ActivationEvent, StagingEvent,
-  RetrievalFeedbackEvent, Episode, TaskStatus, TaskPriority,
+  RetrievalFeedbackEvent, Episode, TaskStatus, TaskPriority, MemoryClass,
   ConsciousState, AutoCheckpoint, CheckpointRow,
 } from '../types/index.js';
 
+/** Safely convert a Node Buffer to Float32Array, respecting byteOffset/byteLength. */
+function bufferToFloat32Array(buf: Buffer | ArrayBuffer): Float32Array {
+  if (buf instanceof ArrayBuffer) return new Float32Array(buf);
+  // Node Buffer may share an underlying ArrayBuffer — slice to the exact region
+  const ab = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+  return new Float32Array(ab);
+}
+
 const DEFAULT_SALIENCE_FEATURES: SalienceFeatures = {
   surprise: 0, decisionMade: false, causalDepth: 0, resolutionEffort: 0, eventType: 'observation',
 };
@@ -162,6 +172,17 @@ export class EngramStore {
       this.db.exec('CREATE INDEX IF NOT EXISTS idx_engrams_task ON engrams(agent_id, task_status)');
     }
 
+    // Migration: add memory_class and supersession columns if missing
+    try {
+      this.db.prepare('SELECT memory_class FROM engrams LIMIT 0').get();
+    } catch {
+      this.db.exec(`
+        ALTER TABLE engrams ADD COLUMN memory_class TEXT NOT NULL DEFAULT 'working';
+        ALTER TABLE engrams ADD COLUMN superseded_by TEXT;
+        ALTER TABLE engrams ADD COLUMN supersedes TEXT;
+      `);
+    }
+
     // Migration: add conscious_state table for checkpointing
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS conscious_state (
@@ -193,8 +214,8 @@ export class EngramStore {
     this.db.prepare(`
       INSERT INTO engrams (id, agent_id, concept, content, embedding, confidence, salience,
         access_count, last_accessed, created_at, salience_features, reason_codes, stage, tags, episode_id,
-        ttl, task_status, task_priority, blocked_by)
-      VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?)
+        ttl, memory_class, supersedes, task_status, task_priority, blocked_by)
+      VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
       id, input.agentId, input.concept, input.content, embeddingBlob,
       input.confidence ?? 0.5,
@@ -205,6 +226,8 @@ export class EngramStore {
       JSON.stringify(input.tags ?? []),
       input.episodeId ?? null,
       input.ttl ?? null,
+      input.memoryClass ?? 'working',
+      input.supersedes ?? null,
       input.taskStatus ?? null,
       input.taskPriority ?? null,
       input.blockedBy ?? null,
@@ -445,6 +468,29 @@ export class EngramStore {
     return row ? this.rowToEngram(row) : null;
   }
 
+  // --- Supersession ---
+
+  /**
+   * Mark an engram as superseded by another.
+   * The old memory stays in the DB (historical) but gets down-ranked in recall.
+   */
+  supersedeEngram(oldId: string, newId: string): void {
+    this.db.prepare('UPDATE engrams SET superseded_by = ? WHERE id = ?').run(newId, oldId);
+    this.db.prepare('UPDATE engrams SET supersedes = ? WHERE id = ?').run(oldId, newId);
+  }
+
+  /**
+   * Check if an engram has been superseded.
+   */
+  isSuperseded(id: string): boolean {
+    const row = this.db.prepare('SELECT superseded_by FROM engrams WHERE id = ?').get(id) as any;
+    return row?.superseded_by != null;
+  }
+
+  updateMemoryClass(id: string, memoryClass: MemoryClass): void {
+    this.db.prepare('UPDATE engrams SET memory_class = ? WHERE id = ?').run(memoryClass, id);
+  }
+
   // --- Associations ---
 
   upsertAssociation(
@@ -478,6 +524,13 @@ export class EngramStore {
     return (rows as any[]).map(r => this.rowToAssociation(r));
   }
 
+  getOutgoingAssociations(engramId: string): Association[] {
+    const rows = this.db.prepare(
+      'SELECT * FROM associations WHERE from_engram_id = ?'
+    ).all(engramId);
+    return (rows as any[]).map(r => this.rowToAssociation(r));
+  }
+
   countAssociationsFor(engramId: string): number {
     const row = this.db.prepare(
       'SELECT COUNT(*) as count FROM associations WHERE from_engram_id = ?'
@@ -641,7 +694,7 @@ export class EngramStore {
       concept: row.concept,
       content: row.content,
       embedding: row.embedding
-        ? Array.from(new Float32Array(row.embedding.buffer ?? row.embedding))
+        ? Array.from(bufferToFloat32Array(row.embedding))
         : null,
       confidence: row.confidence,
       salience: row.salience,
@@ -657,6 +710,9 @@ export class EngramStore {
       retractedAt: row.retracted_at ? new Date(row.retracted_at) : null,
       tags: JSON.parse(row.tags),
       episodeId: row.episode_id ?? null,
+      memoryClass: (row.memory_class ?? 'working') as MemoryClass,
+      supersededBy: row.superseded_by ?? null,
+      supersedes: row.supersedes ?? null,
       taskStatus: row.task_status ?? null,
       taskPriority: row.task_priority ?? null,
       blockedBy: row.blocked_by ?? null,
@@ -751,7 +807,7 @@ export class EngramStore {
       agentId: row.agent_id,
       label: row.label,
       embedding: row.embedding
-        ? Array.from(new Float32Array(row.embedding.buffer ?? row.embedding))
+        ? Array.from(bufferToFloat32Array(row.embedding))
         : null,
       engramCount: row.engram_count,
       startTime: new Date(row.start_time),

package/src/types/agent.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Agent — a consciousness boundary.
  * Each agent has its own isolated memory space with capacity budgets.

package/src/types/checkpoint.ts

@@ -1,44 +1,46 @@
-/**
- * Checkpoint types — conscious state preservation across compaction.
- *
- * ConsciousState: explicit structured snapshot (saved by agent)
- * AutoCheckpoint: implicit lightweight tracking (updated on every write/recall)
- */
-
-export interface ConsciousState {
-  currentTask: string;
-  decisions: string[];
-  activeFiles: string[];
-  nextSteps: string[];
-  relatedMemoryIds: string[];
-  notes: string;
-  episodeId: string | null;
-}
-
-export interface AutoCheckpoint {
-  lastWriteId: string | null;
-  lastRecallContext: string | null;
-  lastRecallIds: string[];
-  lastActivityAt: Date;
-  writeCountSinceConsolidation: number;
-  recallCountSinceConsolidation: number;
-}
-
-export interface CheckpointRow {
-  agentId: string;
-  auto: AutoCheckpoint;
-  executionState: ConsciousState | null;
-  checkpointAt: Date | null;
-  lastConsolidationAt: Date | null;
-  lastMiniConsolidationAt: Date | null;
-  updatedAt: Date;
-}
-
-export interface RestoreResult {
-  executionState: ConsciousState | null;
-  checkpointAt: Date | null;
-  recalledMemories: Array<{ id: string; concept: string; content: string; score: number }>;
-  lastWrite: { id: string; concept: string; content: string } | null;
-  idleMs: number;
-  miniConsolidationTriggered: boolean;
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Checkpoint types — conscious state preservation across compaction.
+ *
+ * ConsciousState: explicit structured snapshot (saved by agent)
+ * AutoCheckpoint: implicit lightweight tracking (updated on every write/recall)
+ */
+
+export interface ConsciousState {
+  currentTask: string;
+  decisions: string[];
+  activeFiles: string[];
+  nextSteps: string[];
+  relatedMemoryIds: string[];
+  notes: string;
+  episodeId: string | null;
+}
+
+export interface AutoCheckpoint {
+  lastWriteId: string | null;
+  lastRecallContext: string | null;
+  lastRecallIds: string[];
+  lastActivityAt: Date;
+  writeCountSinceConsolidation: number;
+  recallCountSinceConsolidation: number;
+}
+
+export interface CheckpointRow {
+  agentId: string;
+  auto: AutoCheckpoint;
+  executionState: ConsciousState | null;
+  checkpointAt: Date | null;
+  lastConsolidationAt: Date | null;
+  lastMiniConsolidationAt: Date | null;
+  updatedAt: Date;
+}
+
+export interface RestoreResult {
+  executionState: ConsciousState | null;
+  checkpointAt: Date | null;
+  recalledMemories: Array<{ id: string; concept: string; content: string; score: number }>;
+  lastWrite: { id: string; concept: string; content: string } | null;
+  idleMs: number;
+  miniConsolidationTriggered: boolean;
+}

package/src/types/engram.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Engram — the fundamental unit of agent memory.
  *
@@ -38,6 +40,13 @@ export interface Engram {
   // Episode grouping
   episodeId: string | null;
 
+  // Memory class
+  memoryClass: MemoryClass;
+
+  // Supersession — "this replaces that" (not retraction — original wasn't wrong, just outdated)
+  supersededBy: string | null;   // ID of the engram that replaced this one
+  supersedes: string | null;     // ID of the engram this one replaces
+
   // Task management (null = not a task)
   taskStatus: TaskStatus | null;
   taskPriority: TaskPriority | null;
@@ -49,6 +58,18 @@ export type EngramStage = 'staging' | 'active' | 'consolidated' | 'archived';
 export type TaskStatus = 'open' | 'in_progress' | 'blocked' | 'done';
 export type TaskPriority = 'urgent' | 'high' | 'medium' | 'low';
 
+/**
+ * Memory class — controls salience floor and recall priority.
+ *
+ * canonical:  Source-of-truth facts (current state, decisions, architecture).
+ *             Never goes to staging. Minimum salience 0.7.
+ * working:    Normal observations, learnings, context (default).
+ *             Standard salience rules apply.
+ * ephemeral:  Temporary context (debugging traces, session-specific notes).
+ *             Stronger time decay, lower recall priority.
+ */
+export type MemoryClass = 'canonical' | 'working' | 'ephemeral';
+
 /**
  * Raw feature scores that produced the salience score.
  * Persisted for auditability and tuning.
@@ -73,6 +94,8 @@ export interface EngramCreate {
   reasonCodes?: string[];
   episodeId?: string;
   ttl?: number;
+  memoryClass?: MemoryClass;
+  supersedes?: string;
   taskStatus?: TaskStatus;
   taskPriority?: TaskPriority;
   blockedBy?: string;

package/src/types/eval.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Evaluation types — measuring whether memory actually helps.
  *

package/src/types/index.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 export * from './engram.js';
 export * from './agent.js';
 export * from './eval.js';