@agentmemory/agentmemory 0.7.0

package/src/functions/frontier.ts

@@ -0,0 +1,196 @@
+import type { ISdk } from "iii-sdk";
+import type { StateKV } from "../state/kv.js";
+import { KV } from "../state/schema.js";
+import type { Action, ActionEdge, Checkpoint, Lease } from "../types.js";
+
+export interface FrontierItem {
+  action: Action;
+  score: number;
+  blockers: string[];
+  leased: boolean;
+}
+
+export function registerFrontierFunction(sdk: ISdk, kv: StateKV): void {
+  sdk.registerFunction(
+    { id: "mem::frontier" },
+    async (data: {
+      project?: string;
+      agentId?: string;
+      limit?: number;
+      includeLeasedByOthers?: boolean;
+    }) => {
+      const actions = await kv.list<Action>(KV.actions);
+      const edges = await kv.list<ActionEdge>(KV.actionEdges);
+      const leases = await kv.list<Lease>(KV.leases);
+      const checkpoints = await kv.list<Checkpoint>(KV.checkpoints);
+      const now = Date.now();
+
+      const activeLeaseMap = new Map<string, Lease>();
+      for (const lease of leases) {
+        if (
+          lease.status === "active" &&
+          new Date(lease.expiresAt).getTime() > now
+        ) {
+          activeLeaseMap.set(lease.actionId, lease);
+        }
+      }
+
+      const checkpointMap = new Map<string, Checkpoint>();
+      for (const cp of checkpoints) {
+        checkpointMap.set(cp.id, cp);
+      }
+
+      const actionMap = new Map<string, Action>();
+      for (const a of actions) actionMap.set(a.id, a);
+
+      const frontier: FrontierItem[] = [];
+
+      for (const action of actions) {
+        if (action.status === "done" || action.status === "cancelled") continue;
+        if (data.project && action.project !== data.project) continue;
+
+        const blockers: string[] = [];
+        const inEdges = edges.filter(
+          (e) => e.sourceActionId === action.id && e.type === "requires",
+        );
+
+        for (const edge of inEdges) {
+          const dep = actionMap.get(edge.targetActionId);
+          if (dep && dep.status !== "done") {
+            blockers.push(`requires:${dep.id}:${dep.title}`);
+          }
+        }
+
+        const gateEdges = edges.filter(
+          (e) => e.sourceActionId === action.id && e.type === "gated_by",
+        );
+        for (const edge of gateEdges) {
+          const cp = checkpointMap.get(edge.targetActionId);
+          if (cp && cp.status !== "passed") {
+            blockers.push(`checkpoint:${cp.id}:${cp.name}`);
+          }
+        }
+
+        const conflictEdges = edges.filter(
+          (e) =>
+            (e.sourceActionId === action.id ||
+              e.targetActionId === action.id) &&
+            e.type === "conflicts_with",
+        );
+        for (const edge of conflictEdges) {
+          const otherId =
+            edge.sourceActionId === action.id
+              ? edge.targetActionId
+              : edge.sourceActionId;
+          const other = actionMap.get(otherId);
+          if (other && other.status === "active") {
+            blockers.push(`conflict:${other.id}:${other.title}`);
+          }
+        }
+
+        if (blockers.length > 0) continue;
+
+        const lease = activeLeaseMap.get(action.id);
+        const leasedByOther =
+          lease && data.agentId && lease.agentId !== data.agentId;
+        if (leasedByOther && !data.includeLeasedByOthers) continue;
+
+        const score = computeScore(action, edges, now);
+
+        frontier.push({
+          action,
+          score,
+          blockers: [],
+          leased: !!lease,
+        });
+      }
+
+      frontier.sort((a, b) => b.score - a.score);
+      const limit = data.limit || 20;
+
+      return {
+        success: true,
+        frontier: frontier.slice(0, limit),
+        totalActions: actions.length,
+        totalUnblocked: frontier.length,
+      };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::next" },
+    async (data: { project?: string; agentId?: string }) => {
+      const result = await sdk.trigger<
+        { project?: string; agentId?: string; limit?: number },
+        {
+          success: boolean;
+          frontier: FrontierItem[];
+          totalActions: number;
+          totalUnblocked: number;
+        }
+      >("mem::frontier", {
+        project: data.project,
+        agentId: data.agentId,
+        limit: 1,
+      });
+
+      if (!result.success) {
+        return {
+          success: false,
+          suggestion: null,
+          message: "Failed to compute frontier",
+          totalActions: 0,
+        };
+      }
+      if (result.frontier.length === 0) {
+        return {
+          success: true,
+          suggestion: null,
+          message: "No actionable work found",
+          totalActions: result.totalActions || 0,
+        };
+      }
+
+      const top = result.frontier[0];
+      return {
+        success: true,
+        suggestion: {
+          actionId: top.action.id,
+          title: top.action.title,
+          description: top.action.description,
+          priority: top.action.priority,
+          score: top.score,
+          tags: top.action.tags,
+        },
+        message: `Suggested: ${top.action.title} (priority ${top.action.priority}, score ${top.score.toFixed(2)})`,
+        totalActions: result.totalActions,
+        totalUnblocked: result.totalUnblocked,
+      };
+    },
+  );
+}
+
+function computeScore(
+  action: Action,
+  edges: ActionEdge[],
+  now: number,
+): number {
+  let score = action.priority * 10;
+
+  const ageHours =
+    (now - new Date(action.createdAt).getTime()) / (1000 * 60 * 60);
+  score += Math.min(ageHours * 0.5, 20);
+
+  const unlockCount = edges.filter(
+    (e) => e.sourceActionId === action.id && e.type === "unlocks",
+  ).length;
+  score += unlockCount * 5;
+
+  if (edges.some((e) => e.sourceActionId === action.id && e.type === "spawned_by")) {
+    score += 3;
+  }
+
+  if (action.status === "active") score += 15;
+
+  return Math.round(score * 100) / 100;
+}

package/src/functions/governance.ts

@@ -0,0 +1,131 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type { Memory, GovernanceFilter, AuditEntry } from "../types.js";
+import { KV } from "../state/schema.js";
+import type { StateKV } from "../state/kv.js";
+import { recordAudit, queryAudit } from "./audit.js";
+
+export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void {
+  sdk.registerFunction(
+    { id: "mem::governance-delete" },
+    async (data: { memoryIds: string[]; reason?: string }) => {
+      const ctx = getContext();
+      if (
+        !data.memoryIds ||
+        !Array.isArray(data.memoryIds) ||
+        data.memoryIds.length === 0
+      ) {
+        return { success: false, error: "memoryIds array is required" };
+      }
+
+      let deleted = 0;
+      for (const id of data.memoryIds) {
+        const mem = await kv.get<Memory>(KV.memories, id);
+        if (mem) {
+          await kv.delete(KV.memories, id);
+          deleted++;
+        }
+      }
+
+      await recordAudit(
+        kv,
+        "delete",
+        "mem::governance-delete",
+        data.memoryIds,
+        {
+          reason: data.reason || "manual deletion",
+          deleted,
+        },
+      );
+
+      ctx.logger.info("Governance delete", {
+        requested: data.memoryIds.length,
+        deleted,
+      });
+      return { success: true, deleted, total: data.memoryIds.length };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::governance-bulk" },
+    async (data: GovernanceFilter & { dryRun?: boolean }) => {
+      const ctx = getContext();
+
+      const hasFilter =
+        (data.type && data.type.length > 0) ||
+        data.dateFrom ||
+        data.dateTo ||
+        data.qualityBelow !== undefined;
+      if (!hasFilter && !data.dryRun) {
+        return {
+          success: false,
+          error: "At least one filter is required for non-dryRun bulk delete",
+        };
+      }
+
+      const memories = await kv.list<Memory>(KV.memories);
+      let candidates = memories;
+
+      if (data.type && data.type.length > 0) {
+        candidates = candidates.filter((m) => data.type!.includes(m.type));
+      }
+      if (data.dateFrom) {
+        const from = new Date(data.dateFrom).getTime();
+        if (Number.isNaN(from)) {
+          return { success: false, error: "Invalid dateFrom format" };
+        }
+        candidates = candidates.filter(
+          (m) => new Date(m.createdAt).getTime() >= from,
+        );
+      }
+      if (data.dateTo) {
+        const to = new Date(data.dateTo).getTime();
+        if (Number.isNaN(to)) {
+          return { success: false, error: "Invalid dateTo format" };
+        }
+        candidates = candidates.filter(
+          (m) => new Date(m.createdAt).getTime() <= to,
+        );
+      }
+      if (data.qualityBelow !== undefined) {
+        candidates = candidates.filter((m) => m.strength < data.qualityBelow!);
+      }
+
+      if (data.dryRun) {
+        return {
+          success: true,
+          dryRun: true,
+          wouldDelete: candidates.length,
+          ids: candidates.map((m) => m.id),
+        };
+      }
+
+      for (const mem of candidates) {
+        await kv.delete(KV.memories, mem.id);
+      }
+
+      await recordAudit(
+        kv,
+        "delete",
+        "mem::governance-bulk",
+        candidates.map((m) => m.id),
+        { filter: data, deleted: candidates.length },
+      );
+
+      ctx.logger.info("Governance bulk delete", { deleted: candidates.length });
+      return { success: true, deleted: candidates.length };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::audit-query" },
+    async (data?: {
+      operation?: AuditEntry["operation"];
+      dateFrom?: string;
+      dateTo?: string;
+      limit?: number;
+    }) => {
+      return queryAudit(kv, data);
+    },
+  );
+}

package/src/functions/graph-retrieval.ts

@@ -0,0 +1,277 @@
+import type {
+  GraphNode,
+  GraphEdge,
+} from "../types.js";
+import { KV } from "../state/schema.js";
+import type { StateKV } from "../state/kv.js";
+
+export interface GraphRetrievalResult {
+  obsId: string;
+  sessionId: string;
+  score: number;
+  graphContext: string;
+  pathLength: number;
+}
+
+function buildGraphContext(
+  path: Array<{ node: GraphNode; edge?: GraphEdge }>,
+): string {
+  const parts: string[] = [];
+  for (const step of path) {
+    const props = Object.entries(step.node.properties)
+      .slice(0, 3)
+      .map(([k, v]) => `${k}=${v}`)
+      .join(", ");
+    let line = `[${step.node.type}] ${step.node.name}`;
+    if (props) line += ` (${props})`;
+    if (step.edge) {
+      line += ` --${step.edge.type}-->`;
+      if (step.edge.context?.reasoning) {
+        line += ` [${step.edge.context.reasoning}]`;
+      }
+      if (step.edge.tvalid) {
+        line += ` @${step.edge.tvalid}`;
+      }
+    }
+    parts.push(line);
+  }
+  return parts.join(" ");
+}
+
+export class GraphRetrieval {
+  constructor(private kv: StateKV) {}
+
+  async searchByEntities(
+    entityNames: string[],
+    maxDepth = 2,
+    maxResults = 20,
+  ): Promise<GraphRetrievalResult[]> {
+    const allNodes = (await this.kv.list<GraphNode>(KV.graphNodes)).filter((n) => !n.stale);
+    const allEdges = (await this.kv.list<GraphEdge>(KV.graphEdges)).filter((e) => !e.stale);
+
+    const matchingNodes = allNodes.filter((n) => {
+      const nameLower = n.name.toLowerCase();
+      return entityNames.some(
+        (e) =>
+          nameLower.includes(e.toLowerCase()) ||
+          e.toLowerCase().includes(nameLower),
+      );
+    });
+
+    if (matchingNodes.length === 0) return [];
+
+    const results: GraphRetrievalResult[] = [];
+    const visitedObs = new Set<string>();
+
+    for (const startNode of matchingNodes) {
+      const paths = this.bfsTraversal(
+        startNode,
+        allNodes,
+        allEdges,
+        maxDepth,
+      );
+
+      for (const path of paths) {
+        const lastNode = path[path.length - 1].node;
+        for (const obsId of lastNode.sourceObservationIds) {
+          if (visitedObs.has(obsId)) continue;
+          visitedObs.add(obsId);
+
+          const pathLength = path.length;
+          const edgeWeights = path
+            .filter((s) => s.edge)
+            .map((s) => s.edge!.weight);
+          const avgWeight =
+            edgeWeights.length > 0
+              ? edgeWeights.reduce((a, b) => a + b, 0) / edgeWeights.length
+              : 0.5;
+          const score = avgWeight * (1 / pathLength);
+
+          results.push({
+            obsId,
+            sessionId: "",
+            score,
+            graphContext: buildGraphContext(path),
+            pathLength,
+          });
+        }
+      }
+
+      for (const obsId of startNode.sourceObservationIds) {
+        if (visitedObs.has(obsId)) continue;
+        visitedObs.add(obsId);
+        results.push({
+          obsId,
+          sessionId: "",
+          score: 1.0,
+          graphContext: `[${startNode.type}] ${startNode.name}`,
+          pathLength: 0,
+        });
+      }
+    }
+
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, maxResults);
+  }
+
+  async expandFromChunks(
+    obsIds: string[],
+    maxDepth = 1,
+    maxResults = 10,
+  ): Promise<GraphRetrievalResult[]> {
+    const allNodes = (await this.kv.list<GraphNode>(KV.graphNodes)).filter((n) => !n.stale);
+    const allEdges = (await this.kv.list<GraphEdge>(KV.graphEdges)).filter((e) => !e.stale);
+
+    const linkedNodes = allNodes.filter((n) =>
+      n.sourceObservationIds.some((id) => obsIds.includes(id)),
+    );
+
+    const results: GraphRetrievalResult[] = [];
+    const visitedObs = new Set<string>(obsIds);
+
+    for (const node of linkedNodes) {
+      const paths = this.bfsTraversal(node, allNodes, allEdges, maxDepth);
+      for (const path of paths) {
+        const lastNode = path[path.length - 1].node;
+        for (const obsId of lastNode.sourceObservationIds) {
+          if (visitedObs.has(obsId)) continue;
+          visitedObs.add(obsId);
+
+          const pathLength = path.length;
+          const score = 0.5 * (1 / (pathLength + 1));
+
+          results.push({
+            obsId,
+            sessionId: "",
+            score,
+            graphContext: buildGraphContext(path),
+            pathLength,
+          });
+        }
+      }
+    }
+
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, maxResults);
+  }
+
+  async temporalQuery(
+    entityName: string,
+    asOf?: string,
+  ): Promise<{
+    entity: GraphNode | null;
+    currentState: GraphEdge[];
+    history: GraphEdge[];
+  }> {
+    const allNodes = (await this.kv.list<GraphNode>(KV.graphNodes)).filter((n) => !n.stale);
+    const allEdges = (await this.kv.list<GraphEdge>(KV.graphEdges)).filter((e) => !e.stale);
+
+    const entity = allNodes.find(
+      (n) => n.name.toLowerCase() === entityName.toLowerCase(),
+    );
+    if (!entity) return { entity: null, currentState: [], history: [] };
+
+    const relatedEdges = allEdges.filter(
+      (e) => e.sourceNodeId === entity.id || e.targetNodeId === entity.id,
+    );
+
+    if (!asOf) {
+      const latestEdges = this.getLatestEdges(relatedEdges);
+      const historicalEdges = relatedEdges.filter(
+        (e) => !latestEdges.some((le) => le.id === e.id),
+      );
+      return { entity, currentState: latestEdges, history: historicalEdges };
+    }
+
+    const asOfDate = new Date(asOf).getTime();
+    const validEdges = relatedEdges.filter((e) => {
+      const commitDate = new Date(e.tcommit || e.createdAt).getTime();
+      if (commitDate > asOfDate) return false;
+      if (e.tvalid) {
+        const validDate = new Date(e.tvalid).getTime();
+        if (validDate > asOfDate) return false;
+      }
+      if (e.tvalidEnd) {
+        const endDate = new Date(e.tvalidEnd).getTime();
+        if (endDate < asOfDate) return false;
+      }
+      return true;
+    });
+
+    return {
+      entity,
+      currentState: this.getLatestEdges(validEdges),
+      history: validEdges,
+    };
+  }
+
+  private getLatestEdges(edges: GraphEdge[]): GraphEdge[] {
+    const byKey = new Map<string, GraphEdge[]>();
+    for (const e of edges) {
+      const key = `${e.sourceNodeId}|${e.targetNodeId}|${e.type}`;
+      if (!byKey.has(key)) byKey.set(key, []);
+      byKey.get(key)!.push(e);
+    }
+
+    const latest: GraphEdge[] = [];
+    for (const group of byKey.values()) {
+      if (group.length === 0) continue;
+      group.sort(
+        (a, b) =>
+          new Date(b.tcommit || b.createdAt).getTime() -
+          new Date(a.tcommit || a.createdAt).getTime(),
+      );
+      const newest = group.find((e) => e.isLatest !== false) || group[0];
+      latest.push(newest);
+    }
+    return latest;
+  }
+
+  private bfsTraversal(
+    startNode: GraphNode,
+    allNodes: GraphNode[],
+    allEdges: GraphEdge[],
+    maxDepth: number,
+  ): Array<Array<{ node: GraphNode; edge?: GraphEdge }>> {
+    const paths: Array<Array<{ node: GraphNode; edge?: GraphEdge }>> = [];
+    const visited = new Set<string>();
+    const queue: Array<{
+      nodeId: string;
+      depth: number;
+      path: Array<{ node: GraphNode; edge?: GraphEdge }>;
+    }> = [{ nodeId: startNode.id, depth: 0, path: [{ node: startNode }] }];
+
+    visited.add(startNode.id);
+
+    while (queue.length > 0) {
+      const { nodeId, depth, path } = queue.shift()!;
+      paths.push(path);
+
+      if (depth >= maxDepth) continue;
+
+      const neighborEdges = allEdges.filter(
+        (e) => e.sourceNodeId === nodeId || e.targetNodeId === nodeId,
+      );
+
+      for (const edge of neighborEdges) {
+        const nextId =
+          edge.sourceNodeId === nodeId
+            ? edge.targetNodeId
+            : edge.sourceNodeId;
+        if (visited.has(nextId)) continue;
+        visited.add(nextId);
+
+        const nextNode = allNodes.find((n) => n.id === nextId);
+        if (!nextNode) continue;
+
+        queue.push({
+          nodeId: nextId,
+          depth: depth + 1,
+          path: [...path, { node: nextNode, edge }],
+        });
+      }
+    }
+
+    return paths;
+  }
+}