adaptive-memory-multi-model-router 2.14.45 → 2.14.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adaptive-memory-multi-model-router",
-  "version": "2.14.45",
+  "version": "2.14.47",
   "shortName": "A3M Router",
   "displayName": "A3M Router - Adaptive Memory Multi-Model Router",
   "description": "🥇 Cheapest LLM router on RouterArena ($0.05/1K) · 15K+ downloads in 2 weeks · Open-source AI gateway with parallel multi-LLM execution across 47+ providers, ensemble voting, semantic cache, and budget enforcement",
@@ -57,7 +57,6 @@
   "keywords": [
     "a3m",
     "a3m-router",
-    "adaptive-memory-multi-model-router",
     "llm-router",
     "llm-routing",
     "model-routing",
@@ -67,94 +66,26 @@
     "routing",
     "router",
     "gateway",
+    "multi-model-router",
+    "multi-provider",
     "multi-llm",
-    "openai",
-    "anthropic",
-    "gemini",
-    "claude",
-    "gpt",
-    "gpt-4",
-    "llama",
-    "llama-3",
-    "deepseek",
-    "mistral",
-    "groq",
-    "qwen",
-    "kimi",
-    "xai",
-    "cohere",
-    "langchain",
-    "vercel-ai",
-    "llamaindex",
-    "llamaindex-gateway",
-    "cost-savings",
+    "cost-optimization",
     "cost-reduction",
+    "smart-routing",
     "caching",
     "semantic-cache",
-    "context-cache",
-    "prompt-cache",
     "fallback",
     "failover",
-    "smart-fallback",
-    "smart-failover",
-    "guardrails",
-    "ai-guardrails",
-    "circuit-breaker",
     "streaming",
-    "streaming-llm",
-    "retry",
-    "ai-agent",
-    "multi-agent",
-    "autonomous-agents",
-    "rag",
-    "chatbot",
-    "ai-coding",
-    "code-generation",
-    "text-generation",
-    "extraction",
-    "summarization",
-    "smart-routing",
-    "semantic-routing",
-    "tier-routing",
-    "intent-routing",
-    "content-routing",
-    "dynamic-routing",
-    "adaptive-routing",
-    "load-balancer",
-    "load-balancing",
-    "parallel-execution",
-    "multi-model",
-    "multi-provider",
-    "openai-compatible",
-    "openai-gateway",
-    "openai-proxy",
+    "openai",
+    "anthropic",
+    "gemini",
+    "claude",
+    "deepseek",
+    "groq",
     "openrouter",
-    "monitoring",
-    "metrics",
-    "observability",
-    "health-check",
-    "open-source",
-    "self-hosted",
-    "local-llm",
-    "serverless",
-    "cost-optimization",
-    "token-optimization",
-    "llm-cost",
-    "token-saving",
-    "cost-analytics",
-    "cost-tracking",
-    "budget-alerts",
-    "cache",
-    "chatgpt",
-    "agent",
-    "low-cost-llm",
-    "cheaper-llm",
-    "provider-failover",
-    "response-cache",
-    "llm-failover",
-    "api-cost-reduction",
-    "multi-llm-router",
-    "multi-model-router"
+    "langchain",
+    "open-source"
   ],
   "author": "Das-rebel <subho@example.com>",
   "license": "MIT",
