How robjvan/icos works
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: conversation.service.ts Conversation runtime · observation.ts Agent orchestration · conversation.controller.ts Conversation API · llm.client.ts LLM client
Components 24
Web client
- Web application
web-client/src/app/components/chat-ui-component/chat-ui-component.ts - Core API client
web-client/src/app/services/core-api.service.ts
Agent runtime
- Conversation API
core/src/conversation/conversation.controller.ts - Conversation runtime
core/src/conversation/conversation.service.ts - Agent orchestration
core/src/agent/observation.ts - LLM client
core/src/llm/llm.client.ts - Provider registry
core/src/providers/provider-registry.service.ts - Session persistence
core/src/session/sqlite-session.repository.ts
Memory and identity
- Memory recall
core/src/memory/recall.service.ts - Epistemic memory
core/src/memory/sqlite-claim.repository.ts - Memory promotion
core/src/memory/promotion.service.ts - Persistent persona
core/src/persona/persona.repository.ts - Persona review
core/src/persona/persona-review.service.ts
Tools and integrations
- Skills
core/src/skills/skill.service.ts - Tool execution
core/src/tools/tool-execution.service.ts - MCP connections
core/src/mcp/mcp-connection.service.ts - Message channels
core/src/channels/channel-delivery.service.ts
Safety and operations
- Human approvals
core/src/approvals/approval.service.ts - Claim verification
core/src/hallucination/hallucination-guard.service.ts - Scheduled jobs
core/src/cron/cron-scheduler.service.ts - Realtime events
core/src/realtime/realtime.gateway.ts
Other components
- User
- Model provider
- MCP server
Connections 24
- User → Web application: sends messages
README.md - Web application → Core API client: requests API
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
README.md - Provider registry → LLM client: resolves endpoints
core/src/providers/provider-registry.service.ts - Conversation runtime → Session persistence: persists sessions
README.md - Conversation runtime → Memory recall: recalls context
README.md - Memory recall → Epistemic memory: reads beliefs
- Memory promotion → Epistemic memory: promotes claims
README.md - Human approvals → Memory promotion: authorizes promotion
README.md - Persona review → Persistent persona: updates identity
core/src/persona/persona-review.service.ts - Conversation runtime → Persistent persona: grounds context
README.md - Agent orchestration → Skills: uses skills
README.md - Agent orchestration → Tool execution: invokes tools
README.md - MCP connections → MCP server: connects tools
README.md - MCP connections → Tool execution: bridges tools
README.md - Message channels → Conversation API: delivers messages
- Claim verification → Agent orchestration: checks claims
README.md - Scheduled jobs → Agent orchestration: schedules runs
- Conversation runtime → Realtime events: streams updates
README.md - Human approvals → Realtime events: publishes changes
core/src/approvals/approval.service.ts