[M-003] MemoryRouter performance optimization: reduce 260ms overhead to <20ms

[rjmurillo-bot]

Context

The MemoryRouter module (M-003, ADR-037) was implemented with correct functionality but does not meet the performance targets specified in ADR-037. This issue tracks the optimization work to achieve the target latency.

Current Performance vs Targets

Metric	ADR-037 Target	Actual	Gap
Serena-only search	<20ms	477.30ms	457ms over target
Augmented (Serena + Forgetful)	<50ms	Not tested	-
Health check (cached)	<1ms	4.48ms	3.48ms over target

Root Cause Analysis

The module adds 260ms overhead compared to the raw benchmark script (217.42ms baseline → 477.30ms with module). Contributing factors identified:

1. SHA-256 Hashing (Estimated: ~100-150ms)

Each matched file has its content hashed for deduplication. With 9-10 results per query and 465 memory files scanned:

# Current implementation (executed per file)
[System.Security.Cryptography.SHA256]::HashData([System.Text.Encoding]::UTF8.GetBytes($Content))

2. File Content Reading (Estimated: ~80-100ms)

Full file content is read for every matched file, even when only the filename matched:

# Current: reads all content upfront
$content = Get-Content -Path $file.FullName -Raw -Encoding UTF8

3. Input Validation (Estimated: ~10-20ms)

ValidatePattern regex executed on every call:

[ValidatePattern('^[a-zA-Z0-9\s\-.,_()&:]+$')]

4. Object Construction (Estimated: ~30-50ms)

Full PSCustomObject created for each result with 6 properties.

Proposed Optimizations

High Impact (P0)

1. Lazy content loading: Don't read file content until explicitly requested

   • Return [Lazy[string]] or callback instead of eager loading
   • Skip SHA-256 hash until merge phase requires it

2. Filename-only mode: Add -NamesOnly switch for index-style queries

   • Return just name + path without content/hash
   • Sufficient for most agent memory lookups

Medium Impact (P1)

3. Content caching: Cache file contents with modification time check

   • $script:ContentCache = @{} with LastWriteTime validation
   • 465 files × ~1KB avg = ~500KB memory footprint

4. Pre-computed keyword index: Build index at module load

   • Map keywords → file paths
   • Refresh on -Force or TTL expiry

Low Impact (P2)

5. Health check pre-warming: Call Test-ForgetfulAvailable at module import

   • Reduces first-call latency
   • Current 4.48ms → target <1ms

6. Batch hashing: Hash multiple files in parallel using runspaces

Acceptance Criteria

• Serena-only search: <20ms (currently 477ms)
• Health check cached: <1ms (currently 4.48ms)
• Augmented search: <50ms (when Forgetful available)
• No regression in test coverage (38 tests passing)
• Memory footprint documented

Validation Approach

Use existing benchmark script to measure before/after:

# Baseline comparison
pwsh scripts/Measure-MemoryPerformance.ps1 -Queries @('memory router', 'git hooks') -Iterations 5

References

• ADR: .agents/architecture/ADR-037-memory-router-architecture.md
• Module: scripts/MemoryRouter.psm1
• Tests: tests/MemoryRouter.Tests.ps1
• Baseline: .agents/analysis/M-003-baseline.md
• Validation: .agents/analysis/M-003-performance-validation.md
• Implementation commit: 59cabcd

Detailed Benchmark Data

Query-by-Query Performance (5 iterations each)

Query	Average (ms)	Results
memory router	490.95	9
PowerShell arrays	392.67	9
git hooks validation	577.45	10
session protocol	411.23	10
security patterns	514.21	10

Observations:

• Queries returning 10 results are ~50ms slower than 9-result queries
• Variance correlates with result count (more files = more hashing)
• git hooks validation is slowest due to keyword density in filenames

---

Created from M-003 implementation (Session 126)

