# ethosagent/ethos architecture

> Architecture diagram of the GitHub repository ethosagent/ethos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ethosagent/ethos
- Repository: https://github.com/ethosagent/ethos

## Overview

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: [`packages/core/src/agent-loop`](https://github.com/ethosagent/ethos/tree/main/packages/core/src/agent-loop) (Agent loop), [`packages/core/src/agent-loop/scoped-storage.ts`](https://github.com/ethosagent/ethos/blob/main/packages/core/src/agent-loop/scoped-storage.ts) (Scoped storage), [`apps/web-api/src/services/personalities.service.ts`](https://github.com/ethosagent/ethos/blob/main/apps/web-api/src/services/personalities.service.ts) (Personality system), [`packages/wiring/src/learning-pipeline.ts`](https://github.com/ethosagent/ethos/blob/main/packages/wiring/src/learning-pipeline.ts) (Learning pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_cli["Ethos CLI<br/>[index.ts]"]
  node_web["Web app<br/>[App.tsx]"]
  node_webapi["Web API<br/>[index.ts]"]
  node_gateway["Messaging gateway<br/>[gateway.ts]"]
end

subgraph group_runtime["Agent runtime"]
  node_agentloop["Agent loop"]
  node_provider["Model provider"]
  node_context["Context compaction<br/>[context-engine.ts]"]
end

subgraph group_domain["Agent capabilities"]
  node_personality["Personality system"]
  node_memory["Memory<br/>[memory.service.ts]"]
  node_sessions["Sessions<br/>[service.ts]"]
  node_teams["Team coordination<br/>[teams.service.ts]"]
  node_learning["Learning pipeline"]
end

subgraph group_platform["Platform services"]
  node_storage["Scoped storage<br/>[scoped-storage.ts]"]
  node_fsstorage["Filesystem storage<br/>[scoped-storage.ts]"]
  node_cryptostorage["Encrypted storage<br/>[crypto-storage.ts]"]
end

subgraph group_extensions["Integrations"]
  node_voice["Voice pipeline<br/>[voice-pipeline.ts]"]
  node_wake["Wake engine<br/>[wake-engine.ts]"]
  node_mcp["MCP server<br/>[server.ts]"]
end

node_user(("User"))
node_channels["Messaging services"]
node_mcpclients["MCP clients"]

node_user -->|"starts chat"| node_cli
node_user -->|"opens"| node_web
node_user -->|"messages"| node_channels
node_web -->|"sends requests"| node_webapi
node_cli -->|"starts turns"| node_agentloop
node_gateway -->|"dispatches turns"| node_agentloop
node_webapi -->|"dispatches chat"| node_agentloop
node_channels -->|"delivers messages"| node_gateway
node_agentloop -->|"requests completion"| node_provider
node_provider -->|"returns completion"| node_agentloop
node_agentloop -->|"uses identity"| node_personality
node_agentloop -->|"uses memory"| node_memory
node_agentloop -->|"records turns"| node_sessions
node_agentloop -->|"compacts context"| node_context
node_agentloop -->|"reads and writes"| node_storage
node_storage -->|"uses backend"| node_fsstorage
node_storage -.->|"can use wrapper"| node_cryptostorage
node_learning -->|"reads live soul"| node_memory
node_learning -->|"parses soul"| node_personality
node_voice -.->|"transcribes audio"| node_provider
node_wake -.->|"detects wake phrase"| node_voice
node_mcpclients -->|"connects"| node_mcp
node_mcp -->|"exposes personalities"| node_personality

click node_cli "https://github.com/ethosagent/ethos/blob/main/apps/ethos/src/index.ts"
click node_web "https://github.com/ethosagent/ethos/blob/main/apps/web/src/App.tsx"
click node_webapi "https://github.com/ethosagent/ethos/blob/main/apps/web-api/src/index.ts"
click node_gateway "https://github.com/ethosagent/ethos/blob/main/apps/ethos/src/commands/gateway.ts"
click node_agentloop "https://github.com/ethosagent/ethos/tree/main/packages/core/src/agent-loop"
click node_personality "https://github.com/ethosagent/ethos/blob/main/apps/web-api/src/services/personalities.service.ts"
click node_memory "https://github.com/ethosagent/ethos/blob/main/apps/web-api/src/services/memory.service.ts"
click node_sessions "https://github.com/ethosagent/ethos/blob/main/apps/web-api/src/features/sessions/service.ts"
click node_teams "https://github.com/ethosagent/ethos/blob/main/apps/web-api/src/services/teams.service.ts"
click node_learning "https://github.com/ethosagent/ethos/blob/main/packages/wiring/src/learning-pipeline.ts"
click node_context "https://github.com/ethosagent/ethos/blob/main/packages/types/src/context-engine.ts"
click node_storage "https://github.com/ethosagent/ethos/blob/main/packages/core/src/agent-loop/scoped-storage.ts"
click node_fsstorage "https://github.com/ethosagent/ethos/blob/main/packages/storage-fs/src/scoped-storage.ts"
click node_cryptostorage "https://github.com/ethosagent/ethos/blob/main/extensions/storage-crypto/src/crypto-storage.ts"
click node_voice "https://github.com/ethosagent/ethos/blob/main/extensions/gateway/src/voice-pipeline.ts"
click node_wake "https://github.com/ethosagent/ethos/blob/main/extensions/voice-satellite/src/wake-engine.ts"
click node_mcp "https://github.com/ethosagent/ethos/blob/main/apps/mcp-server/src/server.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_web,node_webapi,node_gateway,node_user,node_mcpclients toneBlue
class node_agentloop,node_provider,node_context toneAmber
class node_personality,node_memory,node_sessions,node_teams,node_learning toneMint
class node_storage,node_fsstorage,node_cryptostorage toneRose
class node_voice,node_wake,node_mcp,node_channels toneIndigo
```

## Components

### User surfaces

- [Ethos CLI](https://github.com/ethosagent/ethos/blob/main/apps/ethos/src/index.ts): `apps/ethos/src/index.ts`
- [Web app](https://github.com/ethosagent/ethos/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Web API](https://github.com/ethosagent/ethos/blob/main/apps/web-api/src/index.ts): `apps/web-api/src/index.ts`
- [Messaging gateway](https://github.com/ethosagent/ethos/blob/main/apps/ethos/src/commands/gateway.ts): `apps/ethos/src/commands/gateway.ts`

### Agent runtime

- [Agent loop](https://github.com/ethosagent/ethos/tree/main/packages/core/src/agent-loop): `packages/core/src/agent-loop`
- **Model provider**
- [Context compaction](https://github.com/ethosagent/ethos/blob/main/packages/types/src/context-engine.ts): `packages/types/src/context-engine.ts`

### Agent capabilities

- [Personality system](https://github.com/ethosagent/ethos/blob/main/apps/web-api/src/services/personalities.service.ts): `apps/web-api/src/services/personalities.service.ts`
- [Memory](https://github.com/ethosagent/ethos/blob/main/apps/web-api/src/services/memory.service.ts): `apps/web-api/src/services/memory.service.ts`
- [Sessions](https://github.com/ethosagent/ethos/blob/main/apps/web-api/src/features/sessions/service.ts): `apps/web-api/src/features/sessions/service.ts`
- [Team coordination](https://github.com/ethosagent/ethos/blob/main/apps/web-api/src/services/teams.service.ts): `apps/web-api/src/services/teams.service.ts`
- [Learning pipeline](https://github.com/ethosagent/ethos/blob/main/packages/wiring/src/learning-pipeline.ts): `packages/wiring/src/learning-pipeline.ts`

### Platform services

- [Scoped storage](https://github.com/ethosagent/ethos/blob/main/packages/core/src/agent-loop/scoped-storage.ts): `packages/core/src/agent-loop/scoped-storage.ts`
- [Filesystem storage](https://github.com/ethosagent/ethos/blob/main/packages/storage-fs/src/scoped-storage.ts): `packages/storage-fs/src/scoped-storage.ts`
- [Encrypted storage](https://github.com/ethosagent/ethos/blob/main/extensions/storage-crypto/src/crypto-storage.ts): `extensions/storage-crypto/src/crypto-storage.ts`

### Integrations

- [Voice pipeline](https://github.com/ethosagent/ethos/blob/main/extensions/gateway/src/voice-pipeline.ts): `extensions/gateway/src/voice-pipeline.ts`
- [Wake engine](https://github.com/ethosagent/ethos/blob/main/extensions/voice-satellite/src/wake-engine.ts): `extensions/voice-satellite/src/wake-engine.ts`
- [MCP server](https://github.com/ethosagent/ethos/blob/main/apps/mcp-server/src/server.ts): `apps/mcp-server/src/server.ts`

### Other components

- **User**
- **Messaging services**
- **MCP clients**

## Connections

- 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