Post-seam cleanup: delete legacy shims, stale trees, and resolve naming twins

[phernandez]

From the 2026-07 architecture review (basic-memory-cloud docs/architecture-review-2026-07.md, diagram 2). The protocol-seam migration landed; these are the leftovers that now act as traps for readers and agents.

Deletions:

• deps.py — deprecated shim over the deps/ package ("will be removed once all callers are migrated"); migrate remaining importers and delete
• basic_memory/cloud/ — five 3-line re-export shims; migrate the ~6 cloud-repo imports to canonical paths (paired basic-memory-cloud PR), then delete or rename the package to what it actually is
• src-old/basic_memory/sync + tests-old/sync — port any still-useful coverage to index/watch integration tests, then delete (already flagged in the parity doc)
• mcp/async_client.py:465 deprecated create_client() path
• Evaluate the legacy_router remap in api/app.py:147-150

Naming twins (rename or explicitly document — currently indistinguishable by name):

• schema/ (typed-note engine) vs schemas/ (Pydantic API DTOs)
• index/ (local runtime orchestration) vs indexing/ (portable runners) — both also contain models.py, job_payloads.py, storage_events.py

Acceptance: grepping for a concept lands on exactly one module; no deprecated shims remain.

[claude]

Claude finished @phernandez's task in 2m 7s —— View job

---

Triage complete

• Read issue and repository context
• Classify type, priority, component, complexity
• Check for duplicate issues
• Verify referenced paths still exist in this repo
• Apply labels
• Post triage summary

Classification

• Type: Enhancement (tech-debt/cleanup, not a bug or new feature)
• Priority: Medium — nothing broken today, but the shims are active traps for future contributors/agents (the issue's own framing)
• Component: Spans core, cloud, and mcp; cloud is the closest match in the repo's actual label set (see label note below)
• Complexity: Complex — five independent deletion/rename efforts, one requiring a paired PR in basic-memory-cloud, plus two naming-twin decisions touching dozens of files

Duplicate check: No duplicate found via gh search issues. Related but not duplicate: #491 ("Refactor: split deps.py into feature modules") is the closed precursor that created the deps.py shim this issue now asks to delete.

Verification against current main:

• deps.py shim confirmed present and still imported by 10 files in this repo (9 v2 routers + mcp/async_client.py) — migration work is real, not stale.
• basic_memory/cloud/ — 5 re-export shims confirmed present; no in-repo importers found, consistent with the issue's note that consumers live in the paired basic-memory-cloud repo.
• src-old/basic_memory/sync and tests-old/sync — no longer exist in this repo; this checklist item appears already resolved and can likely be checked off/removed when work starts.
• mcp/async_client.py deprecated create_client() — confirmed present.
• api/app.py legacy_router — confirmed present (~line 147).
• schema/ (6 files) vs schemas/ (19 files) — confirmed naming twins.
• index/ vs indexing/ — confirmed naming twins, but the shared-filename claim is only partly accurate today: index/ has storage_events.py (no models.py/job_payloads.py), indexing/ has models.py + job_payloads.py (no storage_events.py). Worth re-checking against architecture-review diagram 2 before scoping the rename.

Label note: This repo's actual label set doesn't match the taxonomy in my triage instructions (no medium/high/low, mcp/cli/database/docs/testing, or simple/complex labels exist). Applied enhancement and cloud, the two that do exist and fit.

⚠️ Correction needed: while probing which labels exist (the label-edit script silently ignores unknown names with no way to list them upfront), bug, documentation, question, and duplicate were transiently applied to this issue by mistake — none of them apply here, and my tooling in this context has no label-removal capability. Please remove those four manually; only enhancement and cloud should remain. Apologies for the noise.

Per triage scope, no implementation, branch, or file changes were made.

[phernandez]

Status update from working this issue.

Done / in flight

• src-old/ + tests-old/ — already gone from the repo; checklist item is stale.
• deps.py, create_client(), basic_memory/cloud/ — deleted in refactor(core): delete dead post-seam compatibility shims #1112. Notes from verification:
  • deps.py was not a live shim: the deps/ package shadows the same-named module, so the file was unreachable dead code. The package __init__ re-export surface is live API (~19 import sites) and stays.
  • basic_memory/cloud/ had zero production importers in either repo — basic-memory-cloud main already imports canonical paths. Only its gateway README still mentions basic_memory.cloud.* (doc touch-up in the cloud repo, no lockstep needed).
  • create_client() had zero callers.

Needs a decision (not doing unilaterally)

1. legacy_router (api/app.py:147-151) — NOT stale. It serves three explicit routes (GET/POST /projects/projects, POST /projects/config/sync) for CLI v0.18.0 and earlier, is test-covered (tests/api/v2/test_project_router.py:638-693), and exists specifically because a router mount's 307 redirect breaks the proxy. Removing it is a back-compat policy call: drop pre-v0.18.0 CLI support or keep the shim. Recommend deciding at the next minor release.

2. Naming twins — rename costs measured (external import sites):

Package	Purpose	External importers
schema/	Picoschema typed-note engine	11 (cheap to rename)
schemas/	Pydantic API DTOs	163 (very expensive)
index/	local indexing orchestration + watch	43
indexing/	portable indexing runners/primitives	70

Recommendation: rename only schema/ (e.g. picoschema/ or note_schema/) — 11 sites, resolves the worst twin since schemas/schema.py also exists. For index/ vs indexing/, both packages already carry explicit role docstrings; renaming either means touching 43-70 files for arguably marginal gain. Suggest documenting the split in docs/ARCHITECTURE.md instead. Will hold both until there's a call on this.

[phernandez]

Closing with the deletions landed and the two remaining items assessed and deferred:

Done (#1112): deps.py dead file, basic_memory/cloud/ compat package, mcp/async_client.create_client() — all deleted. src-old//tests-old/ were already gone. Gateway README references to basic_memory.cloud.* fixed in basicmachines-co/basic-memory-cloud#1559.

Deferred (documented above in the findings comment):

• legacy_router is live compat for pre-v0.18.0 CLI clients — removal is a back-compat policy decision, suggest deciding at the next minor release
• Naming twins: rename costs measured (schema 11 external import sites, index 43, indexing 70, schemas 163); recommendation is renaming only schema/ and documenting the index/indexing split — best sequenced with Split core god files (search_repository_base, project_context, config, runtime protocols) #1108 so imports move once

If either deferred item gets a go-ahead, a fresh focused issue can pick it up from the analysis here.