[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

---

🔗 Similar Issues

Related Issues

• Update agent prompts to use Memory Router interface (ADR-037) #731
• Migrate legacy consolidated memories to tiered index architecture #311
• ADR-007 Bulletproof Enforcement: Claude Code Hooks + Validation Enhancement #729
• Agent Quality: Remediate CodeRabbit PR #43 Findings (7 Issues, 15 Agent Gaps) #44

🔗 Related PRs

#52 - feat: MCP config sync utility and pre-commit architecture documentation [merged]
#222 - fix(workflow): add missing ./ prefix to Import-Module paths [merged]
#301 - docs: autonomous PR monitoring prompt and retrospective [merged]
#365 - fix(memory): ADR-017 compliance - rename skill- files and implement P0 validations [merged]
#703 - feat(validation): complete investigation allowlist per Issue #653 [merged]

👤 Suggested Assignees

• rjmurillo-bot
• rjmurillo

---

🧪 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]

Product Requirements Document

Important

This PRD was automatically generated based on issue triage escalation.
Complexity Score: 8/12 (Detailed)
Escalation Criteria: research_required,multi_phase_work

About this PRD

This PRD was generated by the Explainer Agent after the issue was flagged
for detailed analysis. The document is designed to be self-contained - it can
be passed to a separate AI agent instance for implementation without additional
context.

PRD Depth Levels:

• Standard (4-6): Brief analysis, clear requirements
• Detailed (7-9): Research section, blocking questions
• Comprehensive (10-12): Phased implementation, risk analysis

---

The referenced files (MemoryRouter.psm1, ADR-037-memory-router-architecture.md, M-003-baseline.md) do not exist in this repository. This is a feature that was planned but not yet implemented.

Now I have sufficient context. The issue references files and a module that do not exist yet - this is a feature request for future optimization work on a MemoryRouter module that was planned but not implemented. Let me create the PRD.

Cannot write to the filesystem. Here is the PRD:

---

PRD: MemoryRouter Performance Optimization

Executive Summary

This PRD addresses performance optimization for the MemoryRouter module (M-003). The module was designed to unify memory retrieval across Serena and Forgetful MCP systems but exceeds latency targets by 22x (477ms actual vs 20ms target).

Scope	Status	Blocker
MemoryRouter module existence	🔴 BLOCKED	Module does not exist in repository
ADR-037 specification	🔴 BLOCKED	ADR does not exist in repository
Baseline analysis document	🔴 BLOCKED	M-003-baseline.md does not exist
Performance validation document	🔴 BLOCKED	M-003-performance-validation.md does not exist
Benchmark script	🔴 BLOCKED	Measure-MemoryPerformance.ps1 does not exist

Verdict: 🔴 BLOCKED - All referenced artifacts are missing. This issue describes optimization work for a module that has not been implemented.

Problem Statement

Current State

Artifact	Expected Location	Exists
MemoryRouter.psm1	scripts/MemoryRouter.psm1	NO
ADR-037	.agents/architecture/ADR-037-memory-router-architecture.md	NO
M-003-baseline.md	.agents/analysis/M-003-baseline.md	NO
M-003-performance-validation.md	.agents/analysis/M-003-performance-validation.md	NO
Measure-MemoryPerformance.ps1	scripts/Measure-MemoryPerformance.ps1	NO
MemoryRouter.Tests.ps1	tests/MemoryRouter.Tests.ps1	NO

Verification: Repository search conducted on 2026-01-02. None of the referenced files exist.

Gap Analysis

The issue describes:

1. A MemoryRouter module providing unified memory search across Serena and Forgetful
2. Performance targets specified in ADR-037
3. Baseline measurements from commit 59cabcd
4. 38 passing tests in MemoryRouter.Tests.ps1

Reality: None of these artifacts exist. This issue appears to be:

• A planning document for future work, OR
• Created from a branch that was never merged, OR
• Describing work in a different repository

User Impact

If the module existed, the described performance issues would:

• Delay agent memory retrieval by 260ms per search
• Compound across multi-query sessions (5 queries = 1.3s overhead)
• Violate ADR-037 latency targets

Research Findings

Primary Sources

