Skip to content

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

8.2 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 { Facet } from "../types.js";
import { logger } from "../logger.js";

export async function deleteFacetsForTargets(
  kv: StateKV,
  targetIds: Iterable<string>,
): Promise<void> {
  const ids = new Set(targetIds);
  ids.delete("");
  if (ids.size === 0) return;
  try {
    const live = new Set<string>();
    await Promise.all(
      [...ids].map(async (id) => {
        for (let attempt = 0; attempt < 2; attempt++) {
          try {
            const [mem, sem] = await Promise.all([
              kv.get(KV.memories, id),
              kv.get(KV.semantic, id),
            ]);
            if (mem || sem) live.add(id);
            return;
          } catch {
            if (attempt === 1) {
              live.add(id);
              logger.warn("Facet cleanup skipped unverifiable target", {
                targetId: id,
              });
            }
          }
        }
      }),
    );
    const all = await kv.list<Facet>(KV.facets);
    const matches = all.filter(
      (f) =>
        ids.has(f.targetId) &&
        !live.has(f.targetId) &&
        f.targetType === "memory",
    );
    await Promise.all(matches.map((f) => kv.delete(KV.facets, f.id)));
  } catch (err) {
    logger.warn("Facet cleanup failed", {
      targetIds: ids.size,
      error: err instanceof Error ? err.message : String(err),
    });
  }
}

export function registerFacetsFunction(sdk: IIIClient, kv: StateKV): void {
  sdk.registerFunction("mem::facet-tag", 
    async (data: {
      targetId: string;
      targetType: string;
      dimension: string;
      value: string;
    }) => {
      if (!data.targetId || typeof data.targetId !== "string") {
        return { success: false, error: "targetId is required" };
      }

      const validTypes = ["action", "memory", "observation"];
      if (!validTypes.includes(data.targetType)) {
        return {
          success: false,
          error: `targetType must be one of: ${validTypes.join(", ")}`,
        };
      }

      if (
        !data.dimension ||
        typeof data.dimension !== "string" ||
        data.dimension.trim() === ""
      ) {
        return { success: false, error: "dimension is required" };
      }

      if (
        !data.value ||
        typeof data.value !== "string" ||
        data.value.trim() === ""
      ) {
        return { success: false, error: "value is required" };
      }

      const dimension = data.dimension.trim();
      const value = data.value.trim();

      const existing = await kv.list<Facet>(KV.facets);
      const duplicate = existing.find(
        (f) =>
          f.targetId === data.targetId &&
          f.dimension === dimension &&
          f.value === value,
      );
      if (duplicate) {
        return { success: true, facet: duplicate, skipped: true };
      }

      const facet: Facet = {
        id: generateId("fct"),
        targetId: data.targetId,
        targetType: data.targetType as Facet["targetType"],
        dimension,
        value,
        createdAt: new Date().toISOString(),
      };

      await kv.set(KV.facets, facet.id, facet);
      return { success: true, facet };
    },
  );

  sdk.registerFunction("mem::facet-untag", 
    async (data: {
      targetId: string;
      dimension: string;
      value?: string;
    }) => {
      if (!data.targetId) {
        return { success: false, error: "targetId is required" };
      }
      if (!data.dimension) {
        return { success: false, error: "dimension is required" };
      }

      const all = await kv.list<Facet>(KV.facets);
      const matches = all.filter((f) => {
        if (f.targetId !== data.targetId || f.dimension !== data.dimension) {
          return false;
        }
        if (data.value !== undefined) {
          return f.value === data.value;
        }
        return true;
      });

      for (const f of matches) {
        await kv.delete(KV.facets, f.id);
      }

      return { success: true, removed: matches.length };
    },
  );

  sdk.registerFunction("mem::facet-query", 
    async (data: {
      matchAll?: string[];
      matchAny?: string[];
      targetType?: string;
      limit?: number;
    }) => {
      if (
        (!data.matchAll || data.matchAll.length === 0) &&
        (!data.matchAny || data.matchAny.length === 0)
      ) {
        return {
          success: false,
          error: "at least one of matchAll or matchAny is required",
        };
      }

      const all = await kv.list<Facet>(KV.facets);
      const filtered = data.targetType
        ? all.filter((f) => f.targetType === data.targetType)
        : all;

      const targetFacetMap = new Map<string, { targetType: string; facetKeys: Set<string> }>();
      for (const f of filtered) {
        const key = `${f.dimension}:${f.value}`;
        let entry = targetFacetMap.get(f.targetId);
        if (!entry) {
          entry = { targetType: f.targetType, facetKeys: new Set() };
          targetFacetMap.set(f.targetId, entry);
        }
        entry.facetKeys.add(key);
      }

      const results: Array<{ targetId: string; targetType: string; matchedFacets: string[] }> = [];

      for (const [targetId, entry] of targetFacetMap) {
        const matched: string[] = [];

        if (data.matchAll && data.matchAll.length > 0) {
          const allPresent = data.matchAll.every((k) => entry.facetKeys.has(k));
          if (!allPresent) continue;
          for (const k of data.matchAll) {
            if (!matched.includes(k)) matched.push(k);
          }
        }

        if (data.matchAny && data.matchAny.length > 0) {
          const anyPresent = data.matchAny.filter((k) => entry.facetKeys.has(k));
          if (anyPresent.length === 0) continue;
          for (const k of anyPresent) {
            if (!matched.includes(k)) matched.push(k);
          }
        }

        results.push({
          targetId,
          targetType: entry.targetType,
          matchedFacets: matched,
        });
      }

      const limit = data.limit || 50;
      return { success: true, results: results.slice(0, limit) };
    },
  );

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

      const all = await kv.list<Facet>(KV.facets);
      const targetFacets = all.filter((f) => f.targetId === data.targetId);

      const dimMap = new Map<string, string[]>();
      for (const f of targetFacets) {
        let values = dimMap.get(f.dimension);
        if (!values) {
          values = [];
          dimMap.set(f.dimension, values);
        }
        values.push(f.value);
      }

      const dimensions = Array.from(dimMap.entries()).map(([dimension, values]) => ({
        dimension,
        values,
      }));

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

  sdk.registerFunction("mem::facet-stats", 
    async (data: { targetType?: string }) => {
      const all = await kv.list<Facet>(KV.facets);
      const filtered = data.targetType
        ? all.filter((f) => f.targetType === data.targetType)
        : all;

      const dimMap = new Map<string, Map<string, number>>();
      for (const f of filtered) {
        let valueMap = dimMap.get(f.dimension);
        if (!valueMap) {
          valueMap = new Map();
          dimMap.set(f.dimension, valueMap);
        }
        valueMap.set(f.value, (valueMap.get(f.value) || 0) + 1);
      }

      const dimensions = Array.from(dimMap.entries()).map(([dimension, valueMap]) => ({
        dimension,
        values: Array.from(valueMap.entries()).map(([value, count]) => ({
          value,
          count,
        })),
      }));

      return { success: true, dimensions, totalFacets: filtered.length };
    },
  );

  sdk.registerFunction("mem::facet-dimensions", 
    async () => {
      const all = await kv.list<Facet>(KV.facets);

      const counts = new Map<string, number>();
      for (const f of all) {
        counts.set(f.dimension, (counts.get(f.dimension) || 0) + 1);
      }

      const dimensions = Array.from(counts.entries()).map(([dimension, count]) => ({
        dimension,
        count,
      }));

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