# robjvan/icos architecture

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

- Interactive diagram: https://gitdiagram.com/robjvan/icos
- Repository: https://github.com/robjvan/icos

## Overview

ICOS is a self-hosted cognitive-agent runtime with an Angular web client. The main workflow is a user conversation handled by the core runtime, which consults a provider-independent model boundary, streams results, and persists sessions; surrounding capabilities include epistemic memory, human review, persona, tools/MCP, and safety controls. The README documents the broad workflow and feature set; sampled source and the SOURCE INDEX support only some internal call relationships, so uncertain wiring is left unconnected or marked dashed.

Main entry points: [`core/src/conversation/conversation.service.ts`](https://github.com/robjvan/icos/blob/master/core/src/conversation/conversation.service.ts) (Conversation runtime), [`core/src/agent/observation.ts`](https://github.com/robjvan/icos/blob/master/core/src/agent/observation.ts) (Agent orchestration), [`core/src/conversation/conversation.controller.ts`](https://github.com/robjvan/icos/blob/master/core/src/conversation/conversation.controller.ts) (Conversation API), [`core/src/llm/llm.client.ts`](https://github.com/robjvan/icos/blob/master/core/src/llm/llm.client.ts) (LLM client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Web application"]
  node_api_client["Core API client"]
end

subgraph group_runtime["Agent runtime"]
  node_turn_api["Conversation API"]
  node_turn_service["Conversation runtime"]
  node_agent_loop["Agent orchestration<br/>[observation.ts]"]
  node_llm["LLM client<br/>[llm.client.ts]"]
  node_provider_registry["Provider registry"]
  node_session_store[("Session persistence")]
end

subgraph group_memory["Memory and identity"]
  node_memory_recall["Memory recall<br/>[recall.service.ts]"]
  node_memory_store[("Epistemic memory")]
  node_memory_promotion["Memory promotion"]
  node_persona[("Persistent persona")]
  node_persona_review["Persona review"]
end

subgraph group_integrations["Tools and integrations"]
  node_skills["Skills<br/>[skill.service.ts]"]
  node_tools["Tool execution"]
  node_mcp["MCP connections"]
  node_channels["Message channels"]
end

subgraph group_governance["Safety and operations"]
  node_approvals["Human approvals"]
  node_hallucination["Claim verification"]
  node_cron["Scheduled jobs"]
  node_realtime["Realtime events"]
end

node_user(("User"))
node_model_provider(("Model provider"))
node_mcp_server(("MCP server"))

node_user -->|"sends messages"| node_web
node_web -->|"requests API"| node_api_client
node_api_client -->|"calls REST"| node_turn_api
node_turn_api -.->|"handles turns"| node_turn_service
node_turn_service -.->|"runs agent"| node_agent_loop
node_agent_loop -.->|"requests completion"| node_llm
node_llm -->|"sends requests"| node_model_provider
node_provider_registry -->|"resolves endpoints"| node_llm
node_turn_service -->|"persists sessions"| node_session_store
node_turn_service -->|"recalls context"| node_memory_recall
node_memory_recall -.->|"reads beliefs"| node_memory_store
node_memory_promotion -->|"promotes claims"| node_memory_store
node_approvals -->|"authorizes promotion"| node_memory_promotion
node_persona_review -->|"updates identity"| node_persona
node_turn_service -->|"grounds context"| node_persona
node_agent_loop -->|"uses skills"| node_skills
node_agent_loop -->|"invokes tools"| node_tools
node_mcp -->|"connects tools"| node_mcp_server
node_mcp -->|"bridges tools"| node_tools
node_channels -.->|"delivers messages"| node_turn_api
node_hallucination -->|"checks claims"| node_agent_loop
node_cron -.->|"schedules runs"| node_agent_loop
node_turn_service -->|"streams updates"| node_realtime
node_approvals -->|"publishes changes"| node_realtime

click node_web "https://github.com/robjvan/icos/blob/master/web-client/src/app/components/chat-ui-component/chat-ui-component.ts"
click node_api_client "https://github.com/robjvan/icos/blob/master/web-client/src/app/services/core-api.service.ts"
click node_turn_api "https://github.com/robjvan/icos/blob/master/core/src/conversation/conversation.controller.ts"
click node_turn_service "https://github.com/robjvan/icos/blob/master/core/src/conversation/conversation.service.ts"
click node_agent_loop "https://github.com/robjvan/icos/blob/master/core/src/agent/observation.ts"
click node_llm "https://github.com/robjvan/icos/blob/master/core/src/llm/llm.client.ts"
click node_provider_registry "https://github.com/robjvan/icos/blob/master/core/src/providers/provider-registry.service.ts"
click node_session_store "https://github.com/robjvan/icos/blob/master/core/src/session/sqlite-session.repository.ts"
click node_memory_recall "https://github.com/robjvan/icos/blob/master/core/src/memory/recall.service.ts"
click node_memory_store "https://github.com/robjvan/icos/blob/master/core/src/memory/sqlite-claim.repository.ts"
click node_memory_promotion "https://github.com/robjvan/icos/blob/master/core/src/memory/promotion.service.ts"
click node_persona "https://github.com/robjvan/icos/blob/master/core/src/persona/persona.repository.ts"
click node_persona_review "https://github.com/robjvan/icos/blob/master/core/src/persona/persona-review.service.ts"
click node_skills "https://github.com/robjvan/icos/blob/master/core/src/skills/skill.service.ts"
click node_tools "https://github.com/robjvan/icos/blob/master/core/src/tools/tool-execution.service.ts"
click node_mcp "https://github.com/robjvan/icos/blob/master/core/src/mcp/mcp-connection.service.ts"
click node_channels "https://github.com/robjvan/icos/blob/master/core/src/channels/channel-delivery.service.ts"
click node_approvals "https://github.com/robjvan/icos/blob/master/core/src/approvals/approval.service.ts"
click node_hallucination "https://github.com/robjvan/icos/blob/master/core/src/hallucination/hallucination-guard.service.ts"
click node_cron "https://github.com/robjvan/icos/blob/master/core/src/cron/cron-scheduler.service.ts"
click node_realtime "https://github.com/robjvan/icos/blob/master/core/src/realtime/realtime.gateway.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_web,node_api_client,node_user toneBlue
class node_turn_api,node_turn_service,node_agent_loop,node_llm,node_provider_registry,node_session_store toneAmber
class node_memory_recall,node_memory_store,node_memory_promotion,node_persona,node_persona_review,node_mcp_server toneMint
class node_skills,node_tools,node_mcp,node_channels toneRose
class node_approvals,node_hallucination,node_cron,node_realtime,node_model_provider toneIndigo
```

## Components

### Web client

- [Web application](https://github.com/robjvan/icos/blob/master/web-client/src/app/components/chat-ui-component/chat-ui-component.ts): `web-client/src/app/components/chat-ui-component/chat-ui-component.ts`
- [Core API client](https://github.com/robjvan/icos/blob/master/web-client/src/app/services/core-api.service.ts): `web-client/src/app/services/core-api.service.ts`

### Agent runtime

- [Conversation API](https://github.com/robjvan/icos/blob/master/core/src/conversation/conversation.controller.ts): `core/src/conversation/conversation.controller.ts`
- [Conversation runtime](https://github.com/robjvan/icos/blob/master/core/src/conversation/conversation.service.ts): `core/src/conversation/conversation.service.ts`
- [Agent orchestration](https://github.com/robjvan/icos/blob/master/core/src/agent/observation.ts): `core/src/agent/observation.ts`
- [LLM client](https://github.com/robjvan/icos/blob/master/core/src/llm/llm.client.ts): `core/src/llm/llm.client.ts`
- [Provider registry](https://github.com/robjvan/icos/blob/master/core/src/providers/provider-registry.service.ts): `core/src/providers/provider-registry.service.ts`
- [Session persistence](https://github.com/robjvan/icos/blob/master/core/src/session/sqlite-session.repository.ts): `core/src/session/sqlite-session.repository.ts`

### Memory and identity

- [Memory recall](https://github.com/robjvan/icos/blob/master/core/src/memory/recall.service.ts): `core/src/memory/recall.service.ts`
- [Epistemic memory](https://github.com/robjvan/icos/blob/master/core/src/memory/sqlite-claim.repository.ts): `core/src/memory/sqlite-claim.repository.ts`
- [Memory promotion](https://github.com/robjvan/icos/blob/master/core/src/memory/promotion.service.ts): `core/src/memory/promotion.service.ts`
- [Persistent persona](https://github.com/robjvan/icos/blob/master/core/src/persona/persona.repository.ts): `core/src/persona/persona.repository.ts`
- [Persona review](https://github.com/robjvan/icos/blob/master/core/src/persona/persona-review.service.ts): `core/src/persona/persona-review.service.ts`

### Tools and integrations

- [Skills](https://github.com/robjvan/icos/blob/master/core/src/skills/skill.service.ts): `core/src/skills/skill.service.ts`
- [Tool execution](https://github.com/robjvan/icos/blob/master/core/src/tools/tool-execution.service.ts): `core/src/tools/tool-execution.service.ts`
- [MCP connections](https://github.com/robjvan/icos/blob/master/core/src/mcp/mcp-connection.service.ts): `core/src/mcp/mcp-connection.service.ts`
- [Message channels](https://github.com/robjvan/icos/blob/master/core/src/channels/channel-delivery.service.ts): `core/src/channels/channel-delivery.service.ts`

### Safety and operations

- [Human approvals](https://github.com/robjvan/icos/blob/master/core/src/approvals/approval.service.ts): `core/src/approvals/approval.service.ts`
- [Claim verification](https://github.com/robjvan/icos/blob/master/core/src/hallucination/hallucination-guard.service.ts): `core/src/hallucination/hallucination-guard.service.ts`
- [Scheduled jobs](https://github.com/robjvan/icos/blob/master/core/src/cron/cron-scheduler.service.ts): `core/src/cron/cron-scheduler.service.ts`
- [Realtime events](https://github.com/robjvan/icos/blob/master/core/src/realtime/realtime.gateway.ts): `core/src/realtime/realtime.gateway.ts`

### Other components

- **User**
- **Model provider**
- **MCP server**

## Connections

- User → Web application: sends messages (evidence: `README.md`)
- Web application → Core API client: requests API (evidence: `web-client/src/app/services/core-api.service.ts`)
- Core API client → Conversation API: calls REST
- Conversation API → Conversation runtime: handles turns
- Conversation runtime → Agent orchestration: runs agent
- Agent orchestration → LLM client: requests completion
- LLM client → Model provider: sends requests (evidence: `README.md`)
- Provider registry → LLM client: resolves endpoints (evidence: `core/src/providers/provider-registry.service.ts`)
- Conversation runtime → Session persistence: persists sessions (evidence: `README.md`)
- Conversation runtime → Memory recall: recalls context (evidence: `README.md`)
- Memory recall → Epistemic memory: reads beliefs
- Memory promotion → Epistemic memory: promotes claims (evidence: `README.md`)
- Human approvals → Memory promotion: authorizes promotion (evidence: `README.md`)
- Persona review → Persistent persona: updates identity (evidence: `core/src/persona/persona-review.service.ts`)
- Conversation runtime → Persistent persona: grounds context (evidence: `README.md`)
- Agent orchestration → Skills: uses skills (evidence: `README.md`)
- Agent orchestration → Tool execution: invokes tools (evidence: `README.md`)
- MCP connections → MCP server: connects tools (evidence: `README.md`)
- MCP connections → Tool execution: bridges tools (evidence: `README.md`)
- Message channels → Conversation API: delivers messages
- Claim verification → Agent orchestration: checks claims (evidence: `README.md`)
- Scheduled jobs → Agent orchestration: schedules runs
- Conversation runtime → Realtime events: streams updates (evidence: `README.md`)
- Human approvals → Realtime events: publishes changes (evidence: `core/src/approvals/approval.service.ts`)
