Skip to content

Core API

The TypeScript declarations in packages/core/src are the full contract. This page lists what hosts use.

Import Contents
@familiar-ai/core openWorkspace, definePlugin, defineTool, familiar, schema, memorySecrets, defaultPersona, localMinute, errors and types
@familiar-ai/core/http createHttpApi, HttpApi, Operation, Allow and wire types
@familiar-ai/core/models Pi’s createModels and model types, including CredentialStore
@familiar-ai/core/models/openai openaiProvider
@familiar-ai/core/models/openrouter openrouterProvider
@familiar-ai/core/models/faux fauxProvider, fauxAssistantMessage and other scripted-model helpers
@familiar-ai/core/models/scripted scriptedModels: faux models that answer each request with a script, read as a message, tool result, schedule or background work
@familiar-ai/core/storage/memory MemoryStorage
@familiar-ai/core/extensions Pi Durable’s extension types and helpers
@familiar-ai/core/node Node building blocks: fileSecretStore, fileCredentialStore, lockDataDir, jsonFile. See Plugin API
@familiar-ai/core/diagnostics Memory internals for evaluation tools

The model and extension entries re-export Pi at the exact version core depends on.

Opens a workspace over its storage, resumes unfinished work and starts background work. Returns Promise<Workspace>. Use one process per storage, and dismiss() it when done.

A workspace holds Familiars and the rooms where people talk to them. Each Familiar has its own memory, schedules, model and one working context it carries across all its rooms; plugins, MCP servers, secrets and the model login are shared. Familiars and rooms are stored, so a host creates them once, on the first open.

Option Required Meaning
storage yes Pi Durable Storage
models yes Pi Models with providers registered
chatModel yes { provider, modelId } Familiars’ chats run on by default, until the owner chooses another default or a Familiar its own. Must be in modelChoices
memoryModel { provider, modelId } memory’s filing and profiles run on by default, at its level in modelChoices, as chatModel. Background memory work can use a cheaper model than the chat. Default: chatModel
timeZone yes IANA zone. Throws if invalid
modelChoices { model, thinkingLevel }[] the installation offers: what people may switch a chat to, and what a Familiar’s memory may run on. Must include chatModel and memoryModel. Default: chatModel at medium
hostInstructions What the host adds after each Familiar’s persona, such as what its UI renders
account { login }: lets the owner sign in to chatModel.provider. login is Pi’s LoginOptions; OpenAI needs getDeviceId
plugins FamiliarPlugin[]
secrets SecretStore. Without it, every secret is missing
fetch PluginFetch for tools, used as given. Refuse private destinations the process can reach. Default: on Node, a fetch that refuses every address that isn’t public; elsewhere, the runtime’s
mcpFetch PluginFetch for owner-configured HTTP MCP servers
mcpStdio McpStdioFactory for owner-configured local MCP commands
contextBudget Tokens per request before a Familiar’s older context is compacted. Default 64,000
notify Notify: delivers scheduled replies and plugins’ notifications. See Notifications
maxSchedules Most schedules each Familiar keeps at once, a positive whole number. Default DEFAULT_MAX_SCHEDULES, 50
people Author[]: what people are called at first, by host author ID, such as an owner. Used on the first open only; after that, each person’s name is theirs to change with people.rename
onWake For evictable hosts. Replaces in-process timers. See Host on Cloudflare
now, setTimer Clock and timer overrides, mainly for tests

notify(notification, context?) receives { title, body, url? }, the same for everyone who sees it. A scheduled run also passes a NotificationContext, { scheduleId, creator }. creator is the Author stored with the schedule when it was made, unchanged by restarts or later renames, and undefined when no person asked for it. A plugin’s notification has no context.

Familiar never chooses recipients. Your host decides who sees each notification, in which tenant, and how: through Web Push with PushHost, or its own notification preferences and delivery. The creator is attribution, not a recipient: a reminder’s turn answers it in the room it was made in, where others may also want it, and the host may send it to none of them.

Serve the API has a tenant’s notify that delivers through the app’s own preferences.

A workspace’s plugins and MCP connections are assigned to Familiars, which opt in: a new one uses what familiars.create was given, else the workspace’s default tools (defaultCapabilities(), setDefaultCapabilities(), and the openWorkspace option defaultCapabilities, used on the first open only), and one added to the workspace later is off until it’s turned on with setCapabilities. Core’s own tools are always on, and tool search comes with any MCP connection. A Familiar’s tools are available for everyone who talks to it. A tool reads the person a call runs for with await familiar(context).author(), an Author or undefined, resolved from the stored input that started the call, never from its arguments. It is the message’s author, or a scheduled run’s creator. A run triggered by another Familiar’s reply acts for the person who started the chain. Nested calls and calls rerun after a crash keep it, and a message queued later can’t replace it. It’s undefined for memory filing and any other input with no person behind it. MCP tools don’t receive it.

Familiar stores no permissions. A tool, or the app API behind it, enforces narrower rules about its data and actions against that author. See Serve the API.

Familiars

