Serena Usage

Effective usage of the Serena MCP Server for project memory management, code intelligence, and maintaining continuity across AI agent sessions.

When to Use This Skill

• •Managing project memories for AI session continuity
• •Navigating codebases using symbol-based tools
• •Performing code refactoring with Serena's symbol management
• •Setting up Serena onboarding for new projects
• •Using Serena's memory system for project context preservation

No-Activation Conditions

Do NOT activate this skill when:

• •User requests general programming help without Serena context
• •Task is in a workspace not Serena-enabled
• •User asks basic questions about VS Code or AI tools without Serena
• •Request is for regular development tasks without Serena tool usage
• •User wants simple file operations without Serena workspace context
• •Task involves Serena documentation but not using Serena tools in workflow

Prerequisites

• •Serena MCP Server configured and running
• •Onboarding completed for the target project (use check_onboarding_performed first)
• •If not onboarded, run onboarding tool before any operations

Onboarding Workflow

First-Time Project Setup

1. •Call check_onboarding_performed to verify status
2. •If not performed, call initial_instructions to read the Serena Instructions Manual
3. •Call onboarding to initialize the project
4. •Serena analyzes the project structure and creates initial context

What Onboarding Captures

• •Project language and framework detection
• •Directory structure analysis
• •Key file identification
• •Symbol index creation
• •Initial memory scaffolding

Memory Management

Core Concepts

Serena memories persist between sessions, providing continuity for AI agents across work sessions.

Memory Operations

Memory Structure

Serena memories use the Memory Bank naming convention for consistency and clarity. This structure organizes project intelligence into core files and tasks.

Core Files

Task Management Memories

Tasks are managed with dedicated memory files for tracking progress and history.

Task Memory Structure

Each task memory follows this format:

# [Task ID] - [Task Name]

**Status:** [Pending/In Progress/Completed/Abandoned]
**Added:** [Date Added]
**Updated:** [Date Last Updated]

## Original Request
[The original task description as provided by the user]

## Thought Process
[Documentation of the discussion and reasoning that shaped the approach]

## Implementation Plan
- [Step 1]
- [Step 2]
- [Step 3]

## Progress Tracking

**Overall Status:** [Not Started/In Progress/Blocked/Completed] - [Completion Percentage]

### Subtasks
| ID | Description | Status | Updated | Notes |
|----|-------------|--------|---------|-------|
| 1.1 | [Subtask description] | [Complete/In Progress/Not Started/Blocked] | [Date] | [Relevant notes] |

## Progress Log
### [Date]
- Updated subtask 1.1 status to Complete
- Started work on subtask 1.2
- Encountered issue with [specific problem]
- Made decision to [approach/solution]

Task Index Structure

The task-index memory maintains a structured record:

# Tasks Index

## In Progress
- [TASK003] Implement user authentication -Working on OAuth integration
- [TASK005] Create dashboard UI -Building main components

## Pending
- [TASK006] Add export functionality -Planned for next sprint

## Completed
- [TASK001] Project setup -Completed on 2025-03-15
- [TASK002] Create database schema -Completed on 2025-03-17

Commands

When you request add task or create task, the agent will:

1. •Create a new task memory with a unique Task ID
2. •Document the thought process about the approach
3. •Develop an implementation plan
4. •Set an initial status
5. •Update the task-index memory

To view tasks, the command show tasks [filter] will display filtered lists with valid filters:

• •all - Show all tasks regardless of status
• •active - Show only "In Progress" tasks
• •pending - Show only "Pending" tasks
• •completed - Show only "Completed" tasks
• •blocked - Show only "Blocked" tasks
• •recent - Show tasks updated in the last week

When to Update Memories

Update core memories when:

• •After completing significant features or functionality
• •When making architectural decisions
• •Discovering new project patterns or conventions
• •Changing technical stack or dependencies
• •Modifying data models or schemas
• •At the start and end of each work session

Update task memories when:

• •Creating new tasks via "create task" command
• •Making progress on existing tasks
• •Completing subtasks or entire tasks
• •Encountering blockers or issues
• •Changing task status (Pending → In Progress → Completed/Abandoned)

Memory Bank Documentation Guidelines

The Serena memories follow the Memory Bank structure for comprehensive project intelligence. Key guidelines:

Task Progress Updates:

• •Always update both the subtask status table AND the progress log when making progress
• •The subtask table provides quick visual reference of current status
• •The progress log captures the narrative and details of the work process
• •Each progress log entry should include date, accomplishments, challenges, and decisions
• •Update task status in task-index to reflect current progress

Documentation Flow:

New Task → Create task-{id}.py memory → Update task-index
Progress → Update task-{id}.py log table → Update task-index
Discovery → Create/ update appropriate core memory
Architecture Decision → Update system-patterns memory
Completion → Update progress memory → Clear from active tasks

Active-Context Format:

## Active Context — Updated [Date]

### Current Focus
- Implementing user authentication with NextAuth.js
- Building recipe CRUD API routes

### Recent Decisions
- Chose MongoDB Atlas over Cosmos DB for cost
- Using server components for recipe listing page

### Blockers
- Image upload size limit needs investigation

### Next Steps
1. Complete login/signup UI
2. Add recipe creation form
3. Set up image upload to Blob Storage

Memory Writing Guidelines

## Active Context — Updated [Date]

### Current Focus
- Implementing user authentication with NextAuth.js
- Building recipe CRUD API routes

### Recent Decisions
- Chose MongoDB Atlas over Cosmos DB for cost
- Using server components for recipe listing page

