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)

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