Member Meaning
familiars.list() FamiliarSummary[]: each Familiar’s id, name, and any persona and avatar
familiars.watch() Watch of who each Familiar is
familiars.create({ name, persona, avatar }) Create one, returning its WorkspaceFamiliar. Throws a TypeError for a blank one
familiars.update(id, change) Change its name, persona, avatar, chatModel or memoryModel; null returns one to the default
familiars.get(id) Its WorkspaceFamiliar, or undefined
familiars.remove(id) Remove it, stopping its work. Throws for no such Familiar
modelOptions() ModelOption[]: every model a Familiar may run on
modelDefaults() { chat, memory }: the models and levels Familiars run on unless they choose their own
setModelDefaults({ chat?, memory? }) Each { provider, modelId, thinkingLevel? } given replaces that default. Throws a TypeError for one not offered

Without a persona, a Familiar introduces itself with defaultPersona(name). Its name also titles its notifications and its memory’s prompts. An avatar is a short string, at most 64 characters, that your UI interprets, such as an index into its set of portraits; core keeps it and never reads it, and without one your UI derives one from the ID.

Removing a Familiar stops its turns in every room, its chat’s queue, its schedules and its memory filing, and retires its memory, schedules and settings. It leaves every named room: a room it led becomes open, and one it leaves with no Familiars is archived. Its DMs stay readable but post throws a RoomError there. Rooms keep its replies, under its name at the time, and shared plugins, connections and secrets stay.

Rooms

Member Meaning
rooms.list(person?) RoomSummary[], each room as a list shows it; with a host author ID, only that person’s DMs and every named room, with what they haven’t read
rooms.watch(person?) Watch of the same, by ID
rooms.create(setup) A named room, { name, familiars }, returning its ID. Throws RoomError when refused
rooms.update(id, change) Change a named room’s name or membership. archived: false unarchives the room
rooms.archive(id) Hide a named room and close it to new messages, keeping its history
rooms.dm(familiar, person) The DM between a Familiar and a person, by host author ID, created if new
rooms.get(id, person?) A room’s API; with a host author ID, undefined for someone else’s DM, as the HTTP API uses it

A list shows each room as a RoomListing: its setup, with last, its newest entry worth showing ({ entry, at, text } and who it’s from by kind: a person’s message, a Familiar’s reply with its outcome, a handoff or reminder, or a host’s note), unread, how many entries the person hasn’t read, and turns, each turn in progress as { familiar, status }. Staying quiet adds no entry. A last reply with outcome: 'failed' records a failure. The room updates last and the read markers as entries are posted. It derives turns from the Familiars’ active runs and inboxes, with at most one status per Familiar. Unarchiving checks the room’s setup, so one its last Familiar left needs Familiars in the same change.

Each RoomApi has:

Member Meaning
post({ author, text, requestId, mentions? }) Post a message and start the turns it causes, returning its entry ID. A repeated requestId posts once
note({ text, requestId }) Post a host’s note: shown to each Familiar in the room on its next turn, with no turn of its own. Returns its entry ID
watch(window?) The log’s committed view as value, then start(listener) and stop(). window is Pi’s: the newest 50 entries, or { from } an entry
watchTurns() Activity keyed by Familiar ID, with status queued, elsewhere or running and the reply so far
read(person, entry) Mark it read by a person, by host author ID, up to entry, the newest they’ve seen; never back. Their own messages mark it read up to them
history(query, limit) Pi’s { items, next? } page for inclusive minEntryId/maxEntryId bounds and order
retry(reply) Try a failed reply’s turn again, by its entry ID: its Familiar answers the same entry anew, after it. Asking twice starts it once
stop() Stop this room’s turns, leaving other rooms’ work alone

A DM’s message goes to its Familiar. In a named room, it goes to the Familiars it mentions, or to every Familiar in the room if it mentions none. Each recipient chooses whether to reply and can do so alongside the others. A mention is { kind: 'familiar' | 'person', id, start, end }, the span of an @Name in the text. post throws a MessageError for a mention that doesn’t span an @ or names a Familiar outside the room, and a RoomError for an archived room.

Each Familiar handles one input at a time across its rooms. Its input includes what it missed and who else was replying in the room when the input was prepared. A reply, including its tool calls, is posted as a familiar.reply entry once the run ends. A stopped input that had started has a reply entry with outcome: 'stopped' and an empty messages array.

A note is a familiar.note entry, { text, at }: context for the room’s Familiars, such as “Sam joined” or “the board was updated”, that causes no turn, so no one replies to it. It reads in catch-up as [Note]: …, and takes the same text bounds as a message. It is for short passing context; a Familiar sees it once, and then it lives in that Familiar’s working context only.

A Familiar can call stay_quiet to end its run without posting. In a named room, Familiars receive mention tokens such as @[Mary Jane] for the other members. A reply goes to the Familiars it mentions with those tokens, or to all the other Familiars if it mentions none. Answered replies record their depth in the chain since a person last spoke, and mentions when they name other Familiars. At depth 10, Familiar posts the reply in the room without delivering it to another Familiar.

