Serena Usage

Serena Usage

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

• Leverage native parallel subagent dispatch and 200k+ context windows where available.

Activation Conditions

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

MUST activate when:

• Serena is available for the project
• Task requires project memory continuity
• Task requires symbol navigation or Serena refactoring workflow
• 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

Critical: Always verify project activation FIRST with get_current_config before any Serena operations

Prerequisites

• Serena MCP Server configured and running
• Project activated (use get_current_config to verify, or activate_project if not activated)
• Onboarding completed for the target project (use check_onboarding_performed first)
• If not activated, run activate_project with project name or path
• If not onboarded, run onboarding tool after activation

Onboarding Workflow

First-Time Project Setup

1. Check activation: Call get_current_config to verify if project is activated
2. Activate if needed: If not activated, call activate_project with project name or path
3. Check onboarding: Call check_onboarding_performed to verify onboarding status
4. Read manual: If not onboarded, call initial_instructions to read the Serena Instructions Manual
5. Initialize: Call onboarding to complete project setup
6. 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

Activation Check Pattern

# Always verify activation first
get_current_config
# If no active project, activate it
activate_project project="path/to/project"
# Then proceed with onboarding check
check_onboarding_performed

Project Activation

Why Activation Matters

Project activation is the first step when working with Serena. It tells Serena which project to work with and initializes the workspace context.

Activation Workflow

1. Check current status: Call get_current_config to see if a project is already activated
2. Activate if needed: If no active project, call:

   activate_project project="project-name"
   # OR with path:
   activate_project project="path/to/project/directory"
   

3. Verify activation: Call get_current_config again to confirm activation succeeded
4. Proceed with onboarding: Once activated, check if onboarding is needed

Activation Best Practices

• Always check get_current_config before attempting any Serena operations
• Use the workspace root path when activating
• Activation is session-specific — you may need to reactivate in new sessions
• After activation, the project context is available for all subsequent Serena operations

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 Creation Workflow

CRITICAL: ALWAYS check for relevant existing memories before creating new ones

Step-by-Step Process

1. List available memories: Use list_memories to see all existing memories
2. Analyze relevance: Identify if any existing memory covers the same topic/concept
3. Check memory content: If relevant memories found, use read_memory to examine their content
4. Match criteria:
   • Same feature/technology/topic domain
   • Overlapping purpose or scope
   • Related architectural decisions
   • Similar problem space or concern
5. Decision:
   • IF relevant memory exists: Update the existing memory using edit_memory with new information and current timestamp
   • IF no relevant memory exists: Create new memory using write_memory

Matching Guidelines

A new memory entry is relevant to an existing memory if:

Update Pattern for Existing Memories

When updating existing memories, follow this structure:

## {Topic} — Updated [YYYY-MM-DD HH:MM]

### [Date] - Update
- [New information or decision]
- [Implementation details or findings]
- [Related changes or impacts]
- [Next actions or considerations]

### Previous Context
[Preserve existing relevant information]

Examples of Memory Consolidation

Scenario 1: Adding new admin feature specs

Existing: admin-features.md (500 bytes)
New info: New user moderation workflow specs
Action: Update admin-features.md with new section, update timestamp

Scenario 2: Fixing SQL bug

Existing: csx3006-sql-fixes-2026-02-13.md
New info: Another SQL bug related to same issue
Action: Update csx3006-sql-fixes-2026-02-13.md, add new fix details, update timestamp

Scenario 3: New authentication implementation detail

Existing: auth-context.md
New info: Session management implementation specifics
Action: Update auth-context.md with new implementation section, update timestamp

Scenario 4: New database-fix memory for different issue

Existing: csx3006-sql-fixes-2026-02-13.md (column name fixes)
New info: Index optimization fixes (different topic)
Action: Create NEW memory: csx3006-index-fixes-2026-02-16.md

When to Create New Memories

Create a NEW memory only when:

• Different domain: Topic is fundamentally different from existing memories
• Major milestone: New phase or significant project shift
• New technology stack: Unrelated to existing technical context
• Time-based tracking: Fix memories, daily updates, or dated logs
• Overwhelming size: Existing memory would exceed 5-10 KB with additions

Examples of when to create new memories:

Existing: admin-features.md
New: Performance analysis reports → Create NEW: performance-analysis.md

Existing: ui-components-and-styling.md
New: Mobile responsiveness specifications → Create NEW: mobile-responsive.md

Existing: csx3006-sql-fixes-2026-02-13.md (database schema corrections)
New: API endpoint bug fixes → Create NEW: api-fixes-2026-02-16.md

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. Verify activation: get_current_config → check if project is activated
2. Activate if needed: If no active project, activate_project → activate the workspace
3. Check onboarding: check_onboarding_performed → verify onboarding status
4. Complete onboarding if needed using onboarding workflow
5. list_memories → review all 10 available project memories
6. 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)
7. Begin work with current phase context

