@agentmemory/agentmemory 0.7.0

package/src/functions/temporal-graph.ts

@@ -0,0 +1,476 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type {
+  GraphNode,
+  GraphEdge,
+  GraphEdgeType,
+  EdgeContext,
+  TemporalState,
+  MemoryProvider,
+} from "../types.js";
+import { KV, generateId } from "../state/schema.js";
+import type { StateKV } from "../state/kv.js";
+
+const TEMPORAL_EXTRACTION_SYSTEM = `You are a temporal knowledge extraction engine. Given observations, extract entities AND their temporal relationships with full context metadata.
+
+For each relationship, you MUST provide:
+1. Semantic relation type
+2. Temporal validity (when this fact became true in the real world)
+3. Context metadata: WHY this relationship exists, what reasoning led to it, what alternatives were considered
+
+Output EXACTLY this XML:
+<temporal_graph>
+  <entities>
+    <entity type="file|function|concept|error|decision|pattern|library|person|project|preference|location|organization|event" name="exact name">
+      <property key="key">value</property>
+      <alias>alternate name</alias>
+    </entity>
+  </entities>
+  <relationships>
+    <relationship type="uses|imports|modifies|causes|fixes|depends_on|related_to|works_at|prefers|blocked_by|caused_by|optimizes_for|rejected|avoids|located_in|succeeded_by"
+      source="entity name" target="entity name" weight="0.1-1.0"
+      valid_from="ISO date or 'unknown'" valid_to="ISO date or 'current'">
+      <reasoning>WHY this relationship exists</reasoning>
+      <sentiment>positive|negative|neutral</sentiment>
+      <alternatives>
+        <alt>alternative that was considered</alt>
+      </alternatives>
+    </relationship>
+  </relationships>
+</temporal_graph>
+
+Rules:
+- NEVER overwrite existing relationships — always create new versioned edges
+- Extract temporal validity from context clues ("since last month", "in 2024", "currently")
+- Capture reasoning/motivation behind each relationship
+- Weight relationships by directness: 1.0 = explicit statement, 0.5 = inferred, 0.1 = speculative`;
+
+function parseTemporalGraphXml(
+  xml: string,
+  observationIds: string[],
+): { nodes: GraphNode[]; edges: GraphEdge[] } {
+  const nodes: GraphNode[] = [];
+  const edges: GraphEdge[] = [];
+  const now = new Date().toISOString();
+
+  const entityRegex =
+    /<entity\s+type="([^"]+)"\s+name="([^"]+)"[^>]*>([\s\S]*?)<\/entity>/g;
+  let match;
+  while ((match = entityRegex.exec(xml)) !== null) {
+    const type = match[1] as GraphNode["type"];
+    const name = match[2];
+    const propsBlock = match[3];
+    const properties: Record<string, string> = {};
+    const aliases: string[] = [];
+
+    const propRegex = /<property\s+key="([^"]+)">([^<]*)<\/property>/g;
+    let propMatch;
+    while ((propMatch = propRegex.exec(propsBlock)) !== null) {
+      properties[propMatch[1]] = propMatch[2];
+    }
+
+    const aliasRegex = /<alias>([^<]+)<\/alias>/g;
+    while ((propMatch = aliasRegex.exec(propsBlock)) !== null) {
+      aliases.push(propMatch[1]);
+    }
+
+    nodes.push({
+      id: generateId("gn"),
+      type,
+      name,
+      properties,
+      sourceObservationIds: observationIds,
+      createdAt: now,
+      aliases: aliases.length > 0 ? aliases : undefined,
+    });
+  }
+
+  const relRegex =
+    /<relationship\s+type="([^"]+)"\s+source="([^"]+)"\s+target="([^"]+)"\s+weight="([^"]+)"(?:\s+valid_from="([^"]*)")?(?:\s+valid_to="([^"]*)")?[^>]*>([\s\S]*?)<\/relationship>/g;
+  while ((match = relRegex.exec(xml)) !== null) {
+    const type = match[1] as GraphEdgeType;
+    const sourceName = match[2];
+    const targetName = match[3];
+    const parsedWeight = parseFloat(match[4]);
+    const weight = Number.isNaN(parsedWeight) ? 0.5 : parsedWeight;
+    const validFrom = match[5] || undefined;
+    const validTo = match[6] || undefined;
+    const metaBlock = match[7] || "";
+
+    const sourceNode = nodes.find(
+      (n) =>
+        n.name === sourceName ||
+        (n.aliases && n.aliases.includes(sourceName)),
+    );
+    const targetNode = nodes.find(
+      (n) =>
+        n.name === targetName ||
+        (n.aliases && n.aliases.includes(targetName)),
+    );
+
+    if (sourceNode && targetNode) {
+      const reasoning =
+        metaBlock.match(/<reasoning>([^<]*)<\/reasoning>/)?.[1] || undefined;
+      const sentiment =
+        metaBlock.match(/<sentiment>([^<]*)<\/sentiment>/)?.[1] || undefined;
+      const alternatives: string[] = [];
+      const altRegex = /<alt>([^<]+)<\/alt>/g;
+      let altMatch;
+      while ((altMatch = altRegex.exec(metaBlock)) !== null) {
+        alternatives.push(altMatch[1]);
+      }
+
+      const context: EdgeContext = {};
+      if (reasoning) context.reasoning = reasoning;
+      if (sentiment) context.sentiment = sentiment;
+      if (alternatives.length > 0) context.alternatives = alternatives;
+      context.confidence = Math.max(0, Math.min(1, weight));
+
+      edges.push({
+        id: generateId("ge"),
+        type,
+        sourceNodeId: sourceNode.id,
+        targetNodeId: targetNode.id,
+        weight: Math.max(0, Math.min(1, weight)),
+        sourceObservationIds: observationIds,
+        createdAt: now,
+        tcommit: now,
+        tvalid:
+          validFrom && validFrom !== "unknown" ? validFrom : undefined,
+        tvalidEnd:
+          validTo && validTo !== "current" ? validTo : undefined,
+        context: Object.keys(context).length > 0 ? context : undefined,
+        version: 1,
+        isLatest: true,
+      });
+    }
+  }
+
+  return { nodes, edges };
+}
+
+export function registerTemporalGraphFunctions(
+  sdk: ISdk,
+  kv: StateKV,
+  provider: MemoryProvider,
+): void {
+  sdk.registerFunction(
+    {
+      id: "mem::temporal-graph-extract",
+      description:
+        "Extract temporal knowledge graph with context metadata from observations",
+    },
+    async (data: {
+      observations: Array<{
+        id: string;
+        title: string;
+        narrative: string;
+        concepts: string[];
+        files: string[];
+        type: string;
+        timestamp: string;
+      }>;
+    }) => {
+      const ctx = getContext();
+      if (!data.observations || data.observations.length === 0) {
+        return { success: false, error: "No observations provided" };
+      }
+
+      const items = data.observations
+        .map(
+          (o, i) =>
+            `[${i + 1}] Type: ${o.type}\nTimestamp: ${o.timestamp}\nTitle: ${o.title}\nNarrative: ${o.narrative}\nConcepts: ${(o.concepts ?? []).join(", ")}\nFiles: ${(o.files ?? []).join(", ")}`,
+        )
+        .join("\n\n");
+
+      try {
+        const response = await provider.compress(
+          TEMPORAL_EXTRACTION_SYSTEM,
+          `Extract temporal knowledge graph from:\n\n${items}`,
+        );
+
+        const obsIds = data.observations.map((o) => o.id);
+        const { nodes, edges } = parseTemporalGraphXml(response, obsIds);
+
+        const existingNodes = await kv.list<GraphNode>(KV.graphNodes);
+        const existingEdges = await kv.list<GraphEdge>(KV.graphEdges);
+
+        const idRemap = new Map<string, string>();
+        for (const node of nodes) {
+          const existing = existingNodes.find(
+            (n) =>
+              n.name === node.name && n.type === node.type,
+          );
+          if (existing) {
+            const oldId = node.id;
+            const merged = {
+              ...existing,
+              sourceObservationIds: [
+                ...new Set([
+                  ...existing.sourceObservationIds,
+                  ...obsIds,
+                ]),
+              ],
+              properties: { ...existing.properties, ...node.properties },
+              updatedAt: new Date().toISOString(),
+              aliases: [
+                ...new Set([
+                  ...(existing.aliases || []),
+                  ...(node.aliases || []),
+                ]),
+              ],
+            };
+            if (merged.aliases.length === 0) delete (merged as any).aliases;
+            await kv.set(KV.graphNodes, existing.id, merged);
+            node.id = existing.id;
+            idRemap.set(oldId, existing.id);
+          } else {
+            await kv.set(KV.graphNodes, node.id, node);
+            existingNodes.push(node);
+          }
+        }
+
+        for (const edge of edges) {
+          if (idRemap.has(edge.sourceNodeId)) {
+            edge.sourceNodeId = idRemap.get(edge.sourceNodeId)!;
+          }
+          if (idRemap.has(edge.targetNodeId)) {
+            edge.targetNodeId = idRemap.get(edge.targetNodeId)!;
+          }
+          const existingKey = `${edge.sourceNodeId}|${edge.targetNodeId}|${edge.type}`;
+          const existingEdge = existingEdges.find(
+            (e) =>
+              `${e.sourceNodeId}|${e.targetNodeId}|${e.type}` ===
+              existingKey,
+          );
+
+          if (existingEdge) {
+            const updatedOld = {
+              ...existingEdge,
+              isLatest: false,
+              tvalidEnd:
+                existingEdge.tvalidEnd || new Date().toISOString(),
+              supersededBy: edge.id,
+            };
+            await kv.set(KV.graphEdges, existingEdge.id, updatedOld);
+
+            await kv.set(KV.graphEdgeHistory, existingEdge.id, updatedOld);
+
+            edge.version = (existingEdge.version || 1) + 1;
+          }
+
+          await kv.set(KV.graphEdges, edge.id, edge);
+          existingEdges.push(edge);
+        }
+
+        ctx.logger.info("Temporal graph extraction complete", {
+          nodes: nodes.length,
+          edges: edges.length,
+        });
+        return {
+          success: true,
+          nodesAdded: nodes.length,
+          edgesAdded: edges.length,
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.logger.error("Temporal graph extraction failed", { error: msg });
+        return { success: false, error: msg };
+      }
+    },
+  );
+
+  sdk.registerFunction(
+    {
+      id: "mem::temporal-query",
+      description:
+        "Query entity state at a specific point in time with full history",
+    },
+    async (data: {
+      entityName: string;
+      asOf?: string;
+      includeHistory?: boolean;
+    }): Promise<TemporalState | { error: string }> => {
+      const allNodes = await kv.list<GraphNode>(KV.graphNodes);
+      const allEdges = await kv.list<GraphEdge>(KV.graphEdges);
+
+      const entity = allNodes.find(
+        (n) =>
+          n.name.toLowerCase() === data.entityName.toLowerCase() ||
+          (n.aliases &&
+            n.aliases.some(
+              (a) =>
+                a.toLowerCase() === data.entityName.toLowerCase(),
+            )),
+      );
+
+      if (!entity) {
+        return { error: `Entity "${data.entityName}" not found` } as any;
+      }
+
+      const relatedEdges = allEdges.filter(
+        (e) => e.sourceNodeId === entity.id || e.targetNodeId === entity.id,
+      );
+
+      const historicalEdges = await kv
+        .list<GraphEdge>(KV.graphEdgeHistory)
+        .catch(() => [] as GraphEdge[]);
+      const entityHistory = historicalEdges.filter(
+        (e) => e.sourceNodeId === entity.id || e.targetNodeId === entity.id,
+      );
+
+      const allEntityEdges = [...relatedEdges, ...entityHistory];
+
+      if (data.asOf) {
+        const asOfTime = new Date(data.asOf).getTime();
+        const validEdges = allEntityEdges.filter((e) => {
+          const commitTime = new Date(
+            e.tcommit || e.createdAt,
+          ).getTime();
+          if (commitTime > asOfTime) return false;
+          if (e.tvalid) {
+            const validTime = new Date(e.tvalid).getTime();
+            if (validTime > asOfTime) return false;
+          }
+          if (e.tvalidEnd) {
+            const endTime = new Date(e.tvalidEnd).getTime();
+            if (endTime < asOfTime) return false;
+          }
+          return true;
+        });
+
+        const currentEdges = getLatestByKey(validEdges);
+        const historical = data.includeHistory ? validEdges : [];
+
+        return {
+          entity,
+          currentEdges,
+          historicalEdges: historical,
+          timeline: buildTimeline(allEntityEdges),
+        };
+      }
+
+      const currentEdges = relatedEdges.filter(
+        (e) => e.isLatest !== false,
+      );
+
+      return {
+        entity,
+        currentEdges,
+        historicalEdges: data.includeHistory ? entityHistory : [],
+        timeline: buildTimeline(allEntityEdges),
+      };
+    },
+  );
+
+  sdk.registerFunction(
+    {
+      id: "mem::differential-state",
+      description:
+        "Compute state changes between two entities over time",
+    },
+    async (data: {
+      entityName: string;
+      from?: string;
+      to?: string;
+    }) => {
+      const allNodes = await kv.list<GraphNode>(KV.graphNodes);
+      const allEdges = await kv.list<GraphEdge>(KV.graphEdges);
+      const historicalEdges = await kv
+        .list<GraphEdge>(KV.graphEdgeHistory)
+        .catch(() => [] as GraphEdge[]);
+
+      const entity = allNodes.find(
+        (n) => n.name.toLowerCase() === data.entityName.toLowerCase(),
+      );
+      if (!entity) return { error: "Entity not found" };
+
+      const allEntityEdges = [
+        ...allEdges.filter(
+          (e) =>
+            e.sourceNodeId === entity.id || e.targetNodeId === entity.id,
+        ),
+        ...historicalEdges.filter(
+          (e) =>
+            e.sourceNodeId === entity.id || e.targetNodeId === entity.id,
+        ),
+      ];
+
+      allEntityEdges.sort(
+        (a, b) =>
+          new Date(a.tcommit || a.createdAt).getTime() -
+          new Date(b.tcommit || b.createdAt).getTime(),
+      );
+
+      const fromTime = data.from
+        ? new Date(data.from).getTime()
+        : 0;
+      const toTime = data.to
+        ? new Date(data.to).getTime()
+        : Date.now();
+
+      const filtered = allEntityEdges.filter((e) => {
+        const t = new Date(e.tcommit || e.createdAt).getTime();
+        return t >= fromTime && t <= toTime;
+      });
+
+      const changes = filtered.map((e) => ({
+        type: e.type,
+        target:
+          e.sourceNodeId === entity.id
+            ? e.targetNodeId
+            : e.sourceNodeId,
+        validFrom: e.tvalid || e.createdAt,
+        validTo: e.tvalidEnd,
+        reasoning: e.context?.reasoning,
+        sentiment: e.context?.sentiment,
+        version: e.version || 1,
+        isLatest: e.isLatest !== false,
+      }));
+
+      return {
+        entity: entity.name,
+        totalChanges: changes.length,
+        changes,
+      };
+    },
+  );
+}
+
+function getLatestByKey(edges: GraphEdge[]): GraphEdge[] {
+  const byKey = new Map<string, GraphEdge>();
+  for (const e of edges) {
+    const key = `${e.sourceNodeId}|${e.targetNodeId}|${e.type}`;
+    const existing = byKey.get(key);
+    if (
+      !existing ||
+      new Date(e.tcommit || e.createdAt).getTime() >
+        new Date(existing.tcommit || existing.createdAt).getTime()
+    ) {
+      byKey.set(key, e);
+    }
+  }
+  return Array.from(byKey.values());
+}
+
+function buildTimeline(
+  edges: GraphEdge[],
+): Array<{
+  edge: GraphEdge;
+  validFrom: string;
+  validTo?: string;
+  context?: EdgeContext;
+}> {
+  const sorted = [...edges].sort(
+    (a, b) =>
+      new Date(a.tcommit || a.createdAt).getTime() -
+      new Date(b.tcommit || b.createdAt).getTime(),
+  );
+
+  return sorted.map((e) => ({
+    edge: e,
+    validFrom: e.tvalid || e.createdAt,
+    validTo: e.tvalidEnd,
+    context: e.context,
+  }));
+}

package/src/functions/timeline.ts

@@ -0,0 +1,138 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type {
+  CompressedObservation,
+  Session,
+  TimelineEntry,
+} from "../types.js";
+import { KV } from "../state/schema.js";
+import { StateKV } from "../state/kv.js";
+
+export function registerTimelineFunction(sdk: ISdk, kv: StateKV): void {
+  sdk.registerFunction(
+    {
+      id: "mem::timeline",
+      description: "Get chronological observations around an anchor point",
+    },
+    async (data: {
+      anchor: string;
+      project?: string;
+      before?: number;
+      after?: number;
+    }) => {
+      const ctx = getContext();
+      const before = Math.max(0, Math.floor(data.before ?? 5));
+      const after = Math.max(0, Math.floor(data.after ?? 5));
+
+      if (!data.anchor || typeof data.anchor !== "string") {
+        return { entries: [], anchor: data.anchor, reason: "invalid_anchor" };
+      }
+
+      let anchorTime: number;
+      const isoPattern = /^\d{4}-\d{2}-\d{2}/;
+      if (isoPattern.test(data.anchor)) {
+        anchorTime = new Date(data.anchor).getTime();
+        if (isNaN(anchorTime)) {
+          return { entries: [], anchor: data.anchor, reason: "invalid_date" };
+        }
+      } else {
+        const searchResults = await findByKeyword(
+          kv,
+          data.anchor,
+          data.project,
+        );
+        if (searchResults.length === 0) {
+          return { entries: [], anchor: data.anchor, reason: "no_match" };
+        }
+        anchorTime = new Date(searchResults[0].timestamp).getTime();
+      }
+
+      const sessions = await kv.list<Session>(KV.sessions);
+      const filtered = data.project
+        ? sessions.filter((s) => s.project === data.project)
+        : sessions;
+
+      const allObs: Array<CompressedObservation & { sid: string }> = [];
+      for (const session of filtered) {
+        const observations = await kv.list<CompressedObservation>(
+          KV.observations(session.id),
+        );
+        for (const obs of observations) {
+          if (obs.title && obs.timestamp) {
+            allObs.push({ ...obs, sid: session.id });
+          }
+        }
+      }
+
+      allObs.sort(
+        (a, b) =>
+          new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime(),
+      );
+
+      let anchorIdx = 0;
+      let minDist = Infinity;
+      for (let i = 0; i < allObs.length; i++) {
+        const dist = Math.abs(
+          new Date(allObs[i].timestamp).getTime() - anchorTime,
+        );
+        if (dist < minDist) {
+          minDist = dist;
+          anchorIdx = i;
+        }
+      }
+
+      const startIdx = Math.max(0, anchorIdx - before);
+      const endIdx = Math.min(allObs.length - 1, anchorIdx + after);
+      const entries: TimelineEntry[] = [];
+
+      for (let i = startIdx; i <= endIdx; i++) {
+        const obs = allObs[i];
+        const { sid, ...observation } = obs;
+        entries.push({
+          observation,
+          sessionId: sid,
+          relativePosition: i - anchorIdx,
+        });
+      }
+
+      ctx.logger.info("Timeline retrieved", {
+        anchor: data.anchor,
+        entries: entries.length,
+      });
+      return { entries, anchorIndex: anchorIdx - startIdx };
+    },
+  );
+}
+
+async function findByKeyword(
+  kv: StateKV,
+  keyword: string,
+  project?: string,
+): Promise<CompressedObservation[]> {
+  const sessions = await kv.list<Session>(KV.sessions);
+  const filtered = project
+    ? sessions.filter((s) => s.project === project)
+    : sessions;
+
+  const lower = keyword.toLowerCase();
+  const matches: CompressedObservation[] = [];
+
+  for (const session of filtered) {
+    const observations = await kv.list<CompressedObservation>(
+      KV.observations(session.id),
+    );
+    for (const obs of observations) {
+      if (
+        obs.title?.toLowerCase().includes(lower) ||
+        obs.narrative?.toLowerCase().includes(lower) ||
+        obs.concepts?.some((c) => c.toLowerCase().includes(lower))
+      ) {
+        matches.push(obs);
+      }
+    }
+  }
+
+  return matches.sort(
+    (a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime(),
+  );
+}