embodiment

A small, tested core for giving an app an embodied AI presence — being rebuilt into Gwen, a background realtime voice app.

Status

The realtime app is planned, not built. As of this release nothing in the package listens, speaks, runs as a daemon or serves a dashboard. What ships is the core below and a CLI with introspection verbs only.

• The direction is specified in docs/specs/2026-09-21-realtime-embodiment-app.md and planned in docs/plans/2026-09-21-realtime-embodiment-app.md.
• Everything that used to live here — the strategist tier, the configuration lane, the muse, drones, the example hosts and every live-test result — is archived in git history, not deleted from the record. The tag archive/pre-realtime-0.14.0 is the last commit that contains it.

Why the archive

The reason is the old package's own published verdicts, not a change of taste. By its final cycle this was a 37.7k-line library of loop, strategist, configuration-lane and muse experiments, and its own record said, cycle after cycle, mechanism proven, value not:

• The strategist's ScopeBench Stage 1 returned INCONCLUSIVE, and the one matched live control had the governed arm spend 189.6 s and 3663 strategist tokens to apply zero directives and return a materially identical answer.
• The configuration lane shipped with its value unmeasured.
• The muse measured a 1.2% intervention rate for 2.4–4.4× the token cost, and its tool lane returned INCONCLUSIVE while measuring real harm.

Every one of those tiers shipped opt-in and off. Nothing in the package ran as an app, nothing listened or spoke, and no sibling repo imported it. Presence is a felt claim, and the library never let anyone feel it.

The redesign does not claim value either. It has no measurement yet. When it does, the number is published as measured, including if it is bad.

Software presence, not a body

"Embodiment" is an overloaded word in this mesh. reachy-mini-cli owns the physical robot — and has its own agent embody layer, which is a different thing from this package — and reachy-lobes owns its local brain. This package gives an application a loop and a presence. It does not drive hardware and nothing here claims a body. A later stage lets a Reachy Mini act as a relay for Gwen's ears and voice; that is a planned, stated seam, never an implication drawn from the name.

What is in the package today

1271 tests, 97% coverage.

What is planned

Gwen, on one rig, built on the lobes /v1/realtime API:

• A daemon — embodiment start / stop / status. It works with no browser open; the dashboard is one client of it.
• The daemon runs the turn. The realtime socket stays ears-only. The daemon takes the transcript, injects recalled memory, calls the speaker model and speaks. The turn is built on loop.py with an empty tool registry, so tools and agent triggers arrive later as additions rather than a rewrite.
• Interchangeable ears. Host microphone and speaker, a browser, and later a secret-authenticated robot relay — one active at a time.
• Memory that is private by default. Nothing said in the room reaches a committed store unless the operator promotes it.
• A dashboard with a live assistant waveform, reachable remotely behind Cloudflare Access. MQTT is the internal event substrate; the browser sees a server-sent projection of it.

Not in the first release: tools, vision, a face, voice from the phone, robot support, or any claim that this is useful. The base is accepted on one rig only.

Dependencies — what installing this costs you

Dependencies are human-gated: tests/test_zero_deps.py pins the exact approved set and fails on any change in either direction.

headspace-cli (and with it the docker SDK) left with its only consumer in the archive.

CLI

embodiment whoami        # identity from culture.yaml
embodiment learn         # structured self-teaching prompt
embodiment explain       # markdown docs; `explain <path>` for any verb
embodiment overview      # descriptive snapshot
embodiment doctor        # agent-identity invariants
embodiment cli overview  # the CLI surface

Every verb takes --json. Results go to stdout, errors and diagnostics to stderr, never mixed. Exit codes: 0 success, 1 user error, 2 environment error. No verb drives the loop or starts anything yet.

Development

uv sync
uv run pytest -n auto
uv run pytest --cov=embodiment --cov-report=term   # gate: 60%
uv run teken cli doctor . --strict                 # the agent-first rubric CI enforces

Lint stack (line length 100): black, isort, flake8, bandit, markdownlint-cli2. Every PR bumps the version.

Where embodiment sits

License

See LICENSE.