Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

9.0 KB
Raw Blame
import * as Match from "effect/Match";
import * as NodeCrypto from "node:crypto";

import {
  AkeruMarkdownMemoryArchiveV3,
  type AkeruConversationMemorySnapshot,
  type AkeruMarkdownMemoryArchiveV3 as AkeruMarkdownMemoryArchiveV3Value,
  type AkeruMarkdownMemoryImportApplyResult,
  type AkeruMarkdownMemoryImportPreview,
  type AkeruMemoryDocumentTarget,
  type ThreadId,
} from "@akeru/contracts";
import * as Schema from "effect/Schema";

import { BotMemoryError, type BotMemoryAccess, type BotMemoryStore } from "./BotMemory.ts";
import { encodeMemoryArchiveJson } from "./MemoryArchiveJson.ts";

const checksum = (value: string) => NodeCrypto.createHash("sha256").update(value).digest("hex");

const decodeArchive = Schema.decodeUnknownSync(AkeruMarkdownMemoryArchiveV3);

const documentPath = (access: BotMemoryAccess, target: AkeruMemoryDocumentTarget): string =>
  Match.value(target).pipe(
    Match.when("user", () => `bots/${access.botId}/USER.md`),
    Match.when("memory", () => `bots/${access.botId}/MEMORY.md`),
    Match.orElse(() => `bots/${access.botId}/groups/${access.groupId}/GROUP.md`),
  );

const manifestValue = (archive: Omit<AkeruMarkdownMemoryArchiveV3Value, "manifestSha256">) =>
  encodeMemoryArchiveJson({
    schemaVersion: archive.schemaVersion,
    anchorThreadId: archive.anchorThreadId,
    botId: archive.botId,
    groupId: archive.groupId,
    createdAt: archive.createdAt,
    documents: archive.documents.map(({ botId, groupId, target, path, sha256 }) => ({
      botId,
      groupId,
      target,
      path,
      sha256,
    })),
    conversation: { sha256: archive.conversation.sha256 },
  });

export async function exportBotMemoryArchive(input: {
  readonly store: BotMemoryStore;
  readonly access: BotMemoryAccess;
  readonly threadId: ThreadId;
  readonly conversation: AkeruConversationMemorySnapshot;
  readonly createdAt: string;
}): Promise<AkeruMarkdownMemoryArchiveV3Value> {
  const snapshot = await input.store.readSnapshot(input.access);

  const documents = [
    snapshot.user,
    snapshot.memory,
    ...(snapshot.group ? [snapshot.group] : []),
  ].map((document) => ({
    botId: input.access.botId,
    groupId: document.target === "group" ? input.access.groupId : null,
    target: document.target,
    path: documentPath(input.access, document.target),
    content: document.content,
    sha256: checksum(document.content),
  }));

  const conversation = {
    snapshot: input.conversation,
    sha256: checksum(encodeMemoryArchiveJson(input.conversation)),
  };

  const withoutManifest = {
    schemaVersion: 3 as const,
    anchorThreadId: input.threadId,
    botId: input.access.botId,
    groupId: input.access.groupId,
    createdAt: input.createdAt,
    documents,
    conversation,
  };

  return decodeArchive({
    ...withoutManifest,
    manifestSha256: checksum(manifestValue(withoutManifest)),
  });
}

