Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

8.4 KB
Raw Blame
import type { CopilotKitIntelligence } from "@copilotkit/runtime/v2";

/**
 * The slice of the Intelligence client memory needs. Typed from the client OpenBot already uses, so a
 * test can hand in a fake without standing up the platform.
 */
export type IntelligenceMemoryClient = Pick<
  CopilotKitIntelligence,
  | "getRuntimeEntitlements"
  | "listMemories"
  | "createMemory"
  | "updateMemory"
  | "removeMemory"
  | "recallMemories"
>;

/** A memory as Intelligence holds it: the person's own (`scope: "user"`), and live. */
export type IntelligenceMemoryRecord = {
  id: string;
  content: string;
  score?: number;
};

/**
 * Every call names the person and asks for their own memories only.
 *
 * READ-WRITE ON USER, NONE ON PROJECT, ALWAYS. A project-scoped memory is shared by everyone in the
 * Intelligence project, so reading project scope here would hand one person's Bot another person's
 * facts. Results are also filtered to `scope === "user"` after they arrive, so a platform that
 * ignored the grant still could not leak project rows into a person's memory.
 */
const GRANT = { user: "read-write", project: "none" } as const;
const KIND = "topical";

/** How long a known answer about whether memory is available is reused. */
const AVAILABLE_TTL_MS = 10 * 60_000;
/** How long a failure holds memory on the local store before Intelligence is asked again. */
const FAILURE_TTL_MS = 60_000;
/**
 * How long a person's list is reused. Every turn reads it for the memory context, so without this
 * each turn would wait on a platform round trip. Any write of that person's through this client
 * clears it, so OpenBot's own changes show at once; a memory another app adds shows within this.
 */
const LIST_TTL_MS = 30_000;

export type IntelligenceMemory = {
  /** Whether Intelligence memory is entitled and reachable right now. Never throws. */
  available(): Promise<boolean>;
  /** The person's live memories, newest first, at most the platform's list limit (200). */
  list(userId: string): Promise<IntelligenceMemoryRecord[] | undefined>;
  /** Ranked recall over the person's memories. */
  recall(
    userId: string,
    query: string,
    limit: number,
  ): Promise<IntelligenceMemoryRecord[] | undefined>;
  /** Store content; the id may be an existing memory's when Intelligence absorbed a near-duplicate. */
  create(userId: string, content: string): Promise<string | undefined>;
  /** Replace a memory's content. Intelligence retires the old row, so the id changes. */
  supersede(
    userId: string,
    id: string,
    content: string,
  ): Promise<string | undefined | "gone">;
  /** Retire a memory. True when it is gone, whether this call or an earlier one retired it. */
  remove(userId: string, id: string): Promise<boolean>;
};

function statusOf(error: unknown): number | undefined {
  return error && typeof error === "object" && "status" in error
    ? (error as { status?: number }).status
    : undefined;
}

/**
 * Intelligence memory behind one guard: entitled, reachable, or out of the way.
 *
 * Memory is a licensed Intelligence feature, and OpenBot has to work without it. So every call here
 * answers `undefined` instead of throwing when the deployment is not entitled, Intelligence is
 * unreachable, or a call fails; the store then keeps working on its own tables. A `403` (the
 * platform's `MEMORY_NOT_ENTITLED`), a `401` or a network failure holds memory on the local store
 * for a minute before asking again, so a lapsed licence costs one failed call a minute, not one per
 * turn.
 */
