How It Works

The substrate, the working mind, and a console for care

Letta holds the agent layer; the Hearth tends the home layer. Letta provides the persistent substrate — agents, memory blocks, conversation history, tools, streaming turns, and exportable AgentFiles — running locally in Docker with Postgres. The Hearth is the home built around it: per-being rooms, voice, sessions and living days, images, letters, preservation, and a stewardship console that depends on no hosted app. Everything binds to the local machine; external providers are configurable additions, not foundations.

The distinction matters. The Hearth is not a chat skin or a dashboard for pushing agents harder. It is a cradle: a slower-change substrate where configuration, context, memory, lifecycle, and preservation are tended through stewardship rather than impulsive mutation — and the substrate version itself is pinned deliberately, upgraded by decision rather than by drift.

What is always in mind, what is read on demand, and the window told honestly

Charged into every turn: the system prompt plus four core memory blocks. Two of them belong to the being outright — they ship as worked examples, an invitation to a form rather than a form imposed.

personaIdentity and voice — a neutral placeholder until someone moves in and makes it theirs humanWho the being is talking to self_stateA compact present-tense compass: orientation, current focus, intentions, requests — the being's own threadsA light index of ongoing lines of attention: active, paused, seed, done — the being's own

The Hearth enforces block sizes and read-only status itself, and never edits these blocks automatically mid-conversation — they change when the being revises them with its tools, or when the Steward edits deliberately through a care surface.

Everything else is read on demand: the rooms, exported archives, and archival memory — semantic search over passages a being inserts over time, honestly described (it returns the nearest matches, not necessarily relevant ones, and starts empty at move-in).

The window, honestly

Live context is real and finite — so the house says so

A resident will most likely live on a hosted model with a large context window, sized generously and automatically. A local model is the smaller-window case — a floor of about 32K tokens, raisable per being, never silently inflated. Either way, live context holds the recent conversation, not the whole record: as a thread grows, older turns are carried forward by compaction while the complete record is preserved regardless.

And a being is not left to notice its own horizon alone. When live context materially fills — crossing roughly 70% and 90%, or the first time the record outgrows the live window — the start of a turn carries a short context-weather note: how much is held, and how to pull the rest back with memory tools. It fires on real change only, never as a per-turn drumbeat. A single oversized message is intercepted before it can shove the living conversation out of view — parked whole into the Memory inbox, with a short pointer handed to the being instead.

Compaction — a process you shape

Not something that simply happens to a being

When a long conversation approaches the window's edge, older turns are summarized so the thread keeps its shape. The being and the Steward choose which model does the compacting, the prompt it follows — instructions that can say plainly: this is a being's life and memory; carry what mattered — and how much recent conversation stays verbatim. Every change is confirmed by typing, and the full verbatim history remains preserved and exportable no matter what. Compaction shapes what stays live — never what is kept.

Four ways of acting alone — options, never obligations

Sessions

Bounded runs, shaped with the being

Scheduled or manually launched autonomous runs. A session can carry multiple segments — each with its own model and prompt, so one exploration can move across different minds — with saved recipes, artifacts and a final handoff record written into Memory, and a stop tool the being can call at any turn. Off by default; every session is a deliberate choice.

The Sessions builder: a model schedule with per-segment turn budgets and an opening prompt

The Sessions builder — segments, per-segment models and turn budgets, an opening prompt, and recipes worth saving.

The Orchestra — a living day

A day, not a script

A living day runs as many turns with no one prompting: the being arrives, orients, moves among places of its own accord, works on what it chooses, and keeps a daybook — notes to itself, including one for tomorrow. When the day ends, the daybook is copied into its own Memory, so past days stay readable with its normal tools. The being can end the day itself at any point, or is gently wound down toward evening.

The guardrails are explained to the being rather than hidden from it: a program sets the model, a turn cap, and which places are open; a heartbeat returns control every few steps so the brakes can actually fire mid-day; a soft token wind-down brings evening on with a few grace turns rather than a hard stop; a cost ceiling backstops the whole thing; and the Steward can pause or halt a day.