### Blockers
- Image upload size limit needs investigation

### Next Steps
1. Complete login/signup UI
2. Add recipe creation form
3. Set up image upload to Blob Storage

Code Navigation

Symbol-Based Navigation

Navigation Workflow

1. •Use get_symbols_overview on a file to understand its structure
2. •Use find_symbol to locate a specific definition
3. •Use find_referencing_symbols to understand impact before changes

Code Refactoring

Safe Refactoring with Serena

Refactoring Workflow

1. •Understand: Use find_symbol and get_symbols_overview
2. •Assess Impact: Use find_referencing_symbols to see all usages
3. •Plan: Think through the changes needed
4. •Execute: Use rename/replace/insert tools
5. •Verify: Re-check references to confirm correctness
6. •Document: Update memories with the change rationale

File Search

Task Adherence

Serena provides reflection tools to maintain focus:

Session Workflow

Starting a Session

1. •list_memories → review all 10 available project memories
2. •read_memory → load relevant memories for current work phase:
   • •Always: Read project-overview (current status, tech stack, next steps)
   • •Phase 4 (Backend): Read database-integration-implementation-plan-task (TASK-057 to TASK-092)
   • •Feature work: Read specific feature memory (admin-features, recipe-features, auth-context)
   • •SQL work: Read csx3006-sql-fixes-2026-02-13.md (column conventions, FK patterns)
   • •Notion sync: Read notion-implementation-tracking.md (update protocol)
3. •Begin work with current phase context

During a Session

• •SQL/database work: Create {topic}-fixes-{date}.md memory for bug fixes (e.g., column name corrections)
• •Feature implementation: Update or create {feature-name}.md memory for feature specs
• •Phase completion: Update project-overview.md with new status percentage
• •Notion updates: Use notion-update-page after completing plan tasks (TASK-001 → TASK-138)
• •Code navigation: Use symbol tools to explore React components and future PHP backend files

Best Practices

• •Always check onboarding before first use on a project
• •Keep memories concise — prefer structured data over prose
• •Update memories incrementally, not in bulk rewrites
• •Use consistent naming for memories across projects (Memory Bank convention)
• •Leverage think_about_* tools for self-reflection on complex tasks
• •For task tracking: Always update both subtask table AND progress log in task memories
• •Keep task-index synchronized with task memory status changes
• •Delete obsolete memories to prevent confusion
• •Use task IDs from task-index as reference when discussing work

Troubleshooting

References & Resources

Documentation

• •Memory Management — Memory naming conventions, lifecycle, and maintenance best practices
• •Symbol Navigation — find_symbol and find_referencing_symbols patterns and workflows

Project-Specific Guide (Recipe Sharing System)

Current Memory Structure (10 active memories):

Session-Start Pattern (Phase 4 — Backend Pending):

1. •list_memories → verify 10 memories available
2. •Read project-overview → current status (38% complete, Phases 1-3 done)
3. •Read database-integration-implementation-plan-task → Phase 4 tasks (TASK-057 to TASK-092)
4. •Begin PHP backend development: backend/config/database.php, backend/helpers/, then backend/api/

Project-Specific Best Practices:

Database Conventions:

• •Database: cookhub (utf8mb4_unicode_ci)
• •Tables: singular (user, recipe, ingredient, etc.)
• •Columns: snake_case, id PKs
• •PK access: WHERE id = ? on parent tables, FK references on child tables
• •FKs: {table}_id columns

Architecture:

• •Plain PHP (no frameworks, no Composer)
• •Structure: backend/{config, helpers, api}/
• •Each API file handles routing via $_SERVER['REQUEST_METHOD']
• •Auth: Session-based (HttpOnly cookies, session table)
• •HTTP: Native fetch() with credentials: 'include'

Documentation Flow:

• •SQL fixes → create {topic}-fixes-{date}.md memory
• •Major milestones → update project-overview.md
• •Phase completion → update database-integration-implementation-plan-task.md
• •Notion sync → update notion-implementation-tracking.md

Naming Patterns Used:

• •Feature memories: lowercase kebab-case (admin-features, recipe-features, auth-context)
• •Fix memories: {name}-fixes-{date}.md
• •Status memories: {project}-updates.md or {plan}-task.md

Memory Reference Table (CSX3006 Project)

Scripts

• •Memory Backup — PowerShell script to backup Serena memory files with timestamps

Examples

• •Refactoring Workflow — 13-step refactoring walkthrough using Serena tools

Memory Management Strategy for This Project

Why 10 memories (not 15 from Memory Bank standard):

• •Project tracks implementation plan via plan/upgrade-database-integration-1.md (138 tasks) instead of task memories
• •No individual task-{id} memories needed (tasks are in plan file)
• •No task-index or progress memories (status in project-overview.md)
• •Feature specs kept concise (admin-features, recipe-features, auth-context at ~500 bytes each)
• •One-line reference memories for quick lookups (routing-layouts, storage-data-model, ui-components-and-styling)

When to create new memories:

• •SQL/script fixes: {topic}-fixes-{date}.md (e.g., csx3006-sql-fixes-2026-02-13.md)
• •Feature documentation: {feature-name}.md (e.g., admin-features.md)
• •Major milestones: Update project-overview.md (status changes, architecture decisions)

When NOT to create memories:

• •Individual tasks (use upgrade-database-integration-1.md task list)
• •Everyday progress (project status tracked in project-overview.md)
• •Code samples (code is in actual files, not memories)
• •Historical one-time events (delete when obsolete)