@lov3kaizen/agentsea-memory 0.5.1

package/dist/retrieval/index.cjs

@@ -0,0 +1,1262 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/retrieval/index.ts
+var retrieval_exports = {};
+__export(retrieval_exports, {
+  HybridRetrieval: () => HybridRetrieval,
+  PipelineBuilder: () => PipelineBuilder,
+  RetrievalPipeline: () => RetrievalPipeline,
+  SemanticRetrieval: () => SemanticRetrieval,
+  TemporalRetrieval: () => TemporalRetrieval,
+  TimeWindows: () => TimeWindows,
+  createHybridRetrieval: () => createHybridRetrieval,
+  createPipelineBuilder: () => createPipelineBuilder,
+  createRetrievalPipeline: () => createRetrievalPipeline,
+  createSemanticRetrieval: () => createSemanticRetrieval,
+  createTemporalRetrieval: () => createTemporalRetrieval
+});
+module.exports = __toCommonJS(retrieval_exports);
+
+// src/retrieval/strategies/SemanticRetrieval.ts
+var SemanticRetrieval = class {
+  store;
+  embedFn;
+  config;
+  constructor(store, embedFn, config = {}) {
+    this.store = store;
+    this.embedFn = embedFn;
+    this.config = {
+      topK: config.topK ?? 10,
+      minScore: config.minScore ?? 0.7,
+      reranking: config.reranking ?? false,
+      maxCandidates: config.maxCandidates ?? 100,
+      ...config
+    };
+  }
+  /**
+   * Retrieve memories semantically similar to the query
+   */
+  async retrieve(options) {
+    const startTime = Date.now();
+    const queryEmbedding = await this.embedFn(options.query);
+    const results = await this.store.search(queryEmbedding, {
+      topK: options.topK ?? this.config.topK,
+      minScore: options.minScore ?? this.config.minScore,
+      namespace: options.namespace,
+      filter: options.filter
+    });
+    let finalResults = results;
+    if (this.config.reranking && this.config.rerankFn) {
+      finalResults = await this.rerank(options.query, results);
+    }
+    const memories = finalResults.map((r) => {
+      const entry = { ...r.entry };
+      if (!options.includeEmbeddings) {
+        delete entry.embedding;
+      }
+      return entry;
+    });
+    return {
+      memories,
+      scores: finalResults.map((r) => r.score),
+      totalCandidates: results.length,
+      retrievalTimeMs: Date.now() - startTime,
+      strategy: "semantic"
+    };
+  }
+  /**
+   * Retrieve with context - includes surrounding memories
+   */
+  async retrieveWithContext(options, contextWindow = 2) {
+    const result = await this.retrieve(options);
+    const contextMemories = [];
+    for (const memory of result.memories) {
+      const surrounding = await this.getSurroundingMemories(
+        memory,
+        contextWindow
+      );
+      contextMemories.push(surrounding);
+    }
+    return {
+      ...result,
+      contextMemories
+    };
+  }
+  /**
+   * Get memories surrounding a given memory by timestamp
+   */
+  async getSurroundingMemories(memory, windowSize) {
+    const before = await this.store.query({
+      endTime: memory.timestamp - 1,
+      limit: windowSize,
+      namespace: memory.metadata.namespace
+    });
+    const after = await this.store.query({
+      startTime: memory.timestamp + 1,
+      limit: windowSize,
+      namespace: memory.metadata.namespace
+    });
+    return [...before.entries.reverse(), ...after.entries];
+  }
+  /**
+   * Rerank results using provided rerank function
+   */
+  async rerank(query, results) {
+    if (!this.config.rerankFn) {
+      return results;
+    }
+    const reranked = await this.config.rerankFn(query, results);
+    return Promise.resolve(
+      reranked.sort((a, b) => b.score - a.score)
+    );
+  }
+  /**
+   * Find memories similar to a given memory
+   */
+  async findSimilar(memory, options) {
+    if (!memory.embedding) {
+      const embedding = await this.embedFn(memory.content);
+      return this.store.search(embedding, {
+        topK: options?.topK ?? this.config.topK,
+        minScore: options?.minScore ?? this.config.minScore,
+        namespace: options?.namespace ?? memory.metadata.namespace,
+        filter: {
+          ...options?.filter,
+          // Exclude the source memory
+          id: { $ne: memory.id }
+        }
+      });
+    }
+    return this.store.search(memory.embedding, {
+      topK: (options?.topK ?? this.config.topK) + 1,
+      // +1 to exclude self
+      minScore: options?.minScore ?? this.config.minScore,
+      namespace: options?.namespace ?? memory.metadata.namespace,
+      filter: options?.filter
+    }).then((results) => results.filter((r) => r.entry.id !== memory.id));
+  }
+  /**
+   * Cluster memories by semantic similarity
+   */
+  async cluster(memories, numClusters = 5) {
+    const clusters = /* @__PURE__ */ new Map();
+    const memoriesWithEmbeddings = await Promise.all(
+      memories.map(async (m) => {
+        if (m.embedding) return m;
+        return {
+          ...m,
+          embedding: await this.embedFn(m.content)
+        };
+      })
+    );
+    const centerIndices = this.randomSample(
+      memoriesWithEmbeddings.length,
+      numClusters
+    );
+    const centers = centerIndices.map(
+      (i) => memoriesWithEmbeddings[i].embedding
+    );
+    for (let iteration = 0; iteration < 10; iteration++) {
+      for (let i = 0; i < numClusters; i++) {
+        clusters.set(i, []);
+      }
+      for (const memory of memoriesWithEmbeddings) {
+        let bestCluster = 0;
+        let bestSimilarity = -Infinity;
+        for (let i = 0; i < centers.length; i++) {
+          const similarity = this.cosineSimilarity(
+            memory.embedding,
+            centers[i]
+          );
+          if (similarity > bestSimilarity) {
+            bestSimilarity = similarity;
+            bestCluster = i;
+          }
+        }
+        clusters.get(bestCluster).push(memory);
+      }
+      for (let i = 0; i < numClusters; i++) {
+        const clusterMemories = clusters.get(i);
+        if (clusterMemories.length > 0) {
+          centers[i] = this.averageEmbedding(
+            clusterMemories.map((m) => m.embedding)
+          );
+        }
+      }
+    }
+    return clusters;
+  }
+  /**
+   * Calculate cosine similarity between two vectors
+   */
+  cosineSimilarity(a, b) {
+    if (a.length !== b.length) return 0;
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dotProduct += a[i] * b[i];
+      normA += a[i] * a[i];
+      normB += b[i] * b[i];
+    }
+    const magnitude = Math.sqrt(normA) * Math.sqrt(normB);
+    return magnitude === 0 ? 0 : dotProduct / magnitude;
+  }
+  /**
+   * Calculate average embedding
+   */
+  averageEmbedding(embeddings) {
+    const dim = embeddings[0].length;
+    const avg = new Array(dim).fill(0);
+    for (const emb of embeddings) {
+      for (let i = 0; i < dim; i++) {
+        avg[i] += emb[i];
+      }
+    }
+    for (let i = 0; i < dim; i++) {
+      avg[i] /= embeddings.length;
+    }
+    return avg;
+  }
+  /**
+   * Random sample without replacement
+   */
+  randomSample(max, count) {
+    const result = [];
+    const used = /* @__PURE__ */ new Set();
+    while (result.length < count && result.length < max) {
+      const index = Math.floor(Math.random() * max);
+      if (!used.has(index)) {
+        used.add(index);
+        result.push(index);
+      }
+    }
+    return result;
+  }
+  /**
+   * Update configuration
+   */
+  configure(config) {
+    this.config = { ...this.config, ...config };
+  }
+  /**
+   * Get current configuration
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+};
+function createSemanticRetrieval(store, embedFn, config) {
+  return new SemanticRetrieval(store, embedFn, config);
+}
+
+// src/retrieval/strategies/HybridRetrieval.ts
+var HybridRetrieval = class {
+  store;
+  semanticRetrieval;
+  config;
+  constructor(store, embedFn, config = {}) {
+    this.store = store;
+    this.config = {
+      semanticWeight: config.semanticWeight ?? 0.7,
+      keywordWeight: config.keywordWeight ?? 0.3,
+      topK: config.topK ?? 10,
+      minScore: config.minScore ?? 0.5,
+      fusionMethod: config.fusionMethod ?? "rrf",
+      ...config
+    };
+    this.semanticRetrieval = new SemanticRetrieval(store, embedFn, {
+      topK: config.topK ?? 10,
+      minScore: 0
+      // Lower threshold for candidates
+    });
+  }
+  /**
+   * Retrieve memories using hybrid search
+   */
+  async retrieve(options) {
+    const startTime = Date.now();
+    const topK = options.topK ?? this.config.topK;
+    const semanticWeight = options.semanticWeight ?? this.config.semanticWeight;
+    const keywordWeight = options.keywordWeight ?? this.config.keywordWeight;
+    const candidateMultiplier = 3;
+    const semanticResult = await this.semanticRetrieval.retrieve({
+      query: options.query,
+      topK: topK * candidateMultiplier,
+      minScore: 0,
+      // Get all candidates
+      namespace: options.namespace,
+      filter: options.filter
+    });
+    const keywordResult = await this.keywordSearch(options.query, {
+      limit: topK * candidateMultiplier,
+      namespace: options.namespace
+    });
+    const fusedResults = this.fuseResults(
+      semanticResult.memories.map((m, i) => ({
+        entry: m,
+        score: semanticResult.scores?.[i] ?? 0
+      })),
+      keywordResult,
+      semanticWeight,
+      keywordWeight
+    );
+    const filtered = fusedResults.filter((r) => r.score >= (options.minScore ?? this.config.minScore)).slice(0, topK);
+    return {
+      memories: filtered.map((r) => r.entry),
+      scores: filtered.map((r) => r.score),
+      totalCandidates: semanticResult.memories.length + keywordResult.length,
+      retrievalTimeMs: Date.now() - startTime,
+      strategy: "hybrid",
+      metadata: {
+        semanticCandidates: semanticResult.memories.length,
+        keywordCandidates: keywordResult.length,
+        fusionMethod: this.config.fusionMethod
+      }
+    };
+  }
+  /**
+   * Keyword-based search using text matching
+   */
+  async keywordSearch(query, options) {
+    const queryTokens = this.tokenize(query);
+    const { entries } = await this.store.query({
+      query,
+      limit: options.limit * 2,
+      // Get more for better recall
+      namespace: options.namespace
+    });
+    const results = [];
+    for (const entry of entries) {
+      const score = this.calculateKeywordScore(queryTokens, entry.content);
+      if (score > 0) {
+        results.push({ entry, score });
+      }
+    }
+    results.sort((a, b) => b.score - a.score);
+    return Promise.resolve(results.slice(0, options.limit));
+  }
+  /**
+   * Tokenize text into terms
+   */
+  tokenize(text) {
+    return text.toLowerCase().replace(/[^\w\s]/g, " ").split(/\s+/).filter((t) => t.length > 2);
+  }
+  /**
+   * Calculate BM25-like keyword score
+   */
+  calculateKeywordScore(queryTokens, content) {
+    const contentTokens = this.tokenize(content);
+    const contentTokenSet = new Set(contentTokens);
+    const termFreq = /* @__PURE__ */ new Map();
+    for (const token of contentTokens) {
+      termFreq.set(token, (termFreq.get(token) ?? 0) + 1);
+    }
+    const k1 = 1.2;
+    const b = 0.75;
+    const avgDocLength = 100;
+    let score = 0;
+    const docLength = contentTokens.length;
+    for (const token of queryTokens) {
+      if (contentTokenSet.has(token)) {
+        const tf = termFreq.get(token) ?? 0;
+        const idf = 1.5;
+        const tfNorm = tf * (k1 + 1) / (tf + k1 * (1 - b + b * docLength / avgDocLength));
+        score += idf * tfNorm;
+      }
+    }
+    return score / queryTokens.length;
+  }
+  /**
+   * Fuse semantic and keyword results
+   */
+  fuseResults(semanticResults, keywordResults, semanticWeight, keywordWeight) {
+    if (this.config.fusionMethod === "rrf") {
+      return this.reciprocalRankFusion(semanticResults, keywordResults);
+    } else {
+      return this.weightedFusion(
+        semanticResults,
+        keywordResults,
+        semanticWeight,
+        keywordWeight
+      );
+    }
+  }
+  /**
+   * Reciprocal Rank Fusion (RRF)
+   */
+  reciprocalRankFusion(list1, list2) {
+    const k = 60;
+    const scoreMap = /* @__PURE__ */ new Map();
+    for (let i = 0; i < list1.length; i++) {
+      const id = list1[i].entry.id;
+      const rrfScore = 1 / (k + i + 1);
+      scoreMap.set(id, {
+        entry: list1[i].entry,
+        score: rrfScore
+      });
+    }
+    for (let i = 0; i < list2.length; i++) {
+      const id = list2[i].entry.id;
+      const rrfScore = 1 / (k + i + 1);
+      const existing = scoreMap.get(id);
+      if (existing) {
+        existing.score += rrfScore;
+      } else {
+        scoreMap.set(id, {
+          entry: list2[i].entry,
+          score: rrfScore
+        });
+      }
+    }
+    const results = Array.from(scoreMap.values()).map((item) => ({
+      entry: item.entry,
+      score: item.score
+    }));
+    results.sort((a, b) => b.score - a.score);
+    return results;
+  }
+  /**
+   * Weighted score fusion
+   */
+  weightedFusion(semanticResults, keywordResults, semanticWeight, keywordWeight) {
+    const scoreMap = /* @__PURE__ */ new Map();
+    const maxSemantic = Math.max(...semanticResults.map((r) => r.score), 1);
+    for (const result of semanticResults) {
+      const normalizedScore = result.score / maxSemantic;
+      scoreMap.set(result.entry.id, {
+        entry: result.entry,
+        semanticScore: normalizedScore,
+        keywordScore: 0
+      });
+    }
+    const maxKeyword = Math.max(...keywordResults.map((r) => r.score), 1);
+    for (const result of keywordResults) {
+      const normalizedScore = result.score / maxKeyword;
+      const existing = scoreMap.get(result.entry.id);
+      if (existing) {
+        existing.keywordScore = normalizedScore;
+      } else {
+        scoreMap.set(result.entry.id, {
+          entry: result.entry,
+          semanticScore: 0,
+          keywordScore: normalizedScore
+        });
+      }
+    }
+    const results = Array.from(scoreMap.values()).map((item) => ({
+      entry: item.entry,
+      score: item.semanticScore * semanticWeight + item.keywordScore * keywordWeight
+    }));
+    results.sort((a, b) => b.score - a.score);
+    return results;
+  }
+  /**
+   * Retrieve with explanation of why each result matched
+   */
+  async retrieveWithExplanation(options) {
+    const startTime = Date.now();
+    const topK = options.topK ?? this.config.topK;
+    const semanticResult = await this.semanticRetrieval.retrieve({
+      query: options.query,
+      topK: topK * 3,
+      minScore: 0,
+      namespace: options.namespace
+    });
+    const keywordResult = await this.keywordSearch(options.query, {
+      limit: topK * 3,
+      namespace: options.namespace
+    });
+    const semanticScores = /* @__PURE__ */ new Map();
+    semanticResult.memories.forEach((m, i) => {
+      semanticScores.set(m.id, semanticResult.scores?.[i] ?? 0);
+    });
+    const keywordScores = /* @__PURE__ */ new Map();
+    keywordResult.forEach((r) => {
+      keywordScores.set(r.entry.id, r.score);
+    });
+    const fusedResults = this.fuseResults(
+      semanticResult.memories.map((m, i) => ({
+        entry: m,
+        score: semanticResult.scores?.[i] ?? 0
+      })),
+      keywordResult,
+      options.semanticWeight ?? this.config.semanticWeight,
+      options.keywordWeight ?? this.config.keywordWeight
+    ).slice(0, topK);
+    const queryTokens = this.tokenize(options.query);
+    const explanations = fusedResults.map((r) => {
+      const semScore = semanticScores.get(r.entry.id);
+      const kwScore = keywordScores.get(r.entry.id);
+      const parts = [];
+      if (semScore !== void 0 && semScore > 0.5) {
+        parts.push(`semantically similar (${(semScore * 100).toFixed(0)}%)`);
+      }
+      if (kwScore !== void 0 && kwScore > 0) {
+        const matchingTokens = queryTokens.filter(
+          (t) => r.entry.content.toLowerCase().includes(t)
+        );
+        if (matchingTokens.length > 0) {
+          parts.push(`keyword matches: "${matchingTokens.join('", "')}"`);
+        }
+      }
+      return parts.length > 0 ? parts.join("; ") : "matched via fuzzy matching";
+    });
+    return {
+      memories: fusedResults.map((r) => r.entry),
+      scores: fusedResults.map((r) => r.score),
+      totalCandidates: semanticResult.memories.length + keywordResult.length,
+      retrievalTimeMs: Date.now() - startTime,
+      strategy: "hybrid",
+      explanations
+    };
+  }
+  /**
+   * Update configuration
+   */
+  configure(config) {
+    this.config = { ...this.config, ...config };
+  }
+  /**
+   * Get current configuration
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+};
+function createHybridRetrieval(store, embedFn, config) {
+  return new HybridRetrieval(store, embedFn, config);
+}
+
+// src/retrieval/strategies/TemporalRetrieval.ts
+var TemporalRetrieval = class {
+  store;
+  config;
+  constructor(store, config = {}) {
+    this.store = store;
+    this.config = {
+      recencyWeight: config.recencyWeight ?? 0.5,
+      importanceWeight: config.importanceWeight ?? 0.3,
+      accessWeight: config.accessWeight ?? 0.2,
+      decayFunction: config.decayFunction ?? "exponential",
+      decayHalfLife: config.decayHalfLife ?? 24 * 60 * 60 * 1e3,
+      // 24 hours
+      topK: config.topK ?? 10,
+      ...config
+    };
+  }
+  /**
+   * Retrieve memories with temporal scoring
+   */
+  async retrieve(options) {
+    const startTime = Date.now();
+    const { entries } = await this.store.query({
+      startTime: options.startTime,
+      endTime: options.endTime,
+      namespace: options.namespace,
+      types: options.types,
+      limit: 1e3
+      // Get many candidates for scoring
+    });
+    let filtered = entries;
+    if (options.filter) {
+      filtered = this.applyFilter(entries, options.filter);
+    }
+    const now = Date.now();
+    const scored = filtered.map((entry) => ({
+      entry,
+      score: this.calculateTemporalScore(entry, now, options)
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    const topK = options.topK ?? this.config.topK;
+    const results = scored.slice(0, topK);
+    return {
+      memories: results.map((r) => r.entry),
+      scores: results.map((r) => r.score),
+      totalCandidates: filtered.length,
+      retrievalTimeMs: Date.now() - startTime,
+      strategy: "temporal"
+    };
+  }
+  /**
+   * Retrieve memories from specific time windows
+   */
+  async retrieveFromWindows(windows, options) {
+    const results = /* @__PURE__ */ new Map();
+    for (const window of windows) {
+      const label = window.label ?? `${window.start}-${window.end}`;
+      const result = await this.retrieve({
+        ...options,
+        startTime: window.start,
+        endTime: window.end
+      });
+      results.set(label, result);
+    }
+    return results;
+  }
+  /**
+   * Get memories from relative time periods
+   */
+  async retrieveRecent(period, options) {
+    const now = Date.now();
+    const periodMs = {
+      hour: 60 * 60 * 1e3,
+      day: 24 * 60 * 60 * 1e3,
+      week: 7 * 24 * 60 * 60 * 1e3,
+      month: 30 * 24 * 60 * 60 * 1e3
+    };
+    return this.retrieve({
+      ...options,
+      startTime: now - periodMs[period],
+      endTime: now
+    });
+  }
+  /**
+   * Get trending memories (high access in recent time)
+   */
+  async retrieveTrending(windowMs = 24 * 60 * 60 * 1e3, options) {
+    const startTime = Date.now();
+    const windowStart = startTime - windowMs;
+    const { entries } = await this.store.query({
+      startTime: windowStart,
+      namespace: options?.namespace,
+      limit: 1e3
+    });
+    const scored = entries.map((entry) => {
+      const age = startTime - entry.timestamp;
+      const accessRate = entry.accessCount / Math.max(age / (60 * 60 * 1e3), 1);
+      return {
+        entry,
+        score: accessRate * entry.importance
+      };
+    });
+    scored.sort((a, b) => b.score - a.score);
+    const topK = options?.topK ?? this.config.topK;
+    const results = scored.slice(0, topK);
+    return {
+      memories: results.map((r) => r.entry),
+      scores: results.map((r) => r.score),
+      totalCandidates: entries.length,
+      retrievalTimeMs: Date.now() - startTime,
+      strategy: "temporal-trending"
+    };
+  }
+  /**
+   * Get memories matching a temporal pattern
+   */
+  async retrieveByPattern(pattern, lookbackPeriods = 4, options) {
+    const startTime = Date.now();
+    const now = Date.now();
+    const windows = [];
+    for (let i = 0; i < lookbackPeriods; i++) {
+      const periodStart = now - (i + 1) * pattern.interval;
+      const periodEnd = now - i * pattern.interval;
+      if (pattern.peakHours || pattern.peakDays) {
+        const date = new Date(periodStart);
+        const hour = date.getHours();
+        const day = date.getDay();
+        if (pattern.peakHours && !pattern.peakHours.includes(hour)) {
+          continue;
+        }
+        if (pattern.peakDays && !pattern.peakDays.includes(day)) {
+          continue;
+        }
+      }
+      windows.push({ start: periodStart, end: periodEnd });
+    }
+    const allEntries = [];
+    for (const window of windows) {
+      const { entries } = await this.store.query({
+        startTime: window.start,
+        endTime: window.end,
+        namespace: options?.namespace,
+        limit: 100
+      });
+      allEntries.push(...entries);
+    }
+    const uniqueEntries = this.deduplicateEntries(allEntries);
+    const scored = uniqueEntries.map((entry) => ({
+      entry,
+      score: this.calculateTemporalScore(entry, now, options ?? {})
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    const topK = options?.topK ?? this.config.topK;
+    const results = scored.slice(0, topK);
+    return {
+      memories: results.map((r) => r.entry),
+      scores: results.map((r) => r.score),
+      totalCandidates: uniqueEntries.length,
+      retrievalTimeMs: Date.now() - startTime,
+      strategy: "temporal-pattern",
+      metadata: {
+        pattern: pattern.type,
+        windowsMatched: windows.length
+      }
+    };
+  }
+  /**
+   * Get timeline of memories
+   */
+  async getTimeline(options) {
+    const bucketMs = {
+      hour: 60 * 60 * 1e3,
+      day: 24 * 60 * 60 * 1e3,
+      week: 7 * 24 * 60 * 60 * 1e3
+    };
+    const { entries } = await this.store.query({
+      startTime: options.startTime,
+      endTime: options.endTime,
+      namespace: options.namespace,
+      limit: 1e4
+    });
+    const timeline = /* @__PURE__ */ new Map();
+    const size = bucketMs[options.bucketSize];
+    for (const entry of entries) {
+      const bucketStart = Math.floor(entry.timestamp / size) * size;
+      const key = new Date(bucketStart).toISOString();
+      if (!timeline.has(key)) {
+        timeline.set(key, []);
+      }
+      timeline.get(key).push(entry);
+    }
+    return timeline;
+  }
+  /**
+   * Calculate temporal score for a memory
+   */
+  calculateTemporalScore(entry, now, options) {
+    const recencyWeight = options.recencyWeight ?? this.config.recencyWeight;
+    const importanceWeight = options.importanceWeight ?? this.config.importanceWeight;
+    const accessWeight = options.accessWeight ?? this.config.accessWeight;
+    const recencyScore = this.calculateDecay(now - entry.timestamp);
+    const importanceScore = entry.importance;
+    const maxAccessCount = 100;
+    const accessScore = Math.min(entry.accessCount / maxAccessCount, 1);
+    return recencyScore * recencyWeight + importanceScore * importanceWeight + accessScore * accessWeight;
+  }
+  /**
+   * Calculate decay based on configured function
+   */
+  calculateDecay(ageMs) {
+    const halfLife = this.config.decayHalfLife;
+    switch (this.config.decayFunction) {
+      case "exponential":
+        return Math.exp(-Math.LN2 * ageMs / halfLife);
+      case "linear":
+        return Math.max(0, 1 - ageMs / (halfLife * 2));
+      case "step":
+        return ageMs <= halfLife ? 1 : 0;
+      case "logarithmic":
+        return 1 / (1 + Math.log2(1 + ageMs / halfLife));
+      default:
+        return Math.exp(-Math.LN2 * ageMs / halfLife);
+    }
+  }
+  /**
+   * Apply metadata filter to entries
+   */
+  applyFilter(entries, filter) {
+    return entries.filter((entry) => {
+      for (const [key, value] of Object.entries(filter)) {
+        const entryValue = entry.metadata[key];
+        if (Array.isArray(value)) {
+          if (!value.includes(entryValue)) return false;
+        } else if (entryValue !== value) {
+          return false;
+        }
+      }
+      return true;
+    });
+  }
+  /**
+   * Deduplicate entries by ID
+   */
+  deduplicateEntries(entries) {
+    const seen = /* @__PURE__ */ new Set();
+    return entries.filter((entry) => {
+      if (seen.has(entry.id)) return false;
+      seen.add(entry.id);
+      return true;
+    });
+  }
+  /**
+   * Update configuration
+   */
+  configure(config) {
+    this.config = { ...this.config, ...config };
+  }
+  /**
+   * Get current configuration
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+};
+function createTemporalRetrieval(store, config) {
+  return new TemporalRetrieval(store, config);
+}
+var TimeWindows = {
+  lastHour: () => ({
+    start: Date.now() - 60 * 60 * 1e3,
+    end: Date.now(),
+    label: "last-hour"
+  }),
+  lastDay: () => ({
+    start: Date.now() - 24 * 60 * 60 * 1e3,
+    end: Date.now(),
+    label: "last-day"
+  }),
+  lastWeek: () => ({
+    start: Date.now() - 7 * 24 * 60 * 60 * 1e3,
+    end: Date.now(),
+    label: "last-week"
+  }),
+  lastMonth: () => ({
+    start: Date.now() - 30 * 24 * 60 * 60 * 1e3,
+    end: Date.now(),
+    label: "last-month"
+  }),
+  today: () => {
+    const now = /* @__PURE__ */ new Date();
+    const startOfDay = new Date(
+      now.getFullYear(),
+      now.getMonth(),
+      now.getDate()
+    ).getTime();
+    return {
+      start: startOfDay,
+      end: Date.now(),
+      label: "today"
+    };
+  },
+  yesterday: () => {
+    const now = /* @__PURE__ */ new Date();
+    const startOfYesterday = new Date(
+      now.getFullYear(),
+      now.getMonth(),
+      now.getDate() - 1
+    ).getTime();
+    const endOfYesterday = new Date(
+      now.getFullYear(),
+      now.getMonth(),
+      now.getDate()
+    ).getTime();
+    return {
+      start: startOfYesterday,
+      end: endOfYesterday,
+      label: "yesterday"
+    };
+  },
+  custom: (startDate, endDate, label) => ({
+    start: startDate.getTime(),
+    end: endDate.getTime(),
+    label
+  })
+};
+
+// src/retrieval/strategies/RetrievalPipeline.ts
+var RetrievalPipeline = class {
+  stages = /* @__PURE__ */ new Map();
+  config;
+  constructor(config = { stages: [] }) {
+    this.config = {
+      maxCandidates: config.maxCandidates ?? 100,
+      minScore: config.minScore ?? 0,
+      timeout: config.timeout ?? 3e4,
+      ...config
+    };
+    this.registerBuiltInStages();
+  }
+  /**
+   * Register built-in stages
+   */
+  registerBuiltInStages() {
+    this.register("filter", (ctx, config) => {
+      const filters = config.params?.filters;
+      if (!filters) return Promise.resolve(ctx);
+      const filtered = ctx.candidates.filter((c) => {
+        for (const [key, value] of Object.entries(filters)) {
+          const entryValue = c.entry.metadata[key] ?? c.entry[key];
+          if (Array.isArray(value)) {
+            if (!value.includes(entryValue)) return false;
+          } else if (entryValue !== value) {
+            return false;
+          }
+        }
+        return true;
+      });
+      return Promise.resolve({ ...ctx, candidates: filtered });
+    });
+    this.register("boost", (ctx, config) => {
+      const boosts = config.params?.boosts;
+      if (!boosts) return Promise.resolve(ctx);
+      const boosted = ctx.candidates.map((c) => {
+        let newScore = c.score;
+        for (const boost of boosts) {
+          const fieldValue = c.entry.metadata[boost.field] ?? c.entry[boost.field];
+          if (fieldValue === boost.value) {
+            newScore *= boost.factor;
+          }
+        }
+        return { ...c, score: newScore };
+      });
+      boosted.sort((a, b) => b.score - a.score);
+      return Promise.resolve({ ...ctx, candidates: boosted });
+    });
+    this.register("rerank", (ctx, config) => {
+      const weights = config.params?.weights;
+      if (!weights) return Promise.resolve(ctx);
+      const reranked = ctx.candidates.map((c) => {
+        let newScore = 0;
+        let totalWeight = 0;
+        for (const [field, weight] of Object.entries(weights)) {
+          if (field === "originalScore") {
+            newScore += c.score * weight;
+          } else {
+            const value = c.entry.metadata[field] ?? c.entry[field];
+            if (typeof value === "number") {
+              newScore += value * weight;
+            }
+          }
+          totalWeight += weight;
+        }
+        return {
+          ...c,
+          score: totalWeight > 0 ? newScore / totalWeight : c.score
+        };
+      });
+      reranked.sort((a, b) => b.score - a.score);
+      return Promise.resolve({ ...ctx, candidates: reranked });
+    });
+    this.register("dedupe", (ctx, config) => {
+      const field = config.params?.field ?? "content";
+      const seen = /* @__PURE__ */ new Map();
+      const deduped = [];
+      for (const candidate of ctx.candidates) {
+        const key = this.getDedupeKey(candidate.entry, field);
+        const existing = seen.get(key);
+        if (!existing) {
+          seen.set(key, candidate);
+          deduped.push(candidate);
+        } else if (candidate.score > existing.score) {
+          const idx = deduped.indexOf(existing);
+          if (idx !== -1) {
+            deduped[idx] = candidate;
+          }
+          seen.set(key, candidate);
+        }
+      }
+      return Promise.resolve({ ...ctx, candidates: deduped });
+    });
+    this.register("diversify", (ctx, config) => {
+      const field = config.params?.field ?? "type";
+      const maxPerCategory = config.params?.maxPerCategory ?? 3;
+      const categoryCounts = /* @__PURE__ */ new Map();
+      const diversified = [];
+      for (const candidate of ctx.candidates) {
+        const category = String(
+          candidate.entry.metadata[field] ?? candidate.entry[field] ?? "unknown"
+        );
+        const count = categoryCounts.get(category) ?? 0;
+        if (count < maxPerCategory) {
+          diversified.push(candidate);
+          categoryCounts.set(category, count + 1);
+        }
+      }
+      return Promise.resolve({ ...ctx, candidates: diversified });
+    });
+    this.register("truncate", (ctx, config) => {
+      const limit = config.params?.limit ?? this.config.maxCandidates;
+      return Promise.resolve({
+        ...ctx,
+        candidates: ctx.candidates.slice(0, limit)
+      });
+    });
+    this.register("enrich", async (ctx, config) => {
+      const enrichFn = config.params?.enrichFn;
+      if (!enrichFn) return ctx;
+      const enriched = await Promise.all(
+        ctx.candidates.map(async (c) => {
+          const enrichment = await enrichFn(c.entry);
+          return {
+            ...c,
+            entry: {
+              ...c.entry,
+              metadata: { ...c.entry.metadata, ...enrichment }
+            }
+          };
+        })
+      );
+      return { ...ctx, candidates: enriched };
+    });
+  }
+  /**
+   * Register a custom stage
+   */
+  register(name, stage) {
+    this.stages.set(name, stage);
+  }
+  /**
+   * Execute the pipeline
+   */
+  async execute(query, initialCandidates) {
+    const startTime = Date.now();
+    let context = {
+      query,
+      candidates: initialCandidates,
+      metadata: {},
+      timing: {}
+    };
+    for (const stageConfig of this.config.stages) {
+      if (stageConfig.enabled === false) continue;
+      const stage = this.stages.get(stageConfig.name);
+      if (!stage) {
+        console.warn(
+          `Pipeline stage "${stageConfig.name}" not found, skipping`
+        );
+        continue;
+      }
+      const stageStart = Date.now();
+      try {
+        context = await this.executeWithTimeout(
+          stage(context, stageConfig),
+          this.config.timeout
+        );
+        context.timing[stageConfig.name] = Date.now() - stageStart;
+      } catch (error) {
+        console.error(`Pipeline stage "${stageConfig.name}" failed:`, error);
+      }
+    }
+    if (this.config.minScore > 0) {
+      context.candidates = context.candidates.filter(
+        (c) => c.score >= this.config.minScore
+      );
+    }
+    context.candidates = context.candidates.slice(0, this.config.maxCandidates);
+    return {
+      memories: context.candidates.map((c) => c.entry),
+      scores: context.candidates.map((c) => c.score),
+      totalCandidates: initialCandidates.length,
+      retrievalTimeMs: Date.now() - startTime,
+      strategy: "pipeline",
+      metadata: {
+        ...context.metadata,
+        timing: context.timing,
+        stagesExecuted: this.config.stages.filter((s) => s.enabled !== false).length
+      }
+    };
+  }
+  /**
+   * Execute promise with timeout
+   */
+  async executeWithTimeout(promise, timeout) {
+    return Promise.race([
+      promise,
+      new Promise(
+        (_, reject) => setTimeout(() => reject(new Error("Stage timeout")), timeout)
+      )
+    ]);
+  }
+  /**
+   * Get dedupe key for an entry
+   */
+  getDedupeKey(entry, field) {
+    if (field === "id") return entry.id;
+    if (field === "content") {
+      return entry.content.toLowerCase().trim().slice(0, 200);
+    }
+    return String(
+      entry.metadata[field] ?? entry[field] ?? entry.id
+    );
+  }
+  /**
+   * Add a stage to the pipeline
+   */
+  addStage(config) {
+    this.config.stages.push(config);
+    return this;
+  }
+  /**
+   * Remove a stage from the pipeline
+   */
+  removeStage(name) {
+    this.config.stages = this.config.stages.filter((s) => s.name !== name);
+    return this;
+  }
+  /**
+   * Update pipeline configuration
+   */
+  configure(config) {
+    this.config = { ...this.config, ...config };
+  }
+  /**
+   * Get current configuration
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+  /**
+   * Get registered stage names
+   */
+  getStageNames() {
+    return Array.from(this.stages.keys());
+  }
+};
+var PipelineBuilder = class {
+  stages = [];
+  maxCandidates = 100;
+  minScore = 0;
+  timeout = 3e4;
+  customStages = /* @__PURE__ */ new Map();
+  /**
+   * Add a filter stage
+   */
+  filter(filters) {
+    this.stages.push({
+      name: "filter",
+      params: { filters }
+    });
+    return this;
+  }
+  /**
+   * Add a boost stage
+   */
+  boost(boosts) {
+    this.stages.push({
+      name: "boost",
+      params: { boosts }
+    });
+    return this;
+  }
+  /**
+   * Add a rerank stage
+   */
+  rerank(weights) {
+    this.stages.push({
+      name: "rerank",
+      params: { weights }
+    });
+    return this;
+  }
+  /**
+   * Add a dedupe stage
+   */
+  dedupe(field = "content", similarity = 0.95) {
+    this.stages.push({
+      name: "dedupe",
+      params: { field, similarity }
+    });
+    return this;
+  }
+  /**
+   * Add a diversify stage
+   */
+  diversify(field = "type", maxPerCategory = 3) {
+    this.stages.push({
+      name: "diversify",
+      params: { field, maxPerCategory }
+    });
+    return this;
+  }
+  /**
+   * Add a truncate stage
+   */
+  truncate(limit) {
+    this.stages.push({
+      name: "truncate",
+      params: { limit }
+    });
+    return this;
+  }
+  /**
+   * Add an enrich stage
+   */
+  enrich(enrichFn) {
+    this.stages.push({
+      name: "enrich",
+      params: { enrichFn }
+    });
+    return this;
+  }
+  /**
+   * Add a custom stage
+   */
+  custom(name, stage, params) {
+    this.customStages.set(name, stage);
+    this.stages.push({ name, params });
+    return this;
+  }
+  /**
+   * Set maximum candidates
+   */
+  withMaxCandidates(max) {
+    this.maxCandidates = max;
+    return this;
+  }
+  /**
+   * Set minimum score
+   */
+  withMinScore(min) {
+    this.minScore = min;
+    return this;
+  }
+  /**
+   * Set timeout
+   */
+  withTimeout(ms) {
+    this.timeout = ms;
+    return this;
+  }
+  /**
+   * Build the pipeline
+   */
+  build() {
+    const pipeline = new RetrievalPipeline({
+      stages: this.stages,
+      maxCandidates: this.maxCandidates,
+      minScore: this.minScore,
+      timeout: this.timeout
+    });
+    for (const [name, stage] of this.customStages) {
+      pipeline.register(name, stage);
+    }
+    return pipeline;
+  }
+};
+function createPipelineBuilder() {
+  return new PipelineBuilder();
+}
+function createRetrievalPipeline(config) {
+  return new RetrievalPipeline(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HybridRetrieval,
+  PipelineBuilder,
+  RetrievalPipeline,
+  SemanticRetrieval,
+  TemporalRetrieval,
+  TimeWindows,
+  createHybridRetrieval,
+  createPipelineBuilder,
+  createRetrievalPipeline,
+  createSemanticRetrieval,
+  createTemporalRetrieval
+});