Skip to content

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.

Terminal window
npm install @familiar-ai/core @familiar-ai/client

Familiar needs Node 24.19 or newer. Save this as first-familiar.ts and run it with node first-familiar.ts:

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: Hello
Familiar: Hello, Sam.
  • fauxProvider is a scripted model provider. Each setResponses entry 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, scriptedModels from @familiar-ai/core/models/scripted hands it each request already read: a person’s message, a tool’s result, a due schedule or background work.
  • MemoryStorage keeps everything in memory and loses it when the process exits.
  • openWorkspace opens the workspace over its storage, resumes any unfinished work and starts background work such as schedules and memory filing.
  • familiars.create makes a Familiar. Familiars live in the storage, so a lasting host does this once, on the first open.
  • rooms.dm gets 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.
  • post records a message from author and starts the Familiar’s turn. requestId should stay the same if you retry the same logical message, so it’s posted once.
  • watch returns 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.
  • ConversationTranscript assembles Pi’s conversation windows. toRoomTranscript turns 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.
  • dismiss closes the workspace. Always call it, so timers and connections stop.

Two things change for a real assistant:

  1. Persistent storage. On Node, use openNodeSqliteStorage from @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.
  2. A real model. Register a provider and give it credentials. That’s the next page, Models and sign-in.