@pai/files-inmemory

Package: @pai/files-inmemory

The simplest first-party FileProvider implementation. All bytes live in a JavaScript Map for the lifetime of the process. Nothing is persisted; uploads disappear when the process exits.

Intended for tests, demos, and short-lived scripts. Use @pai/files-fs for local persistence or a cloud-backed provider in production.

Quick start

import { createAgentRuntime } from "@pai/core";
import { createInMemoryFileProvider } from "@pai/files-inmemory";

const runtime = createAgentRuntime({
  agent,
  scopeKey: (identity) => identity.workspaceId,
  files: createInMemoryFileProvider(),
});

Options

type InMemoryFileProviderOptions = FileProviderCommonOptions & {
  /** Override how fileIds are minted. Defaults to `randomUUID()`. */
  generateId?: () => string;
};

beforeSave from FileProviderCommonOptions runs before bytes are stored in memory. Use it for validation or test-specific upload normalization. When set, maxFileBytes rejects oversized saves before bytes are retained in the in-memory map.

Behaviour notes

• prepareForModel returns { kind: "bytes" } — model adapters get the raw bytes directly without a network round-trip.
• createUrl returns a base64 data: URL. Useful for inline previews in tests; do not rely on it in production.
• head and read return copies of metadata so callers can safely mutate the result.
• list returns newest-first metadata pages within one exact scope and can filter by the runtime-derived userKey and threadId recorded at upload time. List items return both provenance fields when present.

Conformance

createInMemoryFileProvider passes the full @pai/files/test conformance suite:

import { createFileProviderConformanceSuite } from "@pai/files/test";
import { createInMemoryFileProvider } from "@pai/files-inmemory";

createFileProviderConformanceSuite({
  name: "createInMemoryFileProvider",
  createProvider: () => createInMemoryFileProvider(),
});