During a Session

• SQL/database work: Check if {topic}-fixes-{date}.md exists → update OR create new memory for bug fixes
• Feature implementation: Check if {feature-name}.md exists → update OR create new memory for feature specs
• Phase completion: Update project-overview.md with new status percentage and current timestamp
• 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
• NEW information flow:
  1. Use list_memories to review all existing memories
  2. Identify if any existing memory covers the topic
  3. If relevant memory exists: Use edit_memory with new information + updated timestamp
  4. If no relevant memory: Use write_memory to create new memory

Best Practices

• ALWAYS check activation before any Serena operations using get_current_config
• ALWAYS check for relevant existing memories with list_memories before creating new ones
• CRITICAL: Use edit_memory to update existing memories with new timestamp rather than creating duplicates
• Activate project first if not already activated using activate_project
• Check onboarding after activation, 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
• When adding information to existing memories, update timestamp to YYYY-MM-DD HH:MM format

Troubleshooting

Anti-Patterns

• Starting without a clear success condition: The skill becomes advice-shaped instead of workflow-shaped.
• Skipping the bundled references or scripts: You lose the proven path the catalog is trying to preserve.
• Claiming completion without concrete evidence: A future agent or reviewer cannot trust the result or resume the work safely.

Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The Serena Usage workflow names the agent boundary, delegated scope, and expected return artifact.
2. Pass/fail: Context passed to helpers is minimal, task-local, and free of hidden expected answers.
3. Pass/fail: Results are integrated only after evidence, diffs, or citations are checked by the controller.
4. Pressure-test scenario: Run the workflow on two similar tasks that must not share assumptions or leaked context.
5. Success metric: Zero context leakage; every delegated output is independently reviewable.

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. get_current_config → verify project is activated
2. If not activated, activate_project with current workspace path
3. check_onboarding_performed → verify onboarding status
4. Complete onboarding if needed using standard workflow
5. list_memories → verify 10 memories available
6. Read project-overview → current status (38% complete, Phases 1-3 done)
7. Read database-integration-implementation-plan-task → Phase 4 tasks (TASK-057 to TASK-092)
8. 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 → Check if {topic}-fixes-{date}.md exists → update OR create new memory
• Major milestones → update project-overview.md with new timestamp
• Phase completion → update database-integration-implementation-plan-task.md with progress
• Notion sync → update notion-implementation-tracking.md with sync status
• ALL updates → Include current timestamp in format: "Updated: YYYY-MM-DD HH:MM"

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)
• INFORMATION THAT SHOULD UPDATE AN EXISTING MEMORY instead of creating a new one

Memory Update vs Creation Quick Reference

Decision Tree

Need to store information?
│
├─ Check: `list_memories`
│  │
│  ├─ Existing memory covers this topic?
│  │  │
│  │  ├─ YES → Use `edit_memory` with new info + updated timestamp
│  │  │
│  │  └─ NO → Use `write_memory` to create new memory
│  │
│  └─ Proceed with work

Common Match Patterns

Edit Memory Pattern

# Always use this format when updating existing memories
edit_memory(
  memory_file_name="existing-memory-name",
  needle="section or content to replace or append after",
  repl="new information with timestamp:\n\n## [Section] — Updated YYYY-MM-DD HH:MM\n\n- [new info]",
  mode="literal" # or "regex" as appropriate
)

Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.

• GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the workflow in project instructions when folder discovery is unavailable.
• Claude Code: keep the folder in a local skills directory or a compatible plugin source.
• Codex: install or sync the folder into $CODEX_HOME/skills/serena-usage and restart Codex after major changes.

MCP Availability And Fallback

Preferred MCP Server: Serena MCP

• Fallback prompt: "Use the Serena Usage skill without MCP. Rely on the local SKILL.md, bundled references or scripts, and manual verification. Show the exact commands, evidence, and final checks you used before concluding."
• Use rg, git diff, targeted file reads, and local Markdown memory files when Serena is unavailable.
• Keep a lightweight Memory Bank in repo docs or notes so project continuity still survives across sessions.

Related Skills

• development-workflow: Use it when the workflow also needs planning, quality gates, and delivery tracking.
• documentation-quality: Use it when the workflow also needs documentation review standards and quality gates.
• verification-before-completion: Use it when the workflow also needs final evidence checks before claiming completion.
• code-quality: Use it when the workflow also needs two-stage review (spec compliance first, then code quality), maintainability, and refactoring guidance.