Epic: Memory Enhancement Layer for Serena + Forgetful

[rjmurillo-bot]

Memory Enhancement Layer

Status: v0.3.0 Planning
PRD: PRD-memory-enhancement-layer-for-serena-forgetful.md
Related: #724 (Traceability Graph), #584 (Serena Integration)

Overview

Enhance Serena + Forgetful memory system with GitHub Copilot-inspired features:

• Citation validation (verify memories against code changes)
• Staleness detection (flag outdated memories)
• Graph traversal (navigate memory relationships)
• Confidence scoring (track reliability)

90% of the value at 10% of the cost - augment existing system, don't replace.

---

Implementation Phases

Phase 1: Citation Schema & Verification (P0)

Track: Sub-issues to be created

• Document citation schema
• Citation verification script
• Unit tests

Exit: Can verify citations with python -m memory_enhancement verify

Phase 2: Graph Traversal (P1)

Track: Sub-issues to be created

• BFS/DFS traversal implementation
• Integration with Serena links
• Cycle detection

Exit: Navigate relationships with python -m memory_enhancement graph

Phase 3: Health Reporting & CI (P1)

Track: Sub-issues to be created

• Health check CLI
• CI workflow integration
• Documentation

Exit: CI flags stale memories on PRs

Phase 4: Confidence Scoring (P2)

Track: Sub-issues to be created

• Confidence calculation
• CLI tooling for citations
• Claude Code skill wrapper

Exit: Track confidence over time

---

Success Metrics

• 20% citation coverage for high-value memories

• 90% stale detection accuracy

• CI active on all PRs
• <500ms graph traversal

---

Next Steps

1. Create sub-issues for each phase
2. Link to v0.3.0 milestone
3. Begin Phase 1 when v0.2.0 ships

[traycerai]

Plan

Observations

The codebase has a mature memory system with Serena (lexical), Forgetful (semantic), and Reflexion Memory (episodic/causal) tiers. The PRD proposes a Python-based enhancement layer that augments Serena memories with YAML frontmatter for citations and typed links, enabling GitHub Copilot-inspired features. The existing infrastructure uses PowerShell for memory operations but the enhancement layer will be Python-only for cross-platform compatibility and future ML integration. CI workflows follow a path-filtering pattern with ARM runners for cost optimization.

Approach

The implementation follows a 4-phase incremental approach, building a standalone Python package at file:.claude/skills/memory-enhancement/ that reads/writes Serena memory files with YAML frontmatter extensions. Each phase delivers working CLI tools that can be integrated into CI workflows. The design maintains backward compatibility—memories without citations continue to work, and the enhancement layer coexists with existing Serena MCP tools. This "90% value at 10% cost" strategy avoids replacing the existing stack while adding citation validation, graph traversal, and health reporting capabilities.

Implementation Plan

Phase 1: Citation Schema & Verification (Week 1)

Objective: Enable citation tracking and verification for Serena memories

1.1 Create Package Structure

• Create directory file:.claude/skills/memory-enhancement/src/memory_enhancement/
• Add file:.claude/skills/memory-enhancement/src/memory_enhancement/__init__.py with package metadata
• Create file:.claude/skills/memory-enhancement/tests/ directory for pytest tests
• Add file:.claude/skills/memory-enhancement/SKILL.md documenting the skill interface

1.2 Implement Core Models

Create file:.claude/skills/memory-enhancement/src/memory_enhancement/models.py:

• Define LinkType enum with values: RELATED, SUPERSEDES, BLOCKS, IMPLEMENTS, EXTENDS
• Define Citation dataclass with fields: path, line, snippet, verified, valid, mismatch_reason
• Define Link dataclass with fields: link_type, target_id
• Define Memory dataclass with fields: id, subject, path, content, citations, links, tags, confidence, last_verified
• Implement Memory.from_serena_file() classmethod to parse YAML frontmatter using python-frontmatter library
• Implement helper methods: get_links_by_type(), _parse_date()

1.3 Implement Citation Verification

Create file:.claude/skills/memory-enhancement/src/memory_enhancement/citations.py:

• Define VerificationResult dataclass with fields: memory_id, valid, total_citations, valid_count, stale_citations, confidence
• Implement verify_citation() function:
  • Check file existence at repo_root / citation.path
  • Validate line number is within file bounds
  • Perform fuzzy snippet matching (substring containment)
  • Set citation.valid and citation.mismatch_reason
