winter-super-cli 2026.5.26 → 2026.5.28

package/src/cache/contextreuse.js

@@ -0,0 +1,159 @@
+/**
+ * Context Reuse - Cache and reuse similar conversation contexts.
+ * Reduces API calls by matching new queries against cached responses.
+ */
+
+import { SimilaritySearch } from './similarity.js';
+import { EmbeddingCache } from './embeddings.js';
+import { createHash } from 'crypto';
+
+export class ContextReuseManager {
+  constructor(options = {}) {
+    this.similarity = new SimilaritySearch();
+    this.embeddings = new EmbeddingCache();
+    this.maxCacheSize = options.maxCacheSize || 500;
+    this.minSimilarity = options.minSimilarity || 0.75;
+    this.ttlMs = options.ttlMs || 30 * 60 * 1000; // 30 minutes default
+    this.contexts = new Map();
+    this.hits = 0;
+    this.misses = 0;
+  }
+
+  /**
+   * Store a context-response pair for future reuse.
+   */
+  async store(query, response, metadata = {}) {
+    const hash = this._hash(query);
+    const entry = {
+      hash,
+      query,
+      response,
+      metadata,
+      createdAt: Date.now(),
+      accessCount: 0,
+    };
+
+    // Trim cache if needed
+    if (this.contexts.size >= this.maxCacheSize) {
+      this._evictOldest();
+    }
+
+    this.contexts.set(hash, entry);
+    this.similarity.add(hash, query, { hash, createdAt: Date.now() });
+
+    // Also try to store embedding
+    try {
+      await this.embeddings.cacheEmbedding(query, [], { hash, response: response.substring(0, 200) });
+    } catch {
+      // Embedding cache is optional
+    }
+  }
+
+  /**
+   * Find a similar context for the given query.
+   */
+  async find(query, options = {}) {
+    const threshold = options.threshold || this.minSimilarity;
+    const results = this.similarity.search(query, { limit: 3, threshold });
+
+    for (const result of results) {
+      const entry = this.contexts.get(result.id);
+      if (!entry) continue;
+
+      // Check TTL
+      if (Date.now() - entry.createdAt > this.ttlMs) {
+        this.contexts.delete(result.id);
+        this.similarity.remove(result.id);
+        continue;
+      }
+
+      entry.accessCount++;
+      this.hits++;
+      return {
+        matched: true,
+        query: entry.query,
+        response: entry.response,
+        score: result.score,
+        metadata: entry.metadata,
+        accessCount: entry.accessCount,
+      };
+    }
+
+    this.misses++;
+    return { matched: false };
+  }
+
+  /**
+   * Check if a query has a cached response.
+   */
+  async has(query) {
+    const result = await this.find(query);
+    return result.matched;
+  }
+
+  /**
+   * Get cache statistics.
+   */
+  getStats() {
+    return {
+      size: this.contexts.size,
+      maxSize: this.maxCacheSize,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: this.hits + this.misses > 0
+        ? (this.hits / (this.hits + this.misses)).toFixed(3)
+        : 0,
+      similarityIndexSize: this.similarity.stats().documents,
+      ttlMs: this.ttlMs,
+    };
+  }
+
+  /**
+   * Clear all cached contexts.
+   */
+  clear() {
+    this.contexts.clear();
+    this.similarity.clear();
+    this.hits = 0;
+    this.misses = 0;
+  }
+
+  /**
+   * Remove expired entries.
+   */
+  prune() {
+    const now = Date.now();
+    let removed = 0;
+    for (const [hash, entry] of this.contexts) {
+      if (now - entry.createdAt > this.ttlMs) {
+        this.contexts.delete(hash);
+        this.similarity.remove(hash);
+        removed++;
+      }
+    }
+    return removed;
+  }
+
+  // --- Private helpers ---
+
+  _hash(str) {
+    return createHash('md5').update(String(str)).digest('hex');
+  }
+
+  _evictOldest() {
+    let oldest = null;
+    let oldestHash = null;
+    for (const [hash, entry] of this.contexts) {
+      if (!oldest || entry.createdAt < oldest.createdAt) {
+        oldest = entry;
+        oldestHash = hash;
+      }
+    }
+    if (oldestHash) {
+      this.contexts.delete(oldestHash);
+      this.similarity.remove(oldestHash);
+    }
+  }
+}
+
+export const globalContextReuse = new ContextReuseManager();

