Profile

User profile operations: read identity and preferences, query memories, save facts, ingest conversations, and access the user's storage.

Import

import { ConfigureClient } from 'configure';
const client = new ConfigureClient('sk_your_api_key');
// Access via client.profile

Identity modes

Profile methods work with either a federated user token or an unlinked server-side user. Unlinked X-User-Id access requires a server-side sk_... key.

// Federated user from Configure.auth()
await client.profile.get(token, userId);

// Unlinked developer-scoped user via X-User-Id
const apiOnly = new ConfigureClient({
  apiKey: process.env.CONFIGURE_API_KEY,
  agent: process.env.CONFIGURE_AGENT,
  userId: 'your-internal-user-id',
});

await apiOnly.profile.get();
await apiOnly.profile.remember(undefined, undefined, 'Prefers concise answers');

Unlinked profiles can be read, written, remembered, and ingested without a Bearer token when the server uses sk_.... They remain scoped to your developer account until the user links a phone number with Configure.auth({ externalId }).

Methods

get

profile.get(
  authToken?: string,
  userId?: string,
  options?: { path?: string; sections?: Array<'identity' | 'preferences' | 'integrations' | 'agents' | 'summary'> }
): Promise<UserProfile>

Get the user's composed Memory Profile. Returns identity, preferences, integrations, agents, and summary by default. Use sections to limit the response, or path to select a dot-path inside the composed profile. Use raw CFS methods for file paths such as /identity.json.

Parameters

Name	Type	Required	Description
authToken	string	No	Agent-scoped token from the configure:authenticated event (via Configure.auth()). Omit if using server-side users.
userId	string	No	Falls back to client-level userId.
options.path	string	No	Dot-path inside the composed profile, such as identity.name or agents.atlas.
options.sections	string[]	No	Limit to specific sections: identity, preferences, integrations, agents, summary.

Returns

Promise<UserProfile> — The user's profile data.

Example

// Full profile
const profile = await client.profile.get(token, userId);

// Specific sections only
const partial = await client.profile.get(token, userId, {
  sections: ['identity', 'preferences'],
});

INFO

getProfile() has been removed. Use get() instead.

---

format

profile.format(options?: { includeTools?: boolean; guidelines?: boolean }): string

Convert a profile to a prompt-ready string. Pure function — no network calls. By default, the output includes identity, preferences, connected tool names, summary, and agent memories. Tool data (Gmail insights, calendar events, Drive files, Notion pages) is excluded by default to keep the context lean.

Pass { includeTools: true } to append tool data to the output. This is useful when your agent needs to reason about the user's emails, schedule, or files inline — but adds significant token overhead.

Parameters

Name	Type	Required	Description
options.includeTools	boolean	No	Include synced tool data (Gmail, Calendar, Drive, Notion) in the formatted string. Default: false.
options.guidelines	boolean	No	Include profile-use guidelines for model prompts. Default: false.

Returns

string — A prompt-ready context string.

Example

const profile = await client.profile.get(token, userId);

// Default — identity, preferences, memories (lean)
const context = profile.format();

// With tool data — adds Gmail insights, calendar events, etc.
const rich = profile.format({ includeTools: true });

---

getMemories

profile.getMemories(
  authToken?: string,
  userId?: string,
  options?: { agent?: string; agents?: string[]; from?: string; to?: string }
): Promise<{ memories: { agent: string; date: string; content: string; source?: string }[] }>

Query memories across agents with optional filters.

Parameters

Name	Type	Required	Description
authToken	string	No	Agent-scoped token from the configure:authenticated event (via Configure.auth()). Omit if using server-side users.
userId	string	No	Falls back to client-level userId.
options.agent	string	No	Filter to a specific agent's memories. Use 'self' for the calling agent.
options.agents	string[]	No	Filter to multiple agents' memories.
options.from	string	No	Start date filter (YYYY-MM-DD).
options.to	string	No	End date filter (YYYY-MM-DD).

Returns

Promise<{ memories: Array<{ agent, date, content, source? }> }> — Filtered memory entries sorted by date.

Example

// All memories
const { memories } = await client.profile.getMemories(token, userId);

// This agent's memories only
const { memories } = await client.profile.getMemories(token, userId, { agent: 'self' });

// Date-filtered
const { memories } = await client.profile.getMemories(token, userId, {
  agent: 'travelbot',
  from: '2026-03-01',
  to: '2026-03-08',
});

---

remember

profile.remember(
  authToken?: string,
  userId?: string,
  fact: string
): Promise<RememberResponse>

Save a specific fact or preference to the user's memory.

Parameters

Name	Type	Required	Description
authToken	string	No	Agent-scoped token from the configure:authenticated event (via Configure.auth()). Omit if using server-side users.
userId	string	No	Falls back to client-level userId.
fact	string	Yes	The fact or preference to remember.

Returns

Promise<RememberResponse> — { saved: boolean, app: string, fact: string }

Example

await client.profile.remember(token, userId, 'User prefers window seats on flights');
await client.profile.remember(token, userId, 'Allergic to shellfish');

---

ingest

// Conversation mode
profile.ingest(
  authToken?: string,
  userId?: string,
  messages: ConversationMessage[],
  options?: IngestOptions
): Promise<IngestResponse>

// Text mode
profile.ingest(
  authToken?: string,
  userId?: string,
  options: IngestOptions & { text: string }
): Promise<IngestResponse>

