configure/README.md

Identity layer SDK for AI agents

# Configure TypeScript SDK

Configure is user-controlled memory for AI agents. The public server-side SDK shape is:

```ts
import { Configure } from "configure";

const configure = new Configure({
  apiKey: process.env.CONFIGURE_API_KEY,
  agent: "your-agent",
});

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

const response = await model.run({
  messages,
  tools: profile.tools(),
  executeTool: profile.executeTool,
});

await profile.commit({
  memories: response.memoryCandidates,
  messages,
  response,
});
```

For app-local users that have not linked a Configure identity yet, pass your stable user identifier as `externalId`:

```ts
const profile = configure.profile({ externalId: "customer-123" });
```

`baseUrl` is only for internal staging/local development and advanced deployments; it should not appear in the normal production path.

Default model tools are only:

- `configure_profile_read`
- `configure_profile_search`
- `configure_profile_remember`

`profile.search()` returns compact attributed hits by default. Compact hits omit raw CFS paths and provenance; pass `detail: "full"` when an inspector or admin flow needs safe metadata such as `path`, `markers`, `provenance`, and `updated_at`.

Connector-backed tools are enabled explicitly:

```ts
profile.tools({
  connectors: ["gmail", "calendar", "drive", "notion"],
  actions: ["email.send", "calendar.create_event"],
});
```

Raw file path access is advanced and lives under `configure.files.*`. Raw agent filesystem APIs are not part of the public default SDK shape.

Bulk historical/onboarding backfill is separate from runtime `profile.commit()`:

```ts
const job = await configure.importProfiles({
  mode: "backfill",
  users: [
    {
      externalId: "customer-123",
      profile: { preferences: ["Prefers concise replies."] },
      conversations: [{
        id: "thread-1",
        messages: [{ role: "user", content: "I usually fly out of SFO." }],
      }],
    },
  ],
});

const status = await configure.importJobs.get(job.id);
```

Import is server-side only, requires an `sk_` key, and is not exposed as a model-facing tool.

## Browser linking and components

Production browser integrations should use the hosted script:

```html
<script src="https://configure.dev/js/configure.js"></script>
```

`Configure.link()` handles user-present identity, seeding, consent, iframe isolation, resizing, and the `configure:linked` event. The host sends the returned agent-scoped token to its backend, then the backend uses `configure.profile({ token })`.

For chat inputs, `Configure.personalizationButton()` renders a compact `+` menu entry with the canonical Personalization toggle and opens Configure Link inline from that row:

```js
Configure.personalizationButton({
  el: "#configure-entry",
  publishableKey: "pk_...",
  agent: "your-agent",
  agentName: "Your Agent",
  font: "Inter, -apple-system, BlinkMacSystemFont, sans-serif",
  onImage: () => openImagePicker(),
  onFile: () => openFilePicker(),
});
```

Images and Files stay host-owned; the helper also emits `configure:image-select` and `configure:file-select`.

Raw web components are included for local labs and advanced self-hosted surfaces:

```ts
import "configure/components";
```

The browser bundle is also packaged at `configure/components/cdn`, but the hosted script remains the recommended production path.