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
)

---

<!-- PORTABILITY:START -->

Cross-Client Portability

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

• GitHub Copilot: keep the folder in a Copilot-visible skill or plugin path, or wrap the workflow as project instructions if the host does not support portable skill folders directly.
• Claude Code: keep the folder in a local skills directory or a compatible plugin or marketplace source.
• Codex: install or sync the folder into $CODEX_HOME/skills/<skill-name> and restart Codex after major changes.
• Gemini CLI: this repository generates a project command named /skills:serena-usage from this skill. Rebuild commands with python scripts/export-gemini-skill.py serena-usage and then run /commands reload inside Gemini CLI.

<!-- PORTABILITY:END -->

<!-- MCP:START -->

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.

<!-- MCP:END -->

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.

Changelog

[2026-04-25] - Version 1.2 Verification Protocol Refresh

Added

• Added a Verification Protocol section with skill-specific pass/fail checks, one pressure-test scenario, and a measurable success metric.
• Added guidance to leverage native parallel subagent dispatch and 200k+ context windows where available.

Changed

• Updated SKILL.md frontmatter to version: "1.2" and last_updated: 2026-04-25.
• Reframed activation guidance toward symptom -> action triggers and standardized two-stage review wording where applicable.

[2026-04-24] - Version 1.1 Refresh

Changed

• Updated the SKILL frontmatter version to 1.1 for the 2026-04-24 catalog refresh.

[2026-04-24] - Skill Refresh

Changed

• Standardized the SKILL frontmatter with version metadata, last-updated date, tags, and a concise catalog description.
• Reformatted the portability and MCP guidance with a preferred server line, a copy-paste fallback prompt, and consistent bullet lists.
• Added a catalog-standard Anti-Patterns section and refreshed the Related Skills links at the end of the skill.

[2026-04-24] - Catalog Audit Cleanup

Fixed

• Removed obsolete standalone Skill Paths guidance that duplicated the generated portability section.

All notable changes to this skill will be documented in this file.

[2026-04-04] - Cross-Client Portability Refresh

Changed

• Added a standard portability note covering GitHub Copilot, Claude Code, Codex, and Gemini CLI.
• Documented the preferred MCP server surface for this skill and a local no-MCP fallback workflow.

Tested

• Validated SKILL.md frontmatter, portability sections, and Gemini export readiness with python scripts/validate-skills.py.

[2026-03-09] - Workspace Modernization

Added

• Added a 2026-03-09 maintenance entry after reviewing the skill; it remained the project memory workflow standard for repo maintenance.

[2026-02-28] — Description Rewrite & Cross-References

Changed

• Rewrote skill description to ~200 characters with clear, specific activation keywords
• Improved keyword specificity to reduce overlap with related skills

Added

• ## Related Skills cross-reference table with 2-4 related skills and "Use When" guidance

Complete Refactoring Workflow with Serena

Scenario

Rename the class RecipeService to RecipeRepository and its method getAll to findAll across a TypeScript project. Update all references and document the decision.

---

Step 1: Check Onboarding

Ensure Serena is initialized for the project.

Tool: check_onboarding_performed
Parameters: {}

Response:
  Onboarding has been performed. Project: Kitchen Odyssey
  Languages detected: TypeScript, JavaScript
  Files indexed: 47

Step 2: Read Active Context

Understand current project state before making changes.

Tool: read_memory
Parameters:
  name: "active-context"

Response:
  ## Current Focus
  Refactoring service layer to follow repository pattern.

  ## Recent Changes
  - Migrated database calls from controllers to services
  - Added TypeScript strict mode

Step 3: Get Symbols Overview

Map the file structure before diving into specifics.

Tool: get_symbols_overview
Parameters:
  relative_path: "src/services/RecipeService.ts"
  depth: 1

Response:
  Classes:
    RecipeService (lines 8-95)
      Methods:
        constructor (line 12)
        getAll (line 20)
        getById (line 35)
        create (line 48)
        update (line 62)
        delete (line 78)
  
  Interfaces:
    RecipeFilters (lines 1-6)

Step 4: Find the Target Class

Read the class declaration (without full body) to understand its interface.

