agent-working-memory 0.10.0 → 0.11.0

package/src/storage/store.ts

@@ -1,80 +1,80 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Backend-agnostic storage contract for AWM.
- *
- * AWM 0.8.x introduces a pluggable storage layer:
- *   - SQLiteEngramStore: better-sqlite3 + FTS5 + BLOB embeddings (current default)
- *   - PGliteEngramStore: @electric-sql/pglite + pgvector + tsvector (opt-in via
- *     `AWM_STORE_BACKEND=pglite`, planned default in 0.9.x)
- *   - PostgresEngramStore: real Postgres backend for scale (planned, post-1.0)
- *
- * All backends provide the same public surface — defined here as `IEngramStore`.
- * The cognitive engines (activation, consolidation, Hebbian, eviction, etc.)
- * accept `IEngramStore` and work against any conforming backend.
- *
- * The interface is derived from the SQLite implementation via TypeScript's
- * `Omit<>` so it stays in sync automatically. SQLite-specific methods
- * (DB handle access, WAL checkpointing, slim-cache management, integrity
- * checks) are excluded — these are implementation-internal and don't belong
- * in a backend-agnostic contract.
- *
- * Future backends MUST implement every method on `IEngramStore`. They MAY
- * additionally expose backend-specific methods (e.g., PGlite-specific tooling,
- * Postgres pool management) — those are not part of the contract.
- */
-
-import type { EngramStore as SqliteEngramStore } from './sqlite.js';
-
-/**
- * Backend-specific methods on SqliteEngramStore that are NOT part of the
- * shared contract. Other backends may provide functionally-similar methods
- * under different names or not at all.
- */
-type SqliteSpecificMethods =
-  | 'getDb'              // Returns better-sqlite3 Database — SQLite-only API
-  | 'integrityCheck'     // SQLite PRAGMA integrity_check
-  | 'walCheckpoint'      // SQLite WAL checkpoint
-  | 'stopWalCheckpointTimer'
-  | 'backup'             // SQLite backup API; PGlite/Postgres use pg_dump
-  | 'warmSlimCache'      // In-memory cache pre-population (SQLite-specific perf opt)
-  | 'resetSlimCache'
-  | 'getSlimCacheStats'
-  | 'transaction';       // SQLite sync transaction helper — PGlite uses withTransaction
-
-/**
- * MaybePromise — covariant union that lets sync and async backends share one contract.
- *
- * Engines `await` every store call. `await T` resolves to T immediately when
- * the backend is sync (SQLite, returning bare values) and resolves the Promise
- * when the backend is async (PGlite). Both shapes satisfy the same interface.
- */
-type MaybePromise<T> = T | Promise<T>;
-
-/**
- * Turn every method return type R into `MaybePromise<Awaited<R>>` so the
- * contract accepts both sync and async backends.
- */
-type AsyncifyMethods<T> = {
-  [K in keyof T]: T[K] extends (...args: infer A) => infer R
-    ? (...args: A) => MaybePromise<Awaited<R>>
-    : T[K];
-};
-
-/**
- * The backend-agnostic storage contract.
- *
- * Any class with this shape can be used as the EngramStore for the AWM
- * cognitive engines. New backends should `implements IEngramStore` to get
- * compile-time enforcement of the full surface.
- */
-export type IEngramStore = AsyncifyMethods<Omit<SqliteEngramStore, SqliteSpecificMethods>>;
-
-/**
- * Convenience type-only re-export so consumers can `import type { EngramStore }`
- * from this module and get the backend-agnostic contract instead of the
- * SQLite-specific class. Existing imports from `'../storage/sqlite.js'`
- * continue to work and resolve to the SQLite class (which is a structural
- * supertype of IEngramStore).
- */
-export type EngramStore = IEngramStore;
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Backend-agnostic storage contract for AWM.
+ *
+ * AWM 0.8.x introduces a pluggable storage layer:
+ *   - SQLiteEngramStore: better-sqlite3 + FTS5 + BLOB embeddings (current default)
+ *   - PGliteEngramStore: @electric-sql/pglite + pgvector + tsvector (opt-in via
+ *     `AWM_STORE_BACKEND=pglite`, planned default in 0.9.x)
+ *   - PostgresEngramStore: real Postgres backend for scale (planned, post-1.0)
+ *
+ * All backends provide the same public surface — defined here as `IEngramStore`.
+ * The cognitive engines (activation, consolidation, Hebbian, eviction, etc.)
+ * accept `IEngramStore` and work against any conforming backend.
+ *
+ * The interface is derived from the SQLite implementation via TypeScript's
+ * `Omit<>` so it stays in sync automatically. SQLite-specific methods
+ * (DB handle access, WAL checkpointing, slim-cache management, integrity
+ * checks) are excluded — these are implementation-internal and don't belong
+ * in a backend-agnostic contract.
+ *
+ * Future backends MUST implement every method on `IEngramStore`. They MAY
+ * additionally expose backend-specific methods (e.g., PGlite-specific tooling,
+ * Postgres pool management) — those are not part of the contract.
+ */
+
+import type { EngramStore as SqliteEngramStore } from './sqlite.js';
+
+/**
+ * Backend-specific methods on SqliteEngramStore that are NOT part of the
+ * shared contract. Other backends may provide functionally-similar methods
+ * under different names or not at all.
+ */
+type SqliteSpecificMethods =
+  | 'getDb'              // Returns better-sqlite3 Database — SQLite-only API
+  | 'integrityCheck'     // SQLite PRAGMA integrity_check
+  | 'walCheckpoint'      // SQLite WAL checkpoint
+  | 'stopWalCheckpointTimer'
+  | 'backup'             // SQLite backup API; PGlite/Postgres use pg_dump
+  | 'warmSlimCache'      // In-memory cache pre-population (SQLite-specific perf opt)
+  | 'resetSlimCache'
+  | 'getSlimCacheStats'
+  | 'transaction';       // SQLite sync transaction helper — PGlite uses withTransaction
+
+/**
+ * MaybePromise — covariant union that lets sync and async backends share one contract.
+ *
+ * Engines `await` every store call. `await T` resolves to T immediately when
+ * the backend is sync (SQLite, returning bare values) and resolves the Promise
+ * when the backend is async (PGlite). Both shapes satisfy the same interface.
+ */
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Turn every method return type R into `MaybePromise<Awaited<R>>` so the
+ * contract accepts both sync and async backends.
+ */
+type AsyncifyMethods<T> = {
+  [K in keyof T]: T[K] extends (...args: infer A) => infer R
+    ? (...args: A) => MaybePromise<Awaited<R>>
+    : T[K];
+};
+
+/**
+ * The backend-agnostic storage contract.
+ *
+ * Any class with this shape can be used as the EngramStore for the AWM
+ * cognitive engines. New backends should `implements IEngramStore` to get
+ * compile-time enforcement of the full surface.
+ */
+export type IEngramStore = AsyncifyMethods<Omit<SqliteEngramStore, SqliteSpecificMethods>>;
+
+/**
+ * Convenience type-only re-export so consumers can `import type { EngramStore }`
+ * from this module and get the backend-agnostic contract instead of the
+ * SQLite-specific class. Existing imports from `'../storage/sqlite.js'`
+ * continue to work and resolve to the SQLite class (which is a structural
+ * supertype of IEngramStore).
+ */
+export type EngramStore = IEngramStore;

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/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';

package/src/version.ts

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+/**
+ * The running package version, read from package.json at runtime so the number
+ * reported by /health, the startup banner, and the MCP server always matches
+ * the actually-deployed build. Hand-maintained version literals drifted across
+ * releases (a 0.10.0 build was still reporting 0.8.5/0.8.8) — this removes them.
+ */
+function resolveVersion(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  // src/version.ts (dev) and dist/version.js (build) both sit one level below
+  // the package root; the ../../ fallback covers a deeper output nesting.
+  for (const rel of ['../package.json', '../../package.json']) {
+    try {
+      const v = JSON.parse(readFileSync(join(here, rel), 'utf8')).version;
+      if (typeof v === 'string' && v) return v;
+    } catch {
+      /* try the next candidate path */
+    }
+  }
+  return '0.0.0';
+}
+
+export const VERSION: string = resolveVersion();