Files

Raw path-addressed file operations are advanced SDK methods exposed through configure.files.*.

They are separate from profile reads, search, remembers, forgets, and commits:

const file = await configure.files.read({
  externalId: "customer-123",
  path: "/preferences.md",
});

Use profile.read(), profile.search(), profile.remember(), and profile.forget() for model-facing profile context. profile.commit() is the server-side write-back path. It is not in the default model tool set; tools({ advanced: { commit: true } }) opts it in.

Use file operations only when an application needs explicit file-level reads or writes.

Methods

files.read(options: FileReadOptions): Promise<FileReadResult | null>
files.list(options?: FileListOptions): Promise<FileListResult>
files.write(options: FileWriteOptions): Promise<FileWriteResult>
files.search(options: FileSearchOptions): Promise<FileSearchResult>
files.delete(options: FileDeleteOptions): Promise<FileDeleteResult>

Method	Options	Returns
read	path (required)	{ path, content, type, metadata, tokens, is_directory }, or null when the file does not exist. A missing file does not throw.
list	path (default /), depth (default 1), limit (default 100)	{ entries, count }
write	path, content (required); type ('markdown' | 'json', default 'markdown'); mode	{ path, created, tokens }
search	query (required), path, scope, limit (default 10), filesOnly (default false; drops snippets when true)	{ results, count }
delete	path (required)	{ deleted }

For search, both path and scope limit results to a path prefix (default /). The SDK sends the value as the scope query param. When both are set, path wins.

Write Modes

write() accepts mode: "overwrite" | "append" | "merge". The default is "overwrite".

WARNING

An omitted mode replaces the whole file. To add to an existing file, pass mode: "append" explicitly.

await configure.files.write({
  externalId: "customer-123",
  path: "/preferences.md",
  content: "\n- Prefers aisle seats.",
  mode: "append",
});

Identity Resolution

Every files.* call accepts token, userId, and externalId. The subject resolves in this order: userId, then the call's externalId, then the client-level externalId from the Configure constructor. When none resolves, the call throws ConfigureError with code INVALID_INPUT before any request is made. A token is only an additional auth credential sent as Authorization: Bearer; it is never a standalone subject, so a token-only call with no resolvable externalId still throws.

Path Rules

Paths must not contain ../. The SDK enforces this on write() and throws INVALID_INPUT.

Files Versus Box Addressing

File paths are not accepted by profile.read() or profile.search(). Box and page addressing is: profile.read({ box, page }) and profile.search({ box }) address boxes directly, including projects/<slug> boxes, and REST /v1/profile/search accepts ?box=. Drop to configure.files.* only when you need arbitrary paths.