• Implement verify_memory() function:
  • Iterate through all citations in a memory
  • Calculate confidence score as valid_count / total_citations
  • Return VerificationResult with stale citations list
• Implement verify_all_memories() function for batch processing

1.4 Create CLI Entry Point

Create file:.claude/skills/memory-enhancement/src/memory_enhancement/__main__.py:

• Use argparse to define subcommands: verify, verify-all
• Implement verify command:
  • Accept memory ID or path as argument
  • Support --json flag for JSON output
  • Display human-readable status with ✅/❌ indicators
• Implement verify-all command:
  • Accept --dir argument (default: .serena/memories)
  • Support --json flag for structured output
  • Display summary statistics

1.5 Add Dependencies

Update file:pyproject.toml:

• Add python-frontmatter>=1.0.0 to dependencies
• Ensure Python 3.10+ requirement is specified

1.6 Write Unit Tests

Create file:.claude/skills/memory-enhancement/tests/test_citations.py:

• Test verify_citation() with valid/invalid paths, line numbers, snippets
• Test verify_memory() with memories containing multiple citations
• Test verify_all_memories() batch processing
• Use pytest fixtures for temporary memory files

Create file:.claude/skills/memory-enhancement/tests/test_models.py:

• Test Memory.from_serena_file() parsing with various frontmatter formats
• Test link type filtering with get_links_by_type()
• Test date parsing edge cases

1.7 Documentation

Create file:.claude/skills/memory-enhancement/README.md:

• Document citation schema format
• Provide examples of adding citations to memories
• Document CLI usage for verification commands

Exit Criteria: Run python -m memory_enhancement verify <memory-id> successfully verifies citations

---

Phase 2: Graph Traversal (Week 2)

Objective: Enable navigation of memory relationships via typed links

2.1 Implement Graph Traversal

Create file:.claude/skills/memory-enhancement/src/memory_enhancement/graph.py:

• Define GraphEdge dataclass with fields: source_id, target_id, link_type
• Define GraphResult dataclass with fields: nodes, edges, visited_count, max_depth_reached
• Implement traverse_graph() function:
  • Use BFS with collections.deque for traversal
  • Accept root_id, memories_dir, max_depth, link_types parameters
  • Filter links by type if link_types specified
  • Handle both ID-based and filename-based memory lookup
  • Return GraphResult with visited nodes and edges
• Implement _find_memory_by_id() helper for frontmatter-based lookup
• Implement utility functions:
  • find_superseded_chain() - traverse SUPERSEDES links
  • find_blocking_dependencies() - traverse BLOCKS links
  • find_related_memories() - reverse lookup for incoming links
  • find_root_memories() - find memories with no incoming links

2.2 Extend CLI

Update file:.claude/skills/memory-enhancement/src/memory_enhancement/__main__.py:

• Add graph subcommand:
  • Accept root memory ID as argument
  • Support --depth parameter (default: 3)
  • Support --json flag for structured output
  • Display graph as indented tree or JSON
• Add related subcommand:
  • Accept memory ID as argument
  • Display all memories linking to the target

2.3 Integration with Existing Serena Links

• Review existing Serena memory link formats in file:.serena/memories/
• Ensure backward compatibility with any existing link conventions
• Document migration path for converting old link formats to typed links

2.4 Cycle Detection

Add cycle detection to traverse_graph():

• Track visited nodes to prevent infinite loops
• Optionally warn when cycles are detected
• Add --detect-cycles flag to CLI

2.5 Write Unit Tests

Create file:.claude/skills/memory-enhancement/tests/test_graph.py:

• Test BFS traversal with various graph structures
• Test link type filtering
• Test cycle detection
• Test utility functions (find_superseded_chain, find_root_memories, etc.)
• Use pytest fixtures to create temporary memory graphs

Exit Criteria: Run python -m memory_enhancement graph <root-id> successfully traverses memory relationships

---

Phase 3: Health Reporting & CI Integration (Week 3)

Objective: Enable automated memory health checks in CI/CD pipelines

3.1 Implement Health Reporting

Create file:.claude/skills/memory-enhancement/src/memory_enhancement/health.py:

• Implement generate_health_report() function:
  • Accept memories_dir and format parameters (markdown/json)
  • Scan all memories for citations
  • Run verification on memories with citations
  • Calculate statistics:
    • Total memories vs memories with citations
    • Citation coverage percentage
    • Stale citation count
    • Average confidence score
  • Identify problematic memories (low confidence, stale citations)
  • Generate markdown or JSON report
