feat(memory): knowledge graph memory with temporal entity-relationship tracking #1222
Description
Summary
Add graph-based knowledge memory to augment existing vector + keyword semantic search. The graph stores entities, relationships, and communities extracted from conversations, enabling multi-hop reasoning, temporal fact tracking, and cross-session entity linking.
Motivation
Current limitations of flat vector + FTS5 search:
- No entity relationships (cannot answer "how is X related to Y?")
- No multi-hop reasoning (cannot chain A->B->C)
- No temporal fact tracking (cannot track "user preferred X, then switched to Y")
- No contradiction detection (conflicting facts coexist)
- No cross-session entity linking
Industry benchmarks (Zep/Graphiti, arxiv:2501.13956) show +18.5% accuracy on multi-session temporal reasoning and 90% latency reduction vs full-context approaches.
Architecture
- Storage: SQLite adjacency tables (
graph_entities,graph_edges,graph_communities) + Qdrant embeddings for entity/fact search - Extraction: LLM-powered entity/relation extraction running in background (non-blocking)
- Resolution: Exact-match entity deduplication (MVP), embedding-based resolution (follow-up)
- Retrieval: Entity match + recursive CTE BFS + RRF fusion with existing vector/keyword results
- Temporal: Bi-temporal edges (valid_from/valid_to for facts, created_at/expired_at for ingestion)
- Feature flag:
graph-memory(opt-in, zero impact on existing pipeline)
Design Documents
- Research:
.local/plan/graph-memory-research.md - Architecture:
.local/plan/graph-memory-architecture.md - Critique:
.local/plan/graph-memory-critique.md
Implementation Phases
- Phase 0: refactor(memory): Arc-wrap EmbeddingStore and FuturesUnordered context preparation #1223 — Prerequisite refactors (Arc-wrap EmbeddingStore, FuturesUnordered context)
- Phase 1: feat(memory): graph memory schema, core types, and CRUD operations #1224 — Schema & Core Types (migration 021, CRUD, GraphConfig)
- Phase 2: feat(memory): LLM-powered entity and relation extraction pipeline #1225 — Entity & Relation Extraction (LLM pipeline, resolver)
- Phase 3: feat(memory): graph-aware retrieval with BFS traversal and RRF fusion #1226 — Graph-Aware Retrieval (BFS + RRF fusion)
- Phase 4: feat(memory): background graph extraction and agent loop integration #1227 — Background Extraction & Integration (agent loop, TUI spinner)
- Phase 5: feat(memory): community detection with label propagation #1228 — Community Detection (label propagation, petgraph)
- Phase 6: feat(memory): graph memory init wizard, TUI commands, and observability #1229 — Init Wizard, TUI & Observability (CLI, /graph commands, docs)
Cross-Epic Dependencies (with #1195 Untrusted Content Isolation)
| Graph Memory | Security Epic | Relationship |
|---|---|---|
| #1225 (extraction write) | #1207 (memory write poisoning) | Graph extraction is a new write path — poisoning guard must cover GraphStore writes |
| #1226 (graph retrieval) | #1203 (memory retrieval sanitization) | Graph recall is a new read path — sanitizer must cover graph_recall() output |
| #1223 (FuturesUnordered refactor) | #1199 (context sanitizer, closed) | Refactoring must preserve sanitizer integration from #1199 |
| #1228 (community summaries) | #1204 (quarantined summarizer) | Shared pattern: isolated LLM call — first implemented sets the abstraction |
Recommended order: #1207 before or with #1225; #1203 before or with #1226.
Follow-up Issues
- feat(memory): embedding-based entity resolution for graph memory #1230 — Embedding-based entity resolution
- feat(memory): entity canonicalization with alias table #1231 — Entity canonicalization with alias table
- feat(memory): FTS5 index for graph entities #1232 — FTS5 index for graph entities
- feat(memory): graph memory budget tuning with A/B testing #1233 — Budget tuning with A/B testing
Estimates
- ~2800 LOC production + ~1300 LOC tests
- 92 new tests across 6 phases
- Feature-gated: zero impact when disabled