agent-working-memory 0.5.6 → 0.6.0

package/src/storage/sqlite.ts

@@ -12,7 +12,7 @@ import { randomUUID } from 'node:crypto';
 import type {
   Engram, EngramCreate, EngramStage, Association, AssociationType,
   SearchQuery, SalienceFeatures, ActivationEvent, StagingEvent,
-  RetrievalFeedbackEvent, Episode, TaskStatus, TaskPriority, MemoryClass,
+  RetrievalFeedbackEvent, Episode, TaskStatus, TaskPriority, MemoryClass, MemoryType,
   ConsciousState, AutoCheckpoint, CheckpointRow,
 } from '../types/index.js';
 
@@ -35,6 +35,8 @@ export class EngramStore {
     this.db = new Database(dbPath);
     this.db.pragma('journal_mode = WAL');
     this.db.pragma('foreign_keys = ON');
+    this.db.pragma('busy_timeout = 5000');
+    this.db.pragma('synchronous = NORMAL');
     this.init();
   }
 
@@ -43,6 +45,27 @@ export class EngramStore {
     return this.db;
   }
 
+  /** Run PRAGMA quick_check and return true if DB is healthy. */
+  integrityCheck(): { ok: boolean; result: string } {
+    try {
+      const rows = this.db.pragma('quick_check') as Array<{ quick_check: string }>;
+      const result = rows[0]?.quick_check ?? 'unknown';
+      return { ok: result === 'ok', result };
+    } catch (err) {
+      return { ok: false, result: (err as Error).message };
+    }
+  }
+
+  /** Hot backup using SQLite backup API. Returns the backup path. */
+  backup(destPath: string): void {
+    this.db.backup(destPath);
+  }
+
+  /** Flush WAL to main database file. */
+  walCheckpoint(): void {
+    this.db.pragma('wal_checkpoint(TRUNCATE)');
+  }
+
   private init(): void {
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS engrams (
@@ -63,7 +86,8 @@ export class EngramStore {
         retracted INTEGER NOT NULL DEFAULT 0,
         retracted_by TEXT,
         retracted_at TEXT,
-        tags TEXT NOT NULL DEFAULT '[]'
+        tags TEXT NOT NULL DEFAULT '[]',
+        memory_type TEXT NOT NULL DEFAULT 'unclassified'
       );
 
       CREATE INDEX IF NOT EXISTS idx_engrams_agent ON engrams(agent_id);
@@ -211,6 +235,13 @@ export class EngramStore {
     try {
       this.db.exec(`ALTER TABLE conscious_state ADD COLUMN consolidation_cycle_count INTEGER NOT NULL DEFAULT 0`);
     } catch { /* column already exists */ }
+
+    // Migration: add memory_type column if missing
+    try {
+      this.db.prepare('SELECT memory_type FROM engrams LIMIT 0').get();
+    } catch {
+      this.db.exec(`ALTER TABLE engrams ADD COLUMN memory_type TEXT NOT NULL DEFAULT 'unclassified'`);
+    }
   }
 
   // --- Engram CRUD ---
@@ -225,8 +256,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, memory_class, supersedes, task_status, task_priority, blocked_by)
-      VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?)
+        ttl, memory_class, supersedes, task_status, task_priority, blocked_by, memory_type)
+      VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
       id, input.agentId, input.concept, input.content, embeddingBlob,
       input.confidence ?? 0.5,
@@ -242,6 +273,7 @@ export class EngramStore {
       input.taskStatus ?? null,
       input.taskPriority ?? null,
       input.blockedBy ?? null,
+      input.memoryType ?? 'unclassified',
     );
 
     return this.getEngram(id)!;
@@ -267,9 +299,21 @@ export class EngramStore {
     return (this.db.prepare(query).all(...params) as any[]).map(r => this.rowToEngram(r));
   }
 
