documentation update

docs/services/memory-service.md

@@ -184,6 +184,40 @@ service is responsible only for CRUD — generation logic lives in orchestration
 > For full details on trigger conditions, prompt format, cumulative updates,
 > and ChatML token stripping, see `summarization.md`.
 
+## Delete Behaviour (SQLite + Qdrant consistency)
+
+SQLite cascades handle relational cleanup, but Qdrant is a separate store and
+must be cleaned explicitly. Each delete path that removes embedded rows also
+removes the corresponding vectors:
+
+| Delete | SQLite effect | Qdrant cleanup |
+|---|---|---|
+| `DELETE /episodes/:id` | Row removed | `semantic.deleteEpisode(id)` — vector by point ID |
+| `DELETE /sessions/by-external/:id` | Session + episodes cascade-deleted | `semantic.deleteEpisodesBySession(id)` — **payload-filter** delete on `sessionId` |
+| `DELETE /entities/:id` | Row removed, relationships cascade | `semantic.deleteEntity(id)` — vector by point ID |
+
+All three Qdrant deletes are **fire-and-forget** with error logging, matching
+the fire-and-forget write path — a Qdrant failure logs but does not fail the
+delete.
+
+The session path uses a **payload-filter** delete (matching on the `sessionId`
+field in the vector payload) rather than enumerating episode point IDs. This
+matters because the SQLite cascade has already removed the episode rows by the
+time cleanup runs, so there are no IDs left to enumerate — the filter deletes
+by payload regardless. It also cleans up any pre-existing orphans for that
+session as a side effect.
+
+> **Not cleaned on session delete:** entity vectors. Entities are shared across
+> sessions and projects (`UNIQUE(name, type)` is global), so deleting one
+> session must not remove entities that other sessions still reference. Entity
+> vector lifecycle is tied to explicit entity deletion and the (planned) memory
+> consolidation / orphan-cleanup pass.
+
+> **Historical orphans:** vectors orphaned by session deletes *before* this
+> cleanup existed are not removed retroactively. A one-time sweep (scroll the
+> `episodes` collection, delete points whose `sessionId` no longer exists in
+> SQLite) clears them.
+
 ## Project Delete Behaviour
 
 Deleting a project runs as a transaction — it first nulls out `project_id`
@@ -197,4 +231,4 @@ const doDelete = db.transaction(() => {
 });
 ```
 
-For all HTTP endpoints, see `api-routes.md`.
+For all HTTP endpoints, see `api-routes.md`.