claude-mem/MONOLITH_REFACTOR_REPORT.md

Monolith Refactor Report

Last Updated: 2026-01-03 (post session-logging merge)

Executive Summary

The claude-mem codebase contains ~21,000 lines of TypeScript across 71+ files. Analysis reveals several monolithic files that violate single-responsibility principles and create tight coupling. This report identifies refactoring targets and proposes a modular architecture.

Recent Changes: The session-logging branch merge improved error handling across the codebase. SearchManager was reduced by ~180 lines, but SessionStore grew by ~110 lines due to new migrations and logging.

---

Part 1: Monolith Files Identified

Critical Priority (>1500 lines)

File	Lines	Methods	Primary Issues	Trend
src/services/worker-service.ts	2,034	-	Server init, process management, Cursor hooks, MCP setup all mixed	↓ -28
src/services/sqlite/SessionStore.ts	2,011	49	Migrations + CRUD + queries + transformations all in one class	↑ +108
src/services/worker/SearchManager.ts	1,778	17	Three search strategies crammed together, formatting mixed in	↓ -178

High Priority (500-1500 lines)

File	Lines	Issues	Trend
src/services/sync/ChromaSync.ts	870	Sync and query operations mixed	—
src/services/context-generator.ts	659	23 standalone functions, no class structure	—
src/services/worker/http/routes/SessionRoutes.ts	625	Provider selection mixed with business logic	↑ +7
src/services/worker/OpenRouterAgent.ts	599	80% code duplicated from other agents	↓ -15
src/services/worker/GeminiAgent.ts	574	80% code duplicated from other agents	↓ -15
src/services/worker/SDKAgent.ts	546	Base patterns duplicated across all agents	↓ -15
src/services/sqlite/SessionSearch.ts	526	FTS5 tables maintained for backward compat	—
src/services/sqlite/migrations.ts	509	All 11 migrations in single file	—
src/services/sqlite/PendingMessageStore.ts	447	Message queue operations	↑ +21
src/services/worker/http/routes/SettingsRoutes.ts	414	File I/O, validation, git ops mixed	—

Code Duplication Issue

The three agent files (SDKAgent, GeminiAgent, OpenRouterAgent) share ~80% duplicate code:

• Message building logic
• Result parsing
• Context updating
• Database sync patterns

---

Part 2: System Breakdown Proposal

Domain-Based Module Architecture

src/
├── domains/                    # Business domain modules
│   ├── sessions/               # Session lifecycle
│   │   ├── SessionRepository.ts
│   │   ├── SessionService.ts
│   │   └── types.ts
│   │
│   ├── observations/           # Observation management
│   │   ├── ObservationRepository.ts
│   │   ├── ObservationService.ts
│   │   └── types.ts
│   │
│   ├── summaries/              # Summary generation
│   │   ├── SummaryRepository.ts
│   │   ├── SummaryService.ts
│   │   └── types.ts
│   │
│   ├── prompts/                # Prompt storage
│   │   ├── PromptRepository.ts
│   │   └── types.ts
│   │
│   └── search/                 # Search subsystem
│       ├── strategies/
│       │   ├── ChromaSearchStrategy.ts
│       │   ├── FilterSearchStrategy.ts
│       │   └── SearchStrategy.ts (interface)
│       ├── SearchOrchestrator.ts
│       ├── ResultFormatter.ts
│       └── TimelineBuilder.ts
│
├── infrastructure/             # Cross-cutting infrastructure
│   ├── database/
│   │   ├── DatabaseConnection.ts
│   │   ├── TransactionManager.ts
│   │   └── migrations/
│   │       ├── MigrationRunner.ts
│   │       ├── 001_initial.ts
│   │       ├── 002_add_prompts.ts
│   │       └── ...
│   │
│   ├── vector/
│   │   ├── ChromaClient.ts
│   │   ├── ChromaSyncManager.ts
│   │   └── ChromaQueryEngine.ts
│   │
│   └── agents/
│       ├── BaseAgent.ts        # Shared agent logic
│       ├── AgentFactory.ts
│       ├── MessageBuilder.ts
│       ├── ResponseParser.ts
│       ├── providers/
│       │   ├── ClaudeProvider.ts
│       │   ├── GeminiProvider.ts
│       │   └── OpenRouterProvider.ts
│       └── types.ts
│
├── api/                        # HTTP layer
│   ├── routes/
│   │   ├── sessions.ts
│   │   ├── data.ts
│   │   ├── search.ts
│   │   ├── settings.ts
│   │   └── viewer.ts
│   ├── middleware/
│   └── server.ts
│
├── context/                    # Context injection
│   ├── ContextBuilder.ts
│   ├── ContextConfigLoader.ts
│   ├── ObservationCompiler.ts
│   └── TokenCalculator.ts
│
└── shared/                     # Shared utilities (existing)
    ├── logger.ts
    ├── settings.ts
    └── ...

---

Part 3: Refactoring Targets by Priority

Phase 1: Database Layer Decomposition