• Implement helper functions:
  • calculate_coverage_stats() - citation coverage metrics
  • find_stale_memories() - memories with invalid citations
  • calculate_confidence_distribution() - confidence score histogram

3.2 Extend CLI

Update file:.claude/skills/memory-enhancement/src/memory_enhancement/__main__.py:

• Add health subcommand:
  • Accept --dir parameter (default: .serena/memories)
  • Accept --format parameter (choices: markdown, json)
  • Display health report with color-coded status indicators
  • Support --min-confidence threshold for filtering

3.3 Create CI Workflow

Create file:.github/workflows/memory-enhancement-validation.yml:

• Trigger on:
  • Pull requests modifying .serena/memories/** or src/**
  • Manual workflow dispatch
• Use path filtering similar to file:.github/workflows/memory-validation.yml
• Jobs:
  • check-paths: Determine if validation should run
  • validate-citations: Run python -m memory_enhancement verify-all --json
  • health-report: Run python -m memory_enhancement health --format markdown
• Use ARM runners (ubuntu-24.04-arm) for cost optimization
• Set continue-on-error: true initially (warning mode, not blocking)
• Post health report as PR comment using GitHub Actions

3.4 Serena Integration Helper

Create file:.claude/skills/memory-enhancement/src/memory_enhancement/serena.py:

• Define SERENA_MEMORIES_DIR constant
• Implement search_with_verification() function:
  • Wrap Serena's lexical search with citation verification
  • Accept query, memories_dir, verify, min_confidence parameters
  • Return list of (Memory, VerificationResult) tuples
• Implement add_citation_to_memory() function:
  • Accept memory_path, file_path, line, snippet parameters
  • Load memory with frontmatter
  • Append citation to frontmatter
  • Update last_verified timestamp
  • Write back to file

3.5 Documentation

Update file:.claude/skills/memory-enhancement/README.md:

• Document health reporting metrics
• Provide CI integration examples
• Document add_citation_to_memory() usage

3.6 Write Unit Tests

Create file:.claude/skills/memory-enhancement/tests/test_health.py:

• Test health report generation with various memory states
• Test coverage calculation
• Test stale memory detection
• Test markdown and JSON output formats

Create file:.claude/skills/memory-enhancement/tests/test_serena.py:

• Test add_citation_to_memory() with existing memories
• Test citation appending to frontmatter
• Test timestamp updates

Exit Criteria: CI workflow runs on PRs and flags stale memories

---

Phase 4: Confidence Scoring & Tooling (Week 4)

Objective: Track memory reliability over time and provide developer tooling

4.1 Implement Confidence Scoring

Update file:.claude/skills/memory-enhancement/src/memory_enhancement/citations.py:

• Enhance verify_memory() to track verification history
• Implement confidence decay based on time since last verification
• Add confidence boost for recently verified citations
• Store verification history in memory frontmatter (optional)

4.2 Add Citation Management Commands

Update file:.claude/skills/memory-enhancement/src/memory_enhancement/__main__.py:

• Add add-citation subcommand:
  • Accept memory ID, file path, line number, snippet
  • Call add_citation_to_memory() from serena.py
  • Verify citation after adding
• Add update-confidence subcommand:
  • Recalculate confidence for all memories
  • Update frontmatter with new confidence scores

4.3 Conflict Detection (Optional)

Create file:.claude/skills/memory-enhancement/src/memory_enhancement/conflict.py:

• Implement detect_serena_config() to check for Serena project configuration
• Implement get_active_memory_tools() to list non-excluded Serena tools
• Implement suggest_config_update() to generate exclusion recommendations
• Add doctor subcommand to CLI for conflict detection

4.4 Claude Code Skill Wrapper

Update file:.claude/skills/memory-enhancement/SKILL.md:

• Document skill interface for Claude Code
• Provide examples of using memory enhancement from Claude sessions
• Document integration with existing memory workflow

4.5 Integration with Reflexion Memory

• Review integration points with file:.claude/skills/memory/scripts/ReflexionMemory.psm1
• Consider adding episode citations to link memories with causal graph nodes
• Document how memory enhancement complements reflexion memory

4.6 Write Unit Tests

Create file:.claude/skills/memory-enhancement/tests/test_confidence.py:

• Test confidence calculation with various citation states
• Test confidence decay over time
• Test confidence updates

Create file:.claude/skills/memory-enhancement/tests/test_conflict.py (if implementing):

• Test Serena config detection
• Test conflict resolution suggestions

4.7 Final Documentation

Update file:.claude/skills/memory-enhancement/README.md:

• Add comprehensive usage guide
• Document all CLI commands
• Provide best practices for citation management
• Add troubleshooting section

Create file:.agents/docs/memory-enhancement-guide.md:

• Developer guide for adding citations to memories
• Integration guide for CI/CD
• Migration guide for existing memories

Exit Criteria: Developers can easily add citations via CLI and track confidence over time

---

Cross-Phase Tasks

Testing Strategy

• Maintain >80% code coverage with pytest
• Add integration tests that verify end-to-end workflows
• Use file:tests/conftest.py for shared fixtures
• Follow existing test patterns from file:tests/test_check_skill_exists.py

CI/CD Integration

• Update file:.github/workflows/pytest.yml to include memory enhancement tests
• Ensure path filters include **/*.py and .claude/skills/memory-enhancement/**
• Add security checks with bandit for new Python code

Documentation

• Update file:AGENTS.md to reference memory enhancement capabilities
• Add memory enhancement to file:CLAUDE.md system prompt guidance
• Document tool selection strategy (when to use Serena vs enhancement layer)

Backward Compatibility

• Ensure memories without frontmatter continue to work
• Provide migration script for adding frontmatter to existing memories
• Test with existing Serena memories in file:.serena/memories/

---

Success Metrics

Metric	Target	Verification
Citation coverage	20% of memories	Count memories with citations frontmatter
Stale detection accuracy	>90%	Manual validation of flagged memories
CI integration	Active on all PRs	Check workflow runs in GitHub Actions
Graph traversal performance	<500ms for depth 3	Benchmark with pytest-benchmark
Test coverage	>80%	Coverage report from pytest-cov

---

Mermaid Diagram: Implementation Flow

sequenceDiagram
    participant Dev as Developer
    participant CLI as Memory Enhancement CLI
    participant Serena as Serena Memories
    participant CI as GitHub Actions
    
    Note over Dev,CI: Phase 1: Citation Verification
    Dev->>Serena: Write memory with citations
    Dev->>CLI: python -m memory_enhancement verify
    CLI->>Serena: Read memory with frontmatter
    CLI->>CLI: Verify citations against codebase
    CLI-->>Dev: Report: ✅ Valid / ❌ Stale
    
    Note over Dev,CI: Phase 2: Graph Traversal
    Dev->>CLI: python -m memory_enhancement graph root-id
    CLI->>Serena: Load memory and follow links
    CLI->>CLI: BFS traversal with type filtering
    CLI-->>Dev: Display graph structure
    
    Note over Dev,CI: Phase 3: CI Integration
    Dev->>CI: Push PR with code changes
    CI->>CLI: python -m memory_enhancement verify-all
    CLI->>Serena: Scan all memories
    CLI->>CLI: Verify citations
    CLI-->>CI: Report stale memories
    CI-->>Dev: Post health report as PR comment
    
    Note over Dev,CI: Phase 4: Confidence Tracking
    Dev->>CLI: python -m memory_enhancement add-citation
    CLI->>Serena: Update memory frontmatter
    CLI->>CLI: Calculate confidence score
    CLI->>Serena: Write updated memory
    CLI-->>Dev: Confirmation with new confidence

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a mature memory system with Serena (lexical), Forgetful (semantic), and Reflexion Memory (episodic/causal) tiers. The PRD proposes a Python-based enhancement layer that augments Serena memories with YAML frontmatter for citations and typed links, enabling GitHub Copilot-inspired features. The existing infrastructure uses PowerShell for memory operations but the enhancement layer will be Python-only for cross-platform compatibility and future ML integration. CI workflows follow a path-filtering pattern with ARM runners for cost optimization.

## Approach

The implementation follows a 4-phase incremental approach, building a standalone Python package at `file:.claude/skills/memory-enhancement/` that reads/writes Serena memory files with YAML frontmatter extensions. Each phase delivers working CLI tools that can be integrated into CI workflows. The design maintains backward compatibility—memories without citations continue to work, and the enhancement layer coexists with existing Serena MCP tools. This "90% value at 10% cost" strategy avoids replacing the existing stack while adding citation validation, graph traversal, and health reporting capabilities.

## Implementation Plan

### Phase 1: Citation Schema & Verification (Week 1)

**Objective**: Enable citation tracking and verification for Serena memories

#### 1.1 Create Package Structure
- Create directory `file:.claude/skills/memory-enhancement/src/memory_enhancement/`
- Add `file:.claude/skills/memory-enhancement/src/memory_enhancement/__init__.py` with package metadata
- Create `file:.claude/skills/memory-enhancement/tests/` directory for pytest tests
- Add `file:.claude/skills/memory-enhancement/SKILL.md` documenting the skill interface

#### 1.2 Implement Core Models
Create `file:.claude/skills/memory-enhancement/src/memory_enhancement/models.py`:
- Define `LinkType` enum with values: `RELATED`, `SUPERSEDES`, `BLOCKS`, `IMPLEMENTS`, `EXTENDS`
- Define `Citation` dataclass with fields: `path`, `line`, `snippet`, `verified`, `valid`, `mismatch_reason`
- Define `Link` dataclass with fields: `link_type`, `target_id`
- Define `Memory` dataclass with fields: `id`, `subject`, `path`, `content`, `citations`, `links`, `tags`, `confidence`, `last_verified`
- Implement `Memory.from_serena_file()` classmethod to parse YAML frontmatter using `python-frontmatter` library
- Implement helper methods: `get_links_by_type()`, `_parse_date()`

#### 1.3 Implement Citation Verification
Create `file:.claude/skills/memory-enhancement/src/memory_enhancement/citations.py`:
- Define `VerificationResult` dataclass with fields: `memory_id`, `valid`, `total_citations`, `valid_count`, `stale_citations`, `confidence`
- Implement `verify_citation()` function:
  - Check file existence at `repo_root / citation.path`
  - Validate line number is within file bounds
  - Perform fuzzy snippet matching (substring containment)
  - Set `citation.valid` and `citation.mismatch_reason`
- Implement `verify_memory()` function:
  - Iterate through all citations in a memory
  - Calculate confidence score as `valid_count / total_citations`
  - Return `VerificationResult` with stale citations list
- Implement `verify_all_memories()` function for batch processing

#### 1.4 Create CLI Entry Point
Create `file:.claude/skills/memory-enhancement/src/memory_enhancement/__main__.py`:
- Use `argparse` to define subcommands: `verify`, `verify-all`
- Implement `verify` command:
  - Accept memory ID or path as argument
  - Support `--json` flag for JSON output
  - Display human-readable status with ✅/❌ indicators
- Implement `verify-all` command:
  - Accept `--dir` argument (default: `.serena/memories`)
  - Support `--json` flag for structured output
  - Display summary statistics

#### 1.5 Add Dependencies
Update `file:pyproject.toml`:
- Add `python-frontmatter>=1.0.0` to dependencies
- Ensure Python 3.10+ requirement is specified

#### 1.6 Write Unit Tests
Create `file:.claude/skills/memory-enhancement/tests/test_citations.py`:
- Test `verify_citation()` with valid/invalid paths, line numbers, snippets
- Test `verify_memory()` with memories containing multiple citations
- Test `verify_all_memories()` batch processing
- Use pytest fixtures for temporary memory files

Create `file:.claude/skills/memory-enhancement/tests/test_models.py`:
- Test `Memory.from_serena_file()` parsing with various frontmatter formats
- Test link type filtering with `get_links_by_type()`
- Test date parsing edge cases

#### 1.7 Documentation
Create `file:.claude/skills/memory-enhancement/README.md`:
- Document citation schema format
- Provide examples of adding citations to memories
- Document CLI usage for verification commands

**Exit Criteria**: Run `python -m memory_enhancement verify <memory-id>` successfully verifies citations

---

### Phase 2: Graph Traversal (Week 2)

**Objective**: Enable navigation of memory relationships via typed links

#### 2.1 Implement Graph Traversal
Create `file:.claude/skills/memory-enhancement/src/memory_enhancement/graph.py`:
- Define `GraphEdge` dataclass with fields: `source_id`, `target_id`, `link_type`
- Define `GraphResult` dataclass with fields: `nodes`, `edges`, `visited_count`, `max_depth_reached`
- Implement `traverse_graph()` function:
  - Use BFS with `collections.deque` for traversal
  - Accept `root_id`, `memories_dir`, `max_depth`, `link_types` parameters
  - Filter links by type if `link_types` specified
  - Handle both ID-based and filename-based memory lookup
  - Return `GraphResult` with visited nodes and edges
- Implement `_find_memory_by_id()` helper for frontmatter-based lookup
- Implement utility functions:
  - `find_superseded_chain()` - traverse `SUPERSEDES` links
  - `find_blocking_dependencies()` - traverse `BLOCKS` links
  - `find_related_memories()` - reverse lookup for incoming links
  - `find_root_memories()` - find memories with no incoming links

#### 2.2 Extend CLI
Update `file:.claude/skills/memory-enhancement/src/memory_enhancement/__main__.py`:
- Add `graph` subcommand:
  - Accept `root` memory ID as argument
  - Support `--depth` parameter (default: 3)
  - Support `--json` flag for structured output
  - Display graph as indented tree or JSON
- Add `related` subcommand:
  - Accept memory ID as argument
  - Display all memories linking to the target

#### 2.3 Integration with Existing Serena Links
- Review existing Serena memory link formats in `file:.serena/memories/`
- Ensure backward compatibility with any existing link conventions
- Document migration path for converting old link formats to typed links

#### 2.4 Cycle Detection
Add cycle detection to `traverse_graph()`:
- Track visited nodes to prevent infinite loops
- Optionally warn when cycles are detected
- Add `--detect-cycles` flag to CLI

#### 2.5 Write Unit Tests
Create `file:.claude/skills/memory-enhancement/tests/test_graph.py`:
- Test BFS traversal with various graph structures
- Test link type filtering
- Test cycle detection
- Test utility functions (`find_superseded_chain`, `find_root_memories`, etc.)
- Use pytest fixtures to create temporary memory graphs

**Exit Criteria**: Run `python -m memory_enhancement graph <root-id>` successfully traverses memory relationships

---

### Phase 3: Health Reporting & CI Integration (Week 3)

**Objective**: Enable automated memory health checks in CI/CD pipelines

#### 3.1 Implement Health Reporting
Create `file:.claude/skills/memory-enhancement/src/memory_enhancement/health.py`:
- Implement `generate_health_report()` function:
  - Accept `memories_dir` and `format` parameters (markdown/json)
  - Scan all memories for citations
  - Run verification on memories with citations
  - Calculate statistics:
    - Total memories vs memories with citations
    - Citation coverage percentage
    - Stale citation count
    - Average confidence score
  - Identify problematic memories (low confidence, stale citations)
  - Generate markdown or JSON report
- Implement helper functions:
  - `calculate_coverage_stats()` - citation coverage metrics
  - `find_stale_memories()` - memories with invalid citations
  - `calculate_confidence_distribution()` - confidence score histogram

#### 3.2 Extend CLI
Update `file:.claude/skills/memory-enhancement/src/memory_enhancement/__main__.py`:
- Add `health` subcommand:
  - Accept `--dir` parameter (default: `.serena/memories`)
  - Accept `--format` parameter (choices: markdown, json)
  - Display health report with color-coded status indicators
  - Support `--min-confidence` threshold for filtering

#### 3.3 Create CI Workflow
Create `file:.github/workflows/memory-enhancement-validation.yml`:
- Trigger on:
  - Pull requests modifying `.serena/memories/**` or `src/**`
  - Manual workflow dispatch
- Use path filtering similar to `file:.github/workflows/memory-validation.yml`
- Jobs:
  - `check-paths`: Determine if validation should run
  - `validate-citations`: Run `python -m memory_enhancement verify-all --json`
  - `health-report`: Run `python -m memory_enhancement health --format markdown`
- Use ARM runners (`ubuntu-24.04-arm`) for cost optimization
- Set `continue-on-error: true` initially (warning mode, not blocking)
- Post health report as PR comment using GitHub Actions

#### 3.4 Serena Integration Helper
Create `file:.claude/skills/memory-enhancement/src/memory_enhancement/serena.py`:
- Define `SERENA_MEMORIES_DIR` constant
- Implement `search_with_verification()` function:
  - Wrap Serena's lexical search with citation verification
  - Accept `query`, `memories_dir`, `verify`, `min_confidence` parameters
  - Return list of `(Memory, VerificationResult)` tuples
- Implement `add_citation_to_memory()` function:
  - Accept `memory_path`, `file_path`, `line`, `snippet` parameters
  - Load memory with frontmatter
  - Append citation to frontmatter
  - Update `last_verified` timestamp
  - Write back to file

#### 3.5 Documentation
Update `file:.claude/skills/memory-enhancement/README.md`:
- Document health reporting metrics
- Provide CI integration examples
- Document `add_citation_to_memory()` usage

#### 3.6 Write Unit Tests
Create `file:.claude/skills/memory-enhancement/tests/test_health.py`:
- Test health report generation with various memory states
- Test coverage calculation
- Test stale memory detection
- Test markdown and JSON output formats

Create `file:.claude/skills/memory-enhancement/tests/test_serena.py`:
- Test `add_citation_to_memory()` with existing memories
- Test citation appending to frontmatter
- Test timestamp updates

**Exit Criteria**: CI workflow runs on PRs and flags stale memories

---

### Phase 4: Confidence Scoring & Tooling (Week 4)

**Objective**: Track memory reliability over time and provide developer tooling

#### 4.1 Implement Confidence Scoring
Update `file:.claude/skills/memory-enhancement/src/memory_enhancement/citations.py`:
- Enhance `verify_memory()` to track verification history
- Implement confidence decay based on time since last verification
- Add confidence boost for recently verified citations
- Store verification history in memory frontmatter (optional)

#### 4.2 Add Citation Management Commands
Update `file:.claude/skills/memory-enhancement/src/memory_enhancement/__main__.py`:
- Add `add-citation` subcommand:
  - Accept memory ID, file path, line number, snippet
  - Call `add_citation_to_memory()` from serena.py
  - Verify citation after adding
- Add `update-confidence` subcommand:
  - Recalculate confidence for all memories
  - Update frontmatter with new confidence scores

#### 4.3 Conflict Detection (Optional)
Create `file:.claude/skills/memory-enhancement/src/memory_enhancement/conflict.py`:
- Implement `detect_serena_config()` to check for Serena project configuration
- Implement `get_active_memory_tools()` to list non-excluded Serena tools
- Implement `suggest_config_update()` to generate exclusion recommendations
- Add `doctor` subcommand to CLI for conflict detection

#### 4.4 Claude Code Skill Wrapper
Update `file:.claude/skills/memory-enhancement/SKILL.md`:
- Document skill interface for Claude Code
- Provide examples of using memory enhancement from Claude sessions
- Document integration with existing memory workflow

#### 4.5 Integration with Reflexion Memory
- Review integration points with `file:.claude/skills/memory/scripts/ReflexionMemory.psm1`
- Consider adding episode citations to link memories with causal graph nodes
- Document how memory enhancement complements reflexion memory

#### 4.6 Write Unit Tests
Create `file:.claude/skills/memory-enhancement/tests/test_confidence.py`:
- Test confidence calculation with various citation states
- Test confidence decay over time
- Test confidence updates

Create `file:.claude/skills/memory-enhancement/tests/test_conflict.py` (if implementing):
- Test Serena config detection
- Test conflict resolution suggestions

#### 4.7 Final Documentation
Update `file:.claude/skills/memory-enhancement/README.md`:
- Add comprehensive usage guide
- Document all CLI commands
- Provide best practices for citation management
- Add troubleshooting section

Create `file:.agents/docs/memory-enhancement-guide.md`:
- Developer guide for adding citations to memories
- Integration guide for CI/CD
- Migration guide for existing memories

**Exit Criteria**: Developers can easily add citations via CLI and track confidence over time

---

## Cross-Phase Tasks

### Testing Strategy
- Maintain >80% code coverage with pytest
- Add integration tests that verify end-to-end workflows
- Use `file:tests/conftest.py` for shared fixtures
- Follow existing test patterns from `file:tests/test_check_skill_exists.py`

### CI/CD Integration
- Update `file:.github/workflows/pytest.yml` to include memory enhancement tests
- Ensure path filters include `**/*.py` and `.claude/skills/memory-enhancement/**`
- Add security checks with bandit for new Python code

### Documentation
- Update `file:AGENTS.md` to reference memory enhancement capabilities
- Add memory enhancement to `file:CLAUDE.md` system prompt guidance
- Document tool selection strategy (when to use Serena vs enhancement layer)

### Backward Compatibility
- Ensure memories without frontmatter continue to work
- Provide migration script for adding frontmatter to existing memories
- Test with existing Serena memories in `file:.serena/memories/`

---

## Success Metrics

| Metric | Target | Verification |
|--------|--------|--------------|
| Citation coverage | 20% of memories | Count memories with `citations` frontmatter |
| Stale detection accuracy | >90% | Manual validation of flagged memories |
| CI integration | Active on all PRs | Check workflow runs in GitHub Actions |
| Graph traversal performance | <500ms for depth 3 | Benchmark with `pytest-benchmark` |
| Test coverage | >80% | Coverage report from pytest-cov |

---

## Mermaid Diagram: Implementation Flow

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant CLI as Memory Enhancement CLI
    participant Serena as Serena Memories
    participant CI as GitHub Actions
    
    Note over Dev,CI: Phase 1: Citation Verification
    Dev->>Serena: Write memory with citations
    Dev->>CLI: python -m memory_enhancement verify
    CLI->>Serena: Read memory with frontmatter
    CLI->>CLI: Verify citations against codebase
    CLI-->>Dev: Report: ✅ Valid / ❌ Stale
    
    Note over Dev,CI: Phase 2: Graph Traversal
    Dev->>CLI: python -m memory_enhancement graph root-id
    CLI->>Serena: Load memory and follow links
    CLI->>CLI: BFS traversal with type filtering
    CLI-->>Dev: Display graph structure
    
    Note over Dev,CI: Phase 3: CI Integration
    Dev->>CI: Push PR with code changes
    CI->>CLI: python -m memory_enhancement verify-all
    CLI->>Serena: Scan all memories
    CLI->>CLI: Verify citations
    CLI-->>CI: Report stale memories
    CI-->>Dev: Post health report as PR comment
    
    Note over Dev,CI: Phase 4: Confidence Tracking
    Dev->>CLI: python -m memory_enhancement add-citation
    CLI->>Serena: Update memory frontmatter
    CLI->>CLI: Calculate confidence score
    CLI->>Serena: Write updated memory
    CLI-->>Dev: Confirmation with new confidence
```

---

Execution Information

Branch: main
Commit: 879e07c

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#245 - docs(memory): add decomposition analysis for Issue #239 [merged]
#301 - docs: autonomous PR monitoring prompt and retrospective [merged]
#605 - feat(agents): Phase 1 Spec Layer - spec-generator agent and routing [merged]
#738 - docs(claude): update CLAUDE.md with current repository state [merged]
#752 - feat(memory): memory system foundation (Session 230) [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

AI Triage Summary

Note

This issue has been automatically triaged by AI agents

What is AI Triage?

This issue was analyzed by AI agents:

• Analyst Agent: Categorizes the issue and suggests appropriate labels
• Roadmap Agent: Aligns the issue with project milestones and priorities
• Explainer Agent (if escalated): Generates comprehensive PRD

Triage Results

Property	Value
Category	enhancement
Labels	["enhancement","agent-memory","area-workflows"]
Priority	P1
Milestone	v0.3.0

Categorization Analysis

```json
{
  "labels": ["enhancement", "agent-memory", "area-workflows"],
  "category": "enhancement",
  "confidence": 0.95,
  "reasoning": "Epic describes new memory system features (citation validation, staleness detection, graph traversal) with CI workflow integration"
}

</details>

<details>
<summary>Roadmap Alignment</summary>

```json
Issue is well-structured with a linked PRD already. This is an epic-level issue for v0.3.0 planning that enhances the memory system with 4 phases.

**Analysis:**
- **Priority**: P1 - High impact (core memory system), can wait (v0.3.0, after v0.2.0)
- **Milestone**: v0.3.0 (explicitly stated)
- **Epic**: This IS an epic, not aligned to another
- **PRD**: Already exists (`PRD-memory-enhancement-layer-for-serena-forgetful.md`)
- **Escalate**: No - PRD already complete

**Complexity Score** (for reference):
- Scope: System-wide (3)
- Dependencies: Internal (2) - Serena + Forgetful
- Uncertainty: Some unknowns (2) - phases defined
- Stakeholders: Team-wide (2)
- Total: 9

```json
{
  "milestone": "v0.3.0",
  "priority": "P1",
  "epic_alignment": "",
  "confidence": 0.95,
  "reasoning": "Self-contained epic for v0.3.0 with PRD already complete; high impact memory enhancement, can wait until v0.2.0 ships",
  "escalate_to_prd": false,
  "escalation_criteria": [],
  "complexity_score": 9
}

</details>

---

<sub>Powered by [AI Issue Triage](https://github.com/rjmurillo/ai-agents) workflow</sub>