+  /**
+   * Touch an engram: increment access count, update last_accessed, and
+   * nudge confidence upward. Each retrieval is weak evidence the memory
+   * is useful — bounded so only explicit feedback can push confidence
+   * above 0.85. Diminishing returns: first accesses matter most.
+   *
+   * Boost: +0.02 per access, scaled by 1/sqrt(accessCount+1), capped at 0.85.
+   */
   touchEngram(id: string): void {
     this.db.prepare(`
-      UPDATE engrams SET access_count = access_count + 1, last_accessed = ? WHERE id = ?
+      UPDATE engrams
+      SET access_count = access_count + 1,
+          last_accessed = ?,
+          confidence = MIN(0.85, confidence + 0.02 / (1.0 + sqrt(access_count)))
+      WHERE id = ?
     `).run(new Date().toISOString(), id);
   }
 
@@ -502,6 +546,10 @@ export class EngramStore {
     this.db.prepare('UPDATE engrams SET memory_class = ? WHERE id = ?').run(memoryClass, id);
   }
 
+  updateTags(id: string, tags: string[]): void {
+    this.db.prepare('UPDATE engrams SET tags = ? WHERE id = ?').run(JSON.stringify(tags), id);
+  }
+
   // --- Associations ---
 
   upsertAssociation(
@@ -722,6 +770,7 @@ export class EngramStore {
       tags: JSON.parse(row.tags),
       episodeId: row.episode_id ?? null,
       memoryClass: (row.memory_class ?? 'working') as MemoryClass,
+      memoryType: (row.memory_type ?? 'unclassified') as MemoryType,
       supersededBy: row.superseded_by ?? null,
       supersedes: row.supersedes ?? null,
       taskStatus: row.task_status ?? null,

package/src/types/engram.ts

@@ -43,6 +43,9 @@ export interface Engram {
   // Memory class
   memoryClass: MemoryClass;
 
+  // Memory type (content classification)
+  memoryType: MemoryType;
+
   // 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
@@ -70,6 +73,16 @@ export type TaskPriority = 'urgent' | 'high' | 'medium' | 'low';
  */
 export type MemoryClass = 'canonical' | 'working' | 'ephemeral';
 
+/**
+ * Memory type — content classification for retrieval routing.
+ *
+ * episodic:      Events, incidents, debugging sessions ("we did X because Y").
+ * semantic:      Facts, decisions, patterns ("X is true", "we use Y for Z").
+ * procedural:    How-to, steps, processes ("to deploy, run X then Y").
+ * unclassified:  Default for backwards compatibility.
+ */
+export type MemoryType = 'episodic' | 'semantic' | 'procedural' | 'unclassified';
+
 /**
  * Raw feature scores that produced the salience score.
  * Persisted for auditability and tuning.
@@ -95,6 +108,7 @@ export interface EngramCreate {
   episodeId?: string;
   ttl?: number;
   memoryClass?: MemoryClass;
+  memoryType?: MemoryType;
   supersedes?: string;
   taskStatus?: TaskStatus;
   taskPriority?: TaskPriority;
@@ -147,6 +161,18 @@ export interface PhaseScores {
   rerankerScore: number;   // Cross-encoder relevance (0-1), 0 if reranker disabled
 }
 
+/**
+ * Query mode — controls how the activation pipeline weights its signals.
+ *
+ * targeted:    Query has identifiers, ticket IDs, specific names. Boost BM25,
+ *              narrow graph beam, stronger decay, stricter vector z-gate.
+ * exploratory: Vague/conceptual query. Boost vector/semantic signals, wider
+ *              graph beam, weaker decay, relaxed z-gate.
+ * balanced:    Default weights (current behavior).
+ * auto:        Classify automatically based on query characteristics.
+ */
+export type QueryMode = 'targeted' | 'exploratory' | 'balanced' | 'auto';
+
 export interface ActivationQuery {
   agentId: string;
   context: string;
@@ -158,6 +184,8 @@ export interface ActivationQuery {
   useExpansion?: boolean;      // Enable query expansion (default: true)
   abstentionThreshold?: number; // Min reranker score to return results (default: 0)
   internal?: boolean;          // Skip access count increment, Hebbian update, and event logging (for system calls)
+  memoryType?: MemoryType;     // Filter by memory type (episodic, semantic, procedural)
+  mode?: QueryMode;            // Pipeline mode — 'auto' by default
 }
 
 /**