@@ -168,8 +99,6 @@
   "homepage": "https://das-rebel.github.io/a3m-router/",
   "scripts": {
     "test": "node test.js && node test/provider-test.js",
-    "test:py": "python3 -m pytest -q",
-    "test:all": "npm test && npm run test:py",
     "eval:routing": "node eval/run_eval.js",
     "eval:golden": "node eval/check_golden_routes.js",
     "eval:faults": "node eval/run_fault_injection.js",

package/src/index.ts

@@ -68,6 +68,14 @@ export type { BudgetConfig, SpendRecord, BudgetCheckResult } from './cost/budget
 // MEMORY
 // ============================================================
 export { MemoryTree } from './memory/memoryTree';
+
+// ReasoningBank — experience-based memory (semantic retrieval + learning)
+export { ReasoningBank } from './memory/reasoningBank';
+export type { ReasoningMemory, ReasoningBankConfig } from './memory/reasoningBank';
+
+// Hybrid Memory — merges MemoryTree (keyword) + ReasoningBank (semantic)
+export { HybridMemory } from './memory/hybridMemory';
+export type { HybridMemoryConfig, HybridResult } from './memory/hybridMemory';
 export type { MemoryChunk, TreeNode } from './memory/memoryTree';
 
 // ============================================================

package/src/memory/hybridMemory.ts

@@ -0,0 +1,155 @@
+/**
+ * Hybrid Memory — Merges MemoryTree (keyword) + ReasoningBank (semantic)
+ * 
+ * Provides unified search across both memory systems with configurable
+ * weighting. Falls back gracefully when ReasoningBank has no data or
+ * no embedding keys configured.
+ * 
+ * Merge formula: final_score = keyword_score * w1 + semantic_score * w2
+ * where w1 + w2 = 1.0, configurable via config.
+ */
+
+import { MemoryTree, MemoryChunk } from './memoryTree';
+import { ReasoningBank, ReasoningMemory, ReasoningBankConfig } from './reasoningBank';
+
+export interface HybridMemoryConfig {
+  /** Weight for MemoryTree keyword score (0-1). ReasoningBank gets (1 - this). */
+  keywordWeight: number;
+  /** ReasoningBank config */
+  reasoningBank: Partial<ReasoningBankConfig>;
+}
+
+const DEFAULT_CONFIG: HybridMemoryConfig = {
+  keywordWeight: 0.3,  // 30% keyword, 70% semantic
+  reasoningBank: {},
+};
+
+export interface HybridResult {
+  id: string;
+  content: string;
+  score: number;
+  source: 'keyword' | 'semantic' | 'merged';
+  metadata?: Record<string, unknown>;
+}
+
+export class HybridMemory {
+  private memoryTree: MemoryTree;
+  private reasoningBank: ReasoningBank;
+  private config: HybridMemoryConfig;
+
+  constructor(config: Partial<HybridMemoryConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.memoryTree = new MemoryTree();
+    this.reasoningBank = new ReasoningBank(this.config.reasoningBank);
+  }
+
+  /** Initialize both memory systems */
+  async init(): Promise<void> {
+    await this.reasoningBank.load();
+  }
+
+  /** Add data to MemoryTree (fast, always works) */
+  async add(data: string): Promise<void> {
+    await this.memoryTree.add(data);
+  }
+
+  /** Induce a memory in ReasoningBank from a routing decision */
+  async learnFromDecision(params: {
+    query: string;
+    provider: string;
+    cost: number;
+    complexity: number;
+    success: boolean;
+    reasoning?: string;
+  }): Promise<void> {
+    await this.reasoningBank.induceMemory(params);
+  }
+
+  /**
+   * Unified search across both memory systems.
+   * Returns merged, deduplicated results sorted by relevance.
+   */
+  async search(query: string, topK = 10): Promise<HybridResult[]> {
+    const results: HybridResult[] = [];
+    const seen = new Set<string>();
+
+    // 1. MemoryTree keyword search (always available)
+    const keywordResults = this.memoryTree.search(query, topK * 2);
+    for (const chunk of keywordResults) {
+      const score = this.normalizeScore(chunk.score, 0, 1);
+      results.push({
+        id: chunk.id,
+        content: chunk.content,
+        score: score * this.config.keywordWeight,
+        source: 'keyword',
+        metadata: { accessCount: chunk.accessCount, depth: chunk.depth },
+      });
+      seen.add(chunk.id);
+    }
+
+    // 2. ReasoningBank semantic search (if available)
+    try {
+      const semanticResults = await this.reasoningBank.selectMemories(query);
+      for (const mem of semanticResults) {
+        if (seen.has(mem.id)) continue;
+        results.push({
+          id: mem.id,
+          content: `[${mem.status.toUpperCase()}] ${mem.title}\n${mem.description}\n${mem.content}`,
+          score: 0.7 * (1 - this.config.keywordWeight), // semantic weight
+          source: 'semantic',
+          metadata: {
+            provider: mem.provider,
+            cost: mem.cost,
+            complexity: mem.complexity,
+            status: mem.status,
+          },
+        });
+        seen.add(mem.id);
+      }
+    } catch {
+      // ReasoningBank unavailable — keyword results still returned
+    }
+
+    // 3. Sort by score and return topK
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, topK);
+  }
+
+  /** Get context string for router injection */
+  async getContext(query: string, maxTokens = 3000): Promise<string> {
+    const results = await this.search(query, 5);
+    if (results.length === 0) return '';
+
+    const parts = results.map((r, i) => {
+      const prefix = r.source === 'semantic' ? `[Experience] ` : '';
+      return `${prefix}${r.content}`;
+    });
+
+    let context = parts.join('\n\n');
+    if (context.length > maxTokens) {
+      context = context.slice(0, maxTokens) + '...';
+    }
+    return context;
+  }
+
+  /** Get combined stats */
+  getStats() {
+    return {
+      memoryTree: this.memoryTree.getStats(),
+      reasoningBank: this.reasoningBank.getStats(),
+      keywordWeight: this.config.keywordWeight,
+    };
+  }
+
+  /** Save both systems */
+  async save(): Promise<void> {
+    await this.reasoningBank.save();
+  }
+
+  private normalizeScore(score: number, min: number, max: number): number {
+    if (max === min) return 0.5;
+    return Math.min(1, Math.max(0, (score - min) / (max - min)));
+  }
+}
+
+export default HybridMemory;

