Knowledge Graph: Implement cascading cleanup when memories are deleted

[smian1]

Problem

When a memory is deleted via the API (DELETE /v3/memories/{memory_id}), the knowledge graph is not updated. This leaves orphaned references and stale data in the graph.

Currently:

• ✅ Memory is deleted from the memories collection
• ❌ Knowledge graph nodes/edges still contain the deleted memory_id in their memory_ids arrays
• ❌ Nodes/edges remain in the graph even if they were only derived from deleted memories

Impact:

• Graph contains stale entities that no longer have valid source memories
• memory_ids arrays contain invalid references
• Graph becomes progressively "dirty" as users delete memories
• Only way to fix currently is a full rebuild (POST /v1/knowledge-graph/rebuild)

---

Expected Behavior

When a memory is deleted, the knowledge graph should automatically clean itself:

1. Remove the memory ID from all nodes — scan nodes and remove the deleted memory_id from their memory_ids array
2. Remove the memory ID from all edges — scan edges and remove the deleted memory_id from their memory_ids array
3. Delete orphaned nodes — if a node's memory_ids array becomes empty after cleanup, delete the node
4. Delete orphaned edges — if an edge's memory_ids array becomes empty, OR if either its source/target node was deleted, delete the edge

---

Files to Modify

• backend/routers/memories.py — delete_memory() endpoint
• backend/database/knowledge_graph.py — may need new helper functions for cleanup

---

Considerations

• This should also apply to DELETE /v3/memories (bulk delete all memories) — in that case, the entire knowledge graph should be cleared
• Consider whether this cleanup should be synchronous or run as a background task (for performance)
• Edge case: if a node/edge has multiple memory_ids, only remove the one being deleted, don't delete the node/edge itself

---

Acceptance Criteria

• Deleting a single memory removes its ID from all graph nodes and edges
• Nodes with empty memory_ids are automatically deleted
• Edges with empty memory_ids or missing source/target nodes are automatically deleted
• Bulk memory delete clears the entire knowledge graph
• No orphaned references remain after memory deletion

[fayerman-source]

Hi @smian1, I’ve completed the cascading cleanup for the Knowledge Graph as outlined in the issue.

PR #4009 is ready for review and meets all the requirements:

• Transactional Integrity: Leverages Firestore transactions to ensure atomic updates and deletions, avoiding a “dirty graph” state.
• Edge Case Handling: Removes specific memory_ids from arrays while preserving the node/edge if other sources remain.
• Orphan Management: Automatically deletes nodes with empty source lists and edges whose source or target nodes have been removed.
• Scalability: Uses chunking to stay within Firestore limits.
• Bulk Delete: Integrated with the DELETE /v3/memories endpoint to wipe the entire graph.

Excited to hear your thoughts!