Tool: find_symbol
Parameters:
  name_path_pattern: "RecipeService"
  include_body: false
  depth: 1
  relative_path: "src/services/RecipeService.ts"

Response:
  Symbol: RecipeService (class)
  Path: src/services/RecipeService.ts:8-95
  
  Children:
    constructor(db: Database)
    getAll(filters?: RecipeFilters): Promise<Recipe[]>
    getById(id: string): Promise<Recipe | null>
    create(data: CreateRecipeDTO): Promise<Recipe>
    update(id: string, data: UpdateRecipeDTO): Promise<Recipe>
    delete(id: string): Promise<void>

Step 5: Read the Method to Rename

Get the full implementation of getAll to prepare for renaming.

Tool: find_symbol
Parameters:
  name_path_pattern: "RecipeService/getAll"
  include_body: true

Response:
  async getAll(filters?: RecipeFilters): Promise<Recipe[]> {
    const query = this.db.collection('recipes').find();
    if (filters?.category) {
      query.where('category', filters.category);
    }
    if (filters?.search) {
      query.where('title', { $regex: filters.search, $options: 'i' });
    }
    return query.sort({ createdAt: -1 }).toArray();
  }

Step 6: Find All References to the Class

Understand the impact radius before making changes.

Tool: find_referencing_symbols
Parameters:
  name_path_pattern: "RecipeService"
  relative_path: "src/services/RecipeService.ts"

Response:
  References found: 5

  1. src/controllers/RecipeController.ts:3
     import { RecipeService } from '../services/RecipeService';
     → Inside: top-level import

  2. src/controllers/RecipeController.ts:10
     constructor(private recipeService: RecipeService) {}
     → Inside: RecipeController/constructor

  3. src/routes/recipes.ts:5
     import { RecipeService } from '../services/RecipeService';
     → Inside: top-level import

  4. src/routes/recipes.ts:12
     const service = new RecipeService(db);
     → Inside: registerRecipeRoutes

  5. src/tests/recipe.test.ts:4
     import { RecipeService } from '../services/RecipeService';
     → Inside: top-level import

Step 7: Find All References to the Method

Tool: find_referencing_symbols
Parameters:
  name_path_pattern: "RecipeService/getAll"
  relative_path: "src/services/RecipeService.ts"

Response:
  References found: 3

  1. src/controllers/RecipeController.ts:18
     const recipes = await this.recipeService.getAll(filters);
     → Inside: RecipeController/index

  2. src/routes/recipes.ts:16
     const recipes = await service.getAll(req.query);
     → Inside: registerRecipeRoutes (anonymous handler)

  3. src/tests/recipe.test.ts:22
     const result = await service.getAll();
     → Inside: describe "RecipeService" / it "returns all recipes"

Step 8: Plan Changes

Based on reference analysis, the change set is:

Also rename the file: RecipeService.ts → RecipeRepository.ts

Step 9: Execute — Replace Class Body

Tool: replace_symbol_body
Parameters:
  name_path_pattern: "RecipeService"
  relative_path: "src/services/RecipeService.ts"
  new_body: |
    export class RecipeRepository {
      private db: Database;

      constructor(db: Database) {
        this.db = db;
      }

      async findAll(filters?: RecipeFilters): Promise<Recipe[]> {
        const query = this.db.collection('recipes').find();
        if (filters?.category) {
          query.where('category', filters.category);
        }
        if (filters?.search) {
          query.where('title', { $regex: filters.search, $options: 'i' });
        }
        return query.sort({ createdAt: -1 }).toArray();
      }

      async getById(id: string): Promise<Recipe | null> { ... }
      async create(data: CreateRecipeDTO): Promise<Recipe> { ... }
      async update(id: string, data: UpdateRecipeDTO): Promise<Recipe> { ... }
      async delete(id: string): Promise<void> { ... }
    }

Response:
  Symbol body replaced successfully.

Step 10: Update References

Update each reference file (using standard file edit tools):

src/controllers/RecipeController.ts:

