🔴 BEFORE: Knotted Code & Leaky Abstractions

5 Critical Smells Present

Web & REST API Layer Knot #1 & Knot #4

🔴 Knot #1: _sqlite_conn(storage)

🔴 Knot #4: @router.on_event("startup")

app.py

manage.py

• Knot 1: Web API reaches inside storage to run raw SQL (_UNTAGGED_PREDICATE), bypassing storage engine.
• Knot 4: Deprecated unmanaged infinite loop in documents.py with forgotten TODO workaround.

Models, CLI & Log Layer Knot #2, #3, #5

🔴 Knot #2: 24x Copy-Pasted _sanitize_log_value

🔴 Knot #3: MemoryTypeOntology / TagTaxonomy wrappers

🔴 Knot #5: cli/main.py -> storage._run_in_thread

• Knot 2: _sanitize_log_value copy-pasted in 24 files with drifted behavior (re.sub vs replace).
• Knot 3: 10 empty classmethod wrappers in ontology.py & tag_taxonomy.py adding call overhead.
• Knot 5: CLI reflection on private storage methods (_get_existing_db_embedding_dimension).

Storage Engine Layer (sqlite-vec / milvus) Incomplete Interface

MemoryStorage (base.py)

mixins/delete.py

mixins/retrieve.py

• Missing count_untagged_memories / delete_untagged_memories on SQLite engine, forcing upstream callers to leak SQL.

🟢 AFTER: Untangled Clean Layered Architecture

See PR checks for validation

Web & REST API Layer Clean Contracts

✓ await storage.delete_untagged_memories()

✓ app.py lifespan managed cleanup task

Zero Raw SQL

• Untangled 1: Web API router speaks strictly to MemoryStorage interface. Preserves upstream guarded deletion and sync events.
• Untangled 4: Document upload sessions cleanly managed in web/app.py lifespan with graceful cancellation.

Models, CLI & Log Layer Single Source of Truth

✓ 1 Canonical compat._sanitize_log_value

✓ Direct staticmethod bindings in models

✓ Public storage.get_db_embedding_dimension()

• Untangled 2: 23 copy-paste duplicate definitions deleted; unified import from compat.py.
• Untangled 3: 10 empty wrapper delegates replaced with direct function assignments.
• Untangled 5: Clean async public API replaces private method reflection in CLI.

Storage Engine Layer (sqlite-vec / milvus) Storage API

✓ DeleteMixin.delete_untagged_memories()

✓ EmbeddingsMixin.get_db_embedding_dimension()

Tombstones & HLC Synced

• SQLite engine natively implements untagged counting, soft-delete tombstones, and sync event emission.