System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Serena is an IDE-like toolkit designed for AI coding agents, providing semantic code retrieval, editing, refactoring, and debugging capabilities. It operates at the symbol level, exploiting the relational structure of codebases to allow agents to work more efficiently than with primitive text-based search. The system integrates with various LLM clients via the Model Context Protocol (MCP), serving as a bridge between high-level agent instructions and low-level code manipulations.
The architecture is centered around a multi-layered configuration system and a dual-backend approach for semantic analysis, supporting both open-source Language Servers (LSP) and a dedicated JetBrains IDE plugin. This allows Serena to support over 40 programming languages while providing advanced features like interactive debugging and cross-file refactoring.
Sources: README.md:1-25, src/serena/config/serena_config.py:230-245
Core Components and Backend Integration
The Serena architecture consists of the MCP Server, a configuration engine, a memory management system, and interchangeable semantic backends.
The diagram above illustrates the flow from the AI client through the Serena MCP server to the underlying semantic backends.
Sources: README.md:95-120, src/serena/config/serena_config.py:230-250
Semantic Backends
Serena supports two primary backends for code analysis:
- Language Servers (LSP): Uses the
SolidLSPlibrary to spawn and manage open-source language servers. This is the default backend and supports a wide range of languages. - JetBrains Plugin: A specialized backend that leverages the deep analysis capabilities of JetBrains IDEs (IntelliJ, PyCharm, etc.) for advanced refactoring and debugging.
| Backend | Implementation Detail | Key Capability |
|---|---|---|
| LSP | LanguageBackend.LSP | Symbol overview, find references, find declaration. |
| JetBrains | LanguageBackend.JETBRAINS | Interactive debugging, cross-file move/inline, type hierarchy. |
Sources: src/serena/config/serena_config.py:230-260, README.md:135-155
Configuration System
Serena uses a hierarchical, composable configuration system that allows for global, project-specific, and context-specific overrides.
Configuration Layers
- Global Configuration (
serena_config.yml): Managed in the user's home directory (default~/.serena). It stores registered projects and global settings like thelanguage_backendandweb_dashboardpreferences. - Project Configuration (
project.yml): Located in the.serenafolder of a project root. It defines project-specific languages, ignored paths, and custom prompts. - Local Overrides (
project.local.yml): Allows developers to override project settings locally without committing them to version control. - Modes: Composable YAML fragments (e.g.,
editing.yml,onboarding.yml) that dynamically adjust the toolset and system prompts based on the current task.
Sources: src/serena/config/serena_config.py:65-110, src/serena/config/serena_config.py:328-360, src/serena/config/serena_config.py:726-750
Memory Management System
The memory system is designed for long-lived agent workflows, enabling knowledge sharing across sessions. It follows a "Discovery Model" where information is stored in a graph-like structure.
- Discovery Model: Agents start with
mem:coreas the root and follow references to more specific memories (e.g.,mem:tech_stack,mem:conventions). - Storage: Memories are stored as files within the project's
.serena/memoriesdirectory or in a global user directory. - Maintenance: Includes tools for checking stale references (
serena memories check) and automatic reference updates during renames.
Sources: src/serena/resources/memory_maintenance.md:1-25, src/serena/resources/config/prompt_templates/simple_tool_outputs.yml:10-35
Web Dashboard and Monitoring
Serena provides a web-based dashboard for real-time monitoring of agent activities, tool usage statistics, and log inspection.
The sequence diagram shows how the frontend dashboard polls the Serena server for configuration, logs, and tool statistics.
Sources: src/serena/resources/dashboard/dashboard.js:285-320, src/serena/resources/dashboard/dashboard.js:633-660
Key Dashboard Features
- Execution Queue: Tracks active, queued, and cancelled tool executions.
- Tool Stats: Visualizes input/output tokens and tool call frequency using Chart.js.
- Live Logs: Provides a real-time stream of server events with log levels (DEBUG, INFO, WARNING, ERROR).
- Configuration Editor: Allows editing of global and project configurations directly through the browser.
Sources: src/serena/resources/dashboard/dashboard.js:460-500, src/serena/resources/dashboard/dashboard.js:820-850, src/serena/resources/dashboard/index.html:1-100
Workflow and Agent Interaction
The agent interacts with Serena primarily through symbolic tools. The system prompt instructs the agent to minimize reading full files, instead using symbols to build a mental model of the code.
Standard Workflow
- Onboarding: The agent calls the
onboardingtool to identify project structure and read memory conventions. - Initial Instructions: The agent reads the 'Serena Instructions Manual' via the
initial_instructionstool. - Symbolic Retrieval: Uses
get_symbols_overvieworfind_symbolto locate relevant code. - Symbolic Editing: Applies changes using
replace_symbol_bodyorinsert_after_symbolrather than line-based edits.
Sources: src/serena/tools/workflow_tools.py:12-45, src/serena/resources/config/prompt_templates/system_prompt.yml:10-50
Summary
The Serena system architecture prioritizes semantic understanding and resource efficiency. By abstracting code manipulation into symbol-aware toolsets and providing a robust configuration and memory framework, it transforms AI agents from "text surgeons" into "informed architects." The modularity of its backends ensures that it can scale from lightweight LSP-based analysis to heavy-duty IDE-integrated refactoring.
Sources: README.md:180-200, src/serena/config/serena_config.py:230-260