@agentmemory/agentmemory 0.7.0

package/src/functions/cascade.ts

@@ -0,0 +1,80 @@
+import type { ISdk } from "iii-sdk";
+import type { StateKV } from "../state/kv.js";
+import { KV } from "../state/schema.js";
+import type { Memory, GraphNode, GraphEdge } from "../types.js";
+
+export function registerCascadeFunction(sdk: ISdk, kv: StateKV): void {
+  sdk.registerFunction(
+    { id: "mem::cascade-update" },
+    async (data: { supersededMemoryId: string }) => {
+      if (!data.supersededMemoryId || typeof data.supersededMemoryId !== "string") {
+        return { success: false, error: "supersededMemoryId is required" };
+      }
+
+      const superseded = await kv.get<Memory>(KV.memories, data.supersededMemoryId);
+      if (!superseded) {
+        return { success: false, error: "superseded memory not found" };
+      }
+
+      let flaggedNodes = 0;
+      let flaggedEdges = 0;
+      let flaggedMemories = 0;
+
+      const obsIds = new Set(superseded.sourceObservationIds || []);
+
+      if (obsIds.size > 0) {
+        const now = new Date().toISOString();
+        const nodes = await kv.list<GraphNode>(KV.graphNodes);
+        for (const node of nodes) {
+          if (node.stale) continue;
+          const overlap = (node.sourceObservationIds ?? []).some((id) => obsIds.has(id));
+          if (overlap) {
+            node.stale = true;
+            node.updatedAt = now;
+            await kv.set(KV.graphNodes, node.id, node);
+            flaggedNodes++;
+          }
+        }
+
+        const edges = await kv.list<GraphEdge>(KV.graphEdges);
+        for (const edge of edges) {
+          if (edge.stale) continue;
+          const overlap = (edge.sourceObservationIds ?? []).some((id) => obsIds.has(id));
+          if (overlap) {
+            edge.stale = true;
+            await kv.set(KV.graphEdges, edge.id, edge);
+            flaggedEdges++;
+          }
+        }
+      }
+
+      const supersededConcepts = new Set(
+        (superseded.concepts ?? []).map((c) => c.toLowerCase()),
+      );
+      if (supersededConcepts.size >= 2) {
+        const allMemories = await kv.list<Memory>(KV.memories);
+        for (const mem of allMemories) {
+          if (mem.id === data.supersededMemoryId) continue;
+          if (!mem.isLatest) continue;
+
+          const sharedCount = (mem.concepts ?? []).filter((c) =>
+            supersededConcepts.has(c.toLowerCase()),
+          ).length;
+          if (sharedCount >= 2) {
+            flaggedMemories++;
+          }
+        }
+      }
+
+      return {
+        success: true,
+        flagged: {
+          nodes: flaggedNodes,
+          edges: flaggedEdges,
+          siblingMemories: flaggedMemories,
+        },
+        total: flaggedNodes + flaggedEdges + flaggedMemories,
+      };
+    },
+  );
+}

package/src/functions/checkpoints.ts

