Split core god files (search_repository_base, project_context, config, runtime protocols)

[phernandez]

From the 2026-07 architecture review (basic-memory-cloud docs/architecture-review-2026-07.md, diagram 2).

Split candidates, in rough order of pain:

• repository/search_repository_base.py (2,382 lines originally) — natural seams: FTS query building vs vector sync vs shared row mapping. Also evaluate how much of the twin SQLite/Postgres implementations can collapse into the base
  • Query construction and shared row hydration extracted in refactor(core): split search query and row hydration #1122
  • Semantic source composition, chunking, chunk records, and fingerprints extracted in refactor(core): extract semantic chunk planning #1128
  • Remaining vector-sync orchestration extracted in refactor(core): extract semantic vector synchronization #1129
  • Evaluate safe backend consolidation
• mcp/project_context.py (1,818)
• config.py (1,330) — currently config model + ConfigManager + logging init + legacy migration in one file; four separable concerns
• runtime/note_content.py (1,236 — protocol and value families still share one file) — group contracts by concern
• runtime/contracts.py — already split into storage / jobs / workflows / note content / indexing-cleanup modules; the aggregate file no longer exists
• indexing/project_index_workflow.py — split progress metadata / batch fanout / stale handling / coordinator (also queued in the parity doc)

Sequence after the naming/shim cleanup so imports only move once.

[claude]

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

---

Triage: Split core god files (search_repository_base, project_context, config, runtime protocols)

Type: Enhancement (code-quality/architecture refactor, no functional defect)

Priority: Low — this is internal tech debt with no user-facing impact; nothing is broken today. Recommend scheduling opportunistically rather than urgently.

Component: Spans several core layers rather than one: repository/ (search), mcp/ (project context), plus root-level config.py and runtime/. The repo's label set doesn't have a single tag that covers "core architecture," so no component label was applied — happy to add one if you create it.

Complexity: Complex — multi-file structural refactor across the repository, MCP, config, and runtime layers, explicitly sequenced after other cleanup work in the issue itself.

Verification against current main:

• repository/search_repository_base.py — exists, ~2,150 non-blank lines (issue cites 2,382 total lines) ✅ still the biggest offender
• mcp/project_context.py — exists, ~1,540 non-blank lines (cites 1,818) ✅ confirmed
• config.py — exists, ~1,130 non-blank lines (cites 1,330) ✅ confirmed
• runtime/note_content.py — exists, 14 Protocol classes found (cites 15 in 1,236 lines) ✅ close enough, confirmed
• runtime/contracts.py — no longer exists. runtime/ is already split into storage.py, jobs.py, workflows.py, note_content.py, note_materialization.py, note_move.py, cleanup.py, projects.py, etc. — this matches the exact split the issue asks for, so that checklist item appears already done.
• indexing/project_index_workflow.py — exists but only ~500 non-blank lines, notably smaller than the other candidates; may be lower priority than listed.
• The cited source docs (docs/architecture-review-2026-07.md, docs/local-cloud-runtime-parity.md) live in the basic-memory-cloud repo, not this one — not present here, as expected.

Duplicate check: Searched open/closed issues for related titles and keywords (search_repository_base, project_context.py, "god files") — no existing duplicate found.

Labels applied: enhancement. (Priority/component/complexity labels referenced in the triage template — e.g. low, database, mcp, complex — don't currently exist in this repo's label set, so they couldn't be attached.)

This issue is a straightforward, well-scoped tracking issue for a known-complex refactor — no clarification needed from the reporter. Per triage scope, no implementation, branch, or code changes were made.

[phernandez]

@claude make PR

[claude]

Working on it

Plan: This issue tracks 6 large refactors. Doing all of them safely in one PR isn't realistic (~6,700+ lines across repository/MCP/config/runtime layers, each needing careful test verification and 100% coverage). I'll scope this PR to the most tractable, lowest-risk split, and leave the rest queued for follow-up PRs — exactly as the issue itself specifies ("sequence... so imports only move once").

• Read issue + triage comment context
• Inspect current state of each candidate file to pick the safest first split
• Implement the chosen split
• Run just fast-check / targeted tests
• Push branch and open PR

View job run

[phernandez]

Safe backend consolidation audit (2026-07-21)

The search split is complete after #1122, #1128, #1129, and #1130.

• search_repository_base.py is now 1,213 lines, down from the original 2,382 (about a 49% reduction).
• A structural audit of the SQLite and Postgres classes found 16 common method names but zero identical method bodies.
• Shared retrieval dispatch, vector planning/synchronization, source composition, chunking, row hydration, filtering, and hybrid result assembly now live in the base or extracted modules.
• The remaining overrides are backend boundaries: FTS5 MATCH/bm25 versus tsvector/to_tsquery/ts_rank, SQLite JSON functions versus Postgres JSONB functions, and sqlite-vec versus pgvector schema/session/write operations.
• Even the similar search and count shells have different syntax-error transaction handling and Postgres caller-owned session behavior.

Decision: no further backend collapse is safe or useful for this tracker. A template-method layer could remove a small amount of wrapper code, but it would introduce a SQL-dialect abstraction and change sensitive transaction/session seams without consolidating the substantive logic. Marking the search repository and its consolidation audit complete with no additional PR.