Refactor: split deps.py into feature modules + reduce import graph

[phernandez]

Refactor: split deps.py into feature modules + reduce import graph

Why

basic_memory/deps.py currently centralizes many unrelated dependency factories (DB/session, repositories, services, sync/watch, etc.). This increases coupling and the import graph; small changes ripple across unrelated features.

Scope

• Split dependency wiring into feature-scoped modules:
  • basic_memory/deps/db.py
  • basic_memory/deps/projects.py
  • basic_memory/deps/services.py
  • basic_memory/deps/sync.py
  • basic_memory/deps/http.py
• Keep deps.py as a temporary thin re-export layer during migration (optional), then delete it once callers are migrated.

Acceptance criteria

• Routers/tools only import the deps they need (no global deps.py imports for unrelated deps).
• Import graph is measurably smaller (qualitative is fine: fewer cross-module imports; no new circulars).
• Tests pass (SQLite + Postgres-focused runs).

Dependencies

• Best done after composition roots are introduced (see the container issue), but can start in parallel.

[claude]

Claude finished @phernandez's task in 1m 42s —— View job

---

Issue Triage Complete

I've analyzed this refactoring proposal and here's my assessment:

---

Classification

Type: Enhancement/Refactoring - Architectural improvement to reduce coupling
Component: Core architecture (dependency injection)
Complexity: Medium-to-Complex
Priority: Medium - Important for maintainability but not blocking

---

Current State Analysis

The deps.py file is 722 lines containing:

• Database/session factories
• All repository factories (Project, Entity, Observation, Relation, Search)
• All service factories (Entity, Search, Link, Context, Sync, Project, Directory, File)
• All importer factories (ChatGPT, Claude Conversations, Claude Projects, Memory JSON)
• Both v1 and v2 API variants
• Project resolution logic

This creates a large import graph where changes ripple across unrelated features.

---

Proposed Refactoring

Split into feature-scoped modules:

• basic_memory/deps/db.py - Database and session factories
• basic_memory/deps/projects.py - Project resolution and config
• basic_memory/deps/services.py - Service factories
• basic_memory/deps/sync.py - Sync-related factories
• basic_memory/deps/http.py - HTTP client factories

With a temporary re-export layer during migration.

---

Relationship to #490

This issue is part of a larger architectural refactoring:

• Refactor: reduce coupling + centralize cloud_mode/config wiring #490: Introduces composition roots and centralizes cloud_mode/config wiring
• Refactor: split deps.py into feature modules + reduce import graph #491 (this issue): Splits the monolithic deps.py into feature modules

The issue notes: "Best done after composition roots are introduced, but can start in parallel"

Both issues work together toward better SOLID principles and reduced coupling.

---

Impact & Risk Assessment

Benefits:

• Reduced coupling between features
• Clearer feature boundaries
• Smaller, more focused import graph
• Easier to test individual features in isolation

Risks:

• High touch points - many routers/tools import from deps.py
• Requires careful migration to avoid breaking changes
• Must maintain test coverage throughout

Migration Strategy:

1. Create new feature-scoped modules
2. Keep temporary re-export layer in deps.py
3. Incrementally migrate callers
4. Remove re-export layer once complete
5. Ensure all tests pass (SQLite + Postgres)

---

Recommendation

This is a valuable refactoring that should proceed incrementally and test-driven:

1. Start in parallel with Refactor: reduce coupling + centralize cloud_mode/config wiring #490 but coordinate on shared boundaries
2. Use feature branches with comprehensive test coverage
3. Migrate one feature module at a time
4. Keep the re-export layer until all callers are migrated

The acceptance criteria are well-defined and measurable.

---

Labels applied: enhancement