@agentmemory/agentmemory 0.7.0

package/src/functions/lessons.ts

@@ -0,0 +1,253 @@
+import type { ISdk } from "iii-sdk";
+import type { StateKV } from "../state/kv.js";
+import { KV, fingerprintId } from "../state/schema.js";
+import type { Lesson } from "../types.js";
+import { recordAudit } from "./audit.js";
+
+function reinforceLesson(lesson: Lesson): void {
+  const now = new Date().toISOString();
+  lesson.reinforcements++;
+  lesson.confidence = Math.min(
+    1.0,
+    lesson.confidence + 0.1 * (1 - lesson.confidence),
+  );
+  lesson.lastReinforcedAt = now;
+  lesson.updatedAt = now;
+}
+
+export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void {
+  sdk.registerFunction(
+    { id: "mem::lesson-save" },
+    async (data: {
+      content: string;
+      context?: string;
+      confidence?: number;
+      project?: string;
+      tags?: string[];
+      source?: "crystal" | "manual" | "consolidation";
+      sourceIds?: string[];
+    }) => {
+      if (!data.content?.trim()) {
+        return { success: false, error: "content is required" };
+      }
+
+      const fp = fingerprintId("lsn", data.content.trim().toLowerCase());
+      const existing = await kv.get<Lesson>(KV.lessons, fp);
+
+      if (existing && !existing.deleted) {
+        reinforceLesson(existing);
+        if (data.context && !existing.context) {
+          existing.context = data.context;
+        }
+        await kv.set(KV.lessons, existing.id, existing);
+
+        try {
+          await recordAudit(kv, "lesson_strengthen", "mem::lesson-save", [
+            existing.id,
+          ]);
+        } catch {}
+
+        return {
+          success: true,
+          action: "strengthened",
+          lesson: existing,
+        };
+      }
+
+      const confidence =
+        typeof data.confidence === "number" &&
+        data.confidence >= 0 &&
+        data.confidence <= 1
+          ? data.confidence
+          : 0.5;
+
+      const now = new Date().toISOString();
+      const lesson: Lesson = {
+        id: fp,
+        content: data.content.trim(),
+        context: data.context?.trim() || "",
+        confidence,
+        reinforcements: 0,
+        source: data.source || "manual",
+        sourceIds: data.sourceIds || [],
+        project: data.project,
+        tags: data.tags || [],
+        createdAt: now,
+        updatedAt: now,
+        decayRate: 0.05,
+      };
+
+      await kv.set(KV.lessons, lesson.id, lesson);
+
+      try {
+        await recordAudit(kv, "lesson_save", "mem::lesson-save", [lesson.id]);
+      } catch {}
+
+      return { success: true, action: "created", lesson };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::lesson-recall" },
+    async (data: {
+      query: string;
+      project?: string;
+      minConfidence?: number;
+      limit?: number;
+    }) => {
+      if (!data.query?.trim()) {
+        return { success: false, error: "query is required" };
+      }
+
+      const query = data.query.toLowerCase();
+      const minConfidence = data.minConfidence ?? 0.1;
+      const limit = data.limit ?? 10;
+
+      let lessons = await kv.list<Lesson>(KV.lessons);
+
+      lessons = lessons.filter(
+        (l) => !l.deleted && l.confidence >= minConfidence,
+      );
+
+      if (data.project) {
+        lessons = lessons.filter((l) => l.project === data.project);
+      }
+
+      const scored = lessons
+        .map((l) => {
+          const text = `${l.content} ${l.context} ${l.tags.join(" ")}`.toLowerCase();
+          const terms = query.split(/\s+/).filter((t) => t.length > 1);
+          const matchCount = terms.filter((t) => text.includes(t)).length;
+          if (matchCount === 0) return null;
+
+          const relevance = matchCount / terms.length;
+          const daysSinceReinforced = l.lastReinforcedAt
+            ? (Date.now() - new Date(l.lastReinforcedAt).getTime()) /
+              (1000 * 60 * 60 * 24)
+            : (Date.now() - new Date(l.createdAt).getTime()) /
+              (1000 * 60 * 60 * 24);
+          const recencyBoost = 1 / (1 + daysSinceReinforced * 0.01);
+          const score = l.confidence * relevance * recencyBoost;
+
+          return { lesson: l, score };
+        })
+        .filter(Boolean) as Array<{ lesson: Lesson; score: number }>;
+
+      scored.sort((a, b) => b.score - a.score);
+
+      try {
+        await recordAudit(kv, "lesson_recall", "mem::lesson-recall", [], {
+          query: data.query,
+          resultCount: scored.length,
+        });
+      } catch {}
+
+      return {
+        success: true,
+        lessons: scored.slice(0, limit).map((s) => ({
+          ...s.lesson,
+          score: Math.round(s.score * 1000) / 1000,
+        })),
+      };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::lesson-list" },
+    async (data: {
+      project?: string;
+      source?: string;
+      minConfidence?: number;
+      limit?: number;
+    }) => {
+      const limit = data.limit ?? 50;
+      const minConfidence = data.minConfidence ?? 0;
+      let lessons = await kv.list<Lesson>(KV.lessons);
+
+      lessons = lessons.filter(
+        (l) => !l.deleted && l.confidence >= minConfidence,
+      );
+
+      if (data.project) {
+        lessons = lessons.filter((l) => l.project === data.project);
+      }
+      if (data.source) {
+        lessons = lessons.filter((l) => l.source === data.source);
+      }
+
+      lessons.sort((a, b) => b.confidence - a.confidence);
+
+      return { success: true, lessons: lessons.slice(0, limit) };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::lesson-strengthen" },
+    async (data: { lessonId: string }) => {
+      if (!data.lessonId) {
+        return { success: false, error: "lessonId is required" };
+      }
+
+      const lesson = await kv.get<Lesson>(KV.lessons, data.lessonId);
+      if (!lesson || lesson.deleted) {
+        return { success: false, error: "lesson not found" };
+      }
+
+      reinforceLesson(lesson);
+
+      await kv.set(KV.lessons, lesson.id, lesson);
+
+      try {
+        await recordAudit(kv, "lesson_strengthen", "mem::lesson-strengthen", [
+          lesson.id,
+        ]);
+      } catch {}
+
+      return { success: true, lesson };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::lesson-decay-sweep" },
+    async () => {
+      const lessons = await kv.list<Lesson>(KV.lessons);
+      let decayed = 0;
+      let softDeleted = 0;
+      const now = Date.now();
+      const timestamp = new Date().toISOString();
+      const dirty: Lesson[] = [];
+
+      for (const lesson of lessons) {
+        if (lesson.deleted) continue;
+
+        const baseline = lesson.lastDecayedAt || lesson.lastReinforcedAt || lesson.createdAt;
+        const weeksSinceBaseline =
+          (now - new Date(baseline).getTime()) / (1000 * 60 * 60 * 24 * 7);
+
+        if (weeksSinceBaseline < 1) continue;
+
+        const decay = lesson.decayRate * weeksSinceBaseline;
+        const newConfidence = Math.max(0.05, lesson.confidence - decay);
+
+        if (newConfidence !== lesson.confidence) {
+          lesson.confidence = Math.round(newConfidence * 1000) / 1000;
+          lesson.lastDecayedAt = timestamp;
+          lesson.updatedAt = timestamp;
+
+          if (lesson.confidence <= 0.1 && lesson.reinforcements === 0) {
+            lesson.deleted = true;
+            softDeleted++;
+          } else {
+            decayed++;
+          }
+
+          dirty.push(lesson);
+        }
+      }
+
+      await Promise.all(dirty.map((l) => kv.set(KV.lessons, l.id, l)));
+
+      return { success: true, decayed, softDeleted, total: lessons.length };
+    },
+  );
+}

package/src/functions/mesh.ts

@@ -0,0 +1,434 @@
+import type { ISdk } from "iii-sdk";
+import type { StateKV } from "../state/kv.js";
+import { KV, generateId } from "../state/schema.js";
+import { withKeyedLock } from "../state/keyed-mutex.js";
+import type {
+  MeshPeer,
+  Memory,
+  Action,
+  SemanticMemory,
+  ProceduralMemory,
+  MemoryRelation,
+  GraphNode,
+  GraphEdge,
+} from "../types.js";
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+function isPrivateIP(ip: string): boolean {
+  if (ip === "127.0.0.1" || ip === "::1" || ip === "0.0.0.0") return true;
+  if (ip.startsWith("10.") || ip.startsWith("192.168.")) return true;
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(ip)) return true;
+  if (ip === "169.254.169.254") return true;
+  if (ip.startsWith("fe80:") || ip.startsWith("fc00:") || ip.startsWith("fd")) return true;
+  if (ip.startsWith("::ffff:")) {
+    const v4 = ip.slice(7);
+    return isPrivateIP(v4);
+  }
+  return false;
+}
+
+async function isAllowedUrl(urlStr: string): Promise<boolean> {
+  try {
+    const parsed = new URL(urlStr);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
+    if (parsed.username || parsed.password) return false;
+    const host = parsed.hostname.toLowerCase();
+
+    if (host === "localhost") return false;
+    if (isIP(host) && isPrivateIP(host)) return false;
+
+    if (!isIP(host)) {
+      try {
+        const resolved = await lookup(host, { all: true });
+        if (resolved.some((r) => isPrivateIP(r.address))) return false;
+      } catch {
+        // DNS resolution failed — allow the URL (the actual fetch will fail if unreachable)
+      }
+    }
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const DEFAULT_SHARED_SCOPES = [
+  "memories",
+  "actions",
+  "semantic",
+  "procedural",
+  "relations",
+  "graph:nodes",
+  "graph:edges",
+];
+
+interface MeshSyncPayload {
+  memories?: Memory[];
+  actions?: Action[];
+  semantic?: SemanticMemory[];
+  procedural?: ProceduralMemory[];
+  relations?: MemoryRelation[];
+  graphNodes?: GraphNode[];
+  graphEdges?: GraphEdge[];
+}
+
+async function lwwMergeList<T extends { id: string }>(
+  kv: StateKV,
+  scope: string,
+  items: T[] | undefined,
+  lockPrefix: string,
+  tsField: "updatedAt" | "createdAt",
+): Promise<number> {
+  if (!items || !Array.isArray(items)) return 0;
+  let count = 0;
+  for (const item of items) {
+    if (!item.id || typeof item.id !== "string") continue;
+    const ts = (item as Record<string, unknown>)[tsField];
+    if (typeof ts !== "string" || Number.isNaN(new Date(ts).getTime())) continue;
+    const wrote = await withKeyedLock(`${lockPrefix}:${item.id}`, async () => {
+      const existing = await kv.get<T>(scope, item.id);
+      if (!existing) {
+        await kv.set(scope, item.id, item);
+        return true;
+      }
+      const existingTs = (existing as Record<string, unknown>)[tsField] as string;
+      if (new Date(ts) > new Date(existingTs)) {
+        await kv.set(scope, item.id, item);
+        return true;
+      }
+      return false;
+    });
+    if (wrote) count++;
+  }
+  return count;
+}
+
+function graphNodeTs(node: GraphNode): string {
+  return node.updatedAt || node.createdAt;
+}
+
+async function lwwMergeGraphNodes(
+  kv: StateKV,
+  items: GraphNode[] | undefined,
+): Promise<number> {
+  if (!items || !Array.isArray(items)) return 0;
+  let count = 0;
+  for (const item of items) {
+    if (!item.id || typeof item.id !== "string") continue;
+    const ts = graphNodeTs(item);
+    if (!ts || Number.isNaN(new Date(ts).getTime())) continue;
+    const wrote = await withKeyedLock(`mem:gnode:${item.id}`, async () => {
+      const existing = await kv.get<GraphNode>(KV.graphNodes, item.id);
+      if (!existing) {
+        await kv.set(KV.graphNodes, item.id, item);
+        return true;
+      }
+      if (new Date(ts) > new Date(graphNodeTs(existing))) {
+        await kv.set(KV.graphNodes, item.id, item);
+        return true;
+      }
+      return false;
+    });
+    if (wrote) count++;
+  }
+  return count;
+}
+
+export function registerMeshFunction(sdk: ISdk, kv: StateKV): void {
+  sdk.registerFunction(
+    { id: "mem::mesh-register" },
+    async (data: {
+      url: string;
+      name: string;
+      sharedScopes?: string[];
+      syncFilter?: { project?: string };
+    }) => {
+      if (!data.url || !data.name) {
+        return { success: false, error: "url and name are required" };
+      }
+
+      if (!(await isAllowedUrl(data.url))) {
+        return { success: false, error: "URL blocked: private/local address not allowed" };
+      }
+
+      const existing = await kv.list<MeshPeer>(KV.mesh);
+      const duplicate = existing.find((p) => p.url === data.url);
+      if (duplicate) {
+        return { success: false, error: "peer already registered", peerId: duplicate.id };
+      }
+
+      const peer: MeshPeer = {
+        id: generateId("peer"),
+        url: data.url,
+        name: data.name,
+        status: "disconnected",
+        sharedScopes: data.sharedScopes || DEFAULT_SHARED_SCOPES,
+        syncFilter: data.syncFilter,
+      };
+
+      await kv.set(KV.mesh, peer.id, peer);
+      return { success: true, peer };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::mesh-list" },
+    async () => {
+      const peers = await kv.list<MeshPeer>(KV.mesh);
+      return { success: true, peers };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::mesh-sync" },
+    async (data: { peerId?: string; scopes?: string[]; direction?: "push" | "pull" | "both" }) => {
+      const direction = data.direction || "both";
+      let peers: MeshPeer[];
+
+      if (data.peerId) {
+        const peer = await kv.get<MeshPeer>(KV.mesh, data.peerId);
+        if (!peer) return { success: false, error: "peer not found" };
+        peers = [peer];
+      } else {
+        peers = await kv.list<MeshPeer>(KV.mesh);
+      }
+
+      const results: Array<{
+        peerId: string;
+        peerName: string;
+        pushed: number;
+        pulled: number;
+        errors: string[];
+      }> = [];
+
+      for (const peer of peers) {
+        const result = {
+          peerId: peer.id,
+          peerName: peer.name,
+          pushed: 0,
+          pulled: 0,
+          errors: [] as string[],
+        };
+
+        peer.status = "syncing";
+        await kv.set(KV.mesh, peer.id, peer);
+
+        const scopes = data.scopes || peer.sharedScopes;
+
+        try {
+          if (!(await isAllowedUrl(peer.url))) {
+            result.errors.push("peer URL blocked: private/local address not allowed");
+            peer.status = "error";
+            await kv.set(KV.mesh, peer.id, peer);
+            results.push(result);
+            continue;
+          }
+
+          if (direction === "push" || direction === "both") {
+            const pushData = await collectSyncData(kv, scopes, peer.lastSyncAt, peer.syncFilter);
+            try {
+              const response = await fetch(`${peer.url}/agentmemory/mesh/receive`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(pushData),
+                signal: AbortSignal.timeout(30000),
+                redirect: "error",
+              });
+              if (response.ok) {
+                const body = (await response.json()) as { accepted: number };
+                result.pushed = body.accepted || 0;
+              } else {
+                result.errors.push(`push failed: HTTP ${response.status}`);
+              }
+            } catch (err) {
+              result.errors.push(`push failed: ${String(err)}`);
+            }
+          }
+
+          if (direction === "pull" || direction === "both") {
+            try {
+              const response = await fetch(
+                `${peer.url}/agentmemory/mesh/export?since=${peer.lastSyncAt || ""}`,
+                { signal: AbortSignal.timeout(30000), redirect: "error" },
+              );
+              if (response.ok) {
+                const pullData = (await response.json()) as {
+                  memories?: Memory[];
+                  actions?: Action[];
+                };
+                result.pulled = await applySyncData(kv, pullData, scopes);
+              } else {
+                result.errors.push(`pull failed: HTTP ${response.status}`);
+              }
+            } catch (err) {
+              result.errors.push(`pull failed: ${String(err)}`);
+            }
+          }
+
+          peer.status = result.errors.length > 0 ? "error" : "connected";
+          if (result.errors.length === 0) {
+            peer.lastSyncAt = new Date().toISOString();
+          }
+        } catch (err) {
+          peer.status = "disconnected";
+          result.errors.push(String(err));
+        }
+
+        await kv.set(KV.mesh, peer.id, peer);
+        results.push(result);
+      }
+
+      return { success: true, results };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::mesh-receive" },
+    async (data: MeshSyncPayload) => {
+      let accepted = 0;
+
+      accepted += await lwwMergeList(kv, KV.memories, data.memories, "mem:memory", "updatedAt");
+      accepted += await lwwMergeList(kv, KV.actions, data.actions, "mem:action", "updatedAt");
+      accepted += await lwwMergeList(kv, KV.semantic, data.semantic, "mem:semantic", "updatedAt");
+      accepted += await lwwMergeList(kv, KV.procedural, data.procedural, "mem:procedural", "updatedAt");
+      if (data.relations && Array.isArray(data.relations)) {
+        for (const rel of data.relations) {
+          if (!rel.sourceId || !rel.targetId || !rel.type) continue;
+          const relKey = `${rel.sourceId}:${rel.targetId}:${rel.type}`;
+          await withKeyedLock(`mem:relation:${relKey}`, async () => {
+            const existing = await kv.get<MemoryRelation>(KV.relations, relKey);
+            if (!existing) {
+              await kv.set(KV.relations, relKey, rel);
+              accepted++;
+            }
+          });
+        }
+      }
+      accepted += await lwwMergeGraphNodes(kv, data.graphNodes);
+      accepted += await lwwMergeList(kv, KV.graphEdges, data.graphEdges, "mem:gedge", "createdAt");
+
+      return { success: true, accepted };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::mesh-remove" },
+    async (data: { peerId: string }) => {
+      if (!data.peerId) {
+        return { success: false, error: "peerId is required" };
+      }
+      await kv.delete(KV.mesh, data.peerId);
+      return { success: true };
+    },
+  );
+}
+
+function deltaFilter<T>(
+  items: T[],
+  sinceTime: number,
+  tsField: "updatedAt" | "createdAt",
+): T[] {
+  return items.filter(
+    (item) => new Date((item as Record<string, unknown>)[tsField] as string).getTime() > sinceTime,
+  );
+}
+
+async function collectSyncData(
+  kv: StateKV,
+  scopes: string[],
+  since?: string,
+  syncFilter?: { project?: string },
+): Promise<MeshSyncPayload> {
+  const result: MeshSyncPayload = {};
+  const parsed = since ? new Date(since).getTime() : 0;
+  const sinceTime = Number.isNaN(parsed) ? 0 : parsed;
+
+  if (scopes.includes("memories")) {
+    const all = await kv.list<Memory>(KV.memories);
+    result.memories = deltaFilter(all, sinceTime, "updatedAt");
+  }
+
+  if (scopes.includes("actions")) {
+    let all = await kv.list<Action>(KV.actions);
+    if (syncFilter?.project) {
+      all = all.filter((a) => a.project === syncFilter.project);
+    }
+    result.actions = deltaFilter(all, sinceTime, "updatedAt");
+  }
+
+  const projectScoped = !!syncFilter?.project;
+
+  if (scopes.includes("semantic") && !projectScoped) {
+    const all = await kv.list<SemanticMemory>(KV.semantic);
+    result.semantic = deltaFilter(all, sinceTime, "updatedAt");
+  }
+
+  if (scopes.includes("procedural") && !projectScoped) {
+    const all = await kv.list<ProceduralMemory>(KV.procedural);
+    result.procedural = deltaFilter(all, sinceTime, "updatedAt");
+  }
+
+  if (scopes.includes("relations") && !projectScoped) {
+    const all = await kv.list<MemoryRelation>(KV.relations);
+    result.relations = deltaFilter(all, sinceTime, "createdAt");
+  }
+
+  if (scopes.includes("graph:nodes") && !projectScoped) {
+    const all = await kv.list<GraphNode>(KV.graphNodes);
+    result.graphNodes = all.filter(
+      (n) => new Date(graphNodeTs(n)).getTime() > sinceTime,
+    );
+  }
+
+  if (scopes.includes("graph:edges") && !projectScoped) {
+    const all = await kv.list<GraphEdge>(KV.graphEdges);
+    result.graphEdges = deltaFilter(all, sinceTime, "createdAt");
+  }
+
+  return result;
+}
+
+async function applySyncData(
+  kv: StateKV,
+  data: MeshSyncPayload,
+  scopes: string[],
+): Promise<number> {
+  let applied = 0;
+
+  if (scopes.includes("memories")) {
+    applied += await lwwMergeList(kv, KV.memories, data.memories, "mem:memory", "updatedAt");
+  }
+  if (scopes.includes("actions")) {
+    applied += await lwwMergeList(kv, KV.actions, data.actions, "mem:action", "updatedAt");
+  }
+  if (scopes.includes("semantic")) {
+    applied += await lwwMergeList(kv, KV.semantic, data.semantic, "mem:semantic", "updatedAt");
+  }
+  if (scopes.includes("procedural")) {
+    applied += await lwwMergeList(kv, KV.procedural, data.procedural, "mem:procedural", "updatedAt");
+  }
+  if (scopes.includes("relations") && data.relations) {
+    for (const rel of data.relations) {
+      if (!rel.sourceId || !rel.targetId || !rel.type) continue;
+      const relKey = `${rel.sourceId}:${rel.targetId}:${rel.type}`;
+      const wrote = await withKeyedLock(`mem:relation:${relKey}`, async () => {
+        const existing = await kv.get<MemoryRelation>(KV.relations, relKey);
+        if (!existing) {
+          await kv.set(KV.relations, relKey, rel);
+          return true;
+        }
+        return false;
+      });
+      if (wrote) applied++;
+    }
+  }
+  if (scopes.includes("graph:nodes")) {
+    applied += await lwwMergeGraphNodes(kv, data.graphNodes);
+  }
+  if (scopes.includes("graph:edges")) {
+    applied += await lwwMergeList(kv, KV.graphEdges, data.graphEdges, "mem:gedge", "createdAt");
+  }
+
+  return applied;
+}