Source	Finding	Confidence
Repository file listing	MemoryRouter.psm1 does not exist	CONFIRMED
ADR directory listing	ADR-037 does not exist	CONFIRMED
Analysis directory listing	M-003 baseline files do not exist	CONFIRMED
Tests directory listing	MemoryRouter.Tests.ps1 does not exist	CONFIRMED

Existing Memory Architecture

Based on ADR-007 and ADR-017, the current memory architecture uses:

1. Serena MCP: Canonical memory layer with markdown files in .serena/memories/
2. Forgetful MCP: Supplementary semantic search via HTTP at localhost:8020
3. Tiered Index: Three-level hierarchy per ADR-017 (memory-index -> domain-index -> atomic-file)

The MemoryRouter concept would unify these systems with a single search interface.

Related ADRs

ADR	Relevance
ADR-007: Memory-First Architecture	Defines Serena as canonical, Forgetful as supplementary
ADR-017: Tiered Memory Index	Establishes index structure and token efficiency targets

No ADR-037 exists - this is a gap requiring resolution.

Proposed Solution

Phase 0: Discovery (Status: REQUIRED)

Estimated Effort: S
Blockers: None

This phase must complete before any optimization work.

Task	Description
0.1	Verify issue author intent: Is this future work or referencing a different branch?
0.2	Search git history for commit 59cabcd and associated files
0.3	Determine if MemoryRouter was planned but never merged
0.4	Update issue with findings

Phase 1: Foundation (Status: DEPENDS on Phase 0)

Estimated Effort: M
Blockers: Phase 0 must clarify if module exists elsewhere

If the module needs to be created:

Task	Description
1.1	Draft ADR-037 specifying MemoryRouter architecture
1.2	Define performance targets based on issue description
1.3	Create MemoryRouter.psm1 skeleton with interface
1.4	Create MemoryRouter.Tests.ps1 with baseline tests

Phase 2: Implementation (Status: DEPENDS on Phase 1)

Estimated Effort: L
Blockers: Phase 1 artifacts required

Task	Description
2.1	Implement Serena-only search path
2.2	Implement Forgetful augmentation path
2.3	Add health check caching
2.4	Create Measure-MemoryPerformance.ps1 benchmark script

Phase 3: Optimization (Status: DEPENDS on Phase 2)

Estimated Effort: M
Blockers: Working baseline required for measurement

This phase implements the optimizations described in the issue:

Task	Description
3.1	Implement lazy content loading (P0)
3.2	Add -NamesOnly switch for index-style queries (P0)
3.3	Implement content caching with LastWriteTime validation (P1)
3.4	Build pre-computed keyword index (P1)
3.5	Add health check pre-warming at module import (P2)

Decision Tree

Does MemoryRouter.psm1 exist in any branch?
├── YES (found in branch/commit)
│   └── Merge to main, proceed to Phase 3
└── NO (never existed)
    └── Was this issue created in error?
        ├── YES → Close as invalid
        └── NO (future work)
            └── Execute Phases 1-3 sequentially

Functional Requirements

FR-1: Discovery Requirements

Priority: P0

ID	Requirement	Acceptance Criteria
FR-1.1	Verify artifact existence	Git log searched for commit 59cabcd; result documented
FR-1.2	Clarify issue intent	Issue author confirms whether this is future work or missing artifacts
FR-1.3	Document findings	Analysis file created at .agents/analysis/M-003-artifact-discovery.md

FR-2: Module Requirements (If Creating New)

Priority: P1

ID	Requirement	Acceptance Criteria
FR-2.1	Unified search interface	Single Search-Memory function queries both Serena and Forgetful
FR-2.2	Serena-first fallback	Returns results from Serena when Forgetful unavailable
FR-2.3	Deduplication	Same memory from both sources appears once in results
FR-2.4	Latency targets	Serena-only <20ms; Augmented <50ms; Health check <1ms

FR-3: Optimization Requirements (Issue-Specified)

Priority: P0 (if module exists)

