Customise your assistant
Name and persona
Section titled “Name and persona”Each Familiar has its own identity, given to familiars.create and changed with familiars.update. They live in the workspace’s storage, so create them once, on the first open.
name is what a Familiar is called: in its default persona, notification titles and memory’s prompts.
persona is who it is in conversation. It replaces the default, defaultPersona(name), completely and is used as given, so include the name if the model should know it.
hostInstructions, a workspace option, is what your host adds after every Familiar’s persona, such as what your UI can show, like Markdown. Core still adds its own instructions for rooms, memory, schedules and tools. The prompt changes only when these do, so it stays cached.
import { openWorkspace } from '@familiar-ai/core'import { credentials, publicOnlyFetch, secrets, storage } from './host.ts'import { createModels } from '@familiar-ai/core/models'import { openaiProvider } from '@familiar-ai/core/models/openai'import { greeting } from './plugin.ts'
const models = createModels({ credentials })models.setProvider(openaiProvider())
export const workspace = await openWorkspace({ storage, models, chatModel: { provider: 'openai', modelId: 'gpt-6.1-sol' }, timeZone: 'Europe/London', hostInstructions: 'Replies render as Markdown.', plugins: [greeting], secrets, fetch: publicOnlyFetch,})
// Who it is lives in the workspace, so this runs once, on the first open.if (!(await workspace.familiars.list()).length) { await workspace.familiars.create({ name: 'Willow', persona: 'You are Willow, a helpful assistant for a family kitchen.', // Each Familiar opts in to the plugins and MCP connections it uses. capabilities: { plugins: [greeting.name] }, })}Plugins
Section titled “Plugins”The daemon includes web search and page reading. Core has no tools of its own beyond time, memory and schedules. A plugin adds yours: plain Pi Durable tools, grouped under a stable name with a title for the Connections page and any secrets they share.
Import defineTool and schema from @familiar-ai/core rather than installing your own copy of Pi, so they match the Pi version Familiar runs:
import { definePlugin, defineTool, familiar, schema } from '@familiar-ai/core'
export const greeting = definePlugin({ name: 'greeting', title: 'Greeting', tools: [ defineTool({ name: 'greet', description: 'Greet the person who asked.', parameters: schema.obj({}), // Repeating this tool after a crash has no outside effect. replay: 'safe', execute: async (_args, _api, context) => { const author = await familiar(context).author() return { output: [ { type: 'text', text: `Hello, ${author?.name ?? 'there'}.` }, ], } }, }), ],})Inside execute:
familiar(context)gives the call what Familiar provides:fetch,authorizedFetch,notify,timeZoneandauthor().await familiar(context).author()is the person whose message started this run, or the creator of a scheduled run, traced back through any chain of Familiar replies. Background work, such as memory filing, has no author. Familiar reads it from the stored message, never from the tool’s arguments.- Every tool on a Familiar is available to everyone who chats with it. Rules about particular records or actions, such as who may change a task, are the tool’s to check against the author, or the app API’s behind it.
context.abortSignalis set when the call can be cancelled. Pass it to anything you can cancel.replaydefaults tounsafe. After a crash, Familiar reruns an interrupted call only when it’ssafe. Mark a tool safe only if repeating its effects is harmless.
Secrets and network access
Section titled “Secrets and network access”A plugin declares its secrets and where each may be sent. The owner sets the value through the Connections API. Familiar never passes the value to plugin code.
familiar(context) has two ways to make a request:
fetch(url, init?)is the host’s network access, for requests that need no secret.authorizedFetch(secret, url, init?)is the samefetchwith the named secret attached, only if the request’s origin, method and path match the declaration. Otherwise it throws without sending.
import { definePlugin, defineTool, familiar, schema } from '@familiar-ai/core'
type Task = { id: string; title: string }
export const tasks = definePlugin({ name: 'tasks', title: 'Tasks', // The owner sets this on the Connections page. Plugin code never reads it. secrets: [ { name: 'token', label: 'Tasks API token', sendAs: { header: 'Authorization', prefix: 'Bearer ', origin: 'https://api.tasks.example', requests: [{ method: 'GET', path: '/v1/tasks' }], }, }, ], tools: [ defineTool({ name: 'list_tasks', description: "List the owner's open tasks.", parameters: schema.obj({}), replay: 'safe', execute: async (_args, _api, context) => { const response = await familiar(context).authorizedFetch( 'token', 'https://api.tasks.example/v1/tasks', { signal: context.abortSignal }, ) if (!response.ok) { throw new Error(`Tasks answered ${response.status}.`) } const found = (await response.json()) as Task[] return { // The model reads the text; a UI can render `details`. output: [ { type: 'text', text: found.map((task) => `- ${task.title}`).join('\n'), }, ], details: { tasks: found }, } }, }), ],})A model can be talked into fetching any URL, so fetch must refuse private, loopback and tailnet addresses the process can reach, both when it connects and on every redirect. On Node, Familiar’s default does. In Workers and browsers, which can’t reach those addresses, the default is the runtime’s fetch. Pass fetch to openWorkspace only to replace that policy.
Familiar doesn’t scrub authenticated responses or tool output. Whatever a tool returns, the model reads.
These limits stop the model steering a well-behaved plugin to a private address, or a secret into the wrong request. They don’t contain the plugin itself. A plugin is code you install, trusted like any other dependency: it runs in your process with its privileges, so it could call the global fetch or read whatever the process can. Familiar doesn’t sandbox it. Install only plugins you trust.
Tool details for UIs
Section titled “Tool details for UIs”A tool result has two audiences. output is what the model reads. details is optional JSON a UI can render, such as a list or a card. It reaches the client as ToolCall.details. Clients receive it as unknown, so check its shape before rendering and fall back to the text output.
MCP servers
Section titled “MCP servers”The owner can add MCP servers at runtime through workspace.mcp or the /mcp routes. Every Familiar in the workspace shares them. HTTP servers use mcpFetch, which may reach private networks because the owner chose the endpoint. Local commands need an mcpStdio factory from the host and run with the host’s privileges. Without that factory, local commands aren’t available: they’re saved but show as failed. The host owns MCP transport and destination policy. Familiar checks a server’s shape, then connects through mcpFetch or mcpStdio, so restrict protocols, destinations or commands there.
Run an MCP tool in the background from code
Section titled “Run an MCP tool in the background from code”Once you’ve added the MCP server and enabled it for a Familiar, set the override using the tool name from the server’s listing.
await workspace.connections.updateToolSettings( { kind: 'mcp', name: 'topsail' }, 'watch_print', { runInBackground: true },)When the Familiar calls watch_print directly, Familiar can reply while the request runs and then report the outcome in the original room. Any configured Ask first approval still happens before dispatch. The MCP server can expose an ordinary tool.
Data that belongs to your host
Section titled “Data that belongs to your host”Keep your app’s own records in your app. Familiar’s storage holds rooms, each Familiar’s working context, memory and schedules, and plugin secrets. When a tool needs your data, give it access through a plugin that calls your API or database, and check the call’s author for permission there.
Pi’s own types and helpers
Section titled “Pi’s own types and helpers”@familiar-ai/core/extensions exports Pi Durable’s types and helpers, such as ToolExecutionApi and documents for a tool’s state. They follow the bundled Pi version. A plugin contributes tools only, and hosts never receive Familiar’s running harness.