Target: src/services/sqlite/SessionStore.ts (2,011 lines, 49 methods → ~5 files)

Extract To	Responsibility	Est. Lines
domains/sessions/SessionRepository.ts	Session CRUD ops	~300
domains/observations/ObservationRepository.ts	Observation storage/retrieval	~400
domains/summaries/SummaryRepository.ts	Summary storage/retrieval	~200
infrastructure/database/migrations/MigrationRunner.ts	Schema migrations	~250

Benefits:

• Single responsibility per file
• Testable in isolation
• Reduces coupling

---

Phase 2: Agent Consolidation

Target: 3 agent files (1,719 lines → ~800 lines total)

Extract To	Responsibility
infrastructure/agents/BaseAgent.ts	Common agent logic, prompt building
infrastructure/agents/MessageBuilder.ts	Message construction
infrastructure/agents/ResponseParser.ts	Result parsing (observations, summaries)
infrastructure/agents/providers/*.ts	Provider-specific API calls only

Benefits:

• Eliminates 80% code duplication
• Easy to add new providers
• Centralized message format changes

---

Phase 3: Search Strategy Pattern

Target: src/services/worker/SearchManager.ts (1,778 lines → ~5 files)

Extract To	Responsibility
domains/search/SearchOrchestrator.ts	Coordinates search strategies
domains/search/strategies/ChromaSearchStrategy.ts	Vector search via Chroma
domains/search/strategies/FilterSearchStrategy.ts	SQLite filter-based search
domains/search/ResultFormatter.ts	Formats search results
domains/search/TimelineBuilder.ts	Constructs timeline views

Benefits:

• Strategy pattern for extensibility
• Clear fallback logic
• Testable strategies

---

Phase 4: Context Generator Restructure

Target: src/services/context-generator.ts (659 lines → ~4 files)

Extract To	Responsibility
context/ContextBuilder.ts	Main builder class
context/ContextConfigLoader.ts	Config loading/validation
context/ObservationCompiler.ts	Compiles observations for injection
context/TokenCalculator.ts	Token budget calculations

Benefits:

• Class-based structure
• Clear dependencies
• Easier testing

---

Phase 5: Server/Infrastructure Split

Target: src/services/worker-service.ts (2,034 lines → ~4 files)

Extract To	Responsibility
api/server.ts	Express app, route registration
infrastructure/ProcessManager.ts	PID files, signal handlers
infrastructure/CursorHooksInstaller.ts	Cursor integration
infrastructure/MCPClientManager.ts	MCP client lifecycle

---

Part 4: Dependency Reduction Strategy

Current Pain Points

1. SessionStore imported by 7+ files directly
2. No abstraction between routes and data access
3. All routes depend on DatabaseManager which exposes raw SessionStore

Proposed Dependency Injection

// infrastructure/container.ts
export interface ServiceContainer {
  sessions: SessionService;
  observations: ObservationService;
  summaries: SummaryService;
  search: SearchOrchestrator;
  agents: AgentFactory;
}

// Usage in routes
app.post('/sessions', (req, res) => {
  const { sessions } = getContainer();
  sessions.create(req.body);
});

---

Part 5: Migration Strategy

Incremental Approach

Each phase can be done independently without breaking the system:

1. Create new modules alongside existing code
2. Migrate routes one at a time to use new modules
3. Deprecate old code once all routes migrated
4. Remove deprecated code after testing

Testing Requirements

• Unit tests for each extracted module
• Integration tests for repository operations
• End-to-end tests for API routes

---

Appendix: File Size Distribution

2,034  src/services/worker-service.ts          ████████████████████
2,011  src/services/sqlite/SessionStore.ts     ████████████████████
1,778  src/services/worker/SearchManager.ts    █████████████████
  870  src/services/sync/ChromaSync.ts         ████████
  659  src/services/context-generator.ts       ██████
  625  src/services/worker/http/routes/SessionRoutes.ts  ██████
  599  src/services/worker/OpenRouterAgent.ts  █████
  574  src/services/worker/GeminiAgent.ts      █████
  546  src/services/worker/SDKAgent.ts         █████
  526  src/services/sqlite/SessionSearch.ts    █████
  509  src/services/sqlite/migrations.ts       █████
  466  src/services/worker/http/routes/DataRoutes.ts     ████
  447  src/services/sqlite/PendingMessageStore.ts        ████
  414  src/services/worker/http/routes/SettingsRoutes.ts ████

---

Summary

Metric	Current	After Refactor
Files >500 lines	14	0-2
Max file size	2,034	~400
Code duplication	~1,100 lines	~100 lines
Testable modules	Low	High

Recommended Start: Phase 1 (SessionStore decomposition) - highest impact, clearest boundaries, and growing (now 2,011 lines with 49 methods).

Key Observations Post-Merge

1. SessionStore is still the top priority - it grew by 108 lines and is now the 2nd largest file
2. SearchManager improved - down 178 lines from error handling refactor
3. Agent files slightly smaller - ~45 lines combined reduction
4. Core architecture unchanged - the proposed modular structure remains valid