Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

8.4 KB
Raw Blame
import type { IIIClient } from "iii-sdk";
import type { StateKV } from "../state/kv.js";
import { KV, generateId } from "../state/schema.js";
import type { Action, ActionEdge, Crystal, MemoryProvider } from "../types.js";
import { scrubRecord } from "./privacy.js";

interface CrystalDigest {
  narrative: string;
  keyOutcomes: string[];
  filesAffected: string[];
  lessons: string[];
}

const CRYSTALLIZE_SYSTEM = `You are summarizing a completed chain of agent actions into a compact digest.
Extract: (1) what was accomplished in 1-2 sentences, (2) key decisions as bullet points,
(3) files affected, (4) any lessons or patterns worth remembering.
Return as JSON: { "narrative": "...", "keyOutcomes": ["..."], "filesAffected": ["..."], "lessons": ["..."] }`;

export function registerCrystallizeFunction(
  sdk: IIIClient,
  kv: StateKV,
  provider: MemoryProvider,
): void {
  sdk.registerFunction("mem::crystallize", 
    async (data: {
      actionIds: string[];
      sessionId?: string;
      project?: string;
    }) => {
      if (!data.actionIds || data.actionIds.length === 0) {
        return { success: false, error: "actionIds is required" };
      }

      const actions: Action[] = [];
      for (const id of data.actionIds) {
        const action = await kv.get<Action>(KV.actions, id);
        if (!action) {
          return { success: false, error: `action not found: ${id}` };
        }
        if (action.status !== "done" && action.status !== "cancelled") {
          return {
            success: false,
            error: `action ${id} has status "${action.status}", expected "done" or "cancelled"`,
          };
        }
        actions.push(action);
      }

      const allEdges = await kv.list<ActionEdge>(KV.actionEdges);
      const idSet = new Set(data.actionIds);
      const relevantEdges = allEdges.filter(
        (e) => idSet.has(e.sourceActionId) || idSet.has(e.targetActionId),
      );

      const prompt = buildChainText(actions, relevantEdges);

      try {
        const response = await provider.summarize(CRYSTALLIZE_SYSTEM, prompt);
        const digest = scrubRecord(parseDigest(response));

        const crystal: Crystal = scrubRecord({
          id: generateId("crys"),
          narrative: digest.narrative,
          keyOutcomes: digest.keyOutcomes,
          filesAffected: digest.filesAffected,
          lessons: digest.lessons,
          sourceActionIds: data.actionIds,
          sessionId: data.sessionId,
          project: data.project,
          createdAt: new Date().toISOString(),
        });

        await kv.set(KV.crystals, crystal.id, crystal);

        await Promise.all(
          digest.lessons.map((lesson) =>
            sdk
              .trigger({
                function_id: "mem::lesson-save",
                payload: {
                  content: lesson,
                  context: crystal.narrative,
                  confidence: 0.6,
                  project: crystal.project,
                  tags: [],
                  source: "crystal",
                  sourceIds: [crystal.id],
                },
              })
              .catch(() => {}),
          ),
        );

        for (const action of actions) {
          const updated = { ...action, crystallizedInto: crystal.id };
          await kv.set(KV.actions, action.id, updated);
        }

        return { success: true, crystal };
      } catch (err) {
        return {
          success: false,
          error: `crystallization failed: ${String(err)}`,
        };
      }
    },
  );

  sdk.registerFunction("mem::crystal-list", 
    async (data: {
      project?: string;
      sessionId?: string;
      limit?: number;
    }) => {
      const limit = data.limit ?? 20;
      let crystals = await kv.list<Crystal>(KV.crystals);

      if (data.project) {
        crystals = crystals.filter((c) => c.project === data.project);
      }
      if (data.sessionId) {
        crystals = crystals.filter((c) => c.sessionId === data.sessionId);
      }

      crystals.sort(
        (a, b) =>
          new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
      );

      return { success: true, crystals: crystals.slice(0, limit) };
    },
  );

  sdk.registerFunction("mem::crystal-get", 
    async (data: { crystalId: string }) => {
      if (!data.crystalId) {
        return { success: false, error: "crystalId is required" };
      }

      const crystal = await kv.get<Crystal>(KV.crystals, data.crystalId);
      if (!crystal) {
        return { success: false, error: "crystal not found" };
      }

      return { success: true, crystal };
    },
  );

  sdk.registerFunction("mem::auto-crystallize", 
    async (data: {
      olderThanDays?: number;
      project?: string;
      dryRun?: boolean;
    }) => {
      const olderThanDays = data.olderThanDays ?? 7;
      const dryRun = data.dryRun ?? false;
      const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1000;

      let allActions = await kv.list<Action>(KV.actions);

      allActions = allActions.filter(
        (a) =>
          a.status === "done" &&
          !a.crystallizedInto &&
          new Date(a.createdAt).getTime() < cutoff,
      );

      if (data.project) {
        allActions = allActions.filter((a) => a.project === data.project);
      }

      if (allActions.length === 0) {
        return { success: true, groupCount: 0, crystalIds: [] };
      }

      const groups = new Map<string, Action[]>();
      for (const action of allActions) {
        const key = action.parentId ?? action.project ?? "_ungrouped";
        const group = groups.get(key);
        if (group) {
          group.push(action);
        } else {
          groups.set(key, [action]);
        }
      }

      if (dryRun) {
        const groupSummaries = Array.from(groups.entries()).map(
          ([key, actions]) => ({
            groupKey: key,
            actionCount: actions.length,
            actionIds: actions.map((a) => a.id),
          }),
        );
        return {
          success: true,
          dryRun: true,
          groupCount: groups.size,
          groups: groupSummaries,
          crystalIds: [],
        };
      }

      const crystalIds: string[] = [];
      for (const [, groupActions] of groups) {
        const actionIds = groupActions.map((a) => a.id);
        const project = groupActions[0].project;

        try {
          const result = (await sdk.trigger({ function_id: "mem::crystallize", payload: {
            actionIds,
            project,
          } })) as { success: boolean; crystal?: Crystal };

          if (result.success && result.crystal) {
            crystalIds.push(result.crystal.id);
          }
        } catch {
          continue;
        }
      }

      return {
        success: true,
        groupCount: groups.size,
        crystalIds,
      };
    },
  );
}