package/src/cache/embeddings.js

@@ -0,0 +1,185 @@
+/**
+ * Embeddings Cache - Vector embedding storage with similarity search
+ * and cache_control (TTL-based expiration) support.
+ */
+import { createHash } from 'crypto';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { homedir } from 'os';
+
+const CACHE_DIR = path.join(homedir(), '.winter', 'cache', 'embeddings');
+const INDEX_FILE = path.join(CACHE_DIR, 'index.json');
+
+export class EmbeddingCache {
+  constructor(options = {}) {
+    this.memory = new Map();
+    this.index = { embeddings: [], lastUpdated: null };
+    this.initialized = false;
+    this.defaultTtlMs = options.defaultTtlMs || 30 * 60 * 1000; // 30 min default
+  }
+
+  async init() {
+    if (this.initialized) return;
+    try {
+      await fs.mkdir(CACHE_DIR, { recursive: true });
+      const raw = await fs.readFile(INDEX_FILE, 'utf8').catch(() => '{}');
+      this.index = JSON.parse(raw);
+      if (!this.index.embeddings) this.index.embeddings = [];
+      this.initialized = true;
+    } catch {
+      this.index = { embeddings: [], lastUpdated: null };
+      this.initialized = true;
+    }
+  }
+
+  _hashKey(key) {
+    return createHash('md5').update(String(key)).digest('hex');
+  }
+
+  _isExpired(entry) {
+    if (!entry || !entry.expiresAt) return false;
+    return Date.now() > entry.expiresAt;
+  }
+
+  async cacheEmbedding(text, vector, metadata = {}) {
+    await this.init();
+    const hash = this._hashKey(text);
+    const ttlMs = metadata.ttlMs || this.defaultTtlMs;
+    const entry = {
+      hash,
+      text: text.substring(0, 500),
+      vector,
+      metadata,
+      createdAt: Date.now(),
+      expiresAt: Date.now() + ttlMs,
+      ttlMs,
+    };
+
+    this.memory.set(hash, entry);
+
+    // Update index
+    const existingIdx = this.index.embeddings.findIndex(e => e.hash === hash);
+    if (existingIdx >= 0) {
+      this.index.embeddings[existingIdx] = entry;
+    } else {
+      this.index.embeddings.push(entry);
+    }
+    this.index.lastUpdated = Date.now();
+
+    // Persist
+    const filePath = path.join(CACHE_DIR, `${hash}.json`);
+    await fs.writeFile(filePath, JSON.stringify(entry), 'utf8');
+    await fs.writeFile(INDEX_FILE, JSON.stringify(this.index, null, 2), 'utf8');
+  }
+
+  async getEmbedding(text, options = {}) {
+    await this.init();
+    const hash = this._hashKey(text);
+    const ignoreExpiry = options.ignoreExpiry === true;
+
+    if (this.memory.has(hash)) {
+      const cached = this.memory.get(hash);
+      if (ignoreExpiry || !this._isExpired(cached)) {
+        return cached;
+      }
+      this.memory.delete(hash);
+    }
+
+    try {
+      const filePath = path.join(CACHE_DIR, `${hash}.json`);
+      const raw = await fs.readFile(filePath, 'utf8');
+      const entry = JSON.parse(raw);
+      if (ignoreExpiry || !this._isExpired(entry)) {
+        this.memory.set(hash, entry);
+        return entry;
+      }
+      await fs.unlink(filePath).catch(() => {});
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  async findSimilar(text, threshold = 0.8, limit = 5) {
+    await this.init();
+    if (this.index.embeddings.length === 0) return [];
+
+    const now = Date.now();
+    const results = [];
+    const expired = [];
+
+    for (const entry of this.index.embeddings) {
+      if (entry.expiresAt && now > entry.expiresAt) {
+        expired.push(entry.hash);
+        continue;
+      }
+      const score = this._cosineSimilarity(text, entry.text);
+      if (score >= threshold) {
+        results.push({ score, entry });
+      }
+    }
+
+    // Clean expired entries
+    if (expired.length > 0) {
+      this.index.embeddings = this.index.embeddings.filter(
+        e => !expired.includes(e.hash)
+      );
+      this.index.lastUpdated = now;
+      for (const hash of expired) {
+        this.memory.delete(hash);
+        const fp = path.join(CACHE_DIR, `${hash}.json`);
+        await fs.unlink(fp).catch(() => {});
+      }
+      await fs.writeFile(INDEX_FILE, JSON.stringify(this.index, null, 2), 'utf8');
+    }
+
+    return results.sort((a, b) => b.score - a.score).slice(0, limit);
+  }
+
+  async pruneExpired() {
+    await this.init();
+    const now = Date.now();
+    const before = this.index.embeddings.length;
+
+    this.index.embeddings = this.index.embeddings.filter(e => {
+      if (e.expiresAt && now > e.expiresAt) {
+        this.memory.delete(e.hash);
+        const fp = path.join(CACHE_DIR, `${e.hash}.json`);
+        fs.unlink(fp).catch(() => {});
+        return false;
+      }
+      return true;
+    });
+
+    this.index.lastUpdated = now;
+    await fs.writeFile(INDEX_FILE, JSON.stringify(this.index, null, 2), 'utf8');
+    return before - this.index.embeddings.length;
+  }
+
+  _cosineSimilarity(a, b) {
+    const tokensA = new Set(a.toLowerCase().split(/\s+/));
+    const tokensB = b.toLowerCase().split(/\s+/);
+    const intersection = tokensB.filter(t => tokensA.has(t)).length;
+    const denom = Math.sqrt(tokensA.size * tokensB.length);
+    return denom === 0 ? 0 : intersection / denom;
+  }
+
+  async getStats() {
+    await this.init();
+    return {
+      totalEmbeddings: this.index.embeddings.length,
+      memoryEntries: this.memory.size,
+      lastUpdated: this.index.lastUpdated,
+      cacheDir: CACHE_DIR,
+      defaultTtlMs: this.defaultTtlMs,
+    };
+  }
+
+  async clear() {
+    this.memory.clear();
+    this.index = { embeddings: [], lastUpdated: null };
+    await fs.writeFile(INDEX_FILE, JSON.stringify(this.index), 'utf8').catch(() => {});
+  }
+}
+
+export const globalEmbeddingCache = new EmbeddingCache();

package/src/cache/similarity.js

@@ -0,0 +1,175 @@
+/**
+ * Similarity Search - Vector similarity and context matching utilities.
+ * Provides multiple similarity algorithms for finding relevant contexts.
+ */
+
+export class SimilaritySearch {
+  constructor() {
+    this.index = [];
+  }
+
+  /**
+   * Add a document to the search index.
+   */
+  add(id, text, metadata = {}) {
+    this.index.push({
+      id,
+      text,
+      tokens: this._tokenize(text),
+      metadata,
+      addedAt: Date.now(),
+    });
+    return this;
+  }
+
+  /**
+   * Add multiple documents at once.
+   */
+  addBatch(documents) {
+    for (const doc of documents) {
+      this.add(doc.id, doc.text, doc.metadata);
+    }
+    return this;
+  }
+
+  /**
+   * Search for similar documents using TF-IDF scoring.
+   */
+  search(query, options = {}) {
+    const {
+      limit = 10,
+      threshold = 0.1,
+      algorithm = 'tfidf',
+    } = options;
+
+    const queryTokens = this._tokenize(query);
+    if (queryTokens.length === 0) return [];
+
+    const scores = this.index.map((doc, idx) => {
+      let score;
+      switch (algorithm) {
+        case 'cosine':
+          score = this._cosineSimilarity(queryTokens, doc.tokens);
+          break;
+        case 'jaccard':
+          score = this._jaccardSimilarity(queryTokens, doc.tokens);
+          break;
+        case 'tfidf':
+        default:
+          score = this._tfidfScore(queryTokens, doc.tokens, idx);
+          break;
+      }
+      return { score, doc, idx };
+    });
+
+    return scores
+      .filter(s => s.score >= threshold)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit)
+      .map(s => ({
+        id: s.doc.id,
+        text: s.doc.text,
+        score: s.score,
+        metadata: s.doc.metadata,
+      }));
+  }
+
+  /**
+   * Remove a document from the index.
+   */
+  remove(id) {
+    this.index = this.index.filter(d => d.id !== id);
+    return this;
+  }
+
+  /**
+   * Clear the index.
+   */
+  clear() {
+    this.index = [];
+    return this;
+  }
+
+  /**
+   * Get index statistics.
+   */
+  stats() {
+    return {
+      documents: this.index.length,
+      totalTokens: this.index.reduce((sum, d) => sum + d.tokens.length, 0),
+      averageTokens: this.index.length
+        ? this.index.reduce((sum, d) => sum + d.tokens.length, 0) / this.index.length
+        : 0,
+    };
+  }
+
+  // --- Private helpers ---
+
+  _tokenize(text) {
+    return String(text || '')
+      .toLowerCase()
+      .replace(/[^a-z0-9\s]/g, '')
+      .split(/\s+/)
+      .filter(t => t.length > 1 && !STOP_WORDS.has(t));
+  }
+
+  _cosineSimilarity(tokensA, tokensB) {
+    const setA = new Set(tokensA);
+    const setB = new Set(tokensB);
+    const intersection = [...setA].filter(t => setB.has(t)).length;
+    const denom = Math.sqrt(setA.size * setB.size);
+    return denom === 0 ? 0 : intersection / denom;
+  }
+
+  _jaccardSimilarity(tokensA, tokensB) {
+    const setA = new Set(tokensA);
+    const setB = new Set(tokensB);
+    const intersection = new Set([...setA].filter(t => setB.has(t)));
+    const union = new Set([...setA, ...setB]);
+    return union.size === 0 ? 0 : intersection.size / union.size;
+  }
+
+  _tfidfScore(queryTokens, docTokens, docIdx) {
+    const docSet = new Set(docTokens);
+    const docFreq = new Map();
+    const totalDocs = this.index.length;
+
+    // Precompute document frequency
+    for (const token of queryTokens) {
+      if (!docFreq.has(token)) {
+        docFreq.set(token, this.index.filter(d => new Set(d.tokens).has(token)).length);
+      }
+    }
+
+    // TF-IDF for matching tokens
+    let score = 0;
+    for (const token of queryTokens) {
+      if (docSet.has(token)) {
+        const tf = docTokens.filter(t => t === token).length / docTokens.length;
+        const idf = Math.log((totalDocs + 1) / (docFreq.get(token) + 1)) + 1;
+        score += tf * idf;
+      }
+    }
+
+    return score;
+  }
+}
+
+const STOP_WORDS = new Set([
+  'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+  'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
+  'should', 'may', 'might', 'shall', 'can', 'need', 'dare', 'ought',
+  'to', 'of', 'in', 'for', 'on', 'with', 'at', 'by', 'from', 'as',
+  'into', 'through', 'during', 'before', 'after', 'above', 'below',
+  'between', 'out', 'off', 'over', 'under', 'again', 'further',
+  'then', 'once', 'here', 'there', 'when', 'where', 'why', 'how',
+  'all', 'each', 'every', 'both', 'few', 'more', 'most', 'other',
+  'some', 'such', 'no', 'nor', 'not', 'only', 'own', 'same', 'so',
+  'than', 'too', 'very', 'just', 'also', 'about', 'up', 'and', 'but',
+  'or', 'if', 'because', 'while', 'that', 'this', 'these', 'those',
+  'it', 'its', 'i', 'me', 'my', 'we', 'us', 'our', 'you', 'your',
+  'he', 'him', 'his', 'she', 'her', 'they', 'them', 'their',
+  'what', 'which', 'who', 'whom', 'whose',
+]);
+
+export default SimilaritySearch;