agent-working-memory 0.7.16 → 0.8.5

package/src/types/agent.ts

@@ -1,67 +1,67 @@
-// 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.
- */
-
-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,
-};
+// 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.
+ */
+
+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

@@ -1,46 +1,46 @@
-// 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;
-}
+// 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

@@ -46,6 +46,15 @@ export interface Engram {
   // Memory type (content classification)
   memoryType: MemoryType;
 
+  // Optional story-time / sequence ordering (0.8 Cluster A). NULL for engrams
+  // without a caller-supplied sequence. Used by `sortBy: "sequence"` on search
+  // and by /memory/latest-by-tag (0.8 Cluster C).
+  sequence: number | null;
+
+  // Typed references to other engrams (0.8 Cluster A schema; wired to HTTP
+  // in Cluster D). Stored as JSON in references_json column.
+  references: EngramReference[] | null;
+
   // 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
@@ -56,7 +65,7 @@ export interface Engram {
   blockedBy: string | null;   // ID of blocking engram/task
 }
 
-export type EngramStage = 'staging' | 'active' | 'consolidated' | 'archived';
+export type EngramStage = 'staging' | 'active' | 'consolidated' | 'fading' | 'archived';
 
 export type TaskStatus = 'open' | 'in_progress' | 'blocked' | 'done';
 export type TaskPriority = 'urgent' | 'high' | 'medium' | 'low';
@@ -71,7 +80,39 @@ export type TaskPriority = 'urgent' | 'high' | 'medium' | 'low';
  * ephemeral:  Temporary context (debugging traces, session-specific notes).
  *             Stronger time decay, lower recall priority.
  */
-export type MemoryClass = 'canonical' | 'working' | 'ephemeral';
+/**
+ * Memory class — write-time classification controlling salience behavior
+ * and downstream retrieval semantics.
+ *
+ * canonical:  Source-of-truth memories. Salience floor 0.7, never stage.
+ *             Surfaced via cognitive `/activate` and deterministic queries.
+ *
+ * working:    Default. Observations, findings, progress notes. Standard
+ *             salience rules apply. Surfaced via all retrieval paths.
+ *
+ * ephemeral:  Temporary context. Stronger time decay, lower recall priority.
+ *
+ * structural: (0.8+) System-written event-log records — chapter analyses,
+ *             promise advancements, materialized-view feeds. Salience floor
+ *             0.7 like canonical, but EXCLUDED from cognitive `/activate`
+ *             by default (callers opt in via `includeStructural: true`),
+ *             skip temporal-adjacency edges, skip default embedding. Used
+ *             for high-volume deterministic substrate where cognitive
+ *             retrieval would just add noise.
+ */
+export type MemoryClass = 'canonical' | 'working' | 'ephemeral' | 'structural';
+
+/**
+ * Typed cross-record link stored alongside an engram in references_json.
+ * Wired through HTTP in 0.8 Cluster D; schema slot added in Cluster A.
+ */
+export interface EngramReference {
+  type: 'advances' | 'resolves' | 'subverts' | 'abandons' | 'extends' | 'supersedes';
+  /** ID of the referenced engram. Either this or matchConcept must be set. */
+  matchEngramId?: string;
+  /** Concept of the referenced engram (resolved at write time in 0.8 D). */
+  matchConcept?: string;
+}
 
 /**
  * Memory type — content classification for retrieval routing.
@@ -113,6 +154,10 @@ export interface EngramCreate {
   taskStatus?: TaskStatus;
   taskPriority?: TaskPriority;
   blockedBy?: string;
+  /** Optional story-time / sequence ordering (0.8 Cluster A). */
+  sequence?: number;
+  /** Typed cross-record links (0.8 Cluster A schema; HTTP in Cluster D). */
+  references?: EngramReference[];
 }
 
 /**
@@ -145,6 +190,20 @@ export interface ActivationResult {
   phaseScores: PhaseScores;  // Per-phase breakdown for explainability
   why: string;               // Human-readable explanation
   associations: Association[];
+  /**
+   * Recall confidence — score-distribution-aware signal in [0, 1].
+   * Same value on every result in the same recall (it describes the
+   * *set*, not the individual). Computed once after final ranking.
+   * See `src/engine/confidence.ts` for the formula.
+   */
+  confidence?: number;
+  /**
+   * Confidence-adaptive content preview (Paper 3: cognitive teaming).
+   * Set when the query opts in via `granularity: 'compact' | 'auto'`.
+   * Trades depth for breadth — short when the agent should scan a diverse
+   * set, full when there is a clear winner worth absorbing in full.
+   */
+  summary?: string;
 }
 
 /**
@@ -183,11 +242,36 @@ export interface ActivationQuery {
   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)
+  /**
+   * Opt-in confidence-based abstention. When set, the recall returns []
+   * if the computed recall confidence (see src/engine/confidence.ts) falls
+   * below the threshold. Independent of `abstentionThreshold` (reranker-based);
+   * uses score-distribution shape rather than reranker score.
+   * Typical values: 0.10 (strict — only abstain on clearly noisy queries),
+   * 0.25 (balanced), 0.40 (aggressive — only return high-confidence recall).
+   */
+  requireConfidence?: number;
   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
   workspace?: string;          // Search across all agents in this workspace (hive mode). If unset, agent-scoped only.
   bm25Only?: boolean;          // Skip embedding — fast text-only retrieval for bulk/benchmark scenarios
