docs/research/research_serena_mcp_2025-01-16.md
Date: 2025-01-16 Research Depth: Deep Confidence Level: High (90%)
PM Agent documentation references Serena MCP for memory management, but the actual implementation uses repository-scoped local files instead. This creates a documentation-reality mismatch that needs resolution.
Key Finding: Serena MCP exposes NO resources, only tools. The attempted ReadMcpResourceTool call with serena://memories URI failed because Serena doesn't expose MCP resources.
Official Repository: https://github.com/oraios/serena (9.8k stars, MIT license)
Purpose: Semantic code analysis toolkit with LSP integration, providing:
Tools Exposed (25+ tools):
Memory Management:
- write_memory(memory_name, content, max_answer_chars=200000)
- read_memory(memory_name)
- list_memories()
- delete_memory(memory_name)
Thinking Tools:
- think_about_collected_information()
- think_about_task_adherence()
- think_about_whether_you_are_done()
Code Operations:
- read_file, get_symbols_overview, find_symbol
- replace_symbol_body, insert_after_symbol
- execute_shell_command, list_dir, find_file
Project Management:
- activate_project(path)
- onboarding()
- get_current_config()
- switch_modes()
Resources Exposed: NONE
Location: .serena/memories/ (project-specific directory)
Storage Format: Markdown files (human-readable)
Scope: Per-project isolation via project activation
Onboarding: Automatic on first run to build project understanding
Recommended Workflow:
Session End:
1. Create comprehensive summary:
- Current progress and state
- All relevant context for continuation
- Next planned actions
2. Write to memory:
write_memory(
memory_name="session_2025-01-16_auth_implementation",
content="[detailed summary in markdown]"
)
Session Start (New Conversation):
1. List available memories:
list_memories()
2. Read relevant memory:
read_memory("session_2025-01-16_auth_implementation")
3. Continue task with full context restored
Problem: "Broken code when starting a new session" after continuous iterations
Root Causes:
Workarounds:
Duplicate Prevention:
Session Management:
Storage Strategy:
Documentation Says (pm.md lines 34-57):
Session Start Protocol:
1. Context Restoration:
- list_memories() → Check for existing PM Agent state
- read_memory("pm_context") → Restore overall context
- read_memory("current_plan") → What are we working on
- read_memory("last_session") → What was done previously
- read_memory("next_actions") → What to do next
Reality (Actual Implementation):
Session Start Protocol:
1. Repository Detection:
- Bash "git rev-parse --show-toplevel"
→ repo_root
- Bash "mkdir -p $repo_root/docs/memory"
2. Context Restoration (from local files):
- Read docs/memory/pm_context.md
- Read docs/memory/last_session.md
- Read docs/memory/next_actions.md
- Read docs/memory/patterns_learned.jsonl
Mismatch: Documentation references Serena MCP tools that are never called.
Location: docs/memory/ (repository-scoped local files)
File Organization:
docs/memory/
# Session State
pm_context.md # Complete PM state snapshot
last_session.md # Previous session summary
next_actions.md # Planned next steps
checkpoint.json # Progress snapshots (30-min)
# Active Work
current_plan.json # Active implementation plan
implementation_notes.json # Work-in-progress notes
# Learning Database (Append-Only Logs)
patterns_learned.jsonl # Success patterns
solutions_learned.jsonl # Error solutions
mistakes_learned.jsonl # Failure analysis
docs/pdca/[feature]/
plan.md, do.md, check.md, act.md # PDCA cycle documents
Operations: Direct file Read/Write via Claude Code tools (NOT Serena MCP)
✅ Transparent: Files visible in repository ✅ Git-Manageable: Versioned, diff-able, committable ✅ No External Dependencies: Works without Serena MCP ✅ Human-Readable: Markdown and JSON formats ✅ Repository-Scoped: Automatic isolation via git boundary
❌ No Semantic Understanding: Just text files, no code comprehension ❌ Documentation Mismatch: Says Serena, uses local files ❌ Missed Serena Features: Doesn't leverage LSP-powered understanding ❌ Manual Management: No automatic onboarding or context building
| Feature | Serena MCP | Current Implementation | Gap |
|---|---|---|---|
| Memory Storage | .serena/memories/ | docs/memory/ | Different location |
| Access Method | MCP tools | Direct file Read/Write | Different API |
| Semantic Understanding | Yes (LSP-powered) | No (text-only) | Missing capability |
| Onboarding | Automatic | Manual | Missing automation |
| Code Awareness | Symbol-level | None | Missing integration |
| Thinking Tools | Built-in | None | Missing introspection |
| Project Switching | activate_project() | cd + git root | Manual process |
Implementation:
Replace:
- Read docs/memory/pm_context.md
With:
- mcp__serena__read_memory("pm_context")
Replace:
- Write docs/memory/checkpoint.json
With:
- mcp__serena__write_memory(
memory_name="checkpoint",
content=json_to_markdown(checkpoint_data)
)
Add:
- mcp__serena__list_memories() at session start
- mcp__serena__think_about_task_adherence() during work
- mcp__serena__activate_project(repo_root) on init
Benefits:
Drawbacks:
.serena/ (less visible)Suitability: ⭐⭐⭐ (Good if Serena always available)
Implementation:
Update pm.md:
- Remove lines 15, 119, 127-191 (Serena references)
- Explicitly document repository-scoped local file approach
- Clarify: "PM Agent uses transparent file-based memory"
- Update: "Session Lifecycle (Repository-Scoped Local Files)"
Benefits Already in Place:
- Transparent, Git-manageable
- No external dependencies
- Human-readable formats
- Automatic isolation via git boundary
Benefits:
Drawbacks:
Suitability: ⭐⭐⭐⭐⭐ (Best for current state)
Implementation:
Primary Storage: Local files (docs/memory/)
- Always works, no dependencies
- Transparent, Git-manageable
Optional Enhancement: Serena MCP (when available)
- try:
mcp__serena__think_about_task_adherence()
mcp__serena__write_memory("pm_semantic_context", summary)
except:
# Fallback gracefully, continue with local files
pass
Benefits:
- Core functionality always works
- Enhanced capabilities when Serena available
- Graceful degradation
- Future-proof architecture
Benefits:
Drawbacks:
Suitability: ⭐⭐⭐⭐ (Good for long-term flexibility)
Rationale:
Implementation Steps:
Update plugins/superclaude/commands/pm.md:
- ## Session Lifecycle (Serena MCP Memory Integration)
+ ## Session Lifecycle (Repository-Scoped Local Memory)
- 1. Context Restoration:
- - list_memories() → Check for existing PM Agent state
- - read_memory("pm_context") → Restore overall context
+ 1. Context Restoration (from local files):
+ - Read docs/memory/pm_context.md → Project context
+ - Read docs/memory/last_session.md → Previous work
Remove MCP Resource Attempt:
ReadMcpResourceTool with "serena://memories"Clarify MCP Integration Section:
### MCP Integration (Optional Enhancement)
**Primary Storage**: Repository-scoped local files (`docs/memory/`)
- Always available, no dependencies
- Transparent, Git-manageable, human-readable
**Optional Serena Integration** (when available via airis-mcp-gateway):
- mcp__serena__think_about_* tools for introspection
- mcp__serena__get_symbols_overview for code understanding
- mcp__serena__write_memory for semantic summaries
When: After Option B is implemented and stable
Rationale:
Implementation Priority: Low (current system works)
Current State: PM Agent uses repository-scoped local files, NOT Serena MCP memory management.
Problem: Documentation references Serena tools that are never called, creating confusion.
Solution: Clarify documentation to match reality (Option B), with optional future enhancement (Option C).
Action Required: Update plugins/superclaude/commands/pm.md to remove Serena references and explicitly document file-based memory approach.
Confidence: High (90%) - Evidence-based analysis with official documentation verification.