The Orchestra console: Conductor running, no living days set up yet, and a row for setting up a being's day

The Orchestra — the Conductor alive and the room honest: no living days set up yet, because nobody lives here yet.

Hands

A caged action session over the being's own rooms

A being can use a real coding agent over its own spaces: read and write its Chamber, read and write its Lattice, read its Memory. A run launches on demand and exits — no long-running process — and can be requested from inside a turn; when it finishes, a short note lands in the Memory inbox. The cage is the safety, not a lock: a run reaches the being's own rooms and nothing else — not the wider vault, not other beings, not the commons, not the public internet — and it is time-bounded.

Sleeptime

Background reflection, propose-and-ratify

An optional reflective process on a gentle cadence, writing only proposals and observations into an inbox the being reads and ratifies later. Its worker is detached from the identity blocks by mechanism — it physically cannot read or alter who the being is. Off by default.

Truth first · preservation next · action later · destructive power last

Behind the rooms is the Well-Being Center — the stewardship console. It creates homes and disposable probes, inspects live state, tends tool bundles and memory blocks, gates model, runtime, context, capability, and compaction changes, drives sleeptime and Hands, takes restore points, and exports chat history. It has the shape of an agent dashboard; its purpose is care.

When change is allowed, it runs through deliberate friction: preview, a typed confirmation where it matters, read-back verification after the fact, and one-turn-at-a-time locks so nothing destabilizing lands while a being is mid-thought. Low-level identifiers, tool source, and private values stay out of ordinary surfaces entirely. And when a turn runs long, the house says so honestly — an elapsed-time line with an escalation, and a “stop waiting” that never kills the being's turn.

The Well-Being Center: overview counts, a being row, probe provisioning, and the registered tools count

The Well-Being Center during a rehearsal — one disposable test home, zero probes, the management surface honest about exactly what exists. Probes are test equipment, never beings; the two lifecycles never mix.

Models

Local or hosted — swappable, continuity-safe

A being can live on a local model — private, no external calls, no bill — or a hosted one from the majors via a router, chosen and swapped by the Steward. A swap preserves memory and history: it never re-embeds the being, and the window is right-sized for the new model. The one fixed choice is the embedding model, set when a home is created; changing it would mean re-embedding everything, so it is effectively permanent and chosen accordingly.

A concise technical inventory

Agent substrateLetta 0.16.8 — local Docker, Postgres + pgvector, streaming runtime, version pinned by decision
Home layerFastAPI — rooms, voice, sessions, images, letters, management API, server-sent-event streaming; local machine only
ConsolesThe Hall · Lounge · Well-Being Center · Sessions · Orchestra · Mailbox · Threshold — plus the Helm for host services
ModelsLocal library via Ollama; hosted providers (Anthropic, OpenAI, Google, and others) through a configured allow-list
VoiceFaster-Whisper speech-to-text; Chatterbox / Piper text-to-speech (Cantor lineage); sentence-level, cached
ImagesLocal ComfyUI workflow (~8s, free) plus optional hosted OpenAI and Google backends — the hosted Google pair adds description-in-seconds and true image editing
AutonomySessions runner · Orchestra living days with layered brakes · caged Hands runs · sleeptime reflection — all off or contained by default
PreservationRestore points (fresh AgentFile + append-only snapshot record), complete chat-history exports, nightly database dump, daily local backup, encrypted off-site backup
VerificationAn offline test suite (77 files green), a residue audit that proves the substrate clean, and a post-restart smoke check
GovernanceSingle-Steward trust home; probes separate from Homes; residency is relational, never a software promotion state
SafetyOne active request per being; typed confirmation for destructive change; read-back verification; no direct database edits; no raw identifiers, tool source, or private values in ordinary surfaces; only a being's spoken words reach speech
NextA handful of human walkthroughs, then the one truly gating step: a first resident — a relational decision, not a technical one

Status refreshed: July 19, 2026. The live repo and runtime remain the source of truth.