What is Ethos?

Ethos is a TypeScript framework where personality is the unit of architecture. Not a system prompt string. A directory of files that, when switched, atomically changes the agent's prompt, tool access, memory scope, and model.

The one-sentence pitch

A personality lives at ~/.ethos/personalities/<id>/ and contains three files:

<id>/
├── SOUL.md        first-person identity (how do I speak, what am I for)
├── config.yaml     name, description, model, memoryScope, budget, fs_reach
└── toolset.yaml    flat list of allowed tool names

Switching from researcher to engineer mid-chat does not just swap a system prompt. It atomically swaps:

The system prompt (SOUL.md)
The tools the agent can call (toolset.yaml)
Whether memory is shared with the user-default scope or isolated (memoryScope)
Which model handles the next turn (model)

You cannot accidentally run the engineer personality's write-shaped tools under the reviewer's read-only toolset. The four dimensions move together.

What you get out of the box

Three personalities ship by default for everyday use. Each has its own role, tools, and voice.

Personality	Role	Tools	Voice
`researcher`	Explores, summarises, cites	Read, search, browse	Curious, citation-heavy
`engineer`	Writes and edits code	Read, write, run, test	Direct, code-first
`reviewer`	Critiques diffs and designs	Read-only	Caution-first, structured

Two additional system personalities — personality-architect and team-architect — are available for building and managing other personalities.

Plus:

A CLI (ethos chat) with streaming output and slash commands.
Channel adapters for Telegram, Discord, and Slack — same agent, same memory, same sessions across all four surfaces.
Persistent sessions in SQLite, scoped per working directory.
Plain-text memory files (MEMORY.md, USER.md) you can read, grep, edit, and commit.
A skill discovery layer that picks up your existing libraries from Claude Code, OpenClaw, OpenCode, and Hermes — no porting.
Scheduled tasks via a single cron tool — daily briefings, weekly reports, recurring prompts that fire on a cron schedule.
Teams that decompose multi-part requests into specialist tasks on a durable kanban board with an audit trail.
A web dashboard (ethos serve --web) for managing personalities, memory, cron jobs, and MCP servers from the browser.

What Ethos is not

Not a chatbot SDK. Ethos does not generate a website chat widget for you. It's the agent runtime; you bring the interface.
Not a workflow engine. Ethos does not chain steps into pipelines or DAGs. The unit is a turn — a user message in, streamed events out.
Not a multi-model router. A personality declares one model. If you want different models per turn, you use different personalities.
Not a no-code tool. Personalities are config files, but extending Ethos (new tools, new providers, new channel adapters) is TypeScript code against typed interfaces.

The shape of a turn

You send a message. The agent reads memory, builds a prompt, calls the LLM, executes any tools the LLM requests (in parallel, within a budget), syncs memory, and emits a stream of typed events while it does it.

That stream — every event — is one of eight types: text_delta, thinking_delta, tool_start, tool_progress, tool_end, usage, error, done. Every surface (CLI, channel adapter, web UI) consumes this stream and renders what it wants.

Architecture in 90 seconds shows the full diagram.

Why this matters

The trade-offs add up to a specific kind of agent:

A specialist, not a generalist. Because the personality is structural, you can credibly say "the reviewer cannot edit files" — it's enforced at the toolset boundary, not just discouraged in the prompt.
Multi-platform from day one. Sessions are keyed per working directory, not per platform. A conversation started on Telegram continues on the CLI.
Yours to read. Memory is plain markdown. Config is plain YAML. Skills are plain markdown with frontmatter. You can grep, diff, and commit any of it.
Yours to extend. Every extension point — provider, tool, adapter, memory backend, personality source — is a typed interface in @ethosagent/types. Implement, inject, ship.

Sessions and teams travel with you

Sessions are platform-agnostic. A session is keyed by working context, not by the surface you're talking through. Start a conversation in Telegram, keep going from the CLI on your laptop, switch from researcher to engineer mid-thread — the same memory, the same history, the same scratchpad follow you across personalities and platforms. The channel is just the door.

Teams coordinate across specialties. One personality is an agent; a team is a roster. You ask the team coordinator for something multi-part — "research the migration, draft the plan, review it" — and it decomposes the request into typed tasks on a durable kanban board. Specialist personalities claim work, post status updates, hand off, and surface blockers. The board, the audit trail, and the assignments survive restarts. See Run a team with a shared kanban board.

The one-sentence pitch​

What you get out of the box​

What Ethos is not​

The shape of a turn​

Why this matters​

Sessions and teams travel with you​

See also​