agentic-memory 0.1.0

package/dist/index.mjs

@@ -0,0 +1,689 @@
+// src/core/utils.ts
+function generateId() {
+  return `mem_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 9)}`;
+}
+function now() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function 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 denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dotProduct / denom;
+}
+function daysSince(isoTimestamp) {
+  const diff = Date.now() - new Date(isoTimestamp).getTime();
+  return diff / (1e3 * 60 * 60 * 24);
+}
+
+// src/store/local.ts
+var LocalStore = class {
+  entries = /* @__PURE__ */ new Map();
+  async get(id) {
+    return this.entries.get(id) ?? null;
+  }
+  async getAll(scope) {
+    const all = Array.from(this.entries.values());
+    if (!scope) return all;
+    return all.filter((e) => e.scope === scope);
+  }
+  async set(entry) {
+    this.entries.set(entry.id, { ...entry });
+  }
+  async delete(id) {
+    return this.entries.delete(id);
+  }
+  async clear(scope) {
+    if (!scope) {
+      this.entries.clear();
+      return;
+    }
+    for (const [id, entry] of this.entries) {
+      if (entry.scope === scope) {
+        this.entries.delete(id);
+      }
+    }
+  }
+  async search(query) {
+    let results = Array.from(this.entries.values());
+    if (query.scope) {
+      results = results.filter((e) => e.scope === query.scope);
+    }
+    if (query.types && query.types.length > 0) {
+      results = results.filter((e) => query.types.includes(e.type));
+    }
+    return results;
+  }
+  /** Get the number of stored entries */
+  get size() {
+    return this.entries.size;
+  }
+};
+
+// src/retrieval/embedder.ts
+var BuiltinEmbedder = class {
+  dim;
+  vocabulary = /* @__PURE__ */ new Map();
+  idfCache = /* @__PURE__ */ new Map();
+  documentCount = 0;
+  documentFreq = /* @__PURE__ */ new Map();
+  constructor(dimensions = 256) {
+    this.dim = dimensions;
+  }
+  dimensions() {
+    return this.dim;
+  }
+  async embed(text) {
+    const tokens = this.tokenize(text);
+    return this.tokensToVector(tokens);
+  }
+  async embedBatch(texts) {
+    return Promise.all(texts.map((t) => this.embed(t)));
+  }
+  /**
+   * Feed documents to build vocabulary and IDF stats.
+   * Call this when adding memories to improve embedding quality.
+   */
+  train(documents) {
+    for (const doc of documents) {
+      this.documentCount++;
+      const uniqueTokens = new Set(this.tokenize(doc));
+      for (const token of uniqueTokens) {
+        this.documentFreq.set(token, (this.documentFreq.get(token) ?? 0) + 1);
+      }
+    }
+    this.idfCache.clear();
+    for (const [token, freq] of this.documentFreq) {
+      this.idfCache.set(token, Math.log((this.documentCount + 1) / (freq + 1)) + 1);
+    }
+  }
+  tokenize(text) {
+    return text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter((t) => t.length > 1);
+  }
+  tokensToVector(tokens) {
+    const vector = new Array(this.dim).fill(0);
+    const tf = /* @__PURE__ */ new Map();
+    for (const token of tokens) {
+      tf.set(token, (tf.get(token) ?? 0) + 1);
+    }
+    for (const [token, freq] of tf) {
+      const idf = this.idfCache.get(token) ?? 1;
+      const weight = freq / tokens.length * idf;
+      const hash = this.hashToken(token);
+      const idx = Math.abs(hash) % this.dim;
+      const sign = this.hashToken(token + "_sign") > 0 ? 1 : -1;
+      vector[idx] += sign * weight;
+    }
+    const norm = Math.sqrt(vector.reduce((sum, v) => sum + v * v, 0));
+    if (norm > 0) {
+      for (let i = 0; i < vector.length; i++) {
+        vector[i] /= norm;
+      }
+    }
+    return vector;
+  }
+  hashToken(token) {
+    let hash = 0;
+    for (let i = 0; i < token.length; i++) {
+      const char = token.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash |= 0;
+    }
+    return hash;
+  }
+};
+
+// src/retrieval/multi-signal.ts
+var DEFAULT_WEIGHTS = {
+  similarity: 0.4,
+  recency: 0.25,
+  importance: 0.2,
+  taskRelevance: 0.15
+};
+var IMPORTANCE_SCORES = {
+  hard: 1,
+  soft: 0.5,
+  ephemeral: 0.2
+};
+var MultiSignalRetriever = class {
+  store;
+  embedder;
+  weights;
+  constructor(store, embedder, weights) {
+    this.store = store;
+    this.embedder = embedder;
+    this.weights = { ...DEFAULT_WEIGHTS, ...weights };
+  }
+  async retrieve(query) {
+    const signals = query.signals ?? ["similarity", "recency", "importance"];
+    const limit = query.limit ?? 10;
+    const threshold = query.threshold ?? 0;
+    const candidates = await this.store.search(query);
+    if (candidates.length === 0) return [];
+    let queryEmbedding = null;
+    if (signals.includes("similarity")) {
+      queryEmbedding = await this.embedder.embed(query.query);
+    }
+    let taskEmbedding = null;
+    if (signals.includes("taskRelevance") && query.taskContext) {
+      taskEmbedding = await this.embedder.embed(query.taskContext);
+    }
+    const scored = [];
+    for (const entry of candidates) {
+      const signalScores = {};
+      let totalScore = 0;
+      let totalWeight = 0;
+      let entryEmbedding = null;
+      const needsEmbedding = signals.includes("similarity") && queryEmbedding || signals.includes("taskRelevance") && taskEmbedding;
+      if (needsEmbedding) {
+        entryEmbedding = entry.embedding ?? await this.embedder.embed(entry.content);
+      }
+      if (signals.includes("similarity") && queryEmbedding && entryEmbedding) {
+        signalScores.similarity = Math.max(0, cosineSimilarity(queryEmbedding, entryEmbedding));
+        totalScore += signalScores.similarity * this.weights.similarity;
+        totalWeight += this.weights.similarity;
+      }
+      if (signals.includes("recency")) {
+        const age = Math.max(0, daysSince(entry.updatedAt));
+        signalScores.recency = Math.exp(-0.693 * age / 7);
+        totalScore += signalScores.recency * this.weights.recency;
+        totalWeight += this.weights.recency;
+      }
+      if (signals.includes("importance")) {
+        signalScores.importance = IMPORTANCE_SCORES[entry.importance] ?? 0.5;
+        totalScore += signalScores.importance * this.weights.importance;
+        totalWeight += this.weights.importance;
+      }
+      if (signals.includes("taskRelevance") && taskEmbedding && entryEmbedding) {
+        signalScores.taskRelevance = Math.max(0, cosineSimilarity(taskEmbedding, entryEmbedding));
+        totalScore += signalScores.taskRelevance * this.weights.taskRelevance;
+        totalWeight += this.weights.taskRelevance;
+      }
+      const normalizedScore = totalWeight > 0 ? totalScore / totalWeight : 0;
+      if (normalizedScore >= threshold) {
+        scored.push({ entry, score: normalizedScore, signalScores });
+      }
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, limit);
+  }
+};
+
+// src/retrieval/conflict.ts
+var NEGATION_PATTERNS = [
+  /\bnot\b/i,
+  /\bnever\b/i,
+  /\bno\b/i,
+  /\bdon't\b/i,
+  /\bdoesn't\b/i,
+  /\bwon't\b/i,
+  /\bcan't\b/i,
+  /\bhate\b/i,
+  /\bdislike\b/i,
+  /\bavoid\b/i,
+  /\bstop\b/i,
+  /\bquit\b/i,
+  /\bremove\b/i,
+  /\bdelete\b/i,
+  /\binstead of\b/i,
+  /\brather than\b/i,
+  /\bno longer\b/i
+];
+var CHANGE_PATTERNS = [
+  /\bnow\b/i,
+  /\bactually\b/i,
+  /\bchanged?\b/i,
+  /\bswitch/i,
+  /\bprefer\b/i,
+  /\bwant\b/i,
+  /\bused to\b/i,
+  /\banymore\b/i
+];
+var ConflictDetector = class {
+  store;
+  embedder;
+  /** Similarity threshold to consider two entries as "same topic" */
+  topicThreshold;
+  constructor(store, embedder, topicThreshold = 0.6) {
+    this.store = store;
+    this.embedder = embedder;
+    this.topicThreshold = topicThreshold;
+  }
+  /**
+   * Check if new content conflicts with any stored memories.
+   * Returns conflicts sorted by confidence (highest first).
+   */
+  async check(content, scope) {
+    const entries = await this.store.getAll(scope);
+    if (entries.length === 0) return [];
+    const contentEmbedding = await this.embedder.embed(content);
+    const conflicts = [];
+    for (const entry of entries) {
+      const entryEmbedding = entry.embedding ?? await this.embedder.embed(entry.content);
+      const similarity = cosineSimilarity(contentEmbedding, entryEmbedding);
+      if (similarity < this.topicThreshold) continue;
+      const contradictionScore = this.scoreContradiction(content, entry.content);
+      if (contradictionScore <= 0) continue;
+      const confidence = Math.min(1, similarity * 0.5 + contradictionScore * 0.5);
+      conflicts.push({
+        incoming: content,
+        stored: entry,
+        confidence,
+        action: this.suggestAction(entry, confidence),
+        reason: this.generateReason(content, entry, contradictionScore)
+      });
+    }
+    conflicts.sort((a, b) => b.confidence - a.confidence);
+    return conflicts;
+  }
+  /**
+   * Score how contradictory two pieces of text are.
+   * Returns 0 (no contradiction) to 1 (strong contradiction).
+   */
+  scoreContradiction(incoming, stored) {
+    let score = 0;
+    const incomingHasNegation = NEGATION_PATTERNS.some((p) => p.test(incoming));
+    const storedHasNegation = NEGATION_PATTERNS.some((p) => p.test(stored));
+    if (incomingHasNegation !== storedHasNegation) {
+      score += 0.5;
+    }
+    const hasChangeLanguage = CHANGE_PATTERNS.some((p) => p.test(incoming));
+    if (hasChangeLanguage) {
+      score += 0.3;
+    }
+    const antonymScore = this.checkAntonyms(incoming, stored);
+    score += antonymScore * 0.4;
+    return Math.min(1, score);
+  }
+  /** Check for common antonym pairs */
+  checkAntonyms(a, b) {
+    const antonyms = [
+      [/\blike\b/i, /\bdislike\b/i],
+      [/\blove\b/i, /\bhate\b/i],
+      [/\byes\b/i, /\bno\b/i],
+      [/\btrue\b/i, /\bfalse\b/i],
+      [/\bvegetarian\b/i, /\bmeat\b/i],
+      [/\bvegan\b/i, /\bmeat\b|\bdairy\b/i],
+      [/\bmorning\b/i, /\bevening\b|\bnight\b/i],
+      [/\blight\b/i, /\bdark\b/i],
+      [/\bhot\b/i, /\bcold\b/i],
+      [/\bfast\b/i, /\bslow\b/i],
+      [/\benable\b/i, /\bdisable\b/i],
+      [/\ballow\b/i, /\bblock\b|\bdeny\b/i],
+      [/\baccept\b/i, /\breject\b/i]
+    ];
+    let matches = 0;
+    for (const [word1, word2] of antonyms) {
+      if (word1.test(a) && word2.test(b) || word2.test(a) && word1.test(b)) {
+        matches++;
+      }
+    }
+    return Math.min(1, matches * 0.5);
+  }
+  suggestAction(stored, confidence) {
+    if (stored.importance === "hard") return "clarify";
+    if (confidence > 0.7 && stored.importance === "soft") return "override";
+    if (stored.importance === "ephemeral") return "override";
+    return "clarify";
+  }
+  generateReason(incoming, stored, contradictionScore) {
+    if (stored.importance === "hard") {
+      return `Conflicts with a hard constraint: "${stored.content}". This memory was marked as non-negotiable - please confirm the change.`;
+    }
+    if (contradictionScore > 0.7) {
+      return `Directly contradicts stored memory: "${stored.content}". The new statement appears to reverse a previous preference.`;
+    }
+    return `Potentially conflicts with: "${stored.content}". The statements may be inconsistent.`;
+  }
+};
+
+// src/core/decay.ts
+var DEFAULT_DECAY_CONFIG = {
+  policies: {
+    constraint: { policy: "none" },
+    preference: { policy: "exponential", halfLife: 30 * 24 * 60 * 60 * 1e3 },
+    // 30 days
+    fact: { policy: "exponential", halfLife: 90 * 24 * 60 * 60 * 1e3 },
+    // 90 days
+    task: { policy: "step", maxAge: 7 * 24 * 60 * 60 * 1e3 },
+    // 7 days then gone
+    episodic: { policy: "exponential", halfLife: 14 * 24 * 60 * 60 * 1e3 }
+    // 14 days
+  },
+  defaultPolicy: "exponential",
+  defaultHalfLife: 30 * 24 * 60 * 60 * 1e3
+};
+var DecayEngine = class {
+  config;
+  constructor(config) {
+    this.config = {
+      ...DEFAULT_DECAY_CONFIG,
+      ...config,
+      policies: { ...DEFAULT_DECAY_CONFIG.policies, ...config?.policies }
+    };
+  }
+  /**
+   * Compute the current effective confidence of a memory entry
+   * after applying temporal decay.
+   * Returns a value between 0 and original confidence.
+   */
+  computeDecayedConfidence(entry) {
+    if (entry.importance === "hard") return entry.confidence;
+    const typeConfig = this.config.policies[entry.type];
+    const policy = typeConfig?.policy ?? this.config.defaultPolicy;
+    const ageMs = Date.now() - new Date(entry.updatedAt).getTime();
+    switch (policy) {
+      case "none":
+        return entry.confidence;
+      case "linear": {
+        const ratePerDay = typeConfig?.ratePerDay ?? 0.01;
+        const ageDays = ageMs / (1e3 * 60 * 60 * 24);
+        return Math.max(0, entry.confidence - ratePerDay * ageDays);
+      }
+      case "exponential": {
+        const halfLife = typeConfig?.halfLife ?? this.config.defaultHalfLife;
+        const decayFactor = Math.exp(-0.693 * ageMs / halfLife);
+        return entry.confidence * decayFactor;
+      }
+      case "step": {
+        const maxAge = typeConfig?.maxAge ?? 7 * 24 * 60 * 60 * 1e3;
+        return ageMs > maxAge ? 0 : entry.confidence;
+      }
+      default:
+        return entry.confidence;
+    }
+  }
+  /**
+   * Filter out memories that have decayed below a threshold.
+   * Useful for periodic cleanup.
+   */
+  filterDecayed(entries, threshold = 0.05) {
+    return entries.filter((e) => this.computeDecayedConfidence(e) >= threshold);
+  }
+  /**
+   * Get entries that should be cleaned up (decayed to near-zero).
+   */
+  getExpired(entries, threshold = 0.01) {
+    return entries.filter((e) => this.computeDecayedConfidence(e) < threshold);
+  }
+};
+
+// src/core/memory.ts
+var AgentMemory = class {
+  backend;
+  embedder;
+  retriever;
+  conflictDetector;
+  decayEngine;
+  checkpoints = /* @__PURE__ */ new Map();
+  defaultScope;
+  maxCheckpoints;
+  constructor(config = {}) {
+    this.backend = config.store === "local" || !config.store ? new LocalStore() : config.store;
+    this.embedder = config.embedder === "builtin" || !config.embedder ? new BuiltinEmbedder() : config.embedder;
+    this.retriever = new MultiSignalRetriever(this.backend, this.embedder);
+    this.conflictDetector = new ConflictDetector(this.backend, this.embedder);
+    this.decayEngine = new DecayEngine(config.decay);
+    this.defaultScope = config.defaultScope ?? "default";
+    this.maxCheckpoints = config.checkpoint?.maxCheckpoints ?? 10;
+  }
+  // ─── Store ───
+  /**
+   * Store a new memory entry.
+   * Automatically generates ID, timestamps, and embedding.
+   */
+  async store(params) {
+    if (!params.content || params.content.trim().length === 0) {
+      throw new Error("Memory content cannot be empty");
+    }
+    if (this.embedder instanceof BuiltinEmbedder) {
+      this.embedder.train([params.content]);
+    }
+    const embedding = await this.embedder.embed(params.content);
+    const entry = {
+      id: generateId(),
+      content: params.content,
+      type: params.type ?? "fact",
+      scope: params.scope ?? this.defaultScope,
+      importance: params.importance ?? "soft",
+      confidence: params.confidence ?? 1,
+      embedding,
+      metadata: params.metadata ?? {},
+      createdAt: now(),
+      updatedAt: now(),
+      version: 1
+    };
+    await this.backend.set(entry);
+    return entry;
+  }
+  /**
+   * Update an existing memory entry.
+   * Increments version and updates timestamp.
+   */
+  async update(id, updates) {
+    const entry = await this.backend.get(id);
+    if (!entry) return null;
+    const updated = {
+      ...entry,
+      ...updates,
+      updatedAt: now(),
+      version: entry.version + 1
+    };
+    if (updates.content && updates.content !== entry.content) {
+      if (updates.content.trim().length === 0) {
+        throw new Error("Memory content cannot be empty");
+      }
+      if (this.embedder instanceof BuiltinEmbedder) {
+        this.embedder.train([updates.content]);
+      }
+      updated.embedding = await this.embedder.embed(updates.content);
+    }
+    await this.backend.set(updated);
+    return updated;
+  }
+  /** Get a memory by ID */
+  async get(id) {
+    return this.backend.get(id);
+  }
+  /** Delete a memory by ID */
+  async delete(id) {
+    return this.backend.delete(id);
+  }
+  /** Get all memories, optionally filtered by scope */
+  async getAll(scope) {
+    return this.backend.getAll(scope);
+  }
+  /** Clear all memories, optionally for a specific scope only */
+  async clear(scope) {
+    return this.backend.clear(scope);
+  }
+  // ─── Retrieve ───
+  /**
+   * Multi-signal retrieval.
+   * Combines similarity, recency, importance, and task-relevance.
+   */
+  async retrieve(query) {
+    return this.retriever.retrieve(query);
+  }
+  // ─── Conflict Detection ───
+  /**
+   * Check if content conflicts with stored memories.
+   * Returns conflicts sorted by confidence.
+   *
+   * @example
+   * ```typescript
+   * const conflicts = await memory.checkConflicts('User likes meat', 'user:123');
+   * if (conflicts.length > 0 && conflicts[0].action === 'clarify') {
+   *   // Ask user to confirm preference change
+   * }
+   * ```
+   */
+  async checkConflicts(content, scope) {
+    return this.conflictDetector.check(content, scope ?? this.defaultScope);
+  }
+  // ─── Decay ───
+  /**
+   * Get the current effective confidence of a memory after decay.
+   */
+  getDecayedConfidence(entry) {
+    return this.decayEngine.computeDecayedConfidence(entry);
+  }
+  /**
+   * Clean up expired memories (decayed below threshold).
+   * Returns the number of deleted entries.
+   */
+  async cleanup(scope, threshold = 0.01) {
+    const entries = await this.backend.getAll(scope);
+    const expired = this.decayEngine.getExpired(entries, threshold);
+    for (const entry of expired) {
+      await this.backend.delete(entry.id);
+    }
+    return expired.length;
+  }
+  // ─── Checkpointing ───
+  /**
+   * Create a checkpoint of current task state.
+   * Use this before context overflow to preserve state.
+   */
+  async checkpoint(params) {
+    const cp = {
+      id: generateId(),
+      taskGraph: params.taskGraph,
+      summary: params.summary,
+      toolOutputs: params.toolOutputs ?? {},
+      activeMemoryIds: params.activeMemoryIds ?? [],
+      createdAt: now()
+    };
+    this.checkpoints.set(cp.id, cp);
+    if (this.checkpoints.size > this.maxCheckpoints) {
+      const oldest = this.checkpoints.keys().next().value;
+      if (oldest) this.checkpoints.delete(oldest);
+    }
+    return cp;
+  }
+  /**
+   * Rehydrate from a checkpoint.
+   * Returns the checkpoint data + relevant memories.
+   */
+  async rehydrate(checkpointId) {
+    const cp = this.checkpoints.get(checkpointId);
+    if (!cp) return null;
+    const memories = [];
+    for (const id of cp.activeMemoryIds) {
+      const entry = await this.backend.get(id);
+      if (entry) memories.push(entry);
+    }
+    return { checkpoint: cp, memories };
+  }
+  /** Get the latest checkpoint */
+  getLatestCheckpoint() {
+    const all = Array.from(this.checkpoints.values());
+    if (all.length === 0) return null;
+    return all[all.length - 1];
+  }
+  /** List all checkpoints */
+  listCheckpoints() {
+    return Array.from(this.checkpoints.values());
+  }
+};
+
+// src/store/file.ts
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { dirname } from "path";
+var FileStore = class {
+  entries = /* @__PURE__ */ new Map();
+  filePath;
+  dirty = false;
+  constructor(filePath) {
+    this.filePath = filePath;
+    this.load();
+  }
+  load() {
+    if (existsSync(this.filePath)) {
+      try {
+        const raw = readFileSync(this.filePath, "utf-8");
+        const data = JSON.parse(raw);
+        for (const entry of data) {
+          this.entries.set(entry.id, entry);
+        }
+      } catch {
+        this.entries.clear();
+      }
+    }
+  }
+  persist() {
+    if (!this.dirty) return;
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    const data = Array.from(this.entries.values());
+    writeFileSync(this.filePath, JSON.stringify(data, null, 2), "utf-8");
+    this.dirty = false;
+  }
+  async get(id) {
+    return this.entries.get(id) ?? null;
+  }
+  async getAll(scope) {
+    const all = Array.from(this.entries.values());
+    if (!scope) return all;
+    return all.filter((e) => e.scope === scope);
+  }
+  async set(entry) {
+    this.entries.set(entry.id, { ...entry });
+    this.dirty = true;
+    this.persist();
+  }
+  async delete(id) {
+    const deleted = this.entries.delete(id);
+    if (deleted) {
+      this.dirty = true;
+      this.persist();
+    }
+    return deleted;
+  }
+  async clear(scope) {
+    if (!scope) {
+      this.entries.clear();
+    } else {
+      for (const [id, entry] of this.entries) {
+        if (entry.scope === scope) {
+          this.entries.delete(id);
+        }
+      }
+    }
+    this.dirty = true;
+    this.persist();
+  }
+  async search(query) {
+    let results = Array.from(this.entries.values());
+    if (query.scope) {
+      results = results.filter((e) => e.scope === query.scope);
+    }
+    if (query.types && query.types.length > 0) {
+      results = results.filter((e) => query.types.includes(e.type));
+    }
+    return results;
+  }
+  get size() {
+    return this.entries.size;
+  }
+};
+export {
+  AgentMemory,
+  BuiltinEmbedder,
+  ConflictDetector,
+  DecayEngine,
+  FileStore,
+  LocalStore,
+  MultiSignalRetriever,
+  cosineSimilarity,
+  generateId
+};