export function createIntelligenceMemory(options: {
  client: IntelligenceMemoryClient;
  now?: () => number;
  log?: (message: string) => void;
}): IntelligenceMemory {
  const { client } = options;
  const now = options.now ?? Date.now;
  const log = options.log ?? ((message: string) => console.warn(message));
  let state: { available: boolean; until: number } | undefined;
  let loggedUnavailable = false;
  const lists = new Map<
    string,
    { memories: IntelligenceMemoryRecord[]; until: number }
  >();

  const hold = (reason: string) => {
    state = { available: false, until: now() + FAILURE_TTL_MS };
    if (!loggedUnavailable) {
      loggedUnavailable = true;
      log(
        JSON.stringify({
          type: "intelligence-memory-unavailable",
          reason,
          timestamp: new Date(now()).toISOString(),
        }),
      );
    }
  };

  async function available(): Promise<boolean> {
    if (state && state.until > now()) return state.available;
    try {
      const response = await client.getRuntimeEntitlements();
      const entitled =
        response.status === "ready" &&
        response.entitlement.active &&
        response.entitlement.features.memory === true;
      state = {
        available: entitled,
        until: now() + (entitled ? AVAILABLE_TTL_MS : FAILURE_TTL_MS),
      };
      if (entitled) loggedUnavailable = false;
      else if (!loggedUnavailable) hold("not entitled");
      return entitled;
    } catch (error) {
      hold(error instanceof Error ? error.name : "entitlement read failed");
      return false;
    }
  }

  async function guarded<T>(
    operation: string,
    call: () => Promise<T>,
  ): Promise<T | undefined> {
    if (!(await available())) return undefined;
    try {
      return await call();
    } catch (error) {
      const status = statusOf(error);
      if (status === undefined || status === 401 || status === 403)
        hold(
          `${operation}: ${status ?? (error instanceof Error ? error.name : "failed")}`,
        );
      else
        log(
          JSON.stringify({
            type: "intelligence-memory-error",
            operation,
            status,
            timestamp: new Date(now()).toISOString(),
          }),
        );
      throw error;
    }
  }

  const live = (
    memories: {
      id: string;
      scope: string;
      content: string;
      invalidatedAt: string | null;
      score?: number;
    }[],
  ): IntelligenceMemoryRecord[] =>
    memories
      .filter((memory) => memory.scope === "user" && !memory.invalidatedAt)
      .map((memory) => ({
        id: memory.id,
        content: memory.content,
        ...(memory.score === undefined ? {} : { score: memory.score }),
      }));

  return {
    available,
    async list(userId) {
      const cached = lists.get(userId);
      if (cached && cached.until > now() && (await available()))
        return cached.memories;
      try {
        const response = await guarded("list", () =>
          client.listMemories({ userId, memoryGrant: GRANT }),
        );
        if (!response) return undefined;
        const memories = live(response.memories);
        lists.set(userId, { memories, until: now() + LIST_TTL_MS });
        return memories;
      } catch {
        return undefined;
      }
    },
    async recall(userId, query, limit) {
      try {
        const response = await guarded("recall", () =>
          client.recallMemories({
            userId,
            memoryGrant: GRANT,
            query,
            limit,
            scope: "user",
          }),
        );
        return response ? live(response.memories) : undefined;
      } catch {
        return undefined;
      }
    },
    async create(userId, content) {
      lists.delete(userId);
      try {
        const saved = await guarded("create", () =>
          client.createMemory({
            userId,
            memoryGrant: GRANT,
            content,
            kind: KIND,
            scope: "user",
          }),
        );
        return saved?.id;
      } catch {
        return undefined;
      }
    },
    async supersede(userId, id, content) {
      lists.delete(userId);
      try {
        const saved = await guarded("supersede", () =>
          client.updateMemory({
            userId,
            memoryGrant: GRANT,
            id,
            content,
            kind: KIND,
            scope: "user",
          }),
        );
        return saved?.id;
      } catch (error) {
        // The row it named was already retired, by the person in another app or an earlier attempt.
        return statusOf(error) === 404 ? "gone" : undefined;
      }
    },
    async remove(userId, id) {
      lists.delete(userId);
      try {
        const done = await guarded("remove", async () => {
          await client.removeMemory({ userId, id, memoryGrant: GRANT });
          return true;
        });
        return done === true;
      } catch (error) {
        return statusOf(error) === 404;
      }
    },
  };
}