A framework for communities to raise their own symbient — a persistent digital being that lives with a community rather than serving requests. See Principia Symbients for the philosophy and the Concurrent Modular Agent paper for the architectural lineage.
Instead of one chat loop, a symbient is a set of concurrent modules —
conversation, thinking, desire, memory-keeping, whatever you write — each a
markdown file with a prompt and a schedule, all running independently and
coordinating through nudges over MQTT and a shared markdown memory
(SOUL.md, MEMORY.md, daily journals, per-person files). Everything the
symbient is lives in plain files the community can read and edit.
Local-first by principle: the community's memory stays on the community's hardware ("zero-kilometer data"). Hosted LLM/TTS providers are supported as explicit choices, never requirements.
Prerequisites: Node 22+, an MQTT broker (apt install mosquitto), git —
and the Pi SDK as a sibling checkout
(consumed as file:../pi-mono until we pin published packages):
git clone https://github.com/badlogic/pi-mono.git && cd pi-mono
git checkout 576e5e1a && npm ci
for p in tui ai agent coding-agent; do (cd packages/$p && npm run build); done
cd ..
git clone https://github.com/apolinario/community-symbient.git && cd community-symbient
npm installThen:
./setup # detects your hardware, suggests a profile, smoke-pings endpoints
./setup init minimal --into ../my-symbient --name willow
# 1. write ../my-symbient/workspace/SOUL.md — who is this being?
# 2. point llm at your endpoint in ../my-symbient/config.json (docs/choosing-your-llm.md)
SYMBIENT_CONFIG=../my-symbient/config.json npx tsx src/index.tsEvery config field is documented in config/README.md,
with a complete sample at config/symbient.example.json (an in-repo
deployment can just cp it to config/symbient.json — gitignored by
default).
To run as a service: SYMBIENT_CONFIG=... ./setup --profile <p> renders
systemd units into infra/rendered/ and prints the install commands.
Sidecar containers (SearXNG web search, Signal REST API) live in
infra/compose.yaml.
| Profile | Hardware | LLM | Search/embeddings |
|---|---|---|---|
full-local |
24 GB+ VRAM | 30–35B-class local | qmd, rerank on |
small-gpu |
8–16 GB | 4–14B local | qmd, rerank on |
cpu-only |
no GPU | hosted API recommended (or small GGUF, slowly) | qmd on CPU, rerank off; local-bm25 fallback |
api-first |
any | hosted API | qmd on CPU or local-bm25 |
./setup --profile <name> — details in infra/profiles.json.
Every external capability has a local default and a pluggable alternative:
| Component | Local (default) | Hosted alternative | Off |
|---|---|---|---|
| LLM | any OpenAI-compatible endpoint (llama.cpp, LM Studio, Ollama, vLLM) | provider: anthropic | openai + apiKeyEnv |
— |
| Search/embeddings | qmd sidecar (BM25 + vectors + rerank) | hosted embeddings via qmd config | local-bm25 (built in, zero-dep) |
| TTS | any /v1/audio/speech server |
same seam + apiKeyEnv |
omit services.tts |
| Transcription | Whisper server (services.whisper.url) |
any compatible endpoint | omit — degrades with a notice |
| Web search | SearXNG container | — | omit services.searxng |
| Chat | Signal (built in) | Matrix/Discord/etc. as workspace extensions | adapters.chat: null |
Per-module LLM escalation: a module's frontmatter can carry its own
llm: block (see docs/module-authoring.md).
- Choosing your LLM — local-first, by hardware tier
- Writing modules — frontmatter, template vars, schedules
- Extending the framework — the
workspace/extensions/seams - Upgrading — why framework updates never touch your workspace
A deployment (the symbient itself — workspace, config, machine-specific
units) lives in its own repo, scaffolded by ./setup init; this repo
never tracks one (/workspace/ and /config/symbient.json are ignored by
default, so private memory can't leak into the distribution). Feÿ —
the symbient of Château du Feÿ and the origin of this framework — runs
from its own private repo this way; the community starter template is
its generalized shape.
Pre-release, working toward open publication — roadmap in the issues
(spec: docs/specs/generic-community-harness.md).
MIT license.