# oraios/serena architecture

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

- Interactive diagram: https://gitdiagram.com/oraios/serena
- Repository: https://github.com/oraios/serena

## Overview

Serena is an MCP-based IDE capability layer for coding agents: an agent invokes tools to retrieve, edit, refactor, or debug project code, with semantic analysis supplied by either SolidLSP language servers or the JetBrains plugin. Project configuration and project services establish the workspace; tools also expose REPL workflows and persistent memories. The README documents the capabilities and backend choices; source-index references support the internal links shown here, but several runtime implementations were not sampled.

Main entry points: [`src/serena/project.py`](https://github.com/oraios/serena/blob/main/src/serena/project.py) (Project services), [`src/serena/ls_manager.py`](https://github.com/oraios/serena/blob/main/src/serena/ls_manager.py) (Language server manager), [`src/solidlsp/ls.py`](https://github.com/oraios/serena/blob/main/src/solidlsp/ls.py) (SolidLSP client), [`src/serena/tools`](https://github.com/oraios/serena/tree/main/src/serena/tools) (Agent tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Agent interface"]
  node_mcp["MCP server<br/>[mcp.py]"]
  node_tools["Agent tools"]
  node_repl["REPL interface<br/>[facade.py]"]
end

subgraph group_project["Project services"]
  node_config["Serena config<br/>[serena_config.py]"]
  node_projectsvc["Project services<br/>[project.py]"]
  node_querytools["Project query tools"]
  node_editor["Code editing<br/>[code_editor.py]"]
end

subgraph group_semantic["Semantic backends"]
  node_lsmanager["Language server manager<br/>[ls_manager.py]"]
  node_solidls["SolidLSP client<br/>[ls.py]"]
  node_lsconfig["Server registry<br/>[ls_config.py]"]
  node_adapters["Language adapters"]
  node_lsprocess["Server processes<br/>[ls_process.py]"]
  node_protocol["LSP protocol<br/>[server.py]"]
  node_jetbrains["JetBrains client"]
end

subgraph group_support["Memory and diagnostics"]
  node_memory["Memory manager<br/>[memory_manager.py]"]
  node_filesystem["File system<br/>[file_system.py]"]
  node_dashboard["Dashboard"]
end

node_agent(("Coding agent"))
node_plugin["JetBrains plugin"]
node_language_servers["Language servers"]

node_agent -->|"connects via MCP"| node_mcp
node_mcp -->|"exposes tools"| node_tools
node_agent -->|"invokes"| node_tools
node_tools -.->|"queries project"| node_projectsvc
node_querytools -->|"queries symbols"| node_jetbrains
node_querytools -->|"routes queries"| node_projectsvc
node_projectsvc -->|"uses settings"| node_config
node_projectsvc -->|"manages servers"| node_lsmanager
node_projectsvc -->|"uses memories"| node_memory
node_projectsvc -.->|"supports edits"| node_editor
node_lsmanager -->|"starts servers"| node_solidls
node_lsmanager -->|"uses registry"| node_lsconfig
node_solidls -->|"uses configuration"| node_lsconfig
node_lsconfig -->|"registers adapters"| node_adapters
node_solidls -->|"manages process"| node_lsprocess
node_lsprocess -->|"uses protocol"| node_protocol
node_adapters -.->|"launches"| node_language_servers
node_jetbrains -->|"calls plugin API"| node_plugin
node_memory -->|"reads and writes"| node_filesystem
node_repl -.->|"offers execution interface"| node_agent
node_projectsvc -.->|"serves project status"| node_dashboard

click node_mcp "https://github.com/oraios/serena/blob/main/src/serena/mcp.py"
click node_tools "https://github.com/oraios/serena/tree/main/src/serena/tools"
click node_repl "https://github.com/oraios/serena/blob/main/src/serena/repl/facade.py"
click node_config "https://github.com/oraios/serena/blob/main/src/serena/config/serena_config.py"
click node_projectsvc "https://github.com/oraios/serena/blob/main/src/serena/project.py"
click node_querytools "https://github.com/oraios/serena/blob/main/src/serena/tools/query_project_tools.py"
click node_editor "https://github.com/oraios/serena/blob/main/src/serena/code_editor.py"
click node_lsmanager "https://github.com/oraios/serena/blob/main/src/serena/ls_manager.py"
click node_solidls "https://github.com/oraios/serena/blob/main/src/solidlsp/ls.py"
click node_lsconfig "https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py"
click node_adapters "https://github.com/oraios/serena/tree/main/src/solidlsp/language_servers"
click node_lsprocess "https://github.com/oraios/serena/blob/main/src/solidlsp/ls_process.py"
click node_protocol "https://github.com/oraios/serena/blob/main/src/solidlsp/lsp_protocol_handler/server.py"
click node_jetbrains "https://github.com/oraios/serena/blob/main/src/serena/jetbrains/jetbrains_plugin_client.py"
click node_memory "https://github.com/oraios/serena/blob/main/src/serena/memories/memory_manager.py"
click node_filesystem "https://github.com/oraios/serena/blob/main/src/serena/util/file_system.py"
click node_dashboard "https://github.com/oraios/serena/blob/main/src/serena/dashboard/dashboard_viewer.py"

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_mcp,node_tools,node_repl toneBlue
class node_config,node_projectsvc,node_querytools,node_editor toneAmber
class node_lsmanager,node_solidls,node_lsconfig,node_adapters,node_lsprocess,node_protocol,node_jetbrains,node_language_servers toneMint
class node_memory,node_filesystem,node_dashboard toneRose
class node_agent,node_plugin toneIndigo
```

## Components

### Agent interface

- [MCP server](https://github.com/oraios/serena/blob/main/src/serena/mcp.py): `src/serena/mcp.py`
- [Agent tools](https://github.com/oraios/serena/tree/main/src/serena/tools): `src/serena/tools`
- [REPL interface](https://github.com/oraios/serena/blob/main/src/serena/repl/facade.py): `src/serena/repl/facade.py`

### Project services

- [Serena config](https://github.com/oraios/serena/blob/main/src/serena/config/serena_config.py): `src/serena/config/serena_config.py`
- [Project services](https://github.com/oraios/serena/blob/main/src/serena/project.py): `src/serena/project.py`
- [Project query tools](https://github.com/oraios/serena/blob/main/src/serena/tools/query_project_tools.py): `src/serena/tools/query_project_tools.py`
- [Code editing](https://github.com/oraios/serena/blob/main/src/serena/code_editor.py): `src/serena/code_editor.py`

### Semantic backends

- [Language server manager](https://github.com/oraios/serena/blob/main/src/serena/ls_manager.py): `src/serena/ls_manager.py`
- [SolidLSP client](https://github.com/oraios/serena/blob/main/src/solidlsp/ls.py): `src/solidlsp/ls.py`
- [Server registry](https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py): `src/solidlsp/ls_config.py`
- [Language adapters](https://github.com/oraios/serena/tree/main/src/solidlsp/language_servers): `src/solidlsp/language_servers`
- [Server processes](https://github.com/oraios/serena/blob/main/src/solidlsp/ls_process.py): `src/solidlsp/ls_process.py`
- [LSP protocol](https://github.com/oraios/serena/blob/main/src/solidlsp/lsp_protocol_handler/server.py): `src/solidlsp/lsp_protocol_handler/server.py`
- [JetBrains client](https://github.com/oraios/serena/blob/main/src/serena/jetbrains/jetbrains_plugin_client.py): `src/serena/jetbrains/jetbrains_plugin_client.py`

### Memory and diagnostics

- [Memory manager](https://github.com/oraios/serena/blob/main/src/serena/memories/memory_manager.py): `src/serena/memories/memory_manager.py`
- [File system](https://github.com/oraios/serena/blob/main/src/serena/util/file_system.py): `src/serena/util/file_system.py`
- [Dashboard](https://github.com/oraios/serena/blob/main/src/serena/dashboard/dashboard_viewer.py): `src/serena/dashboard/dashboard_viewer.py`

### Other components

- **Coding agent**
- **JetBrains plugin**
- **Language servers**

## Connections

- Coding agent → MCP server: connects via MCP
- MCP server → Agent tools: exposes tools
- Coding agent → Agent tools: invokes
- Agent tools → Project services: queries project
- Project query tools → JetBrains client: queries symbols (evidence: `src/serena/tools/query_project_tools.py`)
- Project query tools → Project services: routes queries (evidence: `src/serena/tools/query_project_tools.py`)
- Project services → Serena config: uses settings (evidence: `src/serena/project.py`)
- Project services → Language server manager: manages servers (evidence: `src/serena/project.py`)
- Project services → Memory manager: uses memories (evidence: `src/serena/project.py`)
- Project services → Code editing: supports edits
- Language server manager → SolidLSP client: starts servers (evidence: `src/serena/ls_manager.py`)
- Language server manager → Server registry: uses registry (evidence: `src/serena/ls_manager.py`)
- SolidLSP client → Server registry: uses configuration (evidence: `src/solidlsp/ls.py`)
- Server registry → Language adapters: registers adapters (evidence: `src/solidlsp/ls_config.py`)
- SolidLSP client → Server processes: manages process (evidence: `src/solidlsp/ls.py`)
- Server processes → LSP protocol: uses protocol (evidence: `src/solidlsp/ls_process.py`)
- Language adapters → Language servers: launches
- JetBrains client → JetBrains plugin: calls plugin API (evidence: `src/serena/jetbrains/jetbrains_plugin_client.py`)
- Memory manager → File system: reads and writes (evidence: `src/serena/memories/memory_manager.py`)
- REPL interface → Coding agent: offers execution interface
- Project services → Dashboard: serves project status
