feat: unified cross-entity linking and recall (Memory ↔ Room ↔ Document ↔ Graph)

[ajianaz]

Problem

Uteke has 4 core data entities (Memory, Room, Document, Graph) but they operate as isolated silos. There is no way to:

1. Recall memories referencing a document (or vice versa)
2. See what documents are relevant to a room discussion
3. Traverse from a memory to related documents through the graph

Current Architecture

Memory ←room_memories→ Room          (✅ linked)
Memory ←memory_edges→   Memory       (✅ linked, indexed BFS via edge_bfs)
Memory ←graph_nodes→    Graph        (✅ linked via FK)
Document ←doc_chunks→   Document     (✅ hierarchical)
Memory ←references_doc→ Document    (✅ linked — wire_edges auto-detects [[doc-slug]])
Room    ←room_documents→ Document    (✅ linked — v15 schema, CRUD exists)

Remaining Issues ✅ ALL FIXED

• A. get_related() O(n) full table scan ✅ FIXED
• B. Memory ↔ Document: No cross-reference ✅ FIXED (wire_edges + EDGE_REFERENCES_DOC)
• D. recall_room() SQL missing columns ✅ FIXED
• E. No tests for Room operations ✅ FIXED (PR5 test: room operations test suite (#689 PR5) #701, 44 tests)

---

Solution

Approach: Edge-based linking via [[slug]] wikilinks + existing junction table for rooms

• Memory ↔ Document: wire_edges auto-detects [[doc-slug]] patterns in memory content → creates references_doc edge → queryable via recall_memories_for_document() / recall_documents_for_memory()
• Room ↔ Document: room_documents junction table (v15) + room_summary_with_docs() enrichment
• Unified recall: recall_unified(enrich=true) populates linked_doc_slugs / linked_memory_ids

PR Progress

PR	Description	PR	Status
PR1	Fix get_related() + recall_room() bugs	—	✅ Done
PR5	Room operations test suite (44 tests)	#701	✅ Merged
PR2	Cross-entity enrichment (enrich param)	#703	✅ Merged
PR3	Room → Document enrichment	#705	✅ Merged
PR4	--enrich CLI flag	#704	✅ Merged
PR6	Integration tests	#pending	🔄 In progress

Deliverables per PR

PR2 (#703) — Cross-entity enrichment

• [[doc-slug]] wikilink extraction via wire_edges (auto on remember)
• EDGE_REFERENCES_DOC edge type + backlinks
• recall_memories_for_document(slug) / recall_documents_for_memory(memory_id)
• recall_unified(enrich: bool) — populates linked_doc_slugs / linked_memory_ids
• HTTP API: RecallRequest.enrich field
• 3 enrichment tests (#[ignore] — requires ONNX)

PR3 (#705) — Room → Document enrichment

• RoomSummary.referenced_documents: Option<Vec<String>>
• room_summary_with_docs(room_id) — returns summary with referenced docs
• 3 unit tests

PR4 (#704) — --enrich CLI flag

• --enrich flag on recall command
• Human output: 📄 Docs: for linked doc slugs, 🔗 Memories: N for linked memory count

PR5 (#701) — Room test suite

• 44 test functions (33 Store-level + 11 Uteke-level)
• Full coverage: CRUD, recall, summary, junction table, cascade delete

PR6 — Integration tests

• Store-level cross-entity edge round-trip
• Room ↔ Document full flow
• E2E wikilink tests (#[ignore] — requires ONNX)