@agentmemory/agentmemory 0.7.0

package/src/functions/relations.ts

@@ -0,0 +1,237 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type { Memory, MemoryRelation } from "../types.js";
+import { KV, generateId } from "../state/schema.js";
+import { StateKV } from "../state/kv.js";
+import { withKeyedLock } from "../state/keyed-mutex.js";
+
+function computeConfidence(
+  source: Memory,
+  target: Memory,
+  relationType: MemoryRelation["type"],
+): number {
+  let score = 0.5;
+
+  const sharedSessions = source.sessionIds.filter((sid) =>
+    target.sessionIds.includes(sid),
+  );
+  score += Math.min(sharedSessions.length * 0.1, 0.3);
+
+  const now = Date.now();
+  const sourceAge = now - new Date(source.updatedAt).getTime();
+  const targetAge = now - new Date(target.updatedAt).getTime();
+  const sevenDays = 7 * 24 * 60 * 60 * 1000;
+  const ninetyDays = 90 * 24 * 60 * 60 * 1000;
+  if (sourceAge < sevenDays && targetAge < sevenDays) {
+    score += 0.1;
+  } else if (sourceAge > ninetyDays && targetAge > ninetyDays) {
+    score -= 0.1;
+  }
+
+  if (relationType === "supersedes") score += 0.1;
+  if (relationType === "contradicts") score -= 0.05;
+
+  return Math.max(0, Math.min(1, score));
+}
+
+export function registerRelationsFunction(sdk: ISdk, kv: StateKV): void {
+  sdk.registerFunction(
+    {
+      id: "mem::relate",
+      description: "Create a relationship between memories",
+    },
+    async (data: {
+      sourceId: string;
+      targetId: string;
+      type: MemoryRelation["type"];
+      confidence?: number;
+    }) => {
+      const ctx = getContext();
+      const [firstId, secondId] = [data.sourceId, data.targetId].sort();
+
+      return withKeyedLock(`mem:${firstId}`, () =>
+        withKeyedLock(`mem:${secondId}`, async () => {
+          const source = await kv.get<Memory>(KV.memories, data.sourceId);
+          const target = await kv.get<Memory>(KV.memories, data.targetId);
+          if (!source || !target) {
+            return {
+              success: false,
+              error: "source or target memory not found",
+            };
+          }
+
+          const confidence =
+            data.confidence !== undefined
+              ? Math.max(0, Math.min(1, data.confidence))
+              : computeConfidence(source, target, data.type);
+
+          const relation: MemoryRelation = {
+            type: data.type,
+            sourceId: data.sourceId,
+            targetId: data.targetId,
+            createdAt: new Date().toISOString(),
+            confidence,
+          };
+
+          const relationId = generateId("rel");
+          await kv.set(KV.relations, relationId, relation);
+
+          if (!source.relatedIds) source.relatedIds = [];
+          if (!source.relatedIds.includes(data.targetId)) {
+            source.relatedIds.push(data.targetId);
+            await kv.set(KV.memories, data.sourceId, source);
+          }
+
+          if (!target.relatedIds) target.relatedIds = [];
+          if (!target.relatedIds.includes(data.sourceId)) {
+            target.relatedIds.push(data.sourceId);
+            await kv.set(KV.memories, data.targetId, target);
+          }
+
+          ctx.logger.info("Memory relation created", {
+            relationId,
+            type: data.type,
+            source: data.sourceId,
+            target: data.targetId,
+          });
+          return { success: true, relationId, relation };
+        }),
+      );
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::evolve", description: "Create a new version of a memory" },
+    async (data: {
+      memoryId: string;
+      newContent: string;
+      newTitle?: string;
+    }) => {
+      const ctx = getContext();
+
+      const existing = await kv.get<Memory>(KV.memories, data.memoryId);
+      if (!existing) {
+        return { success: false, error: "memory not found" };
+      }
+
+      const now = new Date().toISOString();
+      const evolved: Memory = {
+        ...existing,
+        id: generateId("mem"),
+        createdAt: now,
+        updatedAt: now,
+        title: data.newTitle || existing.title,
+        content: data.newContent,
+        version: (existing.version || 1) + 1,
+        parentId: existing.id,
+        supersedes: [existing.id, ...(existing.supersedes || [])],
+        isLatest: true,
+      };
+
+      existing.isLatest = false;
+      await kv.set(KV.memories, existing.id, existing);
+
+      await kv.set(KV.memories, evolved.id, evolved);
+
+      const relation: MemoryRelation = {
+        type: "supersedes",
+        sourceId: evolved.id,
+        targetId: existing.id,
+        createdAt: now,
+        confidence: 1.0,
+      };
+      await kv.set(KV.relations, generateId("rel"), relation);
+
+      ctx.logger.info("Memory evolved", {
+        oldId: existing.id,
+        newId: evolved.id,
+        version: evolved.version,
+      });
+      return { success: true, memory: evolved, previousId: existing.id };
+    },
+  );
+
+  sdk.registerFunction(
+    {
+      id: "mem::get-related",
+      description: "Get related memories within N hops",
+    },
+    async (data: {
+      memoryId: string;
+      maxHops?: number;
+      minConfidence?: number;
+    }) => {
+      const ctx = getContext();
+      const maxHops = Math.min(data.maxHops ?? 2, 5);
+      const MAX_VISITED = 500;
+      const rawMinConf = Number(data.minConfidence);
+      const minConfidence = Number.isFinite(rawMinConf)
+        ? Math.max(0, Math.min(1, rawMinConf))
+        : 0;
+
+      const allRelations = await kv
+        .list<MemoryRelation>(KV.relations)
+        .catch(() => []);
+
+      const visited = new Set<string>();
+      const result: Array<{
+        memory: Memory;
+        hop: number;
+        confidence: number;
+      }> = [];
+      const queue: Array<{ id: string; hop: number }> = [
+        { id: data.memoryId, hop: 0 },
+      ];
+
+      while (queue.length > 0 && visited.size < MAX_VISITED) {
+        const current = queue.shift()!;
+        if (visited.has(current.id) || current.hop > maxHops) continue;
+        visited.add(current.id);
+
+        const memory = await kv.get<Memory>(KV.memories, current.id);
+        if (!memory) continue;
+
+        if (current.hop > 0) {
+          const matchingRelations = allRelations.filter(
+            (r) =>
+              (r.sourceId === current.id && visited.has(r.targetId)) ||
+              (r.targetId === current.id && visited.has(r.sourceId)),
+          );
+          const confidence =
+            matchingRelations.length > 0
+              ? Math.max(...matchingRelations.map((r) => r.confidence ?? 0.5))
+              : 0.5;
+          if (confidence >= minConfidence) {
+            result.push({ memory, hop: current.hop, confidence });
+          }
+        }
+
+        const relatedIds = memory.relatedIds || [];
+        const supersedes = memory.supersedes || [];
+        const parentId = memory.parentId ? [memory.parentId] : [];
+
+        const kvLinked = allRelations
+          .filter((r) => r.sourceId === current.id || r.targetId === current.id)
+          .map((r) => (r.sourceId === current.id ? r.targetId : r.sourceId));
+
+        const allLinks = [
+          ...new Set([...relatedIds, ...supersedes, ...parentId, ...kvLinked]),
+        ];
+
+        for (const nextId of allLinks) {
+          if (!visited.has(nextId)) {
+            queue.push({ id: nextId, hop: current.hop + 1 });
+          }
+        }
+      }
+
+      result.sort((a, b) => b.confidence - a.confidence);
+
+      ctx.logger.info("Related memories retrieved", {
+        memoryId: data.memoryId,
+        found: result.length,
+      });
+      return { results: result };
+    },
+  );
+}

package/src/functions/remember.ts

@@ -0,0 +1,162 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type { Memory } from "../types.js";
+import { KV, generateId, jaccardSimilarity } from "../state/schema.js";
+import { StateKV } from "../state/kv.js";
+import { withKeyedLock } from "../state/keyed-mutex.js";
+
+export function registerRememberFunction(sdk: ISdk, kv: StateKV): void {
+  sdk.registerFunction(
+    { id: "mem::remember" },
+    async (data: {
+      content: string;
+      type?: string;
+      concepts?: string[];
+      files?: string[];
+      ttlDays?: number;
+      sourceObservationIds?: string[];
+    }) => {
+      const ctx = getContext();
+      if (
+        !data.content ||
+        typeof data.content !== "string" ||
+        !data.content.trim()
+      ) {
+        return { success: false, error: "content is required" };
+      }
+      if (data.files && !Array.isArray(data.files)) {
+        return { success: false, error: "files must be an array" };
+      }
+      if (data.concepts && !Array.isArray(data.concepts)) {
+        return { success: false, error: "concepts must be an array" };
+      }
+      if (data.sourceObservationIds && !Array.isArray(data.sourceObservationIds)) {
+        return { success: false, error: "sourceObservationIds must be an array" };
+      }
+      const validTypes = new Set([
+        "pattern",
+        "preference",
+        "architecture",
+        "bug",
+        "workflow",
+        "fact",
+      ]);
+      const memType = validTypes.has(data.type || "")
+        ? (data.type as Memory["type"])
+        : "fact";
+
+      const now = new Date().toISOString();
+
+      return withKeyedLock("mem:remember", async () => {
+        const existingMemories = await kv.list<Memory>(KV.memories);
+        let supersededId: string | undefined;
+        let supersededVersion = 1;
+        let supersededMemory: Memory | undefined;
+        const lowerContent = data.content.toLowerCase();
+        for (const existing of existingMemories) {
+          if (existing.isLatest === false) continue;
+          const similarity = jaccardSimilarity(
+            lowerContent,
+            existing.content.toLowerCase(),
+          );
+          if (similarity > 0.7) {
+            supersededId = existing.id;
+            supersededVersion = existing.version ?? 1;
+            supersededMemory = existing;
+            break;
+          }
+        }
+
+        const memory: Memory = {
+          id: generateId("mem"),
+          createdAt: now,
+          updatedAt: now,
+          type: memType,
+          title: data.content.slice(0, 80),
+          content: data.content,
+          concepts: data.concepts || [],
+          files: data.files || [],
+          sessionIds: [],
+          strength: 7,
+          version: supersededId ? supersededVersion + 1 : 1,
+          parentId: supersededId,
+          supersedes: supersededId ? [supersededId] : [],
+          sourceObservationIds: (data.sourceObservationIds || []).filter(
+            (id): id is string => typeof id === "string" && id.length > 0,
+          ),
+          isLatest: true,
+        };
+
+        if (data.ttlDays && typeof data.ttlDays === "number" && data.ttlDays > 0) {
+          memory.forgetAfter = new Date(Date.now() + data.ttlDays * 86400000).toISOString();
+        }
+
+        if (supersededMemory) {
+          supersededMemory.isLatest = false;
+          await kv.set(KV.memories, supersededMemory.id, supersededMemory);
+        }
+        await kv.set(KV.memories, memory.id, memory);
+
+        if (supersededId) {
+          sdk.triggerVoid("mem::cascade-update", {
+            supersededMemoryId: supersededId,
+          });
+        }
+
+        ctx.logger.info("Memory saved", {
+          memId: memory.id,
+          type: memory.type,
+        });
+        return { success: true, memory };
+      });
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::forget" },
+    async (data: {
+      sessionId?: string;
+      observationIds?: string[];
+      memoryId?: string;
+    }) => {
+      const ctx = getContext();
+      let deleted = 0;
+
+      if (data.memoryId) {
+        await kv.delete(KV.memories, data.memoryId);
+        deleted++;
+      }
+
+      if (
+        data.sessionId &&
+        data.observationIds &&
+        data.observationIds.length > 0
+      ) {
+        for (const obsId of data.observationIds) {
+          await kv.delete(KV.observations(data.sessionId), obsId);
+          deleted++;
+        }
+      }
+
+      if (
+        data.sessionId &&
+        (!data.observationIds || data.observationIds.length === 0) &&
+        !data.memoryId
+      ) {
+        const observations = await kv.list<{ id: string }>(
+          KV.observations(data.sessionId),
+        );
+        for (const obs of observations) {
+          await kv.delete(KV.observations(data.sessionId), obs.id);
+          deleted++;
+        }
+        await kv.delete(KV.sessions, data.sessionId);
+        await kv.delete(KV.summaries, data.sessionId);
+        deleted += 2;
+      }
+
+      ctx.logger.info("Memory forgotten", { deleted });
+      return { success: true, deleted };
+    },
+  );
+}

package/src/functions/retention.ts

@@ -0,0 +1,235 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type {
+  Memory,
+  SemanticMemory,
+  RetentionScore,
+  DecayConfig,
+} from "../types.js";
+import { KV } from "../state/schema.js";
+import type { StateKV } from "../state/kv.js";
+
+const DEFAULT_DECAY: DecayConfig = {
+  lambda: 0.01,
+  sigma: 0.3,
+  tierThresholds: {
+    hot: 0.7,
+    warm: 0.4,
+    cold: 0.15,
+  },
+};
+
+function computeRetention(
+  salience: number,
+  createdAt: string,
+  accessTimestamps: number[],
+  config: DecayConfig,
+): number {
+  const now = Date.now();
+  const deltaT = (now - new Date(createdAt).getTime()) / (1000 * 60 * 60 * 24);
+
+  const temporalDecay = Math.exp(-config.lambda * deltaT);
+
+  let reinforcementBoost = 0;
+  for (const tAccess of accessTimestamps) {
+    const daysSinceAccess =
+      (now - tAccess) / (1000 * 60 * 60 * 24);
+    if (daysSinceAccess > 0) {
+      reinforcementBoost += 1 / daysSinceAccess;
+    }
+  }
+  reinforcementBoost *= config.sigma;
+
+  return Math.min(1, salience * temporalDecay + reinforcementBoost);
+}
+
+function computeSalience(
+  memory: Memory | SemanticMemory,
+  accessCount: number,
+): number {
+  let baseSalience = 0.5;
+
+  if ("type" in memory) {
+    const typeWeights: Record<string, number> = {
+      architecture: 0.9,
+      bug: 0.7,
+      pattern: 0.8,
+      preference: 0.85,
+      workflow: 0.6,
+      fact: 0.5,
+    };
+    baseSalience = typeWeights[(memory as Memory).type] || 0.5;
+  }
+
+  if ("confidence" in memory) {
+    baseSalience = Math.max(baseSalience, (memory as SemanticMemory).confidence);
+  }
+
+  const accessBonus = Math.min(0.2, accessCount * 0.02);
+  return Math.min(1, baseSalience + accessBonus);
+}
+
+export function registerRetentionFunctions(
+  sdk: ISdk,
+  kv: StateKV,
+): void {
+  sdk.registerFunction(
+    {
+      id: "mem::retention-score",
+      description:
+        "Compute retention scores for all memories using time-frequency decay",
+    },
+    async (data: { config?: Partial<DecayConfig> }) => {
+      const ctx = getContext();
+      const config = { ...DEFAULT_DECAY, ...data.config };
+
+      const memories = await kv.list<Memory>(KV.memories);
+      const semanticMems = await kv.list<SemanticMemory>(KV.semantic);
+
+      const scores: RetentionScore[] = [];
+
+      for (const mem of memories) {
+        if (!mem.isLatest) continue;
+        const salience = computeSalience(mem, 0);
+        const score = computeRetention(
+          salience,
+          mem.createdAt,
+          [],
+          config,
+        );
+
+        const entry: RetentionScore = {
+          memoryId: mem.id,
+          score,
+          salience,
+          temporalDecay: Math.exp(
+            -config.lambda *
+              ((Date.now() - new Date(mem.createdAt).getTime()) /
+                (1000 * 60 * 60 * 24)),
+          ),
+          reinforcementBoost: 0,
+          lastAccessed: mem.updatedAt,
+          accessCount: 0,
+        };
+
+        scores.push(entry);
+        await kv.set(KV.retentionScores, mem.id, entry);
+      }
+
+      for (const sem of semanticMems) {
+        const accessTimestamps = sem.lastAccessedAt
+          ? [new Date(sem.lastAccessedAt).getTime()]
+          : [];
+        const salience = computeSalience(sem, sem.accessCount);
+        const score = computeRetention(
+          salience,
+          sem.createdAt,
+          accessTimestamps,
+          config,
+        );
+
+        const entry: RetentionScore = {
+          memoryId: sem.id,
+          score,
+          salience,
+          temporalDecay: Math.exp(
+            -config.lambda *
+              ((Date.now() - new Date(sem.createdAt).getTime()) /
+                (1000 * 60 * 60 * 24)),
+          ),
+          reinforcementBoost:
+            score - salience * Math.exp(
+              -config.lambda *
+                ((Date.now() - new Date(sem.createdAt).getTime()) /
+                  (1000 * 60 * 60 * 24)),
+            ),
+          lastAccessed: sem.lastAccessedAt,
+          accessCount: sem.accessCount,
+        };
+
+        scores.push(entry);
+        await kv.set(KV.retentionScores, sem.id, entry);
+      }
+
+      scores.sort((a, b) => b.score - a.score);
+
+      const tiers = {
+        hot: scores.filter((s) => s.score >= config.tierThresholds.hot)
+          .length,
+        warm: scores.filter(
+          (s) =>
+            s.score >= config.tierThresholds.warm &&
+            s.score < config.tierThresholds.hot,
+        ).length,
+        cold: scores.filter(
+          (s) =>
+            s.score >= config.tierThresholds.cold &&
+            s.score < config.tierThresholds.warm,
+        ).length,
+        evictable: scores.filter(
+          (s) => s.score < config.tierThresholds.cold,
+        ).length,
+      };
+
+      ctx.logger.info("Retention scores computed", {
+        total: scores.length,
+        ...tiers,
+      });
+
+      return { success: true, total: scores.length, tiers, scores };
+    },
+  );
+
+  sdk.registerFunction(
+    {
+      id: "mem::retention-evict",
+      description:
+        "Evict memories below retention threshold (tiered storage)",
+    },
+    async (data: {
+      threshold?: number;
+      dryRun?: boolean;
+      maxEvict?: number;
+    }) => {
+      const ctx = getContext();
+      const threshold = data.threshold ?? DEFAULT_DECAY.tierThresholds.cold;
+      const maxEvict = data.maxEvict ?? 50;
+
+      const allScores = await kv.list<RetentionScore>(KV.retentionScores);
+      const candidates = allScores
+        .filter((s) => s.score < threshold)
+        .sort((a, b) => a.score - b.score)
+        .slice(0, maxEvict);
+
+      if (data.dryRun) {
+        return {
+          success: true,
+          dryRun: true,
+          wouldEvict: candidates.length,
+          candidates: candidates.map((c) => ({
+            id: c.memoryId,
+            score: c.score,
+          })),
+        };
+      }
+
+      let evicted = 0;
+      for (const candidate of candidates) {
+        try {
+          await kv.delete(KV.memories, candidate.memoryId);
+          await kv.delete(KV.retentionScores, candidate.memoryId);
+          evicted++;
+        } catch {
+          continue;
+        }
+      }
+
+      ctx.logger.info("Retention-based eviction complete", {
+        evicted,
+        threshold,
+      });
+
+      return { success: true, evicted };
+    },
+  );
+}