agent-working-memory 0.3.0

package/src/types/agent.ts

@@ -0,0 +1,65 @@
+/**
+ * Agent — a consciousness boundary.
+ * Each agent has its own isolated memory space with capacity budgets.
+ */
+
+export interface Agent {
+  id: string;
+  name: string;
+  createdAt: Date;
+  config: AgentConfig;
+}
+
+export interface AgentConfig {
+  // Salience filter thresholds
+  salienceThreshold: number;       // Below this → discard
+  stagingThreshold: number;        // Below salience but above this → staging buffer
+  stagingTtlMs: number;            // Default TTL for staging entries
+
+  // Capacity budgets (eviction triggers when exceeded)
+  maxActiveEngrams: number;        // Hard cap on active memory
+  maxStagingEngrams: number;       // Hard cap on staging buffer
+  maxEdgesPerEngram: number;       // Prevent graph explosion
+
+  // Activation pipeline tuning
+  activationLimit: number;         // Max results per activation query
+  hebbianRate: number;             // Learning rate for association strengthening
+  decayExponent: number;           // ACT-R d parameter (default 0.5)
+  edgeDecayHalfLifeDays: number;   // How fast unused edges weaken
+
+  // Connection engine
+  connectionThreshold: number;     // Min resonance score to form a connection
+  connectionCheckIntervalMs: number;
+
+  // Consolidation
+  consolidationIntervalMs: number; // How often to check for merge candidates
+  consolidationSimilarity: number; // Threshold for merging similar engrams
+
+  // Confidence updates
+  feedbackPositiveBoost: number;   // How much positive feedback increases confidence
+  feedbackNegativePenalty: number; // How much negative feedback decreases confidence
+}
+
+export const DEFAULT_AGENT_CONFIG: AgentConfig = {
+  salienceThreshold: 0.4,
+  stagingThreshold: 0.2,
+  stagingTtlMs: 24 * 60 * 60 * 1000,       // 24 hours
+
+  maxActiveEngrams: 10_000,
+  maxStagingEngrams: 1_000,
+  maxEdgesPerEngram: 20,
+
+  activationLimit: 10,
+  hebbianRate: 0.25,
+  decayExponent: 0.5,
+  edgeDecayHalfLifeDays: 7,
+
+  connectionThreshold: 0.7,
+  connectionCheckIntervalMs: 60_000,
+
+  consolidationIntervalMs: 300_000,          // 5 minutes
+  consolidationSimilarity: 0.85,
+
+  feedbackPositiveBoost: 0.05,
+  feedbackNegativePenalty: 0.1,
+};

package/src/types/checkpoint.ts

