Files

Most agents should use profile.read(), profile.search(), profile.remember(), and profile.forget(). That is the default model tool set. profile.forget(id, { date?, reason? }) deletes a memory by id; reason: "user_request" also adds suppression, and deletes only apply to your agent's own memories. profile.commit() is separate: it is the server-side write-back call your app makes after a run, not a tool the model calls by default.

Raw profile file operations are an advanced escape hatch under configure.files.*. These examples assume a server-side client from Installation, built with import { Configure } from "configure" and new Configure({ apiKey: process.env.CONFIGURE_API_KEY, agent: process.env.CONFIGURE_AGENT }). Raw file operations always require an externalId (or the advanced userId escape hatch, or a client-level externalId default set on the Configure constructor). A token is only an additional auth credential sent as Authorization: Bearer; it is never a standalone subject, and a token-only call with no externalId throws before any request is made. read returns { path, content, type, metadata, tokens, is_directory } and returns null on a missing path (it does not throw).

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

await configure.files.write({
  externalId: "customer-123",
  path: "/agents/your-agent/preferences.md",
  content: "Prefers concise replies.",
  mode: "append", // "overwrite" (default) | "append" | "merge"
});

mode defaults to overwrite when omitted. Pass append or merge explicitly when you want to preserve existing content. write also takes type: "markdown" | "json" (default markdown) and returns { path, created, tokens }.

Available file operations:

configure.files.list({ externalId, path, depth, limit }). depth defaults to 1. limit defaults to 100.
configure.files.read({ externalId, path })
configure.files.write({ externalId, path, content, mode, type })
configure.files.search({ externalId, query, path, limit, filesOnly }). path scopes results to a prefix. limit defaults to 10. filesOnly defaults to false and drops snippets when true.
configure.files.delete({ externalId, path })

list returns { entries, count }, search returns { results, count }, and delete returns { deleted }.

File paths are not accepted by profile.read() or profile.search(). Box and page addressing is accepted: 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.

Files ​

Files