Serena Usage

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

Skill Paths

Workspace skills: .github/skills/
Global skills: C:/Users/LOQ/.agents/skills/

Activation Conditions

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

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

Check current status: Call get_current_config to see if a project is already activated

Activate if needed: If no active project, call:

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

Verify activation: Call get_current_config again to confirm activation succeeded
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

Operation	Tool	Purpose
List all	`list_memories`	See available memories
Read one	`read_memory`	Access specific memory content
Create	`write_memory`	Store new information
Update	`edit_memory`	Modify existing memory
Remove	`delete_memory`	Clean up obsolete information

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

Memory Name	Purpose
`project-brief`	Foundation document defining core requirements and goals. Shapes all other memories. Created at project start.
`product-context`	Why this project exists, problems it solves, how it should work, and user experience goals
`active-context`	Current work focus, recent changes, and next steps with active decisions and considerations
`system-patterns`	System architecture, key technical decisions, design patterns in use, and component relationships
`tech-context`	Technologies used, development setup, technical constraints, and dependencies
`progress`	What works, what's left to build, current status, and known issues

Task Management Memories

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

Memory Name	Purpose
`task-{id}`	Individual task tracking (e.g., TASK001-implement-login.md) with original request, thought process, implementation plan, and progress logs
`task-index`	Master list of all tasks with IDs, names, statuses (Pending/In Progress/Completed/Abandoned), and last updated dates

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:

Create a new task memory with a unique Task ID
Document the thought process about the approach
Develop an implementation plan
Set an initial status
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

List available memories: Use list_memories to see all existing memories
Analyze relevance: Identify if any existing memory covers the same topic/concept
Check memory content: If relevant memories found, use read_memory to examine their content
Match criteria:
- Same feature/technology/topic domain
- Overlapping purpose or scope
- Related architectural decisions
- Similar problem space or concern
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:

Criteria	Example
Same feature area	"admin-features" already covers admin workflows → add new admin task details to it
Same technology	"auth-context" already covers authentication → add new auth implementation details to it
Related architecture	"system-patterns" covers architecture decisions → add new architectural choices to it
Same domain concern	"ui-components-and-styling" covers component library → add new component specs to it
Project-wide update	"project-overview" covers overall status → add general project updates to it

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

Tool	Use Case
`find_symbol`	Locate specific classes, functions, variables by name path
`find_referencing_symbols`	Find all usages of a symbol across the codebase
`get_symbols_overview`	High-level summary of symbols in a file

Navigation Workflow

Use get_symbols_overview on a file to understand its structure
Use find_symbol to locate a specific definition
Use find_referencing_symbols to understand impact before changes

Code Refactoring

Safe Refactoring with Serena

Tool	Operation
`rename_symbol`	Rename across all references
`replace_symbol_body`	Replace implementation of a function/method
`insert_after_symbol`	Add new code after a definition
`insert_before_symbol`	Add new code before a definition

Refactoring Workflow

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

File Search

Tool	Purpose
`find_file`	Locate files matching a name pattern
`list_dir`	Browse directory contents
`search_for_pattern`	Search for text/regex patterns across codebase

Task Adherence

Serena provides reflection tools to maintain focus:

Tool	When to Use
`think_about_collected_information`	After gathering context — is it sufficient?
`think_about_task_adherence`	After many interactions — am I still on track?
`think_about_whether_you_are_done`	Before concluding — have I completed everything?

Session Workflow

Starting a Session

Verify activation: get_current_config → check if project is activated
Activate if needed: If no active project, activate_project → activate the workspace
Check onboarding: check_onboarding_performed → verify onboarding status
Complete onboarding if needed using onboarding workflow
list_memories → review all 10 available project memories
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)
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

Issue	Solution
Project not activated	Run `get_current_config` to verify, then `activate_project` with project path
Onboarding not detected	After activation, run `onboarding` tool explicitly
Memory not found	Check exact name with `list_memories`
Symbol not found	Ensure file is indexed; try broader name
Stale memories	Use `edit_memory` to update with current state and timestamp
Conflicting memories	Delete outdated entry, merge into single memory with consolidated content
Duplicate memories	Avoid by ALWAYS checking `list_memories` before creating new ones; use `edit_memory` to update existing
Unsure which memory to update	Use `list_memories` → review purpose of each → read relevant memories → update the most appropriate one

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):

Memory	Purpose	Notes
`project-overview`	Project status, tech stack, next steps	Central reference, read first
`database-integration-implementation-plan-task`	138-task plan v2.0 status	38% complete (Phases 1-3 done)
`csx3006-sql-fixes-2026-02-13`	SQL script corrections	Keep for debugging
`notion-implementation-tracking`	Notion sync protocol	Update when completing tasks
`admin-features`	Admin workflow, moderation, user management	Feature specs only
`recipe-features`	Recipe CRUD, search, reviews, engagement	Feature specs only
`auth-context`	Session-based authentication flow	Phase 4 backend, Phase 5 integration
`routing-layouts`	Route configuration and page layouts	HashRouter with layout guards
`storage-data-model`	Pre-Phase 5 localStorage structure	Will be replaced by API
`ui-components-and-styling`	Component library and Tailwind v4	Reusable components

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

get_current_config → verify project is activated
If not activated, activate_project with current workspace path
check_onboarding_performed → verify onboarding status
Complete onboarding if needed using standard workflow
list_memories → verify 10 memories available
Read project-overview → current status (38% complete, Phases 1-3 done)
Read database-integration-implementation-plan-task → Phase 4 tasks (TASK-057 to TASK-092)
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'