agent-working-memory 0.5.4 → 0.5.6

package/src/core/hebbian.ts

@@ -1,93 +1,93 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Hebbian Learning — "neurons that fire together wire together"
- *
- * When two engrams are co-activated (retrieved together in the same
- * activation query), their association weight increases.
- *
- * Log-space weight update prevents runaway growth:
- *   logNew = log(w) + signal * log(1 + rate)
- *
- * Associations decay symmetrically when unused.
- */
-
-const MIN_WEIGHT = 0.001;
-const MAX_WEIGHT = 5.0;  // Cap at 5 to prevent graph walk explosion
-
-/**
- * Strengthen an association weight after co-activation.
- */
-export function strengthenAssociation(
-  currentWeight: number,
-  signal: number = 1.0,
-  rate: number = 0.25
-): number {
-  const logW = Math.log(Math.max(currentWeight, MIN_WEIGHT));
-  const logNew = logW + signal * Math.log(1 + rate);
-  return Math.min(Math.exp(logNew), MAX_WEIGHT);
-}
-
-/**
- * Weaken an association weight due to lack of co-activation.
- * Called periodically by the connection engine.
- */
-export function decayAssociation(
-  currentWeight: number,
-  daysSinceActivation: number,
-  halfLife: number = 7.0 // days
-): number {
-  const decayFactor = Math.pow(0.5, daysSinceActivation / halfLife);
-  return Math.max(currentWeight * decayFactor, MIN_WEIGHT);
-}
-
-/**
- * Ring buffer for tracking recent co-activations.
- * Feeds the Hebbian worker — when two engrams appear in the buffer
- * within a window, their association is strengthened.
- */
-export class CoActivationBuffer {
-  private buffer: { engramId: string; timestamp: number }[] = [];
-  private maxSize: number;
-
-  constructor(maxSize: number = 50) {
-    this.maxSize = maxSize;
-  }
-
-  push(engramId: string): void {
-    this.buffer.push({ engramId, timestamp: Date.now() });
-    if (this.buffer.length > this.maxSize) {
-      this.buffer.shift();
-    }
-  }
-
-  pushBatch(engramIds: string[]): void {
-    for (const id of engramIds) {
-      this.push(id);
-    }
-  }
-
-  /**
-   * Get all pairs of engrams that were co-activated within windowMs.
-   */
-  getCoActivatedPairs(windowMs: number = 5000): [string, string][] {
-    const pairs: [string, string][] = [];
-    for (let i = 0; i < this.buffer.length; i++) {
-      for (let j = i + 1; j < this.buffer.length; j++) {
-        const a = this.buffer[i];
-        const b = this.buffer[j];
-        if (
-          a.engramId !== b.engramId &&
-          Math.abs(a.timestamp - b.timestamp) <= windowMs
-        ) {
-          pairs.push([a.engramId, b.engramId]);
-        }
-      }
-    }
-    return pairs;
-  }
-
-  clear(): void {
-    this.buffer = [];
-  }
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Hebbian Learning — "neurons that fire together wire together"
+ *
+ * When two engrams are co-activated (retrieved together in the same
+ * activation query), their association weight increases.
+ *
+ * Log-space weight update prevents runaway growth:
+ *   logNew = log(w) + signal * log(1 + rate)
+ *
+ * Associations decay symmetrically when unused.
+ */
+
+const MIN_WEIGHT = 0.001;
+const MAX_WEIGHT = 5.0;  // Cap at 5 to prevent graph walk explosion
+
+/**
+ * Strengthen an association weight after co-activation.
+ */
+export function strengthenAssociation(
+  currentWeight: number,
+  signal: number = 1.0,
+  rate: number = 0.25
+): number {
+  const logW = Math.log(Math.max(currentWeight, MIN_WEIGHT));
+  const logNew = logW + signal * Math.log(1 + rate);
+  return Math.min(Math.exp(logNew), MAX_WEIGHT);
+}
+
+/**
+ * Weaken an association weight due to lack of co-activation.
+ * Called periodically by the connection engine.
+ */
+export function decayAssociation(
+  currentWeight: number,
+  daysSinceActivation: number,
+  halfLife: number = 7.0 // days
+): number {
+  const decayFactor = Math.pow(0.5, daysSinceActivation / halfLife);
+  return Math.max(currentWeight * decayFactor, MIN_WEIGHT);
+}
+
+/**
+ * Ring buffer for tracking recent co-activations.
+ * Feeds the Hebbian worker — when two engrams appear in the buffer
+ * within a window, their association is strengthened.
+ */
+export class CoActivationBuffer {
+  private buffer: { engramId: string; timestamp: number }[] = [];
+  private maxSize: number;
+
+  constructor(maxSize: number = 50) {
+    this.maxSize = maxSize;
+  }
+
+  push(engramId: string): void {
+    this.buffer.push({ engramId, timestamp: Date.now() });
+    if (this.buffer.length > this.maxSize) {
+      this.buffer.shift();
+    }
+  }
+
+  pushBatch(engramIds: string[]): void {
+    for (const id of engramIds) {
+      this.push(id);
+    }
+  }
+
+  /**
+   * Get all pairs of engrams that were co-activated within windowMs.
+   */
+  getCoActivatedPairs(windowMs: number = 5000): [string, string][] {
+    const pairs: [string, string][] = [];
+    for (let i = 0; i < this.buffer.length; i++) {
+      for (let j = i + 1; j < this.buffer.length; j++) {
+        const a = this.buffer[i];
+        const b = this.buffer[j];
+        if (
+          a.engramId !== b.engramId &&
+          Math.abs(a.timestamp - b.timestamp) <= windowMs
+        ) {
+          pairs.push([a.engramId, b.engramId]);
+        }
+      }
+    }
+    return pairs;
+  }
+
+  clear(): void {
+    this.buffer = [];
+  }
+}

package/src/core/index.ts

@@ -1,5 +1,5 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-export * from './decay.js';
-export * from './hebbian.js';
-export * from './salience.js';
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+export * from './decay.js';
+export * from './hebbian.js';
+export * from './salience.js';

package/src/core/logger.ts

@@ -1,36 +1,36 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Simple file logger for AWM activity.
- *
- * Appends one line per event to data/awm.log (next to memory.db).
- * Format: ISO timestamp | agent | event | detail
- *
- * Designed for dev pilot observability — know at a glance what's happening.
- */
-
-import { appendFileSync, mkdirSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-
-let logPath: string | null = null;
-
-export function initLogger(dbPath: string): void {
-  const dir = dirname(resolve(dbPath));
-  mkdirSync(dir, { recursive: true });
-  logPath = resolve(dir, 'awm.log');
-}
-
-export function log(agentId: string, event: string, detail: string): void {
-  if (!logPath) return;
-  const ts = new Date().toISOString();
-  const line = `${ts} | ${agentId} | ${event} | ${detail}\n`;
-  try {
-    appendFileSync(logPath, line);
-  } catch {
-    // Logging should never crash the server
-  }
-}
-
-export function getLogPath(): string | null {
-  return logPath;
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Simple file logger for AWM activity.
+ *
+ * Appends one line per event to data/awm.log (next to memory.db).
+ * Format: ISO timestamp | agent | event | detail
+ *
+ * Designed for dev pilot observability — know at a glance what's happening.
+ */
+
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+let logPath: string | null = null;
+
+export function initLogger(dbPath: string): void {
+  const dir = dirname(resolve(dbPath));
+  mkdirSync(dir, { recursive: true });
+  logPath = resolve(dir, 'awm.log');
+}
+
+export function log(agentId: string, event: string, detail: string): void {
+  if (!logPath) return;
+  const ts = new Date().toISOString();
+  const line = `${ts} | ${agentId} | ${event} | ${detail}\n`;
+  try {
+    appendFileSync(logPath, line);
+  } catch {
+    // Logging should never crash the server
+  }
+}
+
+export function getLogPath(): string | null {
+  return logPath;
+}

package/src/core/query-expander.ts

@@ -1,66 +1,66 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Query Expander — rewrites queries with synonyms and related terms.
- *
- * Uses Xenova/flan-t5-small (~80MB ONNX) to expand search queries
- * with related terms that improve BM25 recall.
- *
- * Example: "What is Caroline's identity?" →
- *   "What is Caroline's identity? Caroline personal gender transgender self"
- *
- * Singleton pattern — call getExpander() to get the shared instance.
- */
-
-import { pipeline, type Text2TextGenerationPipeline } from '@huggingface/transformers';
-
-const MODEL_ID = 'Xenova/flan-t5-small';
-
-let instance: Text2TextGenerationPipeline | null = null;
-let initPromise: Promise<Text2TextGenerationPipeline> | null = null;
-
-/**
- * Get or initialize the text generation pipeline (singleton).
- * First call downloads the model (~80MB), subsequent calls are instant.
- */
-export async function getExpander(): Promise<Text2TextGenerationPipeline> {
-  if (instance) return instance;
-  if (initPromise) return initPromise;
-
-  initPromise = pipeline('text2text-generation', MODEL_ID, {
-    dtype: 'fp32',
-  }).then(pipe => {
-    instance = pipe as Text2TextGenerationPipeline;
-    console.log(`Query expander loaded: ${MODEL_ID}`);
-    return instance;
-  });
-
-  return initPromise;
-}
-
-/**
- * Expand a query with related terms and synonyms.
- * Returns the original query + generated expansion terms.
- * Falls back to the original query on any error.
- */
-export async function expandQuery(originalQuery: string): Promise<string> {
-  try {
-    const expander = await getExpander();
-    const prompt = `Expand this search query with synonyms and related terms. Only output the additional terms, not the original query. Query: ${originalQuery}. Additional terms:`;
-
-    const result = await expander(prompt, {
-      max_new_tokens: 25,
-      no_repeat_ngram_size: 2,
-    });
-
-    const expanded = Array.isArray(result) ? (result[0] as any)?.generated_text ?? '' : '';
-    const cleanExpanded = expanded.trim();
-
-    if (cleanExpanded && cleanExpanded.length > 2) {
-      return `${originalQuery} ${cleanExpanded}`;
-    }
-    return originalQuery;
-  } catch {
-    return originalQuery;
-  }
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Query Expander — rewrites queries with synonyms and related terms.
+ *
+ * Uses Xenova/flan-t5-small (~80MB ONNX) to expand search queries
+ * with related terms that improve BM25 recall.
+ *
+ * Example: "What is Caroline's identity?" →
+ *   "What is Caroline's identity? Caroline personal gender transgender self"
+ *
+ * Singleton pattern — call getExpander() to get the shared instance.
+ */
+
+import { pipeline, type Text2TextGenerationPipeline } from '@huggingface/transformers';
+
+const MODEL_ID = 'Xenova/flan-t5-small';
+
+let instance: Text2TextGenerationPipeline | null = null;
+let initPromise: Promise<Text2TextGenerationPipeline> | null = null;
+
+/**
+ * Get or initialize the text generation pipeline (singleton).
+ * First call downloads the model (~80MB), subsequent calls are instant.
+ */
+export async function getExpander(): Promise<Text2TextGenerationPipeline> {
+  if (instance) return instance;
+  if (initPromise) return initPromise;
+
+  initPromise = pipeline('text2text-generation', MODEL_ID, {
+    dtype: 'fp32',
+  }).then(pipe => {
+    instance = pipe as Text2TextGenerationPipeline;
+    console.log(`Query expander loaded: ${MODEL_ID}`);
+    return instance;
+  });
+
+  return initPromise;
+}
+
+/**
+ * Expand a query with related terms and synonyms.
+ * Returns the original query + generated expansion terms.
+ * Falls back to the original query on any error.
+ */
+export async function expandQuery(originalQuery: string): Promise<string> {
+  try {
+    const expander = await getExpander();
+    const prompt = `Expand this search query with synonyms and related terms. Only output the additional terms, not the original query. Query: ${originalQuery}. Additional terms:`;
+
+    const result = await expander(prompt, {
+      max_new_tokens: 25,
+      no_repeat_ngram_size: 2,
+    });
+
+    const expanded = Array.isArray(result) ? (result[0] as any)?.generated_text ?? '' : '';
+    const cleanExpanded = expanded.trim();
+
+    if (cleanExpanded && cleanExpanded.length > 2) {
+      return `${originalQuery} ${cleanExpanded}`;
+    }
+    return originalQuery;
+  } catch {
+    return originalQuery;
+  }
+}

package/src/core/reranker.ts

@@ -1,101 +1,101 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Cross-Encoder Re-Ranker — scores (query, passage) pairs for relevance.
- *
- * Uses Xenova/ms-marco-MiniLM-L-6-v2 (~22MB ONNX) which is trained on
- * MS-MARCO passage ranking. Unlike bi-encoders, cross-encoders see both
- * query and passage together via full attention — much better at judging
- * if a passage actually answers a question.
- *
- * Uses direct tokenizer + model inference (NOT the text-classification
- * pipeline, which doesn't support text_pair and returns identical scores).
- *
- * Singleton pattern — call getReranker() to get the shared instance.
- */
-
-import {
-  AutoTokenizer,
-  AutoModelForSequenceClassification,
-  type PreTrainedTokenizer,
-  type PreTrainedModel,
-} from '@huggingface/transformers';
-
-const DEFAULT_MODEL = 'Xenova/ms-marco-MiniLM-L-6-v2';
-const MODEL_ID = process.env.AWM_RERANKER_MODEL || DEFAULT_MODEL;
-
-let tokenizer: PreTrainedTokenizer | null = null;
-let model: PreTrainedModel | null = null;
-let initPromise: Promise<void> | null = null;
-
-async function ensureLoaded(): Promise<void> {
-  if (tokenizer && model) return;
-  if (initPromise) return initPromise;
-
-  initPromise = (async () => {
-    tokenizer = await AutoTokenizer.from_pretrained(MODEL_ID);
-    model = await AutoModelForSequenceClassification.from_pretrained(MODEL_ID, {
-      dtype: 'fp32',
-    });
-    console.log(`Re-ranker model loaded: ${MODEL_ID}`);
-  })();
-
-  return initPromise;
-}
-
-/** Kept for backwards compat — returns the model (unused externally). */
-export async function getReranker(): Promise<any> {
-  await ensureLoaded();
-  return model;
-}
-
-export interface RerankResult {
-  index: number;
-  score: number; // sigmoid-normalized relevance (0-1)
-}
-
-function sigmoid(x: number): number {
-  return 1 / (1 + Math.exp(-x));
-}
-
-/**
- * Re-rank candidate passages against a query using the cross-encoder.
- * Returns results sorted by relevance score (descending).
- */
-export async function rerank(
-  query: string,
-  passages: string[],
-): Promise<RerankResult[]> {
-  if (passages.length === 0) return [];
-
-  await ensureLoaded();
-
-  const results: RerankResult[] = [];
-
-  for (let i = 0; i < passages.length; i++) {
-    try {
-      // Tokenize as a query-passage PAIR using text_pair
-      const inputs = tokenizer!(query, {
-        text_pair: passages[i],
-        padding: true,
-        truncation: true,
-        return_tensors: 'pt',
-      });
-
-      const output = await model!(inputs);
-
-      // Model outputs raw logits — extract the single relevance logit
-      const logits = output.logits ?? output.last_hidden_state;
-      const rawLogit = logits.data[0] as number;
-
-      // Apply sigmoid to map to 0-1 probability
-      results.push({ index: i, score: sigmoid(rawLogit) });
-    } catch {
-      results.push({ index: i, score: 0 });
-    }
-  }
-
-  // Sort by score descending
-  results.sort((a, b) => b.score - a.score);
-  return results;
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Cross-Encoder Re-Ranker — scores (query, passage) pairs for relevance.
+ *
+ * Uses Xenova/ms-marco-MiniLM-L-6-v2 (~22MB ONNX) which is trained on
+ * MS-MARCO passage ranking. Unlike bi-encoders, cross-encoders see both
+ * query and passage together via full attention — much better at judging
+ * if a passage actually answers a question.
+ *
+ * Uses direct tokenizer + model inference (NOT the text-classification
+ * pipeline, which doesn't support text_pair and returns identical scores).
+ *
+ * Singleton pattern — call getReranker() to get the shared instance.
+ */
+
+import {
+  AutoTokenizer,
+  AutoModelForSequenceClassification,
+  type PreTrainedTokenizer,
+  type PreTrainedModel,
+} from '@huggingface/transformers';
+
+const DEFAULT_MODEL = 'Xenova/ms-marco-MiniLM-L-6-v2';
+const MODEL_ID = process.env.AWM_RERANKER_MODEL || DEFAULT_MODEL;
+
+let tokenizer: PreTrainedTokenizer | null = null;
+let model: PreTrainedModel | null = null;
+let initPromise: Promise<void> | null = null;
+
+async function ensureLoaded(): Promise<void> {
+  if (tokenizer && model) return;
+  if (initPromise) return initPromise;
+
+  initPromise = (async () => {
+    tokenizer = await AutoTokenizer.from_pretrained(MODEL_ID);
+    model = await AutoModelForSequenceClassification.from_pretrained(MODEL_ID, {
+      dtype: 'fp32',
+    });
+    console.log(`Re-ranker model loaded: ${MODEL_ID}`);
+  })();
+
+  return initPromise;
+}
+
+/** Kept for backwards compat — returns the model (unused externally). */
+export async function getReranker(): Promise<any> {
+  await ensureLoaded();
+  return model;
+}
+
+export interface RerankResult {
+  index: number;
+  score: number; // sigmoid-normalized relevance (0-1)
+}
+
+function sigmoid(x: number): number {
+  return 1 / (1 + Math.exp(-x));
+}
+
+/**
+ * Re-rank candidate passages against a query using the cross-encoder.
+ * Returns results sorted by relevance score (descending).
+ */
+export async function rerank(
+  query: string,
+  passages: string[],
+): Promise<RerankResult[]> {
+  if (passages.length === 0) return [];
+
+  await ensureLoaded();
+
+  const results: RerankResult[] = [];
+
+  for (let i = 0; i < passages.length; i++) {
+    try {
+      // Tokenize as a query-passage PAIR using text_pair
+      const inputs = tokenizer!(query, {
+        text_pair: passages[i],
+        padding: true,
+        truncation: true,
+        return_tensors: 'pt',
+      });
+
+      const output = await model!(inputs);
+
+      // Model outputs raw logits — extract the single relevance logit
+      const logits = output.logits ?? output.last_hidden_state;
+      const rawLogit = logits.data[0] as number;
+
+      // Apply sigmoid to map to 0-1 probability
+      results.push({ index: i, score: sigmoid(rawLogit) });
+    } catch {
+      results.push({ index: i, score: 0 });
+    }
+  }
+
+  // Sort by score descending
+  results.sort((a, b) => b.score - a.score);
+  return results;
+}