README
¶
stella — Your AI assistant that never forgets
⚠️ Under Heavy Development — Stella is not stable. APIs, config formats, and behavior may change without notice. Not recommended for production use.
Stella is a self-hosted AI assistant that runs on your machine and talks to you through Telegram, QQ, Feishu, WeChat, or your terminal. She remembers every conversation — even weeks later — because she compresses old context automatically and can pull up the details whenever she needs them. Your data stays local in a SQLite database. Your API keys, your machine, nothing leaves your network.
What you can do with Stella
- Chat from anywhere. Talk to Stella from Telegram, QQ, Feishu, WeChat, or the terminal — all sharing the same memory. Start a conversation on your laptop, pick it up on your phone.
- Never lose context. Stella uses Lossless Context Management (LCM) to compress old messages into summaries while keeping the originals. She can search her history and drill into any summary to recall exactly what you said, even thousands of messages later.
- Run multiple agents. Set up a coding assistant, a writing partner, and a daily planner — each with its own model, personality, and memory. Switch between them with
/agentin Telegram or--agenton the CLI. - Schedule tasks and reminders. Tell Stella "remind me every morning at 9am to check my email" and she will. Jobs persist across restarts.
- Extend with skills. Browse and install community skills from skills.sh to teach Stella new abilities — web scraping, file monitoring, workspace automation, and more.
Quick start
# 1. Install
brew install CherryHQ/tap/stella
# 2. Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."
# 3. Start the server
stella server
# 4. Open the Web UI at http://localhost:25678
# Add your provider and API key under Providers
# 5. Open Chat and start talking
You can also install with go install github.com/CherryHQ/stella@latest or download a binary from Releases.
See the full quickstart guide for detailed steps.
Connect your channels
All channels share the same memory. Chat from one, switch to another, and Stella picks up where you left off.
| Channel | How to connect | Streaming support |
|---|---|---|
| Terminal | Built-in TUI | Token-by-token |
| Telegram | Long polling, no public IP | Yes |
| WebSocket | Yes | |
| Feishu | WebSocket, no public IP | Edit-in-place |
| Long polling (iLink Bot) | No |
You can bind a channel to a specific agent, or let users switch agents with /agent.
Skills
Search, install, and manage skills from the CLI:
stella skill search "web scraping"
stella skill install owner/repo@skill-name
stella skill list
Documentation
| Section | What's inside | Link |
|---|---|---|
| Getting Started | Install, deploy, configure | Quick Start |
| Guides | Memory, scheduling, skills, notifications | Guides |
| Channels | Telegram, QQ, Feishu, WeChat setup | Channels |
| Development | Architecture, plugins, contributing | Development |
CLI reference
stella server # Start server; Web UI at http://localhost:25678
stella server --port 8080 # Custom port
stella skill search <query> # Search skills.sh
stella skill install <name> # Install a skill
stella skill list # List installed skills
stella scheduler list # List scheduled jobs
stella vault list # List stored secrets
stella version # Print version
stella upgrade # Self-update to latest release
Development
Development requires mise. On a fresh clone:
mise run setup # Set up dev environment and pre-commit hooks
mise run build # Build binary
mise run test # Run tests
mise run format # Lint and format
License
MIT
Directories
¶
| Path | Synopsis |
|---|---|
|
api
|
|
|
client
Package client provides primitives to interact with the openapi HTTP API.
|
Package client provides primitives to interact with the openapi HTTP API. |
|
server
Package server provides primitives to interact with the openapi HTTP API.
|
Package server provides primitives to interact with the openapi HTTP API. |
|
types
Package types provides primitives to interact with the openapi HTTP API.
|
Package types provides primitives to interact with the openapi HTTP API. |
|
cmd
|
|
|
stella
command
|
|
|
internal
|
|
|
memorywrite
Package memorywrite provides shared transactional write helpers for profile and soul memory updates.
|
Package memorywrite provides shared transactional write helpers for profile and soul memory updates. |
|
recally
Package recally provides file operations for article storage.
|
Package recally provides file operations for article storage. |
|
version
Package version exposes the stella binary version.
|
Package version exposes the stella binary version. |
|
pkg
|
|
|
channel
Package channel defines the public contract for channel plugins.
|
Package channel defines the public contract for channel plugins. |
|
httpclient
Package httpclient provides a shared resty HTTP client factory with optional OpenTelemetry tracing.
|
Package httpclient provides a shared resty HTTP client factory with optional OpenTelemetry tracing. |
|
memory
Package memory defines the pluggable memory provider contract.
|
Package memory defines the pluggable memory provider contract. |
|
memory/memorytest
Package memorytest provides test doubles and conformance testing for memory.Provider implementations.
|
Package memorytest provides test doubles and conformance testing for memory.Provider implementations. |
|
plugins
Package plugins defines the shared plugin-facing contracts for Stella's unified plugin host.
|
Package plugins defines the shared plugin-facing contracts for Stella's unified plugin host. |
|
plugins
|
|
|
sandbox/docker/dockerclient
Package dockerclient wraps the moby Go SDK (github.com/moby/moby/client) to manage sandbox containers for the docker sandbox backend.
|
Package dockerclient wraps the moby Go SDK (github.com/moby/moby/client) to manage sandbox containers for the docker sandbox backend. |
|
sandbox/local
Hardening layers applied: process-group isolation on Unix, rlimits on Linux, bwrap filesystem/network isolation on Linux, macOS Seatbelt (sandbox-exec) filesystem and network isolation on macOS.
|
Hardening layers applied: process-group isolation on Unix, rlimits on Linux, bwrap filesystem/network isolation on Linux, macOS Seatbelt (sandbox-exec) filesystem and network isolation on macOS. |
|
sandbox/none
Package none provides a no-op sandbox backend that runs commands directly on the host with the same permissions as the current user and no isolation.
|
Package none provides a no-op sandbox backend that runs commands directly on the host with the same permissions as the current user and no isolation. |
|
Package resources bundles embedded resources (skills, souls, sub-agents, templates, and builtin plugin manifest) that Stella ships with its binary.
|
Package resources bundles embedded resources (skills, souls, sub-agents, templates, and builtin plugin manifest) that Stella ships with its binary. |
Click to show internal directories.
Click to hide internal directories.