+  /**
+   * Output granularity (Paper 3: cognitive teaming, Brill 2018 ACT-R collaboration).
+   * Controls how much engram content the activation engine surfaces back to the caller,
+   * trading depth for breadth based on recall quality.
+   *
+   * 'full' (default): no change — callers get the raw engram with full content.
+   * 'compact': every result gets a short `summary` field (first ~200 chars of content).
+   *            Engram body is unchanged; callers can choose summary or content.
+   * 'auto':   confidence-adaptive. When the recall has a clear winner (confidence
+   *           ≥ AWM_GRANULARITY_AUTO_THRESHOLD, default 0.4), the top result keeps a
+   *           full-content summary and lower-ranked results get compact ones —
+   *           the agent absorbs the strong match in detail and scans alternatives.
+   *           When confidence is low, all results get compact summaries so the
+   *           agent can scan a diverse set without drowning in content.
+   */
+  granularity?: 'full' | 'compact' | 'auto';
 }
 
 /**
@@ -198,11 +282,25 @@ export interface SearchQuery {
   agentId: string;
   text?: string;          // Exact or partial text match
   concept?: string;       // Exact concept match
-  tags?: string[];        // Tag filter (AND)
+  /** Tag filter — AND semantics. Existing field kept for compat; equivalent to `tagsAll`.
+   *  If both `tags` and `tagsAll` are passed, results match tags from both arrays
+   *  (intersection of both AND-filters). */
+  tags?: string[];
+  /** AND-filter: engram must have ALL of these tags. Alias for legacy `tags`. (0.8 Cluster B) */
+  tagsAll?: string[];
+  /** OR-filter: engram must have AT LEAST ONE of these tags. (0.8 Cluster B) */
+  tagsAny?: string[];
+  /** NOT-filter: engram must have NONE of these tags. (0.8 Cluster B) */
+  tagsNone?: string[];
   stage?: EngramStage;
   retracted?: boolean;
   limit?: number;
   offset?: number;
+  /** Sort field. Defaults to `lastAccessed` (existing behavior preserved when
+   *  unspecified). `sequence` sorts NULL last. (0.8 Cluster B) */
+  sortBy?: 'createdAt' | 'sequence' | 'salience' | 'confidence' | 'lastAccessed';
+  /** Sort direction. Default `desc`. (0.8 Cluster B) */
+  sortOrder?: 'asc' | 'desc';
 }
 
 /**

package/src/types/eval.ts

@@ -1,100 +1,100 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * 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;
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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

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