Core API
The TypeScript declarations in packages/core/src are the full contract. This page lists what hosts use.
Entry points
Section titled “Entry points”| 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.
openWorkspace(options)
Section titled “openWorkspace(options)”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 |
Notifications
Section titled “Notifications”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.
Tool author
Section titled “Tool author”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.
Workspace
Section titled “Workspace”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.