ID	Requirement	Acceptance Criteria
FR-3.1	Lazy content loading	File content not read until explicitly requested
FR-3.2	Filename-only mode	-NamesOnly switch returns path without content/hash
FR-3.3	Content caching	Cache with LastWriteTime invalidation
FR-3.4	Keyword index	Pre-computed index at module load
FR-3.5	Health pre-warming	Test-ForgetfulAvailable called at import

Non-Functional Requirements

Consistency

• Follow ADR-005: PowerShell-only scripting
• Follow .github/instructions/testing.instructions.md for Pester tests
• Follow .agents/steering/powershell-patterns.md for code style

Testability

• Benchmark script must produce reproducible measurements
• Performance tests must run in CI without Forgetful dependency
• Mock Forgetful responses for isolation testing

Documentation

• ADR-037 must be created before implementation
• Module must include comment-based help per PowerShell patterns

Technical Design

Proposed Module Interface

# scripts/MemoryRouter.psm1

function Search-Memory {
    <#
    .SYNOPSIS
        Unified memory search across Serena and Forgetful.

    .PARAMETER Query
        Search terms.

    .PARAMETER NamesOnly
        Return only file names and paths, skip content loading.

    .PARAMETER SerenaOnly
        Skip Forgetful augmentation, Serena results only.
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [string]$Query,

        [Parameter()]
        [switch]$NamesOnly,

        [Parameter()]
        [switch]$SerenaOnly
    )

    # Implementation here
}

function Test-ForgetfulAvailable {
    <#
    .SYNOPSIS
        Check if Forgetful MCP is reachable.
    #>
    [CmdletBinding()]
    param()

    # Cached health check
}

Performance Optimization Patterns

# Lazy content loading pattern
$result = [PSCustomObject]@{
    Name = $file.Name
    Path = $file.FullName
    # Lazy evaluation - content loaded only when accessed
    Content = [Lazy[string]]::new({
        Get-Content -Path $file.FullName -Raw -Encoding UTF8
    })
}

# Content caching pattern
$script:ContentCache = @{}
$script:CacheTimestamps = @{}

function Get-CachedContent {
    param([string]$Path)
    
    $lastWrite = (Get-Item $Path).LastWriteTime
    if ($script:CacheTimestamps[$Path] -eq $lastWrite) {
        return $script:ContentCache[$Path]
    }
    
    $content = Get-Content -Path $Path -Raw -Encoding UTF8
    $script:ContentCache[$Path] = $content
    $script:CacheTimestamps[$Path] = $lastWrite
    return $content
}

Implementation Plan

Prerequisites

• Confirm issue intent with author
• Search git history for referenced commit
• Determine if this is new work or recovery work

Phase 0 Tasks

1. Run git log --all --oneline | grep 59cabcd to find referenced commit
2. Run git log --all --oneline -- scripts/MemoryRouter.psm1 to find any history
3. Document findings in issue comment
4. If not found: Treat as new feature request requiring ADR-037 first

Phase 1 Tasks (If New Work)

1. Create ADR-037 specifying module architecture
2. Get ADR reviewed by architect agent
3. Create module skeleton with public interface
4. Create test file with interface tests

Phase 2-3 Tasks

Proceed per solution phases above.

Outcomes

Phase 0 Complete: Clear understanding of whether artifacts exist or need creation.

Phase 1 Complete: ADR-037 accepted, module interface defined.

Phase 2 Complete: Working module with baseline performance measured.

Phase 3 Complete: All latency targets met per issue specification.

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
Artifacts never existed	High	High	Phase 0 discovery; may need to close issue as invalid or convert to feature request
Forgetful unavailable in CI	Medium	Medium	Mock Forgetful for CI tests; real integration tests run locally
Performance targets unachievable	Low	High	Benchmark early; escalate if lazy loading insufficient
Lazy[T] not supported in PowerShell	Low	Medium	Use ScriptBlock pattern instead

Success Metrics

Metric	Target
Phase 0 completion	Issue intent clarified within 1 session
Serena-only latency	<20ms (if module created)
Augmented latency	<50ms (if module created)
Health check latency	<1ms cached (if module created)
Test coverage	38+ tests (matching issue claim)