Each Familiar, a WorkspaceFamiliar

Member Meaning
id Its FamiliarId
models() ModelOption[]: each chat model with its name and supported thinkingLevels
watchModel() Watch of its model and level, Pi’s AgentState
setModel(ref) Choose its own chat model. Throws ModelError if it isn’t offered
setThinkingLevel(level) Change the current model’s level. Throws ModelError if unsupported
capabilities() { plugins, mcp }: the plugin and MCP connection names it uses
setCapabilities({ plugins?, mcp? }) Each list given replaces what it uses of that kind, from its next request. Throws a CapabilityError for a name the workspace hasn’t
watch() Its working context across every room, for inspection: never show it to people
memory.watch() Document watch of its memory’s subjects: { subjects, next, months }
memory.page(subject) A subject’s page, { profile, notes }. Rejects with MemoryError for no such subject
memory.section() The memory section of the prompt, exactly as the model sees it now
memory.forget(note) Forget a note. Rejects with MemoryError for no such note
schedules.watch() Document watch for schedules
schedules.cancel(id) Cancel a schedule. Rejects if there’s no such schedule
schedules.pause(id), schedules.resume(id) Stop a schedule running, keeping its next, and run it again. Rejects as cancel

Forgetting removes a note and clears its page’s profile until the night’s work rewrites it. A paused schedule has paused: true. A paused repeat skips the times that fall due, so its next stays the time it would run; a paused one-off whose time passes runs, late, once resumed.

Shared

Member Meaning
connections.list() Plugin and MCP connections, with their tools’ descriptions and whether each secret is set
people.get(author), people.watch(author) An Author as Familiars know them: with the name they chose, if any
people.rename(id, name) What Familiars call a person, by host author ID, from their next message. Throws a TypeError for a blank name
connections.setSecret(connection, name, value) Store a secret. connection is { kind: 'plugin' | 'mcp', name }
connections.deleteSecret(connection, name) Remove a secret
mcp.add(server), mcp.remove(name), mcp.reconnect(name) Manage owner-configured MCP servers. add throws McpConfigError
account The account’s API, if account was passed

Lifecycle

Member Meaning
usage() Pi’s usage totals for the workspace
wake(), resume() For hosts that pass onWake
closed Settles on dismissal or a storage failure. A failed instance must be reopened
dismiss() Close the workspace, its account, its MCP connections and its plugins
plugins The plugins it was opened with, whose routes createHttpApi mounts

Author is { id: string; name: string }. Both must be non-empty. id is stable and owned by the host. name is captured when the message is posted: the name the person chose with people.rename, if they have, else the host’s.

post throws a MessageError, posting nothing, unless the author’s id and name and the text are non-empty and within MESSAGE_LIMITS (256, 128 and 128,000 characters) and requestId is 1 to 128 characters. Familiar namespaces each requestId by the author’s id, so it only needs to be unique per author and can never match one of Familiar’s own submissions, such as a schedule’s.

Schedules are bounded too: a prompt is at most SCHEDULE_LIMITS.prompt (2,000) characters, and a repeat is a five-field cron expression of at most SCHEDULE_LIMITS.repeat (256) characters, read in Familiar’s time zone, such as 0 7 * * 1-5 for 07:00 on weekdays. Croner reads it, including its extensions such as L and #, and decides daylight saving: a time the clock skips runs when the clock resumes. When a time is shown twice, a daily or less frequent repeat runs only the first time, while an hourly one such as 30 * * * * runs at both. A repeat runs at most hourly: each occurrence is at least an hour after the one before, and closer ones, such as most of */5 * * * *, are skipped.

One MCP connection is one session with its server, under one account, shared by every Familiar that uses it, so they share its state. For separate accounts, add separate named connections and assign each to its Familiar.

add throws McpConfigError, saving nothing, for a server of the wrong shape: a bad name, an unknown transport, or a URL that isn’t http:// or https:// or carries credentials, a query or a fragment. Familiar saves any server of the right shape and connects through the transport the host passed, mcpFetch or mcpStdio. The host owns which protocols, destinations and commands those transports allow. A server whose transport the host didn’t pass, or whose connection fails, shows { type: 'failed', error } in connections.list() and never stops Familiar opening. An HTTP server with a bearer token and no token set shows needs-auth.

Workspace, WorkspaceFamiliar, RoomApi, RoomsApi, Room, RoomMessage, Mention, ReplyData, HistoryQuery, HistoryPage, ModelChoice, ModelOption, Notification, NotificationContext, Notify, MemoryApi, SchedulesApi, ConnectionsApi, McpApi, McpServer, AccountState and the plugin types are all exported from @familiar-ai/core, with MESSAGE_LIMITS, MessageError, RoomError, CapabilityError, SCHEDULE_LIMITS, DEFAULT_MAX_SCHEDULES and McpConfigError.

The schema namespace re-exports the pinned @earendil-works/pi-schema, including schema.obj, schema.str, schema.opt, schema.oneOf, schema.Schema and schema.Static.