Your first Familiar
This example runs the real assistant: a workspace with one Familiar, its memory and tools, and a DM to talk to it in. The model is scripted and the storage lives in memory, so you need no credentials or network.
npm install @familiar-ai/core @familiar-ai/clientFamiliar needs Node 24.19 or newer. Save this as first-familiar.ts and run it with node first-familiar.ts:
import { ConversationTranscript, toRoomTranscript, type Transcript,} from '@familiar-ai/client'import { openWorkspace } from '@familiar-ai/core'import { createModels } from '@familiar-ai/core/models'import { fauxAssistantMessage, fauxProvider,} from '@familiar-ai/core/models/faux'import { MemoryStorage } from '@familiar-ai/core/storage/memory'
// A scripted model: no credentials, no network.const faux = fauxProvider({ models: [{ id: 'demo' }] })const models = createModels()models.setProvider(faux.provider)faux.setResponses([fauxAssistantMessage('Hello, Sam.')])
const workspace = await openWorkspace({ storage: new MemoryStorage(), models, chatModel: { provider: 'faux', modelId: 'demo' }, timeZone: 'Europe/London',})
try { // One Familiar, and Sam's DM with it. const familiar = await workspace.familiars.create({ name: 'Familiar' }) const dm = (await workspace.rooms.get( await workspace.rooms.dm(familiar.id, 'person-123'), ))!
await dm.post({ author: { id: 'person-123', name: 'Sam' }, text: 'Hello', requestId: crypto.randomUUID(), })
// The room's log, as a chat UI would show it, once the reply is in. const history = new ConversationTranscript(dm.history) const watch = await dm.watch() const transcript = await new Promise<Transcript>((resolve) => { const show = (view: typeof watch.value) => { const shown = toRoomTranscript(history.merge(view)) if (shown.items.some((item) => item.type === 'reply')) { resolve(shown) } } show(watch.value) watch.start(async (call) => { if (call.kind === 'value') { show(call.value) } }) }) await watch.stop() for (const item of transcript.items) { if (item.type === 'message') { console.log(`${item.author.name}: ${item.text}`) } else if (item.type === 'reply') { console.log(`${item.name}: ${item.text}`) } }} finally { await workspace.dismiss()}It prints the DM:
Sam: HelloFamiliar: Hello, Sam.What each part does
Section titled “What each part does”fauxProvideris a scripted model provider. EachsetResponsesentry answers one model request. Use it in tests to drive the real harness without model calls. For a script that answers every request, such as a demo,scriptedModelsfrom@familiar-ai/core/models/scriptedhands it each request already read: a person’s message, a tool’s result, a due schedule or background work.MemoryStoragekeeps everything in memory and loses it when the process exits.openWorkspaceopens the workspace over its storage, resumes any unfinished work and starts background work such as schedules and memory filing.familiars.createmakes a Familiar. Familiars live in the storage, so a lasting host does this once, on the first open.rooms.dmgets or creates the DM between a Familiar and a person, by your host’s ID for them. People talk to Familiars only in rooms: DMs, and named rooms with one or more Familiars.postrecords a message fromauthorand starts the Familiar’s turn.requestIdshould stay the same if you retry the same logical message, so it’s posted once.watchreturns the room’s committed log, then streams each commit’s changes, so you see the reply arrive when the turn ends. Stop it when you’re done.ConversationTranscriptassembles Pi’s conversation windows.toRoomTranscriptturns that log into the items a chat UI shows. It comes from the client package and is pure, so it works on the server too.dismisscloses the workspace. Always call it, so timers and connections stop.
Make it last
Section titled “Make it last”Two things change for a real assistant:
- Persistent storage. On Node, use
openNodeSqliteStoragefrom@earendil-works/pi-durable/storage/sqlite/node. Install the exact Pi Durable version that core depends on, because Pi’s storage format and types change between releases. On Workers, use @familiar-ai/cloudflare. - A real model. Register a provider and give it credentials. That’s the next page, Models and sign-in.