Blocking Questions

Question 1: Artifact Location (CRITICAL)

Question: Where are the referenced artifacts (MemoryRouter.psm1, ADR-037, M-003-baseline.md)?

Context: The issue references commit 59cabcd and multiple files that do not exist in the main branch. These could be in:

• An unmerged feature branch
• A different repository
• A future planning document mistakenly created as an issue

Proposed Ask: Search git history: git log --all --oneline --source | grep 59cabcd

Impact if unanswered: Cannot proceed with optimization work on non-existent code. Issue may need to be closed or converted to a feature request.

Question 2: Issue Intent (CRITICAL)

Question: Was this issue intended as a future work plan, or does it describe existing work that was lost/not merged?

Context: The issue describes detailed performance measurements, test counts, and implementation details that imply the module exists.

Proposed Ask: Comment on issue asking author to clarify.

Impact if unanswered: Cannot determine correct implementation path.

Open Questions (Non-Blocking)

1. Q: Should MemoryRouter be a separate module or integrated into existing memory tooling?

   • Hypothesis: Separate module per ADR-019 script organization patterns
   • Status: Would be validated by ADR-037 architecture review

2. Q: What is the expected memory footprint for content caching (issue claims ~500KB)?

   • Hypothesis: 465 files x 1KB average is reasonable estimate
   • Status: Validate with actual .serena/memories/ file sizes

3. Q: Should keyword index be persisted to disk or rebuilt each session?

   • Hypothesis: Rebuild each session; persistence adds complexity for minimal gain
   • Status: Defer until Phase 3 performance measurement

Appendices

Appendix A: Research Sources

Source	URL/Path	Accessed
Repository root listing	Repository root	2026-01-02
Scripts directory	scripts/	2026-01-02
ADR directory	.agents/architecture/	2026-01-02
Analysis directory	.agents/analysis/	2026-01-02
Tests directory	tests/	2026-01-02
ADR-007	.agents/architecture/ADR-007-memory-first-architecture.md	2026-01-02
ADR-017	.agents/architecture/ADR-017-tiered-memory-index-architecture.md	2026-01-02
Forgetful README	scripts/forgetful/README.md	2026-01-02

Appendix B: Issue-Specified Performance Targets

From issue body (unverified - no ADR-037 exists):

Metric	Target	Reported Actual
Serena-only search	<20ms	477.30ms
Augmented search	<50ms	Not tested
Health check (cached)	<1ms	4.48ms

Appendix C: Related Issues/PRs

Reference	Status	Relevance
ADR-007	Accepted	Defines Serena-first memory architecture
ADR-017	Accepted	Defines tiered index for token efficiency
Issue #167	Open	Vector memory system (superseded by Forgetful per ADR-007)
Issue #584	Open	Serena Integration Layer (P0 per ADR-007)

---

PRD Status: 🔴 REQUIRES_DISCOVERY

Next Action: Execute Phase 0 discovery tasks before any implementation work.

Recommended Routing: Return to orchestrator; recommend routing to analyst for Phase 0 discovery, then back to explainer if artifacts are found or feature scoping is needed.

_{Generated by AI PRD Generation | View Workflow}

[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-infrastructure"]
Priority	P1
Milestone	v1.1
PRD Escalation	Generated (see below)

Categorization Analysis

```json
{
  "labels": ["enhancement", "agent-memory", "area-infrastructure"],
  "category": "enhancement",
  "confidence": 0.95,
  "reasoning": "Issue requests performance optimization for the MemoryRouter module to meet ADR-037 latency targets, with detailed analysis and proposed improvements"
}

</details>

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

```json
```json
{
  "milestone": "v1.1",
  "priority": "P1",
  "epic_alignment": "",
  "confidence": 0.70,
  "reasoning": "Performance infrastructure work aligns with v1.1 Maintainability release; standalone optimization issue, no existing epic match",
  "escalate_to_prd": true,
  "escalation_criteria": ["research_required", "multi_phase_work"],
  "complexity_score": 8
}

</details>

---

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