Project Workflow and State
Relevant source files
The following files were used as context for generating this wiki page:
The Project Workflow and State in Serena defines how the agent discovers, initializes, and maintains state across coding tasks. It relies on a symbol-aware, project-based structure that distinguishes between global configurations and specific project environments. The workflow is designed to be "agent-first," utilizing high-level abstractions for retrieval and editing rather than low-level text manipulation.
The system manages state through three primary mechanisms: the global SerenaConfig, project-specific ProjectConfig files, and a durable memory management system. This ensures that information about code architecture, technical stacks, and project conventions persists across sessions and users.
Sources: README.md:12-25, src/serena/config/serena_config.py:650-680
Project Initialization and Configuration
Initialization begins with either manual registration or automatic discovery of a project root. Serena uses a tiered configuration model where global settings can be overridden by local project settings.
Global vs. Local Configuration
The global configuration (serena_config.yml) tracks all registered projects and default settings like the language backend (LSP or JetBrains). Project-specific state is stored in a .serena/ directory within the project root, containing project.yml for shared settings and project.local.yml for user-specific overrides.
| Configuration Level | File Name | Primary Purpose |
|---|---|---|
| Global | serena_config.yml | Project registration, global tool defaults, dashboard settings. |
| Project Shared | project.yml | Language selection, ignored paths, shared project invariants. |
| Project Local | project.local.yml | Local overrides that should not be committed (e.g., specific tool paths). |
Sources: src/serena/config/serena_config.py:330-360, src/serena/config/serena_config.py:465-480, src/serena/config/serena_config.py:1010-1030
Discovery and Activation Flow
When an agent starts work, it must identify the active project. Serena resolves the project folder location using templates like $projectDir/.serena to locate data folders, memories, and caches.
The diagram shows the sequence from task initiation to project-state stabilization.
Sources: src/serena/config/serena_config.py:410-440, src/serena/tools/workflow_tools.py:18-30, src/serena/resources/config/prompt_templates/system_prompt.yml:7-12
Agent Onboarding Workflow
The OnboardingTool is the critical entry point for establishing project state. It identifies the project structure and essential tasks (building, testing, linting) and instructs the agent to create durable memory files.
Onboarding Steps
- Environment Detection: The tool detects the operating system and system-level configurations.
- Memory Seeding: It ensures a
memory_maintenancememory exists to define style and naming conventions. - Durable Information Gathering: The agent is prompted to fill specific memory slots:
mem:core: Top-level source map and project-wide invariants.mem:tech_stack: Languages, frameworks, and build tools.mem:conventions: Code style, naming, and design patterns.mem:task_completion: Commands for verification (lint, test).
Sources: src/serena/tools/workflow_tools.py:15-32, src/serena/resources/config/prompt_templates/simple_tool_outputs.yml:9-35
State Management through Memories
Serena employs a "Discovery Model" for state, where agents are encouraged to build a graph of memories rather than reading full files.
Memory Discovery Model
Memories are grouped into topics or folders (e.g., mem:frontend/core). References between memories use the mem: prefix, allowing the agent to progressively discover information.
This diagram illustrates the hierarchical reference structure recommended for memory maintenance.
Sources: src/serena/resources/memory_maintenance.md:5-18, src/serena/resources/config/prompt_templates/simple_tool_outputs.yml:25-30
Memory Persistence and Hierarchy
- Global Memories: Stored in
~/.serena/memories/global, accessible across all projects. - Project Memories: Stored in the project's
.serena/directory. - Read-Only Patterns: Configuration can define
read_only_memory_patternsto prevent agents from modifying specific architectural docs.
Sources: src/serena/config/serena_config.py:100-115, src/serena/config/serena_config.py:270-285
Execution Tracking and Real-Time State
The Serena Dashboard provides a real-time view of the system state, including tool usage statistics and the execution queue.
Execution Queue Monitoring
The dashboard tracks active, queued, and last-finished executions. It allows users to monitor "agent drift" (where the agent might stop using semantic tools) and manually intervene.
| State Component | Description | Data Source |
|---|---|---|
active_executions | Currently running tool calls or tasks. | /queued_task_executions |
last_execution | Success/failure status of the most recent task. | /last_execution |
tool_stats | Token counts and call frequencies per tool. | /get_tool_stats |
Sources: src/serena/resources/dashboard/dashboard.js:350-400, src/serena/resources/dashboard/dashboard.js:650-675
Runtime State Polling Flow
The Dashboard UI maintains state by polling multiple endpoints simultaneously.
The sequence diagram shows how the dashboard remains synchronized with the server's internal state.
Sources: src/serena/resources/dashboard/dashboard.js:410-440, src/serena/resources/dashboard/dashboard.js:615-630
Conclusion
The Project Workflow and State in Serena centers on transitioning the agent from a stateless observer to a project-aware participant. By combining structured YAML configurations, a symbol-aware initialization phase, and a graph-based memory system, Serena ensures that complex project context is preserved and efficiently accessible without exhausting the LLM's context window.
Sources: README.md:145-160, src/serena/resources/config/prompt_templates/system_prompt.yml:15-35