package/src/memory/reasoningBank.ts

@@ -0,0 +1,335 @@
+/**
+ * ReasoningBank — Experience-Based Memory Layer
+ * 
+ * Complements MemoryTree with semantic retrieval and experience-based learning.
+ * Learns from both successful and failed routing decisions.
+ * 
+ * Based on: "ReasoningBank: Scaling Agent Self-Evolving with Reasoning Memory"
+ * (Google Research, ICLR 2026) — github.com/google-research/reasoning-bank
+ * 
+ * Architecture:
+ *   MemoryTree (keyword, fast, free) ←→ ReasoningBank (semantic, quality-scored)
+ *   Merge: keyword_score * 0.3 + semantic_score * 0.7
+ * 
+ * Storage: JSONL files (no external vector DB required)
+ * Embedding: Optional — falls back to keyword search when no embedding key configured
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// ============================================================
+// TYPES
+// ============================================================
+
+export interface ReasoningMemory {
+  id: string;
+  taskId: string;
+  query: string;
+  title: string;
+  description: string;  // when to use this memory
+  content: string;       // 1-3 sentences of actionable insight
+  status: 'success' | 'failure';
+  provider: string;      // which model was used
+  cost: number;          // actual cost of the routing decision
+  complexity: number;    // query complexity at time of routing
+  timestamp: number;
+  embedding?: number[];  // optional embedding vector
+}
+
+export interface ReasoningBankConfig {
+  /** Directory to store reasoning bank files */
+  dataDir: string;
+  /** Max memories to retrieve per query */
+  maxResults: number;
+  /** Minimum similarity threshold (0-1) */
+  minSimilarity: number;
+  /** Embedding provider: 'gemini' | 'openai' | 'none' (keyword fallback) */
+  embeddingProvider: 'gemini' | 'openai' | 'none';
+  /** API key for embedding provider */
+  embeddingApiKey?: string;
+  /** Embedding model ID */
+  embeddingModel?: string;
+}
+
+const DEFAULT_CONFIG: ReasoningBankConfig = {
+  dataDir: './data/reasoning-bank',
+  maxResults: 5,
+  minSimilarity: 0.3,
+  embeddingProvider: 'none',
+};
+
+// ============================================================
+// REASONING BANK
+// ============================================================
+
+export class ReasoningBank {
+  private config: ReasoningBankConfig;
+  private memories: ReasoningMemory[] = [];
+  private embeddings: Map<string, number[]> = new Map();
+  private loaded = false;
+
+  constructor(config: Partial<ReasoningBankConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  // ----------------------------------------------------------
+  // STORAGE
+  // ----------------------------------------------------------
+
+  /** Load memories from disk */
+  async load(): Promise<void> {
+    const bankFile = path.join(this.config.dataDir, 'memories.jsonl');
+    const embFile = path.join(this.config.dataDir, 'embeddings.jsonl');
+
+    this.memories = [];
+    this.embeddings = new Map();
+
+    try {
+      if (fs.existsSync(bankFile)) {
+        const lines = fs.readFileSync(bankFile, 'utf8').trim().split('\n').filter(Boolean);
+        for (const line of lines) {
+          try { this.memories.push(JSON.parse(line)); } catch { /* skip corrupt */ }
+        }
+      }
+    } catch { /* no existing bank */ }
+
+    try {
+      if (fs.existsSync(embFile)) {
+        const lines = fs.readFileSync(embFile, 'utf8').trim().split('\n').filter(Boolean);
+        for (const line of lines) {
+          try {
+            const { id, embedding } = JSON.parse(line);
+            if (id && embedding) this.embeddings.set(id, embedding);
+          } catch { /* skip corrupt */ }
+        }
+      }
+    } catch { /* no existing embeddings */ }
+
+    this.loaded = true;
+  }
+
+  /** Save memories to disk */
+  async save(): Promise<void> {
+    if (!fs.existsSync(this.config.dataDir)) {
+      fs.mkdirSync(this.config.dataDir, { recursive: true });
+    }
+
+    const bankFile = path.join(this.config.dataDir, 'memories.jsonl');
+    const embFile = path.join(this.config.dataDir, 'embeddings.jsonl');
+
+    // Save memories
+    const memLines = this.memories.map(m => JSON.stringify(m)).join('\n');
+    fs.writeFileSync(bankFile, memLines + '\n');
+
+    // Save embeddings
+    const embLines = Array.from(this.embeddings.entries())
+      .map(([id, emb]) => JSON.stringify({ id, embedding: emb }))
+      .join('\n');
+    fs.writeFileSync(embFile, embLines + '\n');
+  }
+
+  // ----------------------------------------------------------
+  // MEMORY INDUCTION (Phase 3 of ReasoningBank pipeline)
+  // ----------------------------------------------------------
+
+  /**
+   * Extract a memory from a routing decision.
+   * Called after a query is routed and the outcome is known.
+   */
+  async induceMemory(params: {
+    query: string;
+    provider: string;
+    cost: number;
+    complexity: number;
+    success: boolean;
+    reasoning?: string;
+  }): Promise<ReasoningMemory> {
+    const { query, provider, cost, complexity, success, reasoning } = params;
+
+    // Generate structured memory content
+    const status = success ? 'success' : 'failure';
+    const title = success
+      ? `Successful routing for: ${query.slice(0, 50)}`
+      : `Failed routing for: ${query.slice(0, 50)}`;
+
+    const description = success
+      ? `Use ${provider} for queries with complexity ${complexity.toFixed(2)} and similar patterns`
+      : `Avoid ${provider} for queries with complexity ${complexity.toFixed(2)} — consider higher-tier model`;
+
+    const content = reasoning || (success
+      ? `Routing to ${provider} (cost $${cost.toFixed(4)}) was successful for this ${complexity.toFixed(2)}-complexity query.`
+      : `Routing to ${provider} (cost $${cost.toFixed(4)}) underperformed for this ${complexity.toFixed(2)}-complexity query.`);
+
+    const memory: ReasoningMemory = {
+      id: `rb_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      taskId: `task_${Date.now()}`,
+      query,
+      title,
+      description,
+      content,
+      status,
+      provider,
+      cost,
+      complexity,
+      timestamp: Date.now(),
+    };
+
+    // Generate embedding if provider is configured
+    if (this.config.embeddingProvider !== 'none' && this.config.embeddingApiKey) {
+      try {
+        memory.embedding = await this.embed(query);
+      } catch {
+        // Embedding failed — memory still usable via keyword search
+      }
+    }
+
+    this.memories.push(memory);
+    if (memory.embedding) {
+      this.embeddings.set(memory.id, memory.embedding);
+    }
+
+    // Auto-save every 10 memories
+    if (this.memories.length % 10 === 0) {
+      await this.save();
+    }
+
+    return memory;
+  }
+
+  // ----------------------------------------------------------
+  // RETRIEVAL (Phase 1 of ReasoningBank pipeline)
+  // ----------------------------------------------------------
+
+  /**
+   * Select relevant memories for a query.
+   * Uses embedding similarity if available, falls back to keyword search.
+   */
+  async selectMemories(query: string): Promise<ReasoningMemory[]> {
+    if (!this.loaded) await this.load();
+
+    if (this.memories.length === 0) return [];
+
+    // Try embedding-based retrieval first
+    if (this.config.embeddingProvider !== 'none' && this.config.embeddingApiKey) {
+      try {
+        const queryEmbedding = await this.embed(query);
+        const scored = this.memories.map(m => ({
+          memory: m,
+          score: m.embedding ? this.cosineSimilarity(queryEmbedding, m.embedding) : 0,
+        }));
+        scored.sort((a, b) => b.score - a.score);
+        return scored
+          .filter(s => s.score >= this.config.minSimilarity)
+          .slice(0, this.config.maxResults)
+          .map(s => s.memory);
+      } catch {
+        // Fall through to keyword search
+      }
+    }
+
+    // Keyword fallback: TF-IDF style overlap
+    const queryWords = this.tokenize(query);
+    if (queryWords.length === 0) return [];
+
+    const scored = this.memories.map(m => {
+      const contentWords = this.tokenize(m.query + ' ' + m.content);
+      const contentSet = new Set(contentWords);
+      const matches = queryWords.filter(w => contentSet.has(w)).length;
+      const score = matches / queryWords.length;
+      return { memory: m, score };
+    });
+
+    scored.sort((a, b) => b.score - a.score);
+    return scored
+      .filter(s => s.score >= this.config.minSimilarity)
+      .slice(0, this.config.maxResults)
+      .map(s => s.memory);
+  }
+
+  // ----------------------------------------------------------
+  // EMBEDDING (optional)
+  // ----------------------------------------------------------
+
+  private async embed(text: string): Promise<number[]> {
+    if (this.config.embeddingProvider === 'gemini' && this.config.embeddingApiKey) {
+      return this.embedGemini(text);
+    }
+    if (this.config.embeddingProvider === 'openai' && this.config.embeddingApiKey) {
+      return this.embedOpenAI(text);
+    }
+    throw new Error('No embedding provider configured');
+  }
+
+  private async embedGemini(text: string): Promise<number[]> {
+    const model = this.config.embeddingModel || 'gemini-embedding-001';
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:embedContent?key=${this.config.embeddingApiKey}`;
+    const resp = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        content: { parts: [{ text }] },
+        taskType: 'RETRIEVAL_QUERY',
+      }),
+    });
+    const data = await resp.json() as any;
+    return data.embedding?.values || [];
+  }
+
+  private async embedOpenAI(text: string): Promise<number[]> {
+    const model = this.config.embeddingModel || 'text-embedding-3-small';
+    const resp = await fetch('https://api.openai.com/v1/embeddings', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.config.embeddingApiKey}`,
+      },
+      body: JSON.stringify({ model, input: text }),
+    });
+    const data = await resp.json() as any;
+    return data.data?.[0]?.embedding || [];
+  }
+
+  // ----------------------------------------------------------
+  // UTILITIES
+  // ----------------------------------------------------------
+
+  private cosineSimilarity(a: number[], b: number[]): number {
+    if (a.length !== b.length || a.length === 0) return 0;
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dot += a[i] * b[i];
+      normA += a[i] * a[i];
+      normB += b[i] * b[i];
+    }
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB) + 1e-8);
+  }
+
+  private tokenize(text: string): string[] {
+    return text
+      .toLowerCase()
+      .split(/\s+/)
+      .map(w => w.replace(/[^a-z0-9\u00C0-\u024F]/g, ''))
+      .filter(w => w.length > 2);
+  }
+
+  /** Get bank statistics */
+  getStats() {
+    return {
+      totalMemories: this.memories.length,
+      successes: this.memories.filter(m => m.status === 'success').length,
+      failures: this.memories.filter(m => m.status === 'failure').length,
+      withEmbeddings: this.embeddings.size,
+      providers: [...new Set(this.memories.map(m => m.provider))],
+    };
+  }
+
+  /** Clear all memories */
+  async clear(): Promise<void> {
+    this.memories = [];
+    this.embeddings = new Map();
+    await this.save();
+  }
+}
+
+export default ReasoningBank;