@@ -0,0 +1,44 @@
+/**
+ * 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

@@ -0,0 +1,194 @@
+/**
+ * Engram — the fundamental unit of agent memory.
+ *
+ * An engram represents a single memory trace with salience metadata,
+ * staging lifecycle, retraction support, and optional task management.
+ */
+
+export interface Engram {
+  id: string;
+  agentId: string;
+  concept: string;
+  content: string;
+  embedding: number[] | null;
+
+  // Cognitive scores
+  confidence: number;    // 0-1 Bayesian posterior — updated on retrieval feedback
+  salience: number;      // Write-time importance score
+  accessCount: number;   // For ACT-R decay calculation
+  lastAccessed: Date;
+  createdAt: Date;
+
+  // Salience audit trail
+  salienceFeatures: SalienceFeatures;
+  reasonCodes: string[];
+
+  // Lifecycle
+  stage: EngramStage;
+  ttl: number | null;    // Milliseconds — only for staging buffer entries
+
+  // Negative memory
+  retracted: boolean;
+  retractedBy: string | null;   // ID of the engram that invalidated this one
+  retractedAt: Date | null;
+
+  // Tags for concept-based retrieval
+  tags: string[];
+
+  // Episode grouping
+  episodeId: string | null;
+
+  // Task management (null = not a task)
+  taskStatus: TaskStatus | null;
+  taskPriority: TaskPriority | null;
+  blockedBy: string | null;   // ID of blocking engram/task
+}
+
+export type EngramStage = 'staging' | 'active' | 'consolidated' | 'archived';
+
+export type TaskStatus = 'open' | 'in_progress' | 'blocked' | 'done';
+export type TaskPriority = 'urgent' | 'high' | 'medium' | 'low';
+
+/**
+ * Raw feature scores that produced the salience score.
+ * Persisted for auditability and tuning.
+ */
+export interface SalienceFeatures {
+  surprise: number;
+  decisionMade: boolean;
+  causalDepth: number;
+  resolutionEffort: number;
+  eventType: string;
+}
+
+export interface EngramCreate {
+  agentId: string;
+  concept: string;
+  content: string;
+  tags?: string[];
+  embedding?: number[];
+  salience?: number;
+  confidence?: number;
+  salienceFeatures?: SalienceFeatures;
+  reasonCodes?: string[];
+  episodeId?: string;
+  ttl?: number;
+  taskStatus?: TaskStatus;
+  taskPriority?: TaskPriority;
+  blockedBy?: string;
+}
+
+/**
+ * Association — weighted edge between two engrams.
+ * Strengthened by Hebbian co-activation, decays when unused.
+ * Capped at MAX_EDGES_PER_ENGRAM to prevent graph explosion.
+ */
+export interface Association {
+  id: string;
+  fromEngramId: string;
+  toEngramId: string;
+  weight: number;            // Log-space, updated via Hebbian rule
+  confidence: number;        // Edge-level confidence (separate from node)
+  type: AssociationType;
+  activationCount: number;   // How many times this edge contributed to retrieval
+  createdAt: Date;
+  lastActivated: Date;
+}
+
+export type AssociationType = 'hebbian' | 'connection' | 'causal' | 'temporal' | 'invalidation' | 'bridge';
+
+export const MAX_EDGES_PER_ENGRAM = 20;
+
+/**
+ * Activation result — returned from the activation pipeline.
+ */
+export interface ActivationResult {
+  engram: Engram;
+  score: number;
+  phaseScores: PhaseScores;  // Per-phase breakdown for explainability
+  why: string;               // Human-readable explanation
+  associations: Association[];
+}
+
+/**
+ * Per-phase scoring breakdown — full audit of how each phase contributed.
+ */
+export interface PhaseScores {
+  textMatch: number;
+  vectorMatch: number;
+  decayScore: number;
+  hebbianBoost: number;
+  graphBoost: number;
+  confidenceGate: number;
+  composite: number;
+  rerankerScore: number;   // Cross-encoder relevance (0-1), 0 if reranker disabled
+}
+
+export interface ActivationQuery {
+  agentId: string;
+  context: string;
+  limit?: number;
+  minScore?: number;
+  includeStaging?: boolean;
+  includeRetracted?: boolean;
+  useReranker?: boolean;       // Enable cross-encoder re-ranking (default: true)
+  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)
+}
+
+/**
+ * Search query — deterministic retrieval for diagnostics and debugging.
+ * Separate from activation (which is cognitive/associative).
+ */
+export interface SearchQuery {
+  agentId: string;
+  text?: string;          // Exact or partial text match
+  concept?: string;       // Exact concept match
+  tags?: string[];        // Tag filter (AND)
+  stage?: EngramStage;
+  retracted?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Retrieval feedback — agent reports whether a memory was useful.
+ * Used to update confidence scores and eval metrics.
+ */
+export interface RetrievalFeedback {
+  engramId: string;
+  useful: boolean;
+  context: string;        // What the agent was doing when it judged usefulness
+}
+
+/**
+ * Retraction — marks a memory as invalid/wrong.
+ */
+export interface Retraction {
+  targetEngramId: string;
+  reason: string;
+  counterContent?: string;  // Optional: what the correct information is
+  agentId: string;
+}
+
+/**
+ * Episode — a temporal grouping of engrams from a session or time window.
+ * Enables episode-first retrieval: find relevant episodes, then drill into engrams.
+ */
+export interface Episode {
+  id: string;
+  agentId: string;
+  label: string;           // Short description (e.g., "Express migration session")
+  embedding: number[] | null;  // Centroid of member engram embeddings
+  engramCount: number;
+  startTime: Date;
+  endTime: Date;
+  createdAt: Date;
+}
+
+export interface EpisodeCreate {
+  agentId: string;
+  label: string;
+  embedding?: number[];
+}

package/src/types/eval.ts

@@ -0,0 +1,98 @@
+/**
+ * Evaluation types — measuring whether memory actually helps.
+ *
+ * Four measurement dimensions:
+ *   1. Retrieval quality (precision, recall, latency)
+ *   2. Connection quality (edge utility, stability)
+ *   3. Staging accuracy (promotion precision, discard regret)
+ *   4. Task impact (with/without memory comparison)
+ */
+
+/**
+ * Single activation event record — logged for offline analysis.
+ */
+export interface ActivationEvent {
+  id: string;
+  agentId: string;
+  timestamp: Date;
+  context: string;
+  resultsReturned: number;
+  topScore: number;
+  latencyMs: number;
+  engramIds: string[];
+  feedback?: RetrievalFeedbackEvent[];
+}
+
+export interface RetrievalFeedbackEvent {
+  engramId: string;
+  useful: boolean;
+  timestamp: Date;
+}
+
+/**
+ * Staging lifecycle event — tracks promote/discard decisions.
+ */
+export interface StagingEvent {
+  engramId: string;
+  agentId: string;
+  action: 'promoted' | 'discarded' | 'expired';
+  resonanceScore: number | null;
+  timestamp: Date;
+  ageMs: number;  // How long it lived in staging
+}
+
+/**
+ * Aggregate metrics snapshot — computed periodically.
+ */
+export interface EvalMetrics {
+  agentId: string;
+  timestamp: Date;
+  window: string;  // e.g., "24h", "7d"
+
+  // Retrieval quality
+  activationCount: number;
+  avgPrecisionAtK: number;    // Of returned results, % judged useful
+  avgLatencyMs: number;
+  p95LatencyMs: number;
+
+  // Connection quality
+  totalEdges: number;
+  edgesUsedInActivation: number;
+  edgeUtilityRate: number;    // % of edges that contributed to retrieval
+  avgEdgeSurvivalDays: number;
+
+  // Staging accuracy
+  totalStaged: number;
+  promotedCount: number;
+  discardedCount: number;
+  promotionPrecision: number; // % of promoted items later used
+  discardRegret: number;      // % of discarded items agent re-introduced
+
+  // Memory health
+  activeEngramCount: number;
+  stagingEngramCount: number;
+  retractedCount: number;
+  consolidatedCount: number;
+  avgConfidence: number;
+
+  // Contamination tracking
+  staleUsageCount: number;        // Activations using outdated engrams
+  retractionRate: number;         // Rate of memories being invalidated
+}
+
+/**
+ * Task trial — for with/without memory comparison.
+ */
+export interface TaskTrial {
+  id: string;
+  agentId: string;
+  taskDescription: string;
+  memoryEnabled: boolean;
+  startedAt: Date;
+  completedAt: Date | null;
+  success: boolean | null;
+  stepsToCompletion: number;
+  errorsEncountered: number;
+  memoriesActivated: number;
+  userCorrections: number;
+}

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export * from './engram.js';
+export * from './agent.js';
+export * from './eval.js';
+export * from './checkpoint.js';