| name | serena-usage |
| version | 1.2 |
| last_updated | "2026-04-25T00:00:00.000Z" |
| tags | ["serena","usage","workflow","automation","guidance"] |
| description | Serena MCP for project memory and code navigation. Use when managing Serena memories, navigating symbols, performing intelligent refactoring, or maintaining context/continuity across AI agent sessions. |
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
- 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
get_current_config
activate_project project="path/to/project"
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 memoriesread_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:
- Use
list_memories to review all existing memories
- Identify if any existing memory covers the topic
- If relevant memory exists: Use
edit_memory with new information + updated timestamp
- 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 |
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":
- Pass/fail: The Serena Usage workflow names the agent boundary, delegated scope, and expected return artifact.
- Pass/fail: Context passed to helpers is minimal, task-local, and free of hidden expected answers.
- Pass/fail: Results are integrated only after evidence, diffs, or citations are checked by the controller.
- Pressure-test scenario: Run the workflow on two similar tasks that must not share assumptions or leaked context.
- 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):
| 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'
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)
| Category | Memory Name | Update Frequency | When to Read |
|---|
| Status & Plan | project-overview | After phase completion, architecture decisions | Always first when starting session |
| Task Tracking | database-integration-implementation-plan-task | After phase completion | When starting backend/frontend work |
| SQL Fixes | csx3006-sql-fixes-2026-02-13.md | When fixing database issues | During SQL/database work |
| Notion Sync | notion-implementation-tracking | When Notion sync pattern changes | Before updating Notion pages |
| Feature Specs | admin-features, recipe-features, auth-context | Feature changes/improvements | Implementing related features |
| Reference | routing-layouts, storage-data-model, ui-components-and-styling | Rarely changes | Quick lookup for these topics |
Scripts
- Memory Backup — PowerShell script to backup Serena memory files with timestamps
Examples
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
| When adding info about... | Check memory... | If exists... | If not... |
|---|
| Admin features/moderation | admin-features | Update it | Create admin-features |
| Recipe CRUD/search | recipe-features | Update it | Create recipe-features |
| Authentication/session | auth-context | Update it | Create auth-context |
| SQL fixes today | {topic}-fixes-{date} | Update it | Create new with today's date |
| Architecture decisions | system-patterns | Update it | Create system-patterns |
| Overall project status | project-overview | ALWAYS update it | Create project-overview |
| Component specs | ui-components-and-styling | Update it | Create if different topic |
Edit Memory Pattern
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"
)
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.
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.