• import { RecipeService } → import { RecipeRepository }
• private recipeService: RecipeService → private recipeRepo: RecipeRepository
• this.recipeService.getAll( → this.recipeRepo.findAll(

src/routes/recipes.ts:

• import { RecipeService } → import { RecipeRepository }
• new RecipeService(db) → new RecipeRepository(db)
• service.getAll( → service.findAll(

src/tests/recipe.test.ts:

• import { RecipeService } → import { RecipeRepository }
• new RecipeService( → new RecipeRepository(
• service.getAll() → service.findAll()

Step 11: Verify — Old Name Has No References

Tool: find_referencing_symbols
Parameters:
  name_path_pattern: "RecipeService"

Response:
  References found: 0
  ✓ No remaining references to old class name.

Tool: search_for_pattern
Parameters:
  substring_pattern: "getAll"
  relative_path: "src/"
  restrict_search_to_code_files: true

Response:
  No matches found.
  ✓ No remaining references to old method name.

Step 12: Verify — New Name Has Expected References

Tool: find_referencing_symbols
Parameters:
  name_path_pattern: "RecipeRepository"

Response:
  References found: 5
  ✓ Matches expected count from Step 6.

Step 13: Update Memories

Record the refactoring decision for future sessions.

Tool: edit_memory
Parameters:
  name: "system-patterns"
  content: |
    ## Data Access Pattern
    Using Repository pattern for all data access layers.
    - Services renamed to Repositories (e.g., RecipeService → RecipeRepository)
    - Method naming: findAll, findById, create, update, delete
    - Each repository takes a Database instance in constructor

    ## Naming Convention
    - Repositories: {Entity}Repository (e.g., RecipeRepository, UserRepository)
    - DTOs: Create{Entity}DTO, Update{Entity}DTO
    - Filters: {Entity}Filters

Tool: edit_memory
Parameters:
  name: "active-context"
  content: |
    ## Current Focus
    Completed RecipeService → RecipeRepository refactor.

    ## Recent Changes
    - Renamed RecipeService to RecipeRepository
    - Renamed getAll to findAll across codebase
    - Established repository naming convention

    ## Next Steps
    - Apply same pattern to UserService, CommentService
    - Update API documentation to reflect new names

---

Summary

Key principle: Use symbolic tools to understand impact before editing, then verify after editing. Always update memories so the next session knows what happened.

Serena Memory Management Reference

Overview

Serena's memory system provides persistent project context across AI agent sessions. Memories store architectural decisions, active context, progress tracking, and project intelligence that survives session resets.

Memory Naming Conventions

Use standardized names for core memories to ensure consistency:

Custom Memory Names

For project-specific memories beyond the core set:

• Use lowercase kebab-case: api-contracts, deployment-config
• Prefix with domain: db-schema-decisions, ui-component-inventory
• Be descriptive but concise: auth-flow-decisions not decisions-about-authentication-flow

Memory Lifecycle

Create (write_memory)

Create a new memory when:

• Starting a new project (core memories)
• Discovering a pattern worth preserving
• Making an architectural decision
• Beginning a new task or feature
• Establishing a convention that should persist

Tool: write_memory
Parameters:
  name: "active-context"
  content: |
    ## Current Focus
    Implementing user authentication with OAuth2.

    ## Recent Changes
    - Set up project structure with Next.js 15
    - Configured MongoDB Atlas connection

    ## Next Steps
    - Implement login/signup pages
    - Set up JWT token handling

Read (read_memory)

Read memories at the start of every session and when:

• Resuming work after a break
• Starting a task that may relate to past decisions
• Checking what patterns are established
• Verifying current project status

Tool: read_memory
Parameters:
  name: "system-patterns"

Update (edit_memory)

Update (not replace) a memory when:

• Adding new information to existing context
• Correcting outdated details
• Marking tasks as complete
• Recording new decisions alongside existing ones

Tool: edit_memory
Parameters:
  name: "progress"
  content: |
    ## What Works
    - User authentication (login, signup, logout)
    - Recipe CRUD operations
    - Search with filters

    ## In Progress
    - Rating system
    - Comment moderation

    ## Known Issues
    - Session timeout not handled gracefully

Delete (delete_memory)

Delete a memory when:

• A task is fully complete and archived
• Information has been consolidated into another memory
• The memory is no longer relevant to the project

Tool: delete_memory
Parameters:
  name: "task-003-deprecated-feature"

Memory Content Structure Guidelines

project-brief

## Project Name
Kitchen Odyssey - Recipe Management Application

## Core Requirements
- User authentication and profiles
- Recipe CRUD with rich media
- Search and filtering
- Social features (comments, ratings)

## Goals
- Responsive, accessible UI
- Sub-200ms API response times
- Support 1000+ concurrent users

## Scope Boundaries
- No payment processing
- No real-time collaboration (v1)

active-context

## Current Focus
[One sentence describing the primary task]

## Recent Changes
- [Change 1 with date]
- [Change 2 with date]

## Active Decisions
- Chose [X] over [Y] because [reason]

## Blockers
- [Any blocking issues]

## Next Steps
1. [Immediate next action]
2. [Follow-up action]

system-patterns

## Architecture
[High-level architecture description]

## Design Patterns
- Repository pattern for data access
- Context providers for shared state
- Compound components for complex UI

## Component Relationships
- AuthContext wraps all protected routes
- RootLayout provides navigation and sidebar

## Conventions
- File naming: PascalCase for components, camelCase for utilities
- API routes follow REST conventions

task-{id}

## Task: [Title]
**Status:** In Progress
**Priority:** High

## Description
[What needs to be done]

## Approach
[How it will be implemented]

## Subtasks
- [x] Subtask 1
- [ ] Subtask 2
- [ ] Subtask 3

## Progress Log
### 2026-02-11
- Started implementation of feature X
- Discovered dependency on module Y

Best Practices

Session Continuity

1. Always read core memories first: Start every session by reading active-context and progress 2. Update before ending: Write session accomplishments to active-context and progress before finishing 3. Record decisions immediately: Don't wait — write architectural decisions to system-patterns as they happen 4. Link related memories: Reference other memory names in content (e.g., "See system-patterns for architecture details")

Memory Size Considerations

• Keep individual memories focused and under 2000 words
• Split large memories into related sub-memories (e.g., api-contracts-auth, api-contracts-recipes)
• Use bullet points and tables over prose for scannability
• Remove resolved items from active-context — move completed work to progress

Linking Related Memories

Reference other memories by name within content:

## Authentication Decision
Chose JWT over sessions. Full rationale in `tech-context`.
Implementation tracked in `task-005-auth`.
Related patterns documented in `system-patterns` under "Auth Flow".

Anti-Patterns

• Stale memories: Forgetting to update active-context leads to confusion next session
• Duplicate information: Store facts in one canonical memory, reference it from others
• Overly broad memories: A single memory covering everything becomes hard to parse
• Missing task memories: Not creating task-{id} memories means losing implementation context
• No progress log: Without dated entries, you can't reconstruct the timeline of decisions

Symbol-Based Code Navigation Guide

Overview

Serena provides semantic code navigation through symbol-aware tools. Instead of reading entire files line-by-line, you navigate by symbol names (classes, functions, methods, variables) — dramatically reducing token usage and improving precision.

Core Tools

get_symbols_overview

Get a high-level map of all symbols in a file. Always start here when exploring an unfamiliar file.

Tool: get_symbols_overview
Parameters:
  relative_path: "src/services/AuthService.ts"
  depth: 0  # 0 = top-level only (default)

Return format: Symbols grouped by kind (classes, functions, variables, interfaces) in compact JSON.

depth parameter:

• 0 — Top-level symbols only (class names, standalone functions)
• 1 — One level deep (class + its methods)
• 2 — Two levels deep (class + methods + nested items)

Use depth: 1 when you need to see a class's API surface without reading implementations.

find_symbol

Locate and optionally read a specific symbol by its name path.

Tool: find_symbol
Parameters:
  name_path_pattern: "AuthService/login"
  include_body: true
  relative_path: "src/services/AuthService.ts"  # optional, speeds up search

Name path patterns:

Key parameters:

• include_body: false — Returns signature/declaration only (saves tokens)
• include_body: true — Returns full implementation
• depth: 1 — Also returns immediate children (methods of a class)
• relative_path — Scope search to a specific file or directory

find_referencing_symbols

Find all places where a symbol is used across the codebase.

Tool: find_referencing_symbols
Parameters:
  name_path_pattern: "AuthService/login"
  relative_path: "src/services/AuthService.ts"  # file containing the definition

Returns:

• File paths where the symbol is referenced
• Code snippets around each reference
• Symbolic context (which function/class contains the reference)

Practical Workflows

Exploring a Class Hierarchy

Goal: Understand a class, its API, and how it's used.

Step 1: Get file overview
  get_symbols_overview(relative_path="src/models/User.ts", depth=1)
  → See class name, all methods, properties

Step 2: Read specific methods of interest
  find_symbol(name_path_pattern="User/validatePassword", include_body=true)
  → Full implementation of validatePassword

Step 3: Check inheritance/implementation
  find_symbol(name_path_pattern="User", include_body=false, depth=0)
  → See class declaration with extends/implements

Step 4: Find subclasses
  search_for_pattern(substring_pattern="extends User", restrict_search_to_code_files=true)
  → All classes that extend User

Finding All Callers of a Function

Goal: Understand the impact of changing a function's signature.

Step 1: Locate the function
  find_symbol(name_path_pattern="calculateTax", include_body=false)
  → Find where it's defined, see its signature

Step 2: Find all references
  find_referencing_symbols(name_path_pattern="calculateTax", relative_path="src/utils/tax.ts")
  → Every file and location that calls calculateTax

Step 3: Understand each call site
  For each reference, find_symbol on the containing function with include_body=true
  → See context of how calculateTax is called

Understanding Module Dependencies

Goal: Map how modules connect before restructuring.

Step 1: Overview of the module
  get_symbols_overview(relative_path="src/services/", depth=1)
  → All exported symbols across service files

Step 2: Pick key exports and trace usage
  find_referencing_symbols(name_path_pattern="RecipeService")
  → Who imports and uses RecipeService

Step 3: Check internal dependencies
  search_for_pattern(
    substring_pattern="import.*from",
    relative_path="src/services/RecipeService.ts"
  )
  → What RecipeService itself depends on

Targeted Reading of a Large File

Goal: Understand a 500+ line file without reading it all.

Step 1: Get the map
  get_symbols_overview(relative_path="src/components/DataTable.tsx", depth=1)
  → See all components, hooks, helpers in the file

Step 2: Read only what matters
  find_symbol(name_path_pattern="DataTable/handleSort", include_body=true)
  find_symbol(name_path_pattern="DataTable/renderHeader", include_body=true)
  → Read just the 2 methods relevant to your task

Step 3: Skip the rest
  → No need to read 400 lines of unrelated rendering code

Safe Refactoring Workflow

Goal: Rename a method ensuring no breakage.

Step 1: Find the symbol
  find_symbol(name_path_pattern="UserService/getUser", include_body=true)
  → See current implementation

Step 2: Find all call sites
  find_referencing_symbols(name_path_pattern="UserService/getUser")
  → Every location that calls getUser

Step 3: Plan the change
  Review each call site to confirm the rename is safe

Step 4: Execute replacement
  replace_symbol_body(name_path_pattern="UserService/getUser", new_body="...")
  → Replace the method definition

Step 5: Update references
  For each call site, use appropriate edit tools to update the name

Step 6: Verify
  find_referencing_symbols for the OLD name → should return nothing
  find_referencing_symbols for the NEW name → should match expected count

search_for_pattern (Fallback)

When you don't know exact symbol names, use pattern search as a discovery step:

Tool: search_for_pattern
Parameters:
  substring_pattern: "async.*fetch.*recipe"
  restrict_search_to_code_files: true
  relative_path: "src/"  # scope to src directory
  context_lines_before: 2
  context_lines_after: 2

Tips:

• Use non-greedy quantifiers: .*? instead of .*
• Scope with relative_path to avoid huge result sets
• Set restrict_search_to_code_files: true to skip config/data files
• Use context_lines_before/after to see surrounding code

Performance Tips

1. Always scope searches with `relative_path` — Searching the entire repo is slow 2. Use `include_body: false` first — Read signatures before implementations 3. Start with `depth: 0` — Drill deeper only when needed 4. Prefer symbolic tools over `read_file` — One find_symbol call replaces reading 50+ lines 5. Combine overview + targeted reads — get_symbols_overview then find_symbol for specific items 6. Use `search_for_pattern` as last resort — Symbolic tools are faster and more precise