@@ -0,0 +1,209 @@
+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 { Action, ActionEdge, Checkpoint } from "../types.js";
+
+export function registerCheckpointsFunction(sdk: ISdk, kv: StateKV): void {
+  sdk.registerFunction(
+    { id: "mem::checkpoint-create" },
+    async (data: {
+      name: string;
+      description?: string;
+      type?: Checkpoint["type"];
+      linkedActionIds?: string[];
+      expiresInMs?: number;
+    }) => {
+      if (!data.name) {
+        return { success: false, error: "name is required" };
+      }
+
+      const validTypes: Checkpoint["type"][] = ["ci", "approval", "deploy", "external", "timer"];
+      if (data.type && !validTypes.includes(data.type)) {
+        return { success: false, error: `invalid checkpoint type: ${data.type}. Must be one of: ${validTypes.join(", ")}` };
+      }
+
+      const now = new Date();
+      const checkpoint: Checkpoint = {
+        id: generateId("ckpt"),
+        name: data.name.trim(),
+        description: (data.description || "").trim(),
+        status: "pending",
+        type: data.type || "external",
+        createdAt: now.toISOString(),
+        linkedActionIds: data.linkedActionIds || [],
+        expiresAt: data.expiresInMs
+          ? new Date(now.getTime() + data.expiresInMs).toISOString()
+          : undefined,
+      };
+
+      if (data.linkedActionIds && data.linkedActionIds.length > 0) {
+        for (const actionId of data.linkedActionIds) {
+          const action = await kv.get<Action>(KV.actions, actionId);
+          if (!action) {
+            return { success: false, error: `linked action not found: ${actionId}` };
+          }
+        }
+      }
+
+      await kv.set(KV.checkpoints, checkpoint.id, checkpoint);
+
+      if (data.linkedActionIds && data.linkedActionIds.length > 0) {
+        for (const actionId of data.linkedActionIds) {
+          const edge: ActionEdge = {
+            id: generateId("ae"),
+            type: "gated_by",
+            sourceActionId: actionId,
+            targetActionId: checkpoint.id,
+            createdAt: now.toISOString(),
+          };
+          await kv.set(KV.actionEdges, edge.id, edge);
+
+          const action = await kv.get<Action>(KV.actions, actionId);
+          if (action && action.status === "pending") {
+            action.status = "blocked";
+            action.updatedAt = now.toISOString();
+            await kv.set(KV.actions, action.id, action);
+          }
+        }
+      }
+
+      return { success: true, checkpoint };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::checkpoint-resolve" },
+    async (data: {
+      checkpointId: string;
+      status: "passed" | "failed";
+      resolvedBy?: string;
+      result?: unknown;
+    }) => {
+      if (!data.checkpointId || !data.status) {
+        return {
+          success: false,
+          error: "checkpointId and status are required",
+        };
+      }
+
+      return withKeyedLock(
+        `mem:checkpoint:${data.checkpointId}`,
+        async () => {
+          const checkpoint = await kv.get<Checkpoint>(
+            KV.checkpoints,
+            data.checkpointId,
+          );
+          if (!checkpoint) {
+            return { success: false, error: "checkpoint not found" };
+          }
+          if (checkpoint.status !== "pending") {
+            return {
+              success: false,
+              error: `checkpoint already ${checkpoint.status}`,
+            };
+          }
+
+          checkpoint.status = data.status;
+          checkpoint.resolvedAt = new Date().toISOString();
+          checkpoint.resolvedBy = data.resolvedBy;
+          checkpoint.result = data.result;
+
+          await kv.set(KV.checkpoints, checkpoint.id, checkpoint);
+
+          let unblockedCount = 0;
+          if (data.status === "passed" && checkpoint.linkedActionIds.length > 0) {
+            const allEdges = await kv.list<ActionEdge>(KV.actionEdges);
+            const allCheckpoints = await kv.list<Checkpoint>(KV.checkpoints);
+            const cpMap = new Map(allCheckpoints.map((c) => [c.id, c]));
+
+            for (const actionId of checkpoint.linkedActionIds) {
+              await withKeyedLock(`mem:action:${actionId}`, async () => {
+                const action = await kv.get<Action>(KV.actions, actionId);
+                if (action && action.status === "blocked") {
+                  const gates = allEdges.filter(
+                    (e) => e.sourceActionId === actionId && e.type === "gated_by",
+                  );
+                  const allGatesPassed = gates.every((g) => {
+                    const cp = cpMap.get(g.targetActionId);
+                    return cp && cp.status === "passed";
+                  });
+                  const requires = allEdges.filter(
+                    (e) => e.sourceActionId === actionId && e.type === "requires",
+                  );
+                  const allActions = await kv.list<Action>(KV.actions);
+                  const actionMap = new Map(allActions.map((a) => [a.id, a]));
+                  const allRequiresMet = requires.every((r) => {
+                    const dep = actionMap.get(r.targetActionId);
+                    return dep && dep.status === "done";
+                  });
+                  if (allGatesPassed && allRequiresMet) {
+                    action.status = "pending";
+                    action.updatedAt = new Date().toISOString();
+                    await kv.set(KV.actions, action.id, action);
+                    unblockedCount++;
+                  }
+                }
+              });
+            }
+          }
+
+          return { success: true, checkpoint, unblockedCount };
+        },
+      );
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::checkpoint-list" },
+    async (data: { status?: string; type?: string }) => {
+      let checkpoints = await kv.list<Checkpoint>(KV.checkpoints);
+
+      if (data.status) {
+        checkpoints = checkpoints.filter((c) => c.status === data.status);
+      }
+      if (data.type) {
+        checkpoints = checkpoints.filter((c) => c.type === data.type);
+      }
+
+      checkpoints.sort(
+        (a, b) =>
+          new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
+      );
+
+      return { success: true, checkpoints };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::checkpoint-expire" },
+    async () => {
+      const checkpoints = await kv.list<Checkpoint>(KV.checkpoints);
+      const now = Date.now();
+      let expired = 0;
+
+      for (const cp of checkpoints) {
+        if (
+          cp.status === "pending" &&
+          cp.expiresAt &&
+          new Date(cp.expiresAt).getTime() <= now
+        ) {
+          const didExpire = await withKeyedLock(
+            `mem:checkpoint:${cp.id}`,
+            async () => {
+              const fresh = await kv.get<Checkpoint>(KV.checkpoints, cp.id);
+              if (!fresh || fresh.status !== "pending") return false;
+              fresh.status = "expired";
+              fresh.resolvedAt = new Date().toISOString();
+              await kv.set(KV.checkpoints, fresh.id, fresh);
+              return true;
+            },
+          );
+          if (didExpire) expired++;
+        }
+      }
+
+      return { success: true, expired };
+    },
+  );
+}

package/src/functions/claude-bridge.ts

@@ -0,0 +1,161 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+import type { Memory, ClaudeBridgeConfig } from "../types.js";
+import { KV } from "../state/schema.js";
+import type { StateKV } from "../state/kv.js";
+import { recordAudit } from "./audit.js";
+
+function parseMemoryMd(content: string): {
+  sections: Map<string, string>;
+  raw: string;
+} {
+  const sections = new Map<string, string>();
+  let currentSection = "";
+  let currentContent: string[] = [];
+
+  for (const line of content.split("\n")) {
+    if (line.startsWith("## ")) {
+      if (currentSection) {
+        sections.set(currentSection, currentContent.join("\n").trim());
+      }
+      currentSection = line.slice(3).trim();
+      currentContent = [];
+    } else {
+      currentContent.push(line);
+    }
+  }
+  if (currentSection) {
+    sections.set(currentSection, currentContent.join("\n").trim());
+  }
+
+  return { sections, raw: content };
+}
+
+function serializeToMemoryMd(
+  memories: Memory[],
+  projectSummary: string,
+  lineBudget: number,
+): string {
+  const lines: string[] = [];
+  lines.push("# Agent Memory (auto-synced by agentmemory)");
+  lines.push("");
+
+  if (projectSummary) {
+    lines.push("## Project Summary");
+    lines.push(projectSummary);
+    lines.push("");
+  }
+
+  lines.push("## Key Memories");
+  lines.push("");
+
+  const sorted = [...memories]
+    .filter((m) => m.isLatest)
+    .sort((a, b) => b.strength - a.strength);
+
+  for (const mem of sorted) {
+    if (lines.length >= lineBudget - 2) break;
+    lines.push(`### ${mem.title}`);
+    const contentLines = mem.content.split("\n");
+    for (const cl of contentLines) {
+      if (lines.length >= lineBudget - 1) break;
+      lines.push(cl);
+    }
+    lines.push("");
+  }
+
+  return lines.slice(0, lineBudget).join("\n");
+}
+
+export function registerClaudeBridgeFunction(
+  sdk: ISdk,
+  kv: StateKV,
+  config: ClaudeBridgeConfig,
+): void {
+  sdk.registerFunction(
+    { id: "mem::claude-bridge-read" },
+    async () => {
+      const ctx = getContext();
+      if (!config.enabled || !config.memoryFilePath) {
+        return { success: false, error: "Claude bridge not configured" };
+      }
+
+      try {
+        if (!existsSync(config.memoryFilePath)) {
+          return { success: true, content: "", parsed: false };
+        }
+        const content = readFileSync(config.memoryFilePath, "utf-8");
+        const { sections } = parseMemoryMd(content);
+
+        await kv.set(KV.claudeBridge, "last-read", {
+          timestamp: new Date().toISOString(),
+          sections: Object.fromEntries(sections),
+          lineCount: content.split("\n").length,
+        });
+
+        ctx.logger.info("Claude bridge: read MEMORY.md", {
+          path: config.memoryFilePath,
+          lines: content.split("\n").length,
+        });
+        return { success: true, content, sections: Object.fromEntries(sections) };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.logger.error("Claude bridge read failed", { error: msg });
+        return { success: false, error: msg };
+      }
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::claude-bridge-sync" },
+    async () => {
+      const ctx = getContext();
+      if (!config.enabled || !config.memoryFilePath) {
+        return { success: false, error: "Claude bridge not configured" };
+      }
+
+      try {
+        const memories = await kv.list<Memory>(KV.memories);
+        const latestMemories = memories.filter((m) => m.isLatest);
+
+        let projectSummary = "";
+        if (config.projectPath) {
+          const profile = await kv
+            .get<{ summary?: string }>(KV.profiles, config.projectPath)
+            .catch(() => null);
+          projectSummary = profile?.summary || "";
+        }
+
+        const md = serializeToMemoryMd(
+          latestMemories,
+          projectSummary,
+          config.lineBudget,
+        );
+
+        const dir = dirname(config.memoryFilePath);
+        if (!existsSync(dir)) {
+          mkdirSync(dir, { recursive: true });
+        }
+        writeFileSync(config.memoryFilePath, md, "utf-8");
+
+        await recordAudit(kv, "export", "mem::claude-bridge-sync", [], {
+          path: config.memoryFilePath,
+          memoryCount: latestMemories.length,
+          lines: md.split("\n").length,
+        });
+
+        ctx.logger.info("Claude bridge: synced to MEMORY.md", {
+          path: config.memoryFilePath,
+          memories: latestMemories.length,
+        });
+        return { success: true, path: config.memoryFilePath, lines: md.split("\n").length };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.logger.error("Claude bridge sync failed", { error: msg });
+        return { success: false, error: msg };
+      }
+    },
+  );
+}

package/src/functions/compress.ts

@@ -0,0 +1,194 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type {
+  RawObservation,
+  CompressedObservation,
+  ObservationType,
+  MemoryProvider,
+} from "../types.js";
+import { KV, STREAM } from "../state/schema.js";
+import { StateKV } from "../state/kv.js";
+import {
+  COMPRESSION_SYSTEM,
+  buildCompressionPrompt,
+} from "../prompts/compression.js";
+import { getXmlTag, getXmlChildren } from "../prompts/xml.js";
+import { getSearchIndex } from "./search.js";
+import { CompressOutputSchema } from "../eval/schemas.js";
+import { validateOutput } from "../eval/validator.js";
+import { scoreCompression } from "../eval/quality.js";
+import { compressWithRetry } from "../eval/self-correct.js";
+import type { MetricsStore } from "../eval/metrics-store.js";
+
+const VALID_TYPES = new Set<string>([
+  "file_read",
+  "file_write",
+  "file_edit",
+  "command_run",
+  "search",
+  "web_fetch",
+  "conversation",
+  "error",
+  "decision",
+  "discovery",
+  "subagent",
+  "notification",
+  "task",
+  "other",
+]);
+
+function parseCompressionXml(
+  xml: string,
+): Omit<CompressedObservation, "id" | "sessionId" | "timestamp"> | null {
+  const rawType = getXmlTag(xml, "type");
+  const title = getXmlTag(xml, "title");
+  if (!rawType || !title) return null;
+  const type = VALID_TYPES.has(rawType) ? rawType : "other";
+
+  return {
+    type: type as ObservationType,
+    title,
+    subtitle: getXmlTag(xml, "subtitle") || undefined,
+    facts: getXmlChildren(xml, "facts", "fact"),
+    narrative: getXmlTag(xml, "narrative"),
+    concepts: getXmlChildren(xml, "concepts", "concept"),
+    files: getXmlChildren(xml, "files", "file"),
+    importance: Math.max(
+      1,
+      Math.min(10, parseInt(getXmlTag(xml, "importance") || "5", 10) || 5),
+    ),
+  };
+}
+
+export function registerCompressFunction(
+  sdk: ISdk,
+  kv: StateKV,
+  provider: MemoryProvider,
+  metricsStore?: MetricsStore,
+): void {
+  sdk.registerFunction(
+    {
+      id: "mem::compress",
+      description: "Compress a raw observation using LLM",
+    },
+    async (data: {
+      observationId: string;
+      sessionId: string;
+      raw: RawObservation;
+    }) => {
+      const ctx = getContext();
+      const startMs = Date.now();
+      const prompt = buildCompressionPrompt({
+        hookType: data.raw.hookType,
+        toolName: data.raw.toolName,
+        toolInput: data.raw.toolInput,
+        toolOutput: data.raw.toolOutput,
+        userPrompt: data.raw.userPrompt,
+        timestamp: data.raw.timestamp,
+      });
+
+      try {
+        const validator = (response: string) => {
+          const parsed = parseCompressionXml(response);
+          if (!parsed) return { valid: false, errors: ["xml_parse_failed"] };
+          const result = validateOutput(
+            CompressOutputSchema,
+            parsed,
+            "mem::compress",
+          );
+          return result.valid
+            ? { valid: true }
+            : { valid: false, errors: result.result.errors };
+        };
+
+        const { response, retried } = await compressWithRetry(
+          provider,
+          COMPRESSION_SYSTEM,
+          prompt,
+          validator,
+          1,
+        );
+
+        const parsed = parseCompressionXml(response);
+        if (!parsed) {
+          const latencyMs = Date.now() - startMs;
+          if (metricsStore) {
+            await metricsStore.record("mem::compress", latencyMs, false);
+          }
+          ctx.logger.warn("Failed to parse compression XML", {
+            obsId: data.observationId,
+            retried,
+          });
+          return { success: false, error: "parse_failed" };
+        }
+
+        const qualityScore = scoreCompression(parsed);
+
+        const compressed: CompressedObservation = {
+          id: data.observationId,
+          sessionId: data.sessionId,
+          timestamp: data.raw.timestamp,
+          ...parsed,
+          confidence: qualityScore / 100,
+        };
+
+        await kv.set(
+          KV.observations(data.sessionId),
+          data.observationId,
+          compressed,
+        );
+
+        getSearchIndex().add(compressed);
+
+        sdk.triggerVoid("stream::set", {
+          stream_name: STREAM.name,
+          group_id: STREAM.group(data.sessionId),
+          item_id: data.observationId,
+          data: { type: "compressed", observation: compressed },
+        });
+
+        sdk.triggerVoid("stream::set", {
+          stream_name: STREAM.name,
+          group_id: STREAM.viewerGroup,
+          item_id: data.observationId,
+          data: {
+            type: "compressed",
+            observation: compressed,
+            sessionId: data.sessionId,
+          },
+        });
+
+        const latencyMs = Date.now() - startMs;
+        if (metricsStore) {
+          await metricsStore.record(
+            "mem::compress",
+            latencyMs,
+            true,
+            qualityScore,
+          );
+        }
+
+        ctx.logger.info("Observation compressed", {
+          obsId: data.observationId,
+          type: compressed.type,
+          importance: compressed.importance,
+          qualityScore,
+          retried,
+        });
+
+        return { success: true, compressed, qualityScore };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const latencyMs = Date.now() - startMs;
+        if (metricsStore) {
+          await metricsStore.record("mem::compress", latencyMs, false);
+        }
+        ctx.logger.error("Compression failed", {
+          obsId: data.observationId,
+          error: msg,
+        });
+        return { success: false, error: "compression_failed" };
+      }
+    },
+  );
+}