Profile Reference

Create a profile runtime handle after a user is linked or identified.

const linkedProfile = configure.profile({ token });
const appLocalProfile = configure.profile({ externalId: "customer-123" });

Use token for linked, portable Configure users. Use externalId for unlinked app-local profiles; it is your stable user identifier and the SDK sends it as X-User-Id. Linked profile handles do not need a separate user ID.

Existing Agent Loop

const profile = configure.profile({ token });
const read = await profile.read();

const response = await model.run({
  messages: [
    { role: "system", content: read.profile.format({ guidelines: true }) },
    ...messages,
  ],
  tools: profile.tools(),
  executeTool: profile.executeTool,
});

await profile.commit({ messages, response });

The browser token stays on the backend. The model receives formatted profile context and Configure tool definitions.

profile.read(options?)

Reads the current user profile.

const data = await profile.read({
  sections: ["identity", "preferences", "summary", "imports"],
});

const promptContext = data.profile.format({ guidelines: true });

Use this when the agent needs the user's identity, preferences, summary, integrations, imports, or agent-attributed context before responding. imports is for user-directed ChatGPT/Claude/etc. memory imports; integrations is for connected tools.

profile.search(options?)

Searches or lists permitted attributed profile data. Omit query or pass query: "*" to list bounded permitted results.

const results = await profile.search({
  query: "travel preferences",
  source: "your-agent",
  from: "2026-05-01",
  to: "2026-05-31",
  limit: 5,
});

const full = await profile.search({
  query: "travel preferences",
  source: "your-agent",
  detail: "full",
});

const listed = await profile.search({ limit: 50 });

const chatgptImport = await profile.search({
  query: "*",
  source: "chatgpt",
  limit: 50,
});

Omit source to search all permitted attributed profile data for the user. Pass an explicit source handle such as tempo, chatgpt, or import:chatgpt to filter to that source. source is a filter, not path authority.

Compact results include id, source, text or snippet, type, and when knowable written_by, created_at, event_at, and score. Compact results do not include raw CFS paths or provenance by default. Pass detail: "full" to include safe inspectable metadata such as path, updated_at, markers, and provenance.

profile.remember(fact)

Stores one explicit memory string as a typed CFS memory entry under /agents/{resolved-agent}/memories/{YYYY-MM-DD}/{mem_id}.json.

await profile.remember("User prefers direct, concise status updates.");

remember() accepts bounded memory text, not raw chat message arrays. Use commit() for conversation packets.

profile.commit(input)

Commits a bounded conversation packet after a model turn. After a read-backed turn, bounded messages or toolResults clear the read obligation; memories are optional durable user facts, preferences, or intentions.

await profile.commit({
  messages: [
    { role: "user", content: "I prefer aisle seats." },
    { role: "assistant", content: "I'll remember that for future trips." },
  ],
  response,
  toolResults: [
    { toolName: "configure_gmail_search", content: { matches: 2 } },
  ],
  memories: ["User prefers aisle seats."],
  sync: false,
});

commit() accepts messages, response, toolResults, memories, and sync. It does not accept metadata or internal read-obligation/source-context fields. The SDK bounds the packet before sending it to the backend.

profile.tools(options?)

Returns model tool definitions for the current runtime handle.

const defaultTools = profile.tools();
const expandedTools = profile.tools({
  connectors: ["gmail"],
  actions: ["email.send"],
  advanced: {
    commit: true,
    files: false,
    utilitySearch: false,
  },
});

The default list contains only configure_profile_read, configure_profile_search, and configure_profile_remember.

Connector tools are added through connectors, action tools through actions, and adapter/runtime tools through advanced.

profile.executeTool(toolCall)

Executes a tool call from the model.

const result = await profile.executeTool(toolCall);

The runtime records which connector, action, and advanced tools were enabled by profile.tools(). executeTool() rejects tools that are unknown or not enabled for this handle.