function buildChainText(actions: Action[], edges: ActionEdge[]): string {
  const lines: string[] = ["## Completed Action Chain\n"];

  const sorted = [...actions].sort(
    (a, b) =>
      new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime(),
  );

  for (const action of sorted) {
    lines.push(`### ${action.title}`);
    if (action.description) lines.push(action.description);
    if (action.result) lines.push(`Result: ${action.result}`);
    lines.push(
      `Tags: ${(action.tags ?? []).join(", ")}`,
    );
    lines.push("");
  }

  if (edges.length > 0) {
    lines.push("## Dependencies");
    for (const edge of edges) {
      lines.push(
        `- ${edge.sourceActionId} --${edge.type}--> ${edge.targetActionId}`,
      );
    }
  }

  return lines.join("\n");
}

function parseDigest(response: string): CrystalDigest {
  try {
    const jsonMatch = response.match(/\{[\s\S]*\}/);
    if (!jsonMatch) {
      return {
        narrative: response,
        keyOutcomes: [],
        filesAffected: [],
        lessons: [],
      };
    }
    const parsed = JSON.parse(jsonMatch[0]) as Record<string, unknown>;
    return {
      narrative:
        typeof parsed.narrative === "string" ? parsed.narrative : response,
      keyOutcomes: Array.isArray(parsed.keyOutcomes)
        ? (parsed.keyOutcomes as string[])
        : [],
      filesAffected: Array.isArray(parsed.filesAffected)
        ? (parsed.filesAffected as string[])
        : [],
      lessons: Array.isArray(parsed.lessons)
        ? (parsed.lessons as string[])
        : [],
    };
  } catch {
    return {
      narrative: response,
      keyOutcomes: [],
      filesAffected: [],
      lessons: [],
    };
  }
}