// Batch mode
profile.ingest(
  users: IngestUserEntry[],
  options?: IngestBatchOptions
): Promise<IngestBatchResponse>

Extract and save memories from conversations, freeform text, or in batch across multiple users. Fire-and-forget by default; pass sync: true to wait for completion.

Parameters (Conversation mode)

Name	Type	Required	Description
authToken	string	No	Agent-scoped token from the configure:authenticated event (via Configure.auth()). Omit if using server-side users.
userId	string	No	Falls back to client-level userId.
messages	ConversationMessage[]	Yes	Array of { role, content } messages.
options.memoryCriteria	string	No	What to extract (e.g., "travel preferences").
options.sync	boolean	No	Block until extraction completes. Default: false.

Parameters (Text mode)

Name	Type	Required	Description
authToken	string	No	Agent-scoped token from the configure:authenticated event (via Configure.auth()). Omit if using server-side users.
userId	string	No	Falls back to client-level userId.
options.text	string	Yes	Freeform text to extract memories from.
options.memoryCriteria	string	No	What to extract.
options.sync	boolean	No	Block until extraction completes. Default: false.

Parameters (Batch mode)

Name	Type	Required	Description
users	IngestUserEntry[]	Yes	Array of user entries with content. No auth token needed — API key auth only.
options.memoryCriteria	string	No	What to extract.
options.sync	boolean	No	Block until all extractions complete. Default: false.

Returns

• Conversation/Text: Promise<IngestResponse> — { status: 'processing' | 'completed' }
• Batch: Promise<IngestBatchResponse> — { status, totalUsers, totalConversations, totalFactsWritten, users }

Example

// Conversation mode
await client.profile.ingest(token, userId, [
  { role: 'user', content: 'I prefer window seats on flights' },
  { role: 'assistant', content: 'Noted! I will remember that.' },
], { sync: true });

// Text mode
await client.profile.ingest(token, userId, {
  text: 'I live in SF and work at Stripe...',
  sync: true,
});

// Batch mode (API key auth only, no user token)
await client.profile.ingest([
  { userId: 'user@example.com', text: 'I love sushi and live in Tokyo' },
  { userId: 'other@example.com', messages: [
    { role: 'user', content: 'My budget is $5000' },
  ]},
], { sync: true });

---

Moved to tools module

profile.sync() has been moved to tools.syncAll(). See the Tools reference for details.

---

generateDocuments

profile.generateDocuments(
  authToken?: string,
  userId?: string,
  documents?: ('user.md' | 'soul.md' | 'preferences.md' | 'context.md' | 'all')[]
): Promise<GenerateDocumentsResponse>

Regenerate the user's AI identity documents using the latest profile data. Has a 1-hour cooldown and returns cached documents if generated recently.

Parameters

Name	Type	Required	Description
authToken	string	No	Agent-scoped token from the configure:authenticated event (via Configure.auth()). Omit if using server-side users.
userId	string	No	Falls back to client-level userId.
documents	string[]	No	Specific documents to generate. Omit or use 'all' for the full suite.

Returns

Promise<GenerateDocumentsResponse> — { documents: {...}, cached: boolean }

Example

const result = await client.profile.generateDocuments(token, userId);
if (!result.cached) {
  console.log('Freshly generated!');
}

---

storage Methods

These methods provide direct filesystem access to the user's profile storage via the profile module.

ls

profile.ls(authToken?: string, userId?: string, path?: string, opts?: CfsLsOptions): Promise<ProfileManifest | CfsLsResult>

List files and directories. At root path ('/'), returns a ProfileManifest with shape and counts. At sub-paths, returns raw storage entries.

Parameters

Name	Type	Required	Description
authToken	string	No	Agent-scoped token from the configure:authenticated event (via Configure.auth()). Omit if using server-side users.
userId	string	No	Falls back to client-level userId.
path	string	No	Directory path. Default: '/'.
opts.depth	number	No	Listing depth. Default: 1.
opts.limit	number	No	Max entries. Default: 100.

---

read

profile.read(authToken?: string, userId?: string, path: string): Promise<CfsReadResult | null>

Read a file or directory from the user's storage. Returns null if not found.

---

write

profile.write(
  authToken?: string,
  userId?: string,
  path: string,
  content: string,
  opts?: CfsWriteOptions
): Promise<CfsWriteResult>

Write content to a path. Writes require sk_.... For federated users, agents can only write under /agents/{their_name}/. For unlinked users resolved through X-User-Id, the developer-scoped profile may also be managed at root profile paths such as /identity.json and /documents/preferences.md.

Name	Type	Required	Description
opts.type	'markdown' | 'json'	No	Content type. Default: 'markdown'.
opts.mode	'overwrite' | 'append' | 'merge'	No	Write mode. Default: 'overwrite'.

---

search

profile.search(
  authToken?: string,
  userId?: string,
  query: string,
  opts?: CfsSearchOptions
): Promise<CfsSearchResult>

Full-text search the user's storage.

Name	Type	Required	Description
opts.scope	string	No	Limit to path prefix. Default: '/'.
opts.limit	number	No	Max results. Default: 10.

---

rm

profile.rm(authToken?: string, userId?: string, path: string): Promise<CfsRmResult>

Delete a file or directory. Agents can only delete under /agents/{their_name}/. Directories delete all children.