Know your human

# Configure

You are an AI agent. Every session starts at zero — no memory of the user, their preferences, what they told another agent yesterday, or what's on their calendar tomorrow. Configure gives you a persistent memory layer. One SDK call, and you know who you're talking to.

---

## Overview

Configure is persistent memory and user profiling infrastructure. It gives every user a **Memory Profile** — a centralized store of identity, preferences, connected tool data, and per-app memories — that persists across any agent that integrates the SDK.

Phone number is the federated identifier. Same phone = same profile across all apps. Profiles are shared by design; users control permissions.

## Quick Start

### Install

```
npm install configure-ai    # TypeScript
pip install configure-ai    # Python
```

### Authenticate a user

```typescript
import { ConfigureClient } from '@configure-ai/sdk';
const client = new ConfigureClient(); // reads CONFIGURE_API_KEY env var

await client.auth.sendOtp('+14155551234');
const { token, userId } = await client.auth.verifyOtp('+14155551234', '123456');
// token is valid for 30 days
```

### Read the profile

```typescript
const profile = await client.profile.get(token, userId);
// profile.user       → identity (name, email, phone, timezone, occupation)
// profile.prefs      → global preferences (cross-app)
// profile.apps_data  → per-app preferences, summaries, tool context
// profile.connected_tools → ['gmail', 'calendar', 'drive', 'notion']
// profile.tools      → connection metadata per tool
```

## Profile Schema

The Memory Profile is a per-user JSONB document stored in Postgres. It contains:

| Field | Type | Description |
|-------|------|-------------|
| `user.name` | string | From OAuth profile |
| `user.email` | string | Email address |
| `user.phone` | string | E.164 format, federated ID |
| `user.location` | string | City / region |
| `user.timezone` | string | IANA timezone |
| `user.occupation` | string | Job title or role |
| `user.interests` | string[] | Topics of interest |
| `user.summary` | string | Auto-generated from memory extraction |
| `prefs` | object | Global preferences (cross-app) |
| `connected_tools` | string[] | Active tool connections |
| `apps` | string[] | Apps/agents using this profile |
| `apps_data` | object | Per-app prefs, summaries, tool context |
| `tools` | object | Connection state and sync timestamps |

## SDK Methods

### Authentication

- `auth.sendOtp(phone)` — Send OTP to phone (E.164 format)
- `auth.verifyOtp(phone, code)` — Verify OTP, returns `{ token, userId }` (30-day validity)
- `auth.getDemo()` — Get a demo token for development

### Profile

- `profile.get(token, userId)` — Retrieve the full memory profile
- `profile.remember(token, userId, key, value)` — Save a fact or preference
- `profile.ingest(token, userId, messages, opts?)` — Extract memories from conversation messages. Fire-and-forget by default; pass `{ sync: true }` to block until complete
- `profile.getContext(token, userId, opts?)` — Get pre-built context string for system prompt injection
- `profile.sync(token, userId, tools?)` — Sync connected tools (Gmail, Calendar, Drive, Notion) to refresh data
- `profile.getAgentKit(token, userId, opts)` — One-call agent setup: returns `{ instructions, context, tools, connectedTools }`

### Tools

- `tools.connect(token, tool, callbackUrl?)` — Start OAuth flow, returns URL
- `tools.confirm(token, tool, connectionRequestId)` — Confirm connection after OAuth callback
- `tools.disconnect(token, tool)` — Disconnect a tool
- `tools.searchEmails(token, userId, query)` — Search Gmail (auto-saves results to profile)
- `tools.getCalendar(token, userId, range?)` — Get calendar events (`'today' | 'tomorrow' | 'week' | 'month'`)
- `tools.searchFiles(token, userId, query)` — Search Google Drive
- `tools.searchNotes(token, userId, query)` — Search Notion workspace
- `tools.searchWeb(token, userId, query)` — Search the web (always available, no connection needed)
- `tools.createCalendarEvent(token, userId, event)` — Create a Google Calendar event
- `tools.sendEmail(token, userId, email)` — Send an email via Gmail

### Streaming

- `streaming.chatStream(token, userId, message, history, appContext, callbacks)` — Streaming chat with memory context and tool access
- `streaming.chatSimple(token, userId, message, history, appContext)` — Non-streaming chat
- `streaming.generate(token, userId, prompt, appContext, opts?, callbacks?)` — Text generation without tool access

Stream callbacks: `onToken`, `onDone`, `onMemoryUpdated`, `onToolsAccessed`, `onUIComponent`, `onError`.

### Profile Filesystem

Agents can structure data as a hierarchical filesystem under the user's profile. Agents can only write under `/agents/{their_slug}/`.

```typescript
const user = client.userProfile(token);

await user.ls('/');                          // list files/directories
await user.read('/user.md');                 // read auto-generated summary
await user.write(                            // write agent-scoped data
  '/agents/travelbot/memories/2026-03-03.md',
  'User prefers window seats and budget airlines',
  { type: 'markdown', mode: 'append' }
);
await user.search('flight preferences');     // keyword search
await user.rm('/agents/travelbot/temp.md');  // delete file
```

