Profiles And Memory

The profile runtime is the public server-side surface for user memory.

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

token is the agent-scoped Configure token returned by Configure Link. For an app-local user that has not linked Configure yet, use configure.profile({ externalId: "customer-123" }); the SDK maps that to the developer-scoped X-User-Id path.

Read

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

const context = read.profile.format({ guidelines: true });

profile.read() returns composed approved context. It does not accept raw file paths. Pass the formatted profile context into the model prompt; do not pass browser tokens or user IDs to the model.

imports contains user-directed ChatGPT, Claude, Gemini, Grok, or other memory imports. integrations contains connected tools such as Gmail, Calendar, Drive, and Notion.

Search

const results = await profile.search({
  query: "meeting preferences",
  source: "tempo",
  from: "2026-05-01",
  to: "2026-05-05",
  limit: 8,
});

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

profile.search() performs deterministic retrieval over permitted attributed profile data. Compact results are the default and include readable memory text plus source attribution. Pass detail: "full" only when you need safe inspectable metadata such as CFS path, markers, provenance, or updated_at.

Remember

await profile.remember("User prefers SMS for urgent billing issues.");

profile.remember() accepts one explicit fact string. It rejects message arrays and raw transcripts. New runtime memories are stored as typed CFS entries at /agents/{agent}/memories/{YYYY-MM-DD}/{mem_id}.json.

Commit

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

profile.commit() submits bounded turn material after a model turn, especially after profile reads. Bounded messages or tool results clear read-backed obligations; explicit memories are optional and should only contain durable user facts, preferences, or intentions. It is runtime plumbing, not a default model tool and not a bulk import API.

Existing Agent Integration

For an existing agent, keep your current model loop and add these steps:

1. Create const profile = configure.profile({ token }) after Link.
2. Run profile.read() before a personalized response.
3. Add read.profile.format({ guidelines: true }) to the system context.
4. Merge profile.tools() with your existing tool list.
5. Route configure_* tool calls to profile.executeTool().
6. Pass tool results back to the model for the final assistant answer.
7. Call profile.commit() after the turn.