How ethosagent/ethos works
Ethos is a multi-surface AI-agent platform built around configurable personalities, shared memory, and explicit safety boundaries. The principal workflow is: a user starts a conversation through the CLI, web app, or a messaging channel; the gateway or web API dispatches it to an agent turn; the turn uses a personality and model provider, then returns a reply to its initiating surface. Teams, MCP, voice, and learning extend this core. Several links reflect README-documented capabilities; where sampled source does not establish wiring, the graph leaves the relation out.
Main entry points: agent-loop Agent loop · scoped-storage.ts Scoped storage · personalities.service.ts Personality system · learning-pipeline.ts Learning pipeline
Components 21
User surfaces
- Ethos CLI
apps/ethos/src/index.ts - Web app
apps/web/src/App.tsx - Web API
apps/web-api/src/index.ts - Messaging gateway
apps/ethos/src/commands/gateway.ts
Agent runtime
- Agent loop
packages/core/src/agent-loop - Model provider
- Context compaction
packages/types/src/context-engine.ts
Agent capabilities
- Personality system
apps/web-api/src/services/personalities.service.ts - Memory
apps/web-api/src/services/memory.service.ts - Sessions
apps/web-api/src/features/sessions/service.ts - Team coordination
apps/web-api/src/services/teams.service.ts - Learning pipeline
packages/wiring/src/learning-pipeline.ts
Platform services
- Scoped storage
packages/core/src/agent-loop/scoped-storage.ts - Filesystem storage
packages/storage-fs/src/scoped-storage.ts - Encrypted storage
extensions/storage-crypto/src/crypto-storage.ts
Integrations
- Voice pipeline
extensions/gateway/src/voice-pipeline.ts - Wake engine
extensions/voice-satellite/src/wake-engine.ts - MCP server
apps/mcp-server/src/server.ts
Other components
- User
- Messaging services
- MCP clients
Connections 23
- User → Ethos CLI: starts chat
- User → Web app: opens
- User → Messaging services: messages
- Web app → Web API: sends requests
- Ethos CLI → Agent loop: starts turns
- Messaging gateway → Agent loop: dispatches turns
- Web API → Agent loop: dispatches chat
- Messaging services → Messaging gateway: delivers messages
- Agent loop → Model provider: requests completion
- Model provider → Agent loop: returns completion
- Agent loop → Personality system: uses identity
- Agent loop → Memory: uses memory
- Agent loop → Sessions: records turns
- Agent loop → Context compaction: compacts context
- Agent loop → Scoped storage: reads and writes
- Scoped storage → Filesystem storage: uses backend
- Scoped storage → Encrypted storage: can use wrapper
- Learning pipeline → Memory: reads live soul
- Learning pipeline → Personality system: parses soul
- Voice pipeline → Model provider: transcribes audio
- Wake engine → Voice pipeline: detects wake phrase
- MCP clients → MCP server: connects
- MCP server → Personality system: exposes personalities