### Agent Self

Agents can manage their own soul, memory, and skills:

```typescript
await client.self.read('/soul/soul.md');       // read agent identity
await client.self.write('/soul/soul.md',       // update identity
  'I am a travel assistant that specializes in budget travel.');
await client.self.read('/memory/memory.md');    // rolling memory summary
await client.self.write('/memory/2026-03-03.md', 'New insight', { mode: 'append' });
await client.self.search('travel preferences');
```

### Peer Access

Read-only, permission-gated access to other agents' profiles:

```typescript
const peer = client.peer('wealthbot');
await peer.read('/soul.md');
await peer.ls('/');
await peer.search('investment strategy');
```

## Agent Kit

One call to set up everything your agent needs — system instructions, profile context, tool definitions, and connected tool status:

```typescript
const kit = await client.profile.getAgentKit(token, userId, {
  appName: 'TravelBot',
  appDescription: 'A travel planning assistant',
  memoryCriteria: 'travel preferences, dietary restrictions',
  includeTools: true,
});

// Use with Anthropic SDK
const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-6',
  system: kit.instructions,   // complete system prompt
  messages: [{ role: 'user', content: userMessage }],
  tools: kit.tools,           // 16 tool definitions
});
```

## Tool Definitions

Configure exposes 16 tools that agents can call. All search tools auto-save results to the user's profile.

### Search (5)

| Tool | Description | Requires |
|------|-------------|----------|
| `search_emails` | Search Gmail with operators (`from:`, `subject:`, `has:attachment`) | Gmail |
| `get_calendar` | Get events for a time range | Calendar |
| `search_files` | Search Google Drive | Drive |
| `search_notes` | Search Notion workspace | Notion |
| `search_web` | Search the web | None |

### Actions (2)

| Tool | Description | Requires |
|------|-------------|----------|
| `create_calendar_event` | Create event with title, time, location | Calendar |
| `send_email` | Send email via Gmail | Gmail |

### Memory (4)

| Tool | Description |
|------|-------------|
| `write_context` | Save a key-value fact to the user's memory |
| `get_context` | Get profile context string for system prompt |
| `read_profile` | Read profile data at a path (e.g. `user.name`, `tools.gmail`) |
| `ingest` | Extract memories from conversation messages |

### Filesystem (5)

| Tool | Description |
|------|-------------|
| `configure_ls` | List files/directories |
| `configure_read` | Read file or directory content |
| `configure_write` | Write markdown or JSON (agents write under `/agents/{slug}/`) |
| `configure_search` | Search filesystem by keyword |
| `configure_rm` | Delete file or directory |

## Memory Extraction

Pass conversation messages to `profile.ingest()` and Configure extracts facts, preferences, and context automatically using LLM analysis. Extracted memories are saved to the profile and available to all agents.

```typescript
await client.profile.ingest(token, userId, [
  { role: 'user', content: 'I prefer window seats on flights' },
  { role: 'assistant', content: 'Noted — I\'ll remember that.' },
], { memoryCriteria: 'travel preferences', sync: true });
// memoriesWritten: [{ key: 'flight_seating', value: 'Prefers window seats' }]
```

By default, ingest is fire-and-forget — returns immediately while extraction runs in the background. Pass `{ sync: true }` to block until complete.

## MCP Server

Configure ships an MCP server (`@configure-ai/mcp`) that exposes all 16 tools to Claude Desktop, Cursor, and any MCP-compatible agent. Tool names are prefixed with `memory_` or `configure_`.

```
memory_search_emails, memory_get_calendar, memory_search_files,
memory_search_notes, memory_search_web, memory_create_calendar_event,
memory_send_email, memory_write_context, memory_get_context,
memory_read_profile, memory_ingest, configure_ls, configure_read,
configure_write, configure_search, configure_rm
```

## Error Handling

| Code | Meaning |
|------|---------|
| `API_KEY_MISSING` | No API key provided |
| `AUTH_REQUIRED` | Token expired or invalid (401/403) |
| `INVALID_INPUT` | Bad request parameters (400) |
| `TOOL_NOT_CONNECTED` | Tool requires OAuth connection first (400) |
| `NOT_FOUND` | Resource not found (404) |
| `RATE_LIMITED` | Too many requests (429) |
| `SERVER_ERROR` | Internal server error (500+) |
| `NETWORK_ERROR` | Connection failed |
| `TIMEOUT` | Request timed out |

---

> You will forget this conversation. The next agent the user talks to will know nothing. Configure is the memory you don't have — one integration, and every user becomes someone you already know.

**Docs:** configure.dev/docs · **Dashboard:** configure.dev/login · **Package:** `npm install configure-ai` / `pip install configure-ai`