async function prepareImport(input: {
  readonly store: BotMemoryStore;
  readonly access: BotMemoryAccess;
  readonly threadId: ThreadId;
  readonly archive: AkeruMarkdownMemoryArchiveV3Value;
  readonly currentConversation: AkeruConversationMemorySnapshot;
  /** When false, the archive may restore every file except a changed MEMORY.md. */
  readonly privateBotMemory?: boolean;
}) {
  const { archive, access } = input;

  if (archive.anchorThreadId !== input.threadId) {
    throw BotMemoryError.fromCode(
      "access-denied",
      "Restore this memory archive in its original chat.",
    );
  }

  if (String(archive.botId) !== String(access.botId)) {
    throw BotMemoryError.fromCode("access-denied", "The archive belongs to a different bot.");
  }

  if (String(archive.groupId) !== String(access.groupId)) {
    throw BotMemoryError.fromCode(
      "access-denied",
      "The archive group does not match the active conversation group.",
    );
  }

  if (
    checksum(encodeMemoryArchiveJson(archive.conversation.snapshot)) !== archive.conversation.sha256
  ) {
    throw BotMemoryError.fromCode("io-error", "The observational-memory checksum is invalid.");
  }

  if (checksum(manifestValue(archive)) !== archive.manifestSha256) {
    throw BotMemoryError.fromCode("io-error", "The memory archive manifest checksum is invalid.");
  }

  const expectedTargets = new Set<AkeruMemoryDocumentTarget>([
    "user",
    "memory",
    ...(access.groupId === null ? [] : (["group"] as const)),
  ]);

  if (archive.documents.length !== expectedTargets.size) {
    throw BotMemoryError.fromCode(
      "invalid-operation",
      "The memory archive has missing or extra files.",
    );
  }

  const seen = new Set<AkeruMemoryDocumentTarget>();
  const current = await input.store.readSnapshot(access);

  const currentByTarget = new Map(
    [current.user, current.memory, ...(current.group ? [current.group] : [])].map((document) => [
      document.target,
      document,
    ]),
  );

  const prepared = archive.documents.map((document) => {
    if (!expectedTargets.has(document.target) || seen.has(document.target)) {
      throw BotMemoryError.fromCode(
        "invalid-operation",
        "The memory archive contains an invalid file set.",
      );
    }

    seen.add(document.target);
    const expectedGroupId = document.target === "group" ? access.groupId : null;

    if (
      String(document.botId) !== String(access.botId) ||
      String(document.groupId) !== String(expectedGroupId) ||
      document.path !== documentPath(access, document.target) ||
      checksum(document.content) !== document.sha256
    ) {
      throw BotMemoryError.fromCode(
        "io-error",
        `The ${document.target} memory file failed validation.`,
      );
    }

    const validated = input.store.validateDocumentReplacement(
      access,
      document.target,
      document.content,
    );

    const existing = currentByTarget.get(document.target)!;

    return {
      target: document.target,
      content: validated.normalized,
      charCount: validated.normalized.length,
      charLimit: validated.charLimit,
      classification:
        existing.content === validated.normalized
          ? ("unchanged" as const)
          : existing.content.length === 0
            ? ("new" as const)
            : ("changed" as const),
    };
  });

  if (
    input.privateBotMemory === false &&
    prepared.some(
      (document) => document.target === "memory" && document.classification !== "unchanged",
    )
  ) {
    throw BotMemoryError.fromCode(
      "invalid-operation",
      "Private bot memory is turned off. Turn it on to restore MEMORY.md from this archive.",
    );
  }

  const currentStateChecksum = checksum(
    encodeMemoryArchiveJson({
      documents: [...currentByTarget.values()].map(({ target, content }) => ({ target, content })),
      conversation: input.currentConversation,
    }),
  );

  const observationsChanged =
    encodeMemoryArchiveJson(input.currentConversation) !==
    encodeMemoryArchiveJson(archive.conversation.snapshot);

  return {
    prepared,
    observationsChanged,
    previewHash: checksum(`${archive.manifestSha256}:${currentStateChecksum}`),
  };
}

export async function previewBotMemoryImport(input: {
  readonly store: BotMemoryStore;
  readonly access: BotMemoryAccess;
  readonly threadId: ThreadId;
  readonly archive: AkeruMarkdownMemoryArchiveV3Value;
  readonly currentConversation: AkeruConversationMemorySnapshot;
  readonly privateBotMemory?: boolean;
}): Promise<AkeruMarkdownMemoryImportPreview> {
  const prepared = await prepareImport(input);

  return {
    previewHash: prepared.previewHash,
    documents: prepared.prepared.map(({ content: _content, ...document }) => document),
    restoresObservations: prepared.observationsChanged,
  };
}

export async function applyBotMemoryImport(input: {
  readonly store: BotMemoryStore;
  readonly access: BotMemoryAccess;
  readonly threadId: ThreadId;
  readonly archive: AkeruMarkdownMemoryArchiveV3Value;
  readonly currentConversation: AkeruConversationMemorySnapshot;
  readonly previewHash: string;
  readonly privateBotMemory?: boolean;
  /** Restores or rolls back atomically, rejecting a stale expected snapshot before mutation. */
  readonly restoreConversation: (
    snapshot: AkeruConversationMemorySnapshot,
    expectedSnapshot: AkeruConversationMemorySnapshot,
  ) => Promise<void>;
}): Promise<AkeruMarkdownMemoryImportApplyResult> {
  return input.store.withDocumentTransaction(input.access, async (replace) => {
    const prepared = await prepareImport(input);

    if (prepared.previewHash !== input.previewHash) {
      throw BotMemoryError.fromCode(
        "invalid-operation",
        "Memory changed after the import preview. Preview the archive again.",
      );
    }

    let changedDocuments = 0;

    for (const document of prepared.prepared) {
      if (document.classification === "unchanged") continue;
      await replace(document.target, document.content);
      changedDocuments += 1;
    }

    if (prepared.observationsChanged) {
      await input.restoreConversation(
        input.archive.conversation.snapshot,
        input.currentConversation,
      );
    }

    return { changedDocuments, restoredObservations: prepared.observationsChanged };
  });
}