Skip to main content

second_brain_core/
kuzu_store.rs

1use std::collections::HashMap;
2use std::path::Path;
3use std::sync::RwLock;
4
5use anyhow::{Context, Result};
6use chrono::{DateTime, Utc};
7use kuzu::{Connection, Database, SystemConfig, Value};
8use uuid::Uuid;
9
10use crate::schema::{
11    Conversation, Entity, Memory, MemoryType, Relation, RelationType, SyncEntry, SyncNodeType,
12    SyncOp, SyncState,
13};
14use crate::store::Store;
15
16type RelationsCache = HashMap<(Uuid, Option<RelationType>), Vec<Relation>>;
17
18pub enum ApplyOutcome {
19    Created,
20    Updated,
21    Deleted,
22    Skipped,
23}
24
25pub struct KuzuStore {
26    db: Database,
27    machine_id: String,
28    // get_relations(id, rel_type) is deterministic and query-independent: its result
29    // only changes when an edge rooted at `id` is created or removed. Caching between
30    // such writes is correct, so every write path that touches a memory's outgoing
31    // edges must evict the affected key (invariant enforced below).
32    relations_cache: RwLock<RelationsCache>,
33}
34
35fn memory_return_cols(alias: &str) -> String {
36    ["id", "content", "memory_type", "confidence", "created_at", "last_accessed", "access_count", "source", "source_id", "project_path", "machine_id", "updated_at"]
37        .iter()
38        .map(|col| format!("{alias}.{col}"))
39        .collect::<Vec<_>>()
40        .join(", ")
41}
42
43fn project_path_from_db(s: &str) -> Option<String> {
44    if s.is_empty() { None } else { Some(s.to_string()) }
45}
46
47impl KuzuStore {
48    pub fn open(path: &Path, machine_id: String) -> Result<Self> {
49        let db = Database::new(path, SystemConfig::default()).context("opening KùzuDB database")?;
50        let store = Self {
51            db,
52            machine_id,
53            relations_cache: RwLock::new(HashMap::new()),
54        };
55        store.init_schema()?;
56        Ok(store)
57    }
58
59    pub fn in_memory(machine_id: String) -> Result<Self> {
60        let db =
61            Database::in_memory(SystemConfig::default()).context("creating in-memory KùzuDB")?;
62        let store = Self {
63            db,
64            machine_id,
65            relations_cache: RwLock::new(HashMap::new()),
66        };
67        store.init_schema()?;
68        Ok(store)
69    }
70
71    fn evict_relations_for(&self, id: Uuid) {
72        let mut cache = self.relations_cache.write().unwrap();
73        cache.retain(|(key_id, _), _| *key_id != id);
74    }
75
76    // A full clear is acceptable on bulk maintenance paths (consolidation purge,
77    // delete-by-source, entity/conversation detach) because they are bursty and rare,
78    // not per-recall, and enumerating every memory whose outgoing edge count changed
79    // (e.g. memories that MENTIONS a deleted entity) is not cheap. Clearing is always
80    // sound; it only discards warmth, never correctness.
81    fn clear_relations_cache(&self) {
82        self.relations_cache.write().unwrap().clear();
83    }
84
85    pub fn machine_id(&self) -> &str {
86        &self.machine_id
87    }
88
89    fn conn(&self) -> Result<Connection<'_>> {
90        Connection::new(&self.db).context("creating connection")
91    }
92
93    pub fn diagnostic(&self) -> Result<String> {
94        let conn = self.conn()?;
95
96        let mut result = conn.query("MATCH (m:Memory) RETURN count(m);")?;
97        let total: i64 = result
98            .next()
99            .map(|r| match &r[0] {
100                Value::Int64(v) => *v,
101                _ => -1,
102            })
103            .unwrap_or(-1);
104
105        let mut result = conn.query(
106            "MATCH (m:Memory) WHERE size(m.embedding) > 0 AND m.embedding[1] <> 0.0 RETURN count(m);",
107        )?;
108        let with_emb: i64 = result
109            .next()
110            .map(|r| match &r[0] {
111                Value::Int64(v) => *v,
112                _ => -1,
113            })
114            .unwrap_or(-1);
115
116        let zeros: Vec<String> = (0..384).map(|_| "0.0".to_string()).collect();
117        let zeros_str = format!("[{}]", zeros.join(","));
118        let idx_query = format!(
119            "CALL QUERY_VECTOR_INDEX('Memory', 'memory_emb_idx', {}, 1) YIELD node, distance RETURN distance;",
120            zeros_str
121        );
122        let idx_status = match conn.query(&idx_query) {
123            Ok(mut r) => match r.next() {
124                Some(row) => format!("ok (distance: {:?})", &row[0]),
125                None => "ok (0 results)".to_string(),
126            },
127            Err(e) => format!("error: {e}"),
128        };
129
130        Ok(format!(
131            "total memories: {total}\nwith embeddings: {with_emb}\nvector index: {idx_status}"
132        ))
133    }
134
135    fn init_schema(&self) -> Result<()> {
136        let conn = self.conn()?;
137
138        conn.query(
139            "CREATE NODE TABLE IF NOT EXISTS Memory(
140                id STRING PRIMARY KEY,
141                content STRING,
142                embedding FLOAT[384],
143                memory_type STRING,
144                confidence FLOAT,
145                created_at STRING,
146                last_accessed STRING,
147                access_count INT64,
148                source STRING,
149                source_id STRING,
150                project_path STRING
151            );",
152        )
153        .context("creating Memory table")?;
154
155        conn.query("ALTER TABLE Memory ADD project_path STRING DEFAULT '';").ok();
156
157        conn.query(
158            "CREATE NODE TABLE IF NOT EXISTS Machine(
159                id STRING PRIMARY KEY,
160                name STRING
161            );",
162        )
163        .context("creating Machine table")?;
164
165        conn.query("ALTER TABLE Memory ADD machine_id STRING DEFAULT '';").ok();
166
167        conn.query("ALTER TABLE Memory ADD updated_at STRING DEFAULT '';").ok();
168        conn.query("MATCH (m:Memory) WHERE m.updated_at = '' SET m.updated_at = m.created_at;").ok();
169
170        conn.query(
171            "CREATE NODE TABLE IF NOT EXISTS Entity(
172                id STRING PRIMARY KEY,
173                name STRING,
174                entity_type STRING,
175                embedding FLOAT[384],
176                aliases STRING[]
177            );",
178        )
179        .context("creating Entity table")?;
180
181        conn.query(
182            "CREATE NODE TABLE IF NOT EXISTS Conversation(
183                id STRING PRIMARY KEY,
184                source STRING,
185                machine_id STRING,
186                started_at STRING,
187                project_path STRING
188            );",
189        )
190        .context("creating Conversation table")?;
191
192        conn.query(
193            "CREATE NODE TABLE IF NOT EXISTS IngestLog(
194                file_path STRING PRIMARY KEY,
195                file_hash STRING,
196                ingested_at STRING,
197                memory_count INT64,
198                source STRING
199            );",
200        )
201        .context("creating IngestLog table")?;
202
203        conn.query(
204            "CREATE REL TABLE IF NOT EXISTS RELATES_TO(
205                FROM Memory TO Memory,
206                strength FLOAT,
207                context STRING
208            );",
209        )
210        .context("creating RELATES_TO rel")?;
211
212        conn.query(
213            "CREATE REL TABLE IF NOT EXISTS MENTIONS(
214                FROM Memory TO Entity,
215                position INT64
216            );",
217        )
218        .context("creating MENTIONS rel")?;
219
220        conn.query(
221            "CREATE REL TABLE IF NOT EXISTS DERIVED_FROM(
222                FROM Memory TO Conversation,
223                transformation STRING
224            );",
225        )
226        .context("creating DERIVED_FROM rel")?;
227
228        conn.query(
229            "CREATE REL TABLE IF NOT EXISTS DISTILLED_FROM(
230                FROM Memory TO Memory,
231                model STRING
232            );",
233        )
234        .context("creating DISTILLED_FROM rel")?;
235
236        conn.query(
237            "CREATE REL TABLE IF NOT EXISTS CONTRADICTS(
238                FROM Memory TO Memory,
239                resolution STRING
240            );",
241        )
242        .context("creating CONTRADICTS rel")?;
243
244        conn.query(
245            "CREATE REL TABLE IF NOT EXISTS REINFORCES(
246                FROM Memory TO Memory
247            );",
248        )
249        .context("creating REINFORCES rel")?;
250
251        conn.query(
252            "CREATE REL TABLE IF NOT EXISTS SUPERSEDES(
253                FROM Memory TO Memory,
254                reason STRING
255            );",
256        )
257        .context("creating SUPERSEDES rel")?;
258
259        self.migrate_sync_log(&conn).context("migrating SyncLog table")?;
260
261        conn.query(
262            "CREATE NODE TABLE IF NOT EXISTS SyncState(
263                peer_id STRING PRIMARY KEY,
264                last_seq INT64,
265                last_sync_at STRING
266            );",
267        )
268        .context("creating SyncState table")?;
269
270        conn.query(
271            "CREATE NODE TABLE IF NOT EXISTS ConsolidationLog(
272                memory_id STRING PRIMARY KEY,
273                distilled_id STRING,
274                consolidated_at STRING,
275                model STRING
276            );",
277        )
278        .context("creating ConsolidationLog table")?;
279
280        conn.query(
281            "CREATE NODE TABLE IF NOT EXISTS WikiExportLog(
282                id STRING PRIMARY KEY,
283                last_sync_seq INT64,
284                exported_at STRING,
285                vault_path STRING,
286                pages_created INT64,
287                pages_updated INT64,
288                memories_processed INT64
289            );",
290        )
291        .context("creating WikiExportLog table")?;
292
293        conn.query(
294            "CREATE NODE TABLE IF NOT EXISTS Tombstone(
295                node_id STRING PRIMARY KEY,
296                node_type STRING,
297                deleted_at STRING,
298                machine_id STRING);",
299        )
300        .context("creating Tombstone table")?;
301
302        conn.query(
303            "CALL CREATE_VECTOR_INDEX('Memory', 'memory_emb_idx', 'embedding', metric := 'cosine');",
304        )
305        .ok();
306
307        Ok(())
308    }
309
310    fn migrate_sync_log(&self, conn: &Connection<'_>) -> Result<()> {
311        // Probe by column: a missing column or a missing table makes the query
312        // fail, so on a fresh DB both probes fail and control falls through to
313        // the CREATE below. We drop only when the pre-redesign `seq` schema is
314        // the one actually present.
315        let new_schema_present = conn
316            .query("MATCH (s:SyncLog) RETURN s.id LIMIT 1;")
317            .is_ok();
318        if !new_schema_present {
319            let old_schema_present = conn
320                .query("MATCH (s:SyncLog) RETURN s.seq LIMIT 1;")
321                .is_ok();
322            if old_schema_present {
323                conn.query("DROP TABLE SyncLog;")?;
324                conn.query("MATCH (s:SyncState) SET s.last_seq = 0;").ok();
325            }
326        }
327        conn.query(
328            "CREATE NODE TABLE IF NOT EXISTS SyncLog(
329                id STRING PRIMARY KEY,
330                local_seq INT64,
331                origin_machine_id STRING,
332                origin_seq INT64,
333                op STRING,
334                node_type STRING,
335                node_id STRING,
336                timestamp STRING,
337                data STRING
338            );",
339        )?;
340        Ok(())
341    }
342
343    fn with_transaction<T>(&self, f: impl FnOnce(&Connection<'_>) -> Result<T>) -> Result<T> {
344        let conn = self.conn()?;
345        conn.query("BEGIN TRANSACTION;")?;
346        match f(&conn) {
347            Ok(v) => {
348                conn.query("COMMIT;")?;
349                Ok(v)
350            }
351            Err(e) => {
352                let _ = conn.query("ROLLBACK;");
353                Err(e)
354            }
355        }
356    }
357
358    fn append_sync_log(
359        &self,
360        conn: &Connection<'_>,
361        op: SyncOp,
362        node_type: SyncNodeType,
363        node_id: &str,
364        data: Option<&str>,
365        origin_machine_id: &str,
366        origin_seq: Option<i64>,
367    ) -> Result<()> {
368        let mut r = conn.query("MATCH (s:SyncLog) RETURN max(s.local_seq);")?;
369        let local_seq: i64 = match r.next() {
370            Some(row) => match &row[0] {
371                Value::Int64(n) => n + 1,
372                _ => 1,
373            },
374            None => 1,
375        };
376        let origin_seq = origin_seq.unwrap_or(local_seq);
377        let id = format!("{}:{}", origin_machine_id, origin_seq);
378        let id_esc = escape_cypher(&id);
379        let mut dup = conn.query(&format!(
380            "MATCH (s:SyncLog {{id: '{id_esc}'}}) RETURN s.id LIMIT 1;"
381        ))?;
382        if dup.next().is_some() {
383            return Ok(());
384        }
385        let timestamp = chrono::Utc::now().to_rfc3339();
386        let op_str = match op {
387            SyncOp::Create => "create",
388            SyncOp::Update => "update",
389            SyncOp::Delete => "delete",
390        };
391        let nt_str = match node_type {
392            SyncNodeType::Memory => "memory",
393            SyncNodeType::Entity => "entity",
394            SyncNodeType::Conversation => "conversation",
395            SyncNodeType::Relation => "relation",
396        };
397        let origin_machine_esc = escape_cypher(origin_machine_id);
398        let node_id_esc = escape_cypher(node_id);
399        let data_esc = data.map(escape_cypher).unwrap_or_default();
400        conn.query(&format!(
401            "CREATE (:SyncLog {{id:'{id_esc}', local_seq:{local_seq}, \
402             origin_machine_id:'{origin_machine_esc}', origin_seq:{origin_seq}, \
403             op:'{op_str}', node_type:'{nt_str}', node_id:'{node_id_esc}', \
404             timestamp:'{timestamp}', data:'{data_esc}'}});"
405        ))?;
406        Ok(())
407    }
408
409    pub fn tombstone_exists(&self, id: Uuid) -> Result<bool> {
410        let conn = self.conn()?;
411        let id_esc = escape_cypher(&id.to_string());
412        let mut result = conn.query(&format!(
413            "MATCH (t:Tombstone {{node_id: '{id_esc}'}}) RETURN t.node_id LIMIT 1;"
414        ))?;
415        Ok(result.next().is_some())
416    }
417
418    fn upsert_tombstone(
419        &self,
420        conn: &Connection<'_>,
421        node_id: &str,
422        node_type: &str,
423        machine_id: &str,
424    ) -> Result<()> {
425        let node_id_esc = escape_cypher(node_id);
426        let node_type_esc = escape_cypher(node_type);
427        let machine_id_esc = escape_cypher(machine_id);
428        let deleted_at = chrono::Utc::now().to_rfc3339();
429        conn.query(&format!(
430            "MERGE (t:Tombstone {{node_id: '{node_id_esc}'}}) \
431             SET t.node_type = '{node_type_esc}', \
432                 t.deleted_at = '{deleted_at}', \
433                 t.machine_id = '{machine_id_esc}';"
434        ))?;
435        Ok(())
436    }
437}
438
439impl Store for KuzuStore {
440    fn store_memory(&self, memory: &Memory) -> Result<()> {
441        let data = serde_json::to_string(memory).ok();
442        self.with_transaction(|conn| {
443            self.create_memory_node(conn, memory)?;
444            self.append_sync_log(
445                conn,
446                SyncOp::Create,
447                SyncNodeType::Memory,
448                &memory.id.to_string(),
449                data.as_deref(),
450                &self.machine_id,
451                None,
452            )
453        })
454    }
455
456    fn get_memory(&self, id: Uuid) -> Result<Option<Memory>> {
457        let conn = self.conn()?;
458        let query = format!(
459            "MATCH (m:Memory {{id: '{}'}}) RETURN {};",
460            id, memory_return_cols("m")
461        );
462
463        let mut result = conn.query(&query)?;
464        match result.next() {
465            Some(row) => Ok(Some(row_to_memory(&row)?)),
466            None => Ok(None),
467        }
468    }
469
470    fn delete_memory(&self, id: Uuid) -> Result<()> {
471        let id_string = id.to_string();
472        let result = self.with_transaction(|conn| {
473            conn.query(&format!(
474                "MATCH (m:Memory {{id: '{id_string}'}}) DETACH DELETE m;"
475            ))?;
476            self.upsert_tombstone(conn, &id_string, "memory", &self.machine_id)?;
477            self.append_sync_log(
478                conn,
479                SyncOp::Delete,
480                SyncNodeType::Memory,
481                &id_string,
482                None,
483                &self.machine_id,
484                None,
485            )
486        });
487        // DETACH DELETE drops this memory's outgoing edges; its cached relations are
488        // now stale. Edges where this memory was the target also vanish, but those
489        // keys belong to other source ids; a delete is rare enough that a full clear
490        // is the safe choice to avoid serving a stale neighbor's relation list.
491        self.clear_relations_cache();
492        result
493    }
494
495    fn store_entity(&self, entity: &Entity) -> Result<()> {
496        let data = serde_json::to_string(entity).ok();
497        self.with_transaction(|conn| {
498            self.create_entity_node(conn, entity)?;
499            self.append_sync_log(
500                conn,
501                SyncOp::Create,
502                SyncNodeType::Entity,
503                &entity.id.to_string(),
504                data.as_deref(),
505                &self.machine_id,
506                None,
507            )
508        })
509    }
510
511    fn get_entity(&self, id: Uuid) -> Result<Option<Entity>> {
512        let conn = self.conn()?;
513        let mut result = conn.query(&format!(
514            "MATCH (e:Entity {{id: '{}'}}) RETURN e.id, e.name, e.entity_type;",
515            id
516        ))?;
517
518        match result.next() {
519            Some(row) => Ok(Some(row_to_entity(&row)?)),
520            None => Ok(None),
521        }
522    }
523
524    fn find_entity_by_name(&self, name: &str) -> Result<Option<Entity>> {
525        let conn = self.conn()?;
526        let name_escaped = escape_cypher(name);
527        let query = format!(
528            "MATCH (e:Entity) WHERE e.name = '{}' RETURN e.id, e.name, e.entity_type;",
529            name_escaped
530        );
531        let mut result = conn.query(&query)?;
532
533        match result.next() {
534            Some(row) => Ok(Some(row_to_entity(&row)?)),
535            None => Ok(None),
536        }
537    }
538
539    fn store_conversation(&self, conversation: &Conversation) -> Result<()> {
540        let data = serde_json::to_string(conversation).ok();
541        self.with_transaction(|conn| {
542            self.create_conversation_node(conn, conversation)?;
543            self.append_sync_log(
544                conn,
545                SyncOp::Create,
546                SyncNodeType::Conversation,
547                &conversation.id.to_string(),
548                data.as_deref(),
549                &self.machine_id,
550                None,
551            )
552        })
553    }
554
555    fn store_relation(&self, relation: &Relation) -> Result<()> {
556        let rel_type = format!("{:?}", relation.relation_type).to_lowercase();
557        let node_id = format!("{}:{}:{}", relation.from_id, relation.to_id, rel_type);
558        let data = serde_json::to_string(relation).ok();
559        let result = self.with_transaction(|conn| {
560            self.create_relation_edge(conn, relation)?;
561            self.append_sync_log(
562                conn,
563                SyncOp::Create,
564                SyncNodeType::Relation,
565                &node_id,
566                data.as_deref(),
567                &self.machine_id,
568                None,
569            )
570        });
571        // get_relations keys on the source (from_id) only, so evicting that id is the
572        // exact and minimal invalidation for a new outgoing edge.
573        self.evict_relations_for(relation.from_id);
574        result
575    }
576
577    fn get_relations(
578        &self,
579        node_id: Uuid,
580        relation_type: Option<RelationType>,
581    ) -> Result<Vec<Relation>> {
582        let cache_key = (node_id, relation_type);
583        if let Some(hit) = self.relations_cache.read().unwrap().get(&cache_key) {
584            return Ok(hit.clone());
585        }
586
587        let conn = self.conn()?;
588        let id = node_id.to_string();
589
590        let query = match relation_type {
591            Some(RelationType::RelatesTo) => format!(
592                "MATCH (a:Memory {{id: '{}'}})-[r:RELATES_TO]->(b:Memory) RETURN b.id, r.strength, r.context;",
593                id
594            ),
595            Some(RelationType::Contradicts) => format!(
596                "MATCH (a:Memory {{id: '{}'}})-[r:CONTRADICTS]->(b:Memory) RETURN b.id, r.resolution;",
597                id
598            ),
599            Some(RelationType::Reinforces) => format!(
600                "MATCH (a:Memory {{id: '{}'}})-[:REINFORCES]->(b:Memory) RETURN b.id;",
601                id
602            ),
603            Some(RelationType::Supersedes) => format!(
604                "MATCH (a:Memory {{id: '{}'}})-[r:SUPERSEDES]->(b:Memory) RETURN b.id, r.reason;",
605                id
606            ),
607            Some(RelationType::Mentions) => format!(
608                "MATCH (a:Memory {{id: '{}'}})-[:MENTIONS]->(b:Entity) RETURN b.id;",
609                id
610            ),
611            Some(RelationType::DerivedFrom) => format!(
612                "MATCH (a:Memory {{id: '{}'}})-[:DERIVED_FROM]->(b:Conversation) RETURN b.id;",
613                id
614            ),
615            Some(RelationType::DistilledFrom) => format!(
616                "MATCH (a:Memory {{id: '{}'}})-[:DISTILLED_FROM]->(b:Memory) RETURN b.id;",
617                id
618            ),
619            None => {
620                let mut relations = Vec::new();
621                let mem_to_mem = [
622                    ("RELATES_TO", RelationType::RelatesTo),
623                    ("REINFORCES", RelationType::Reinforces),
624                    ("CONTRADICTS", RelationType::Contradicts),
625                    ("SUPERSEDES", RelationType::Supersedes),
626                    ("DISTILLED_FROM", RelationType::DistilledFrom),
627                ];
628                for (label, rt) in &mem_to_mem {
629                    let q = format!(
630                        "MATCH (a:Memory {{id: '{}'}})-[:{}]->(b:Memory) RETURN b.id;",
631                        id, label
632                    );
633                    if let Ok(mut result) = conn.query(&q) {
634                        for row in &mut result {
635                            let to_id_str = value_to_string(&row[0]);
636                            let to_id = Uuid::parse_str(&to_id_str).unwrap_or_default();
637                            relations.push(Relation {
638                                from_id: node_id,
639                                to_id,
640                                relation_type: *rt,
641                                strength: 1.0,
642                                context: None,
643                            });
644                        }
645                    }
646                }
647                for (label, target, rt) in [
648                    ("MENTIONS", "Entity", RelationType::Mentions),
649                    ("DERIVED_FROM", "Conversation", RelationType::DerivedFrom),
650                ] {
651                    let q = format!(
652                        "MATCH (a:Memory {{id: '{}'}})-[:{}]->(b:{}) RETURN b.id;",
653                        id, label, target
654                    );
655                    if let Ok(mut result) = conn.query(&q) {
656                        for row in &mut result {
657                            let to_id_str = value_to_string(&row[0]);
658                            let to_id = Uuid::parse_str(&to_id_str).unwrap_or_default();
659                            relations.push(Relation {
660                                from_id: node_id,
661                                to_id,
662                                relation_type: rt,
663                                strength: 1.0,
664                                context: None,
665                            });
666                        }
667                    }
668                }
669                self.relations_cache
670                    .write()
671                    .unwrap()
672                    .insert(cache_key, relations.clone());
673                return Ok(relations);
674            }
675        };
676
677        let mut result = conn.query(&query)?;
678        let mut relations = Vec::new();
679
680        for row in &mut result {
681            let to_id_str = value_to_string(&row[0]);
682            let to_id = Uuid::parse_str(&to_id_str).unwrap_or_default();
683
684            relations.push(Relation {
685                from_id: node_id,
686                to_id,
687                relation_type: relation_type.unwrap_or(RelationType::RelatesTo),
688                strength: 1.0,
689                context: None,
690            });
691        }
692
693        self.relations_cache
694            .write()
695            .unwrap()
696            .insert(cache_key, relations.clone());
697        Ok(relations)
698    }
699
700    fn vector_search(&self, embedding: &[f32], limit: usize) -> Result<Vec<(Memory, f32)>> {
701        let conn = self.conn()?;
702        let embedding_str = format_embedding(embedding);
703
704        let query = format!(
705            "CALL QUERY_VECTOR_INDEX('Memory', 'memory_emb_idx', {}, {}) YIELD node, distance
706             RETURN {}, distance;",
707            embedding_str, limit, memory_return_cols("node")
708        );
709
710        let mut result = conn.query(&query)?;
711        let mut results = Vec::new();
712
713        for row in &mut result {
714            let memory = row_to_memory(&row[..12])?;
715            let distance = value_to_f32(&row[12]);
716            let similarity = 1.0 - distance;
717            results.push((memory, similarity));
718        }
719
720        Ok(results)
721    }
722
723    fn traverse(&self, start_id: Uuid, depth: u32) -> Result<Vec<(Memory, Vec<Relation>)>> {
724        let conn = self.conn()?;
725        let query = format!(
726            "MATCH (start:Memory {{id: '{}'}})-[r:RELATES_TO|REINFORCES*1..{}]->(m:Memory)
727             RETURN DISTINCT {};",
728            start_id, depth, memory_return_cols("m")
729        );
730
731        let mut result = conn.query(&query)?;
732        let mut results = Vec::new();
733
734        for row in &mut result {
735            let memory = row_to_memory(&row)?;
736            results.push((memory, Vec::new()));
737        }
738
739        Ok(results)
740    }
741
742    fn memories_by_source(&self, source: &str) -> Result<Vec<Memory>> {
743        let conn = self.conn()?;
744        let source_escaped = escape_cypher(source);
745        let query = format!(
746            "MATCH (m:Memory) WHERE m.source = '{}' RETURN {};",
747            source_escaped, memory_return_cols("m")
748        );
749        let mut result = conn.query(&query)?;
750
751        let mut memories = Vec::new();
752        for row in &mut result {
753            memories.push(row_to_memory(&row)?);
754        }
755        Ok(memories)
756    }
757
758    fn memories_by_type(&self, memory_type: MemoryType) -> Result<Vec<Memory>> {
759        let conn = self.conn()?;
760        let type_str = format!("{:?}", memory_type).to_lowercase();
761        let query = format!(
762            "MATCH (m:Memory) WHERE m.memory_type = '{}' RETURN {};",
763            type_str, memory_return_cols("m")
764        );
765        let mut result = conn.query(&query)?;
766
767        let mut memories = Vec::new();
768        for row in &mut result {
769            memories.push(row_to_memory(&row)?);
770        }
771        Ok(memories)
772    }
773
774    fn memories_needing_decay(&self, threshold_days: u32) -> Result<Vec<Memory>> {
775        let conn = self.conn()?;
776        let cutoff = chrono::Utc::now() - chrono::Duration::days(threshold_days as i64);
777        let cutoff_str = cutoff.to_rfc3339();
778
779        let query = format!(
780            "MATCH (m:Memory) WHERE m.last_accessed < '{}' AND m.confidence > 0.05 RETURN {};",
781            cutoff_str, memory_return_cols("m")
782        );
783
784        let mut result = conn.query(&query)?;
785        let mut memories = Vec::new();
786        for row in &mut result {
787            memories.push(row_to_memory(&row)?);
788        }
789        Ok(memories)
790    }
791
792    fn update_memory(&self, memory: &Memory) -> Result<()> {
793        let id = memory.id.to_string();
794        let last_accessed = memory.last_accessed.to_rfc3339();
795        let updated_at = memory.updated_at.to_rfc3339();
796        let project_path_escaped = escape_cypher(memory.project_path.as_deref().unwrap_or(""));
797        let machine_id_escaped = escape_cypher(&memory.machine_id);
798        let data = serde_json::to_string(memory).ok();
799        self.with_transaction(|conn| {
800            let query = format!(
801                "MATCH (m:Memory {{id: '{}'}}) SET m.confidence = {}, m.last_accessed = '{}', m.access_count = {}, m.project_path = '{}', m.updated_at = '{}', m.machine_id = '{}';",
802                id, memory.confidence, last_accessed, memory.access_count, project_path_escaped, updated_at, machine_id_escaped
803            );
804            conn.query(&query)?;
805            self.append_sync_log(
806                conn,
807                SyncOp::Update,
808                SyncNodeType::Memory,
809                &id,
810                data.as_deref(),
811                &self.machine_id,
812                None,
813            )
814        })
815    }
816
817    fn record_access(&self, memory: &Memory) -> Result<()> {
818        let id_esc = escape_cypher(&memory.id.to_string());
819        let last_accessed = memory.last_accessed.to_rfc3339();
820        let last_accessed_esc = escape_cypher(&last_accessed);
821        let conn = self.conn()?;
822        conn.query(&format!(
823            "MATCH (m:Memory {{id: '{id_esc}'}}) SET \
824             m.last_accessed = '{last_accessed_esc}', \
825             m.access_count = {}, \
826             m.confidence = {};",
827            memory.access_count, memory.confidence
828        ))?;
829        Ok(())
830    }
831
832    fn text_search(&self, query: &str, limit: usize) -> Result<Vec<Memory>> {
833        let conn = self.conn()?;
834        let query_escaped = escape_cypher(&query.to_lowercase());
835        let cypher = format!(
836            "MATCH (m:Memory) WHERE lower(m.content) CONTAINS '{}' RETURN {} LIMIT {};",
837            query_escaped, memory_return_cols("m"), limit
838        );
839
840        let mut result = conn.query(&cypher)?;
841        let mut memories = Vec::new();
842        for row in &mut result {
843            memories.push(row_to_memory(&row)?);
844        }
845        Ok(memories)
846    }
847
848    fn memory_count(&self) -> Result<usize> {
849        let conn = self.conn()?;
850        let mut result = conn.query("MATCH (m:Memory) RETURN count(m);")?;
851        match result.next() {
852            Some(row) => match &row[0] {
853                Value::Int64(n) => Ok(*n as usize),
854                _ => Ok(0),
855            },
856            None => Ok(0),
857        }
858    }
859
860    fn all_memory_ids(&self) -> Result<Vec<Uuid>> {
861        let conn = self.conn()?;
862        let mut result = conn.query("MATCH (m:Memory) RETURN m.id;")?;
863        let mut ids = Vec::new();
864        for row in &mut result {
865            let id_str = value_to_string(&row[0]);
866            ids.push(Uuid::parse_str(&id_str).unwrap_or_default());
867        }
868        Ok(ids)
869    }
870
871    fn all_relations(&self) -> Result<Vec<Relation>> {
872        let conn = self.conn()?;
873        let mut relations = Vec::new();
874
875        let mem_to_mem = [
876            ("RELATES_TO", RelationType::RelatesTo),
877            ("REINFORCES", RelationType::Reinforces),
878            ("CONTRADICTS", RelationType::Contradicts),
879            ("SUPERSEDES", RelationType::Supersedes),
880            ("DISTILLED_FROM", RelationType::DistilledFrom),
881        ];
882        for (label, rt) in &mem_to_mem {
883            let q = format!(
884                "MATCH (a:Memory)-[:{}]->(b:Memory) RETURN a.id, b.id;",
885                label
886            );
887            let mut result = conn.query(&q)?;
888            for row in &mut result {
889                let from_id = Uuid::parse_str(&value_to_string(&row[0])).unwrap_or_default();
890                let to_id = Uuid::parse_str(&value_to_string(&row[1])).unwrap_or_default();
891                relations.push(Relation {
892                    from_id,
893                    to_id,
894                    relation_type: *rt,
895                    strength: 1.0,
896                    context: None,
897                });
898            }
899        }
900
901        for (label, target, rt) in [
902            ("MENTIONS", "Entity", RelationType::Mentions),
903            ("DERIVED_FROM", "Conversation", RelationType::DerivedFrom),
904        ] {
905            let q = format!(
906                "MATCH (a:Memory)-[:{}]->(b:{}) RETURN a.id, b.id;",
907                label, target
908            );
909            let mut result = conn.query(&q)?;
910            for row in &mut result {
911                let from_id = Uuid::parse_str(&value_to_string(&row[0])).unwrap_or_default();
912                let to_id = Uuid::parse_str(&value_to_string(&row[1])).unwrap_or_default();
913                relations.push(Relation {
914                    from_id,
915                    to_id,
916                    relation_type: rt,
917                    strength: 1.0,
918                    context: None,
919                });
920            }
921        }
922
923        Ok(relations)
924    }
925}
926
927impl KuzuStore {
928    pub fn find_or_create_entity(&self, name: &str, entity_type: &str) -> Result<Entity> {
929        if let Some(existing) = self.find_entity_by_name(name)? {
930            return Ok(existing);
931        }
932        let entity = Entity::new(name.to_string(), entity_type.to_string());
933        self.store_entity(&entity)?;
934        Ok(entity)
935    }
936
937    pub fn memory_content_exists(&self, content_prefix: &str) -> Result<bool> {
938        let conn = self.conn()?;
939        let escaped = escape_cypher(content_prefix);
940        let query = format!(
941            "MATCH (m:Memory) WHERE starts_with(m.content, '{}') RETURN m.id LIMIT 1;",
942            escaped
943        );
944        let mut result = conn.query(&query)?;
945        Ok(result.next().is_some())
946    }
947
948    pub fn unconsolidated_memories(&self, limit: usize) -> Result<Vec<Memory>> {
949        let conn = self.conn()?;
950        let query = format!(
951            "MATCH (m:Memory) WHERE NOT EXISTS {{MATCH (c:ConsolidationLog) WHERE c.memory_id = m.id}} AND m.source <> 'consolidation' RETURN {} LIMIT {};",
952            memory_return_cols("m"), limit
953        );
954        let mut result = conn.query(&query)?;
955        let mut memories = Vec::new();
956        for row in &mut result {
957            memories.push(row_to_memory(&row)?);
958        }
959        Ok(memories)
960    }
961
962    pub fn memories_created_between(
963        &self,
964        start: &DateTime<Utc>,
965        end: &DateTime<Utc>,
966    ) -> Result<Vec<Memory>> {
967        let conn = self.conn()?;
968        let query = format!(
969            "MATCH (m:Memory) WHERE m.created_at >= '{}' AND m.created_at < '{}' RETURN {} ORDER BY m.created_at ASC;",
970            start.to_rfc3339(),
971            end.to_rfc3339(),
972            memory_return_cols("m")
973        );
974        let mut result = conn.query(&query)?;
975        let mut memories = Vec::new();
976        for row in &mut result {
977            memories.push(row_to_memory(&row)?);
978        }
979        Ok(memories)
980    }
981
982    pub fn mark_consolidated(&self, raw_id: Uuid, distilled_id: Uuid, model: &str) -> Result<()> {
983        let conn = self.conn()?;
984        let now = Utc::now().to_rfc3339();
985        let query = format!(
986            "CREATE (:ConsolidationLog {{memory_id: '{}', distilled_id: '{}', consolidated_at: '{}', model: '{}'}});",
987            raw_id,
988            distilled_id,
989            now,
990            escape_cypher(model)
991        );
992        conn.query(&query)?;
993        Ok(())
994    }
995
996    pub fn consolidation_count(&self) -> Result<usize> {
997        let conn = self.conn()?;
998        let mut result = conn.query("MATCH (c:ConsolidationLog) RETURN count(c);")?;
999        match result.next() {
1000            Some(row) => match &row[0] {
1001                Value::Int64(n) => Ok(*n as usize),
1002                _ => Ok(0),
1003            },
1004            None => Ok(0),
1005        }
1006    }
1007
1008    pub fn delete_consolidated_raw(&self) -> Result<usize> {
1009        let ids: Vec<Uuid> = {
1010            let conn = self.conn()?;
1011            let result = conn.query(
1012                "MATCH (c:ConsolidationLog) WHERE c.memory_id <> c.distilled_id RETURN c.memory_id;",
1013            )?;
1014            let mut acc = Vec::new();
1015            for row in result {
1016                if let Value::String(id) = &row[0]
1017                    && let Ok(uuid) = Uuid::parse_str(id)
1018                {
1019                    acc.push(uuid);
1020                }
1021            }
1022            acc
1023        };
1024        let count = ids.len();
1025        let machine_id = self.machine_id.clone();
1026        for id in &ids {
1027            let id_str = id.to_string();
1028            let mid = machine_id.clone();
1029            self.with_transaction(|conn| {
1030                conn.query(&format!(
1031                    "MATCH (m:Memory {{id: '{id_str}'}}) DETACH DELETE m;"
1032                ))?;
1033                self.upsert_tombstone(conn, &id_str, "memory", &mid)?;
1034                self.append_sync_log(
1035                    conn,
1036                    SyncOp::Delete,
1037                    SyncNodeType::Memory,
1038                    &id_str,
1039                    None,
1040                    &mid,
1041                    None,
1042                )
1043            })?;
1044        }
1045        if count > 0 {
1046            self.clear_relations_cache();
1047        }
1048        Ok(count)
1049    }
1050
1051    pub fn rebuild_vector_index(&self) -> Result<()> {
1052        let conn = self.conn()?;
1053        conn.query("CALL DROP_VECTOR_INDEX('Memory', 'memory_emb_idx');")
1054            .ok();
1055        conn.query(
1056            "CALL CREATE_VECTOR_INDEX('Memory', 'memory_emb_idx', 'embedding', metric := 'cosine');",
1057        )?;
1058        Ok(())
1059    }
1060
1061    pub fn clear_ingest_log(&self) -> Result<usize> {
1062        let conn = self.conn()?;
1063        let mut result = conn.query("MATCH (l:IngestLog) RETURN count(l);")?;
1064        let count = match result.next() {
1065            Some(row) => match &row[0] {
1066                Value::Int64(n) => *n as usize,
1067                _ => 0,
1068            },
1069            None => 0,
1070        };
1071        conn.query("MATCH (l:IngestLog) DETACH DELETE l;")?;
1072        Ok(count)
1073    }
1074
1075    pub fn delete_memories_by_source(&self, source: &str) -> Result<usize> {
1076        let conn = self.conn()?;
1077        let escaped = escape_cypher(source);
1078        let mut result = conn.query(&format!(
1079            "MATCH (m:Memory) WHERE m.source = '{}' RETURN count(m);",
1080            escaped
1081        ))?;
1082        let count = match result.next() {
1083            Some(row) => match &row[0] {
1084                Value::Int64(n) => *n as usize,
1085                _ => 0,
1086            },
1087            None => 0,
1088        };
1089        conn.query(&format!(
1090            "MATCH (m:Memory) WHERE m.source = '{}' DETACH DELETE m;",
1091            escaped
1092        ))?;
1093        if count > 0 {
1094            self.clear_relations_cache();
1095        }
1096        Ok(count)
1097    }
1098
1099
1100    pub fn delete_memories_by_source_id(&self, source_id: &str) -> Result<usize> {
1101        let conn = self.conn()?;
1102        let escaped = escape_cypher(source_id);
1103        let mut result = conn.query(&format!(
1104            "MATCH (m:Memory) WHERE m.source_id = '{}' RETURN count(m);",
1105            escaped
1106        ))?;
1107        let count = match result.next() {
1108            Some(row) => match &row[0] {
1109                Value::Int64(n) => *n as usize,
1110                _ => 0,
1111            },
1112            None => 0,
1113        };
1114        conn.query(&format!(
1115            "MATCH (m:Memory) WHERE m.source_id = '{}' DETACH DELETE m;",
1116            escaped
1117        ))?;
1118        if count > 0 {
1119            self.clear_relations_cache();
1120        }
1121        Ok(count)
1122    }
1123
1124    pub fn is_file_ingested(&self, file_path: &str) -> Result<bool> {
1125        let conn = self.conn()?;
1126        let escaped = escape_cypher(file_path);
1127        let mut result = conn.query(&format!(
1128            "MATCH (l:IngestLog {{file_path: '{}'}}) RETURN l.file_path;",
1129            escaped
1130        ))?;
1131        Ok(result.next().is_some())
1132    }
1133
1134    pub fn is_file_changed(&self, file_path: &str, file_hash: &str) -> Result<bool> {
1135        let conn = self.conn()?;
1136        let escaped = escape_cypher(file_path);
1137        let mut result = conn.query(&format!(
1138            "MATCH (l:IngestLog {{file_path: '{}'}}) RETURN l.file_hash;",
1139            escaped
1140        ))?;
1141        match result.next() {
1142            Some(row) => {
1143                let stored_hash = value_to_string(&row[0]);
1144                Ok(stored_hash != file_hash)
1145            }
1146            None => Ok(true),
1147        }
1148    }
1149
1150    pub fn mark_ingested(
1151        &self,
1152        file_path: &str,
1153        file_hash: &str,
1154        memory_count: usize,
1155        source: &str,
1156    ) -> Result<()> {
1157        let conn = self.conn()?;
1158        let path_escaped = escape_cypher(file_path);
1159        let hash_escaped = escape_cypher(file_hash);
1160        let source_escaped = escape_cypher(source);
1161        let now = chrono::Utc::now().to_rfc3339();
1162
1163        conn.query(&format!(
1164            "MERGE (l:IngestLog {{file_path: '{}'}})
1165             SET l.file_hash = '{}', l.ingested_at = '{}', l.memory_count = {}, l.source = '{}';",
1166            path_escaped, hash_escaped, now, memory_count as i64, source_escaped
1167        ))?;
1168        Ok(())
1169    }
1170
1171    pub fn ingested_file_count(&self) -> Result<usize> {
1172        let conn = self.conn()?;
1173        let mut result = conn.query("MATCH (l:IngestLog) RETURN count(l);")?;
1174        match result.next() {
1175            Some(row) => match &row[0] {
1176                Value::Int64(n) => Ok(*n as usize),
1177                _ => Ok(0),
1178            },
1179            None => Ok(0),
1180        }
1181    }
1182}
1183
1184impl KuzuStore {
1185    fn create_memory_node(&self, conn: &Connection<'_>, memory: &Memory) -> Result<()> {
1186        let id = memory.id.to_string();
1187        let memory_type = format!("{:?}", memory.memory_type).to_lowercase();
1188        let created_at = memory.created_at.to_rfc3339();
1189        let last_accessed = memory.last_accessed.to_rfc3339();
1190        let embedding_str = format_embedding(&memory.embedding);
1191        let content_escaped = escape_cypher(&memory.content);
1192        let source_escaped = escape_cypher(&memory.source);
1193        let source_id_escaped = escape_cypher(&memory.source_id);
1194        let project_path_escaped = escape_cypher(memory.project_path.as_deref().unwrap_or(""));
1195        let machine_id_escaped = escape_cypher(&memory.machine_id);
1196        let updated_at = memory.updated_at.to_rfc3339();
1197
1198        let query = format!(
1199            "CREATE (:Memory {{
1200                id: '{id}',
1201                content: '{content_escaped}',
1202                embedding: {embedding_str},
1203                memory_type: '{memory_type}',
1204                confidence: {confidence},
1205                created_at: '{created_at}',
1206                last_accessed: '{last_accessed}',
1207                access_count: {access_count},
1208                source: '{source_escaped}',
1209                source_id: '{source_id_escaped}',
1210                project_path: '{project_path_escaped}',
1211                machine_id: '{machine_id_escaped}',
1212                updated_at: '{updated_at}'
1213            }});",
1214            confidence = memory.confidence,
1215            access_count = memory.access_count,
1216        );
1217
1218        conn.query(&query)?;
1219        Ok(())
1220    }
1221
1222    fn create_entity_node(&self, conn: &Connection<'_>, entity: &Entity) -> Result<()> {
1223        let id = entity.id.to_string();
1224        let embedding_str = format_embedding(&entity.embedding);
1225        let aliases_str = format_string_array(&entity.aliases);
1226        let name_escaped = escape_cypher(&entity.name);
1227        let etype_escaped = escape_cypher(&entity.entity_type);
1228
1229        let query = format!(
1230            "CREATE (:Entity {{
1231                id: '{id}',
1232                name: '{name_escaped}',
1233                entity_type: '{etype_escaped}',
1234                embedding: {embedding_str},
1235                aliases: {aliases_str}
1236            }});"
1237        );
1238
1239        conn.query(&query)?;
1240        Ok(())
1241    }
1242
1243    fn create_conversation_node(
1244        &self,
1245        conn: &Connection<'_>,
1246        conversation: &Conversation,
1247    ) -> Result<()> {
1248        let id = conversation.id.to_string();
1249        let started_at = conversation.started_at.to_rfc3339();
1250        let source_escaped = escape_cypher(&conversation.source);
1251        let machine_escaped = escape_cypher(&conversation.machine_id);
1252        let project_escaped = escape_cypher(conversation.project_path.as_deref().unwrap_or(""));
1253
1254        let query = format!(
1255            "CREATE (:Conversation {{
1256                id: '{id}',
1257                source: '{source_escaped}',
1258                machine_id: '{machine_escaped}',
1259                started_at: '{started_at}',
1260                project_path: '{project_escaped}'
1261            }});"
1262        );
1263
1264        conn.query(&query)?;
1265        Ok(())
1266    }
1267
1268    fn create_relation_edge(&self, conn: &Connection<'_>, relation: &Relation) -> Result<()> {
1269        let from_id = relation.from_id.to_string();
1270        let to_id = relation.to_id.to_string();
1271
1272        let query = match relation.relation_type {
1273            RelationType::RelatesTo => format!(
1274                "MATCH (a:Memory {{id: '{}'}}), (b:Memory {{id: '{}'}}) CREATE (a)-[:RELATES_TO {{strength: {}, context: '{}'}}]->(b);",
1275                from_id,
1276                to_id,
1277                relation.strength,
1278                relation.context.as_deref().unwrap_or("")
1279            ),
1280            RelationType::Mentions => format!(
1281                "MATCH (a:Memory {{id: '{}'}}), (b:Entity {{id: '{}'}}) CREATE (a)-[:MENTIONS {{position: 0}}]->(b);",
1282                from_id, to_id
1283            ),
1284            RelationType::DerivedFrom => format!(
1285                "MATCH (a:Memory {{id: '{}'}}), (b:Conversation {{id: '{}'}}) CREATE (a)-[:DERIVED_FROM {{transformation: '{}'}}]->(b);",
1286                from_id,
1287                to_id,
1288                relation.context.as_deref().unwrap_or("direct")
1289            ),
1290            RelationType::Contradicts => format!(
1291                "MATCH (a:Memory {{id: '{}'}}), (b:Memory {{id: '{}'}}) CREATE (a)-[:CONTRADICTS {{resolution: '{}'}}]->(b);",
1292                from_id,
1293                to_id,
1294                relation.context.as_deref().unwrap_or("")
1295            ),
1296            RelationType::Reinforces => format!(
1297                "MATCH (a:Memory {{id: '{}'}}), (b:Memory {{id: '{}'}}) CREATE (a)-[:REINFORCES]->(b);",
1298                from_id, to_id
1299            ),
1300            RelationType::DistilledFrom => format!(
1301                "MATCH (a:Memory {{id: '{}'}}), (b:Memory {{id: '{}'}}) CREATE (a)-[:DISTILLED_FROM {{model: '{}'}}]->(b);",
1302                from_id,
1303                to_id,
1304                relation.context.as_deref().unwrap_or("")
1305            ),
1306            RelationType::Supersedes => format!(
1307                "MATCH (a:Memory {{id: '{}'}}), (b:Memory {{id: '{}'}}) CREATE (a)-[:SUPERSEDES {{reason: '{}'}}]->(b);",
1308                from_id,
1309                to_id,
1310                relation.context.as_deref().unwrap_or("")
1311            ),
1312        };
1313
1314        conn.query(&query)?;
1315        Ok(())
1316    }
1317}
1318
1319impl KuzuStore {
1320    pub fn get_conversation(&self, id: Uuid) -> Result<Option<Conversation>> {
1321        let conn = self.conn()?;
1322        let mut result = conn.query(&format!(
1323            "MATCH (c:Conversation {{id: '{}'}}) RETURN c.id, c.source, c.machine_id, c.started_at, c.project_path;",
1324            id
1325        ))?;
1326
1327        match result.next() {
1328            Some(row) => {
1329                let id = Uuid::parse_str(&value_to_string(&row[0])).unwrap_or_default();
1330                let source = value_to_string(&row[1]);
1331                let machine_id = value_to_string(&row[2]);
1332                let started_at_str = value_to_string(&row[3]);
1333                let project_path = {
1334                    let s = value_to_string(&row[4]);
1335                    if s.is_empty() { None } else { Some(s) }
1336                };
1337                let started_at = chrono::DateTime::parse_from_rfc3339(&started_at_str)
1338                    .map(|dt| dt.with_timezone(&chrono::Utc))
1339                    .unwrap_or_else(|_| chrono::Utc::now());
1340
1341                Ok(Some(Conversation {
1342                    id,
1343                    source,
1344                    machine_id,
1345                    started_at,
1346                    project_path,
1347                }))
1348            }
1349            None => Ok(None),
1350        }
1351    }
1352
1353    pub fn get_memory_with_embedding(&self, id: Uuid) -> Result<Option<Memory>> {
1354        let conn = self.conn()?;
1355        let query = format!(
1356            "MATCH (m:Memory {{id: '{}'}}) RETURN {}, m.embedding;",
1357            id, memory_return_cols("m")
1358        );
1359
1360        let mut result = conn.query(&query)?;
1361        match result.next() {
1362            Some(row) => {
1363                let mut memory = row_to_memory(&row[..12])?;
1364                memory.embedding = value_to_f32_vec(&row[12]);
1365                Ok(Some(memory))
1366            }
1367            None => Ok(None),
1368        }
1369    }
1370
1371    pub fn sync_log_since(&self, after_seq: u64) -> Result<Vec<SyncEntry>> {
1372        self.sync_log_page(after_seq, None)
1373    }
1374
1375    fn tombstone_exists_on(&self, conn: &Connection<'_>, id: Uuid) -> Result<bool> {
1376        let id_esc = escape_cypher(&id.to_string());
1377        let mut result = conn.query(&format!(
1378            "MATCH (t:Tombstone {{node_id: '{id_esc}'}}) RETURN t.node_id LIMIT 1;"
1379        ))?;
1380        Ok(result.next().is_some())
1381    }
1382
1383    fn normalize_incoming(mem: &mut Memory) {
1384        if mem.updated_at == DateTime::UNIX_EPOCH {
1385            mem.updated_at = mem.created_at;
1386        }
1387    }
1388
1389    pub fn apply_create_memory(
1390        &self,
1391        mem: &Memory,
1392        origin_machine_id: &str,
1393        origin_seq: i64,
1394    ) -> Result<ApplyOutcome> {
1395        let mut mem = mem.clone();
1396        Self::normalize_incoming(&mut mem);
1397        let data = serde_json::to_string(&mem).ok();
1398        let node_id = mem.id.to_string();
1399        self.with_transaction(|conn| {
1400            if self.tombstone_exists_on(conn, mem.id)? {
1401                return Ok(ApplyOutcome::Skipped);
1402            }
1403            if self.get_memory(mem.id)?.is_some() {
1404                return Ok(ApplyOutcome::Skipped);
1405            }
1406            self.create_memory_node(conn, &mem)?;
1407            self.append_sync_log(
1408                conn,
1409                SyncOp::Create,
1410                SyncNodeType::Memory,
1411                &node_id,
1412                data.as_deref(),
1413                origin_machine_id,
1414                Some(origin_seq),
1415            )?;
1416            Ok(ApplyOutcome::Created)
1417        })
1418    }
1419
1420    // Holds a single write transaction open for the whole closure so a batch of
1421    // creates commits with one fsync instead of one per record. KuzuDB is single
1422    // writer and forbids nested transactions, so the closure must not call any
1423    // method that opens its own transaction; it may only use the `*_on_tx` apply
1424    // helpers and read-only lookups (which run on separate read connections and
1425    // see committed state, matching the per-record skip semantics).
1426    pub fn with_write_transaction<T>(
1427        &self,
1428        f: impl FnOnce(&Connection<'_>) -> Result<T>,
1429    ) -> Result<T> {
1430        self.with_transaction(f)
1431    }
1432
1433    pub fn apply_create_memory_on_tx(
1434        &self,
1435        conn: &Connection<'_>,
1436        mem: &Memory,
1437        origin_machine_id: &str,
1438        origin_seq: i64,
1439    ) -> Result<ApplyOutcome> {
1440        let mut mem = mem.clone();
1441        Self::normalize_incoming(&mut mem);
1442        let data = serde_json::to_string(&mem).ok();
1443        let node_id = mem.id.to_string();
1444        if self.tombstone_exists_on(conn, mem.id)? {
1445            return Ok(ApplyOutcome::Skipped);
1446        }
1447        if self.get_memory(mem.id)?.is_some() {
1448            return Ok(ApplyOutcome::Skipped);
1449        }
1450        self.create_memory_node(conn, &mem)?;
1451        self.append_sync_log(
1452            conn,
1453            SyncOp::Create,
1454            SyncNodeType::Memory,
1455            &node_id,
1456            data.as_deref(),
1457            origin_machine_id,
1458            Some(origin_seq),
1459        )?;
1460        Ok(ApplyOutcome::Created)
1461    }
1462
1463    pub fn apply_create_conversation_on_tx(
1464        &self,
1465        conn: &Connection<'_>,
1466        conv: &Conversation,
1467        origin_machine_id: &str,
1468        origin_seq: i64,
1469    ) -> Result<ApplyOutcome> {
1470        let data = serde_json::to_string(conv).ok();
1471        let node_id = conv.id.to_string();
1472        if self.get_conversation(conv.id)?.is_some() {
1473            return Ok(ApplyOutcome::Skipped);
1474        }
1475        self.create_conversation_node(conn, conv)?;
1476        self.append_sync_log(
1477            conn,
1478            SyncOp::Create,
1479            SyncNodeType::Conversation,
1480            &node_id,
1481            data.as_deref(),
1482            origin_machine_id,
1483            Some(origin_seq),
1484        )?;
1485        Ok(ApplyOutcome::Created)
1486    }
1487
1488    pub fn apply_create_entity_on_tx(
1489        &self,
1490        conn: &Connection<'_>,
1491        entity: &Entity,
1492        origin_machine_id: &str,
1493        origin_seq: i64,
1494    ) -> Result<ApplyOutcome> {
1495        let data = serde_json::to_string(entity).ok();
1496        let node_id = entity.id.to_string();
1497        if self.get_entity(entity.id)?.is_some() {
1498            return Ok(ApplyOutcome::Skipped);
1499        }
1500        self.create_entity_node(conn, entity)?;
1501        self.append_sync_log(
1502            conn,
1503            SyncOp::Create,
1504            SyncNodeType::Entity,
1505            &node_id,
1506            data.as_deref(),
1507            origin_machine_id,
1508            Some(origin_seq),
1509        )?;
1510        Ok(ApplyOutcome::Created)
1511    }
1512
1513    pub fn apply_create_relation_on_tx(
1514        &self,
1515        conn: &Connection<'_>,
1516        relation: &Relation,
1517        origin_machine_id: &str,
1518        origin_seq: i64,
1519    ) -> Result<ApplyOutcome> {
1520        let rel_type = format!("{:?}", relation.relation_type).to_lowercase();
1521        let node_id = format!("{}:{}:{}", relation.from_id, relation.to_id, rel_type);
1522        let data = serde_json::to_string(relation).ok();
1523        match self.create_relation_edge(conn, relation) {
1524            Ok(()) => {
1525                self.append_sync_log(
1526                    conn,
1527                    SyncOp::Create,
1528                    SyncNodeType::Relation,
1529                    &node_id,
1530                    data.as_deref(),
1531                    origin_machine_id,
1532                    Some(origin_seq),
1533                )?;
1534                Ok(ApplyOutcome::Created)
1535            }
1536            // create_relation_edge fails when an endpoint node is absent; a relation
1537            // whose endpoints are not present yet is skipped, matching the per-record path.
1538            Err(_) => Ok(ApplyOutcome::Skipped),
1539        }
1540    }
1541
1542    pub fn note_relation_created(&self, from_id: Uuid) {
1543        self.evict_relations_for(from_id);
1544    }
1545
1546    pub fn apply_update_memory(
1547        &self,
1548        incoming: &Memory,
1549        origin_machine_id: &str,
1550        origin_seq: i64,
1551    ) -> Result<(ApplyOutcome, Option<Memory>)> {
1552        let mut incoming = incoming.clone();
1553        Self::normalize_incoming(&mut incoming);
1554        let data = serde_json::to_string(&incoming).ok();
1555        let node_id = incoming.id.to_string();
1556        self.with_transaction(|conn| {
1557            match self.get_memory(incoming.id)? {
1558                None => {
1559                    if self.tombstone_exists_on(conn, incoming.id)? {
1560                        return Ok((ApplyOutcome::Skipped, None));
1561                    }
1562                    self.create_memory_node(conn, &incoming)?;
1563                    self.append_sync_log(
1564                        conn,
1565                        SyncOp::Create,
1566                        SyncNodeType::Memory,
1567                        &node_id,
1568                        data.as_deref(),
1569                        origin_machine_id,
1570                        Some(origin_seq),
1571                    )?;
1572                    Ok((ApplyOutcome::Created, Some(incoming)))
1573                }
1574                Some(existing) => {
1575                    let incoming_wins = if incoming.updated_at != existing.updated_at {
1576                        incoming.updated_at > existing.updated_at
1577                    } else if incoming.access_count != existing.access_count {
1578                        incoming.access_count > existing.access_count
1579                    } else {
1580                        incoming.machine_id > existing.machine_id
1581                    };
1582
1583                    if !incoming_wins {
1584                        return Ok((ApplyOutcome::Skipped, None));
1585                    }
1586
1587                    let id = incoming.id.to_string();
1588                    let content_escaped = escape_cypher(&incoming.content);
1589                    let memory_type = format!("{:?}", incoming.memory_type).to_lowercase();
1590                    let created_at = incoming.created_at.to_rfc3339();
1591                    let last_accessed = incoming.last_accessed.to_rfc3339();
1592                    let updated_at = incoming.updated_at.to_rfc3339();
1593                    let source_escaped = escape_cypher(&incoming.source);
1594                    let source_id_escaped = escape_cypher(&incoming.source_id);
1595                    let project_path_escaped =
1596                        escape_cypher(incoming.project_path.as_deref().unwrap_or(""));
1597                    let machine_id_escaped = escape_cypher(&incoming.machine_id);
1598                    // embedding is excluded because KuzuDB forbids SET on HNSW-indexed columns;
1599                    // the embedding is recomputed at ingest time so skipping it here is safe
1600                    conn.query(&format!(
1601                        "MATCH (m:Memory {{id: '{id}'}}) SET \
1602                         m.content = '{content_escaped}', \
1603                         m.memory_type = '{memory_type}', \
1604                         m.confidence = {confidence}, \
1605                         m.created_at = '{created_at}', \
1606                         m.last_accessed = '{last_accessed}', \
1607                         m.access_count = {access_count}, \
1608                         m.source = '{source_escaped}', \
1609                         m.source_id = '{source_id_escaped}', \
1610                         m.project_path = '{project_path_escaped}', \
1611                         m.machine_id = '{machine_id_escaped}', \
1612                         m.updated_at = '{updated_at}';",
1613                        confidence = incoming.confidence,
1614                        access_count = incoming.access_count,
1615                    ))?;
1616                    self.append_sync_log(
1617                        conn,
1618                        SyncOp::Update,
1619                        SyncNodeType::Memory,
1620                        &node_id,
1621                        data.as_deref(),
1622                        origin_machine_id,
1623                        Some(origin_seq),
1624                    )?;
1625                    Ok((ApplyOutcome::Updated, Some(incoming)))
1626                }
1627            }
1628        })
1629    }
1630
1631    pub fn apply_delete_memory(
1632        &self,
1633        node_id: &str,
1634        origin_machine_id: &str,
1635        origin_seq: i64,
1636    ) -> Result<ApplyOutcome> {
1637        let result = self.with_transaction(|conn| {
1638            conn.query(&format!(
1639                "MATCH (m:Memory {{id: '{node_id}'}}) DETACH DELETE m;"
1640            ))?;
1641            self.upsert_tombstone(conn, node_id, "memory", origin_machine_id)?;
1642            self.append_sync_log(
1643                conn,
1644                SyncOp::Delete,
1645                SyncNodeType::Memory,
1646                node_id,
1647                None,
1648                origin_machine_id,
1649                Some(origin_seq),
1650            )?;
1651            Ok(ApplyOutcome::Deleted)
1652        });
1653        // DETACH DELETE removes both this memory's outgoing edges and edges where it
1654        // was the target (changing neighbors' relation lists), so clear the whole cache.
1655        self.clear_relations_cache();
1656        result
1657    }
1658
1659    pub fn apply_create_conversation(
1660        &self,
1661        conv: &Conversation,
1662        origin_machine_id: &str,
1663        origin_seq: i64,
1664    ) -> Result<ApplyOutcome> {
1665        let data = serde_json::to_string(conv).ok();
1666        let node_id = conv.id.to_string();
1667        self.with_transaction(|conn| {
1668            if self.get_conversation(conv.id)?.is_some() {
1669                return Ok(ApplyOutcome::Skipped);
1670            }
1671            self.create_conversation_node(conn, conv)?;
1672            self.append_sync_log(
1673                conn,
1674                SyncOp::Create,
1675                SyncNodeType::Conversation,
1676                &node_id,
1677                data.as_deref(),
1678                origin_machine_id,
1679                Some(origin_seq),
1680            )?;
1681            Ok(ApplyOutcome::Created)
1682        })
1683    }
1684
1685    pub fn apply_upsert_conversation(
1686        &self,
1687        conv: &Conversation,
1688        origin_machine_id: &str,
1689        origin_seq: i64,
1690    ) -> Result<ApplyOutcome> {
1691        let data = serde_json::to_string(conv).ok();
1692        let node_id = conv.id.to_string();
1693        let source_escaped = escape_cypher(&conv.source);
1694        let machine_escaped = escape_cypher(&conv.machine_id);
1695        let project_escaped = escape_cypher(conv.project_path.as_deref().unwrap_or(""));
1696        let started_at = conv.started_at.to_rfc3339();
1697        self.with_transaction(|conn| {
1698            conn.query(&format!(
1699                "MERGE (c:Conversation {{id: '{node_id}'}}) SET \
1700                 c.source = '{source_escaped}', \
1701                 c.machine_id = '{machine_escaped}', \
1702                 c.started_at = '{started_at}', \
1703                 c.project_path = '{project_escaped}';"
1704            ))?;
1705            self.append_sync_log(
1706                conn,
1707                SyncOp::Update,
1708                SyncNodeType::Conversation,
1709                &node_id,
1710                data.as_deref(),
1711                origin_machine_id,
1712                Some(origin_seq),
1713            )?;
1714            Ok(ApplyOutcome::Updated)
1715        })
1716    }
1717
1718    pub fn apply_delete_conversation(
1719        &self,
1720        node_id: &str,
1721        origin_machine_id: &str,
1722        origin_seq: i64,
1723    ) -> Result<ApplyOutcome> {
1724        let result = self.with_transaction(|conn| {
1725            conn.query(&format!(
1726                "MATCH (c:Conversation {{id: '{node_id}'}}) DETACH DELETE c;"
1727            ))?;
1728            self.append_sync_log(
1729                conn,
1730                SyncOp::Delete,
1731                SyncNodeType::Conversation,
1732                node_id,
1733                None,
1734                origin_machine_id,
1735                Some(origin_seq),
1736            )?;
1737            Ok(ApplyOutcome::Deleted)
1738        });
1739        // DETACH DELETE drops DERIVED_FROM edges from memories pointing at this
1740        // conversation, changing those memories' relation lists. The source ids are not
1741        // enumerated here, so clear the whole cache.
1742        self.clear_relations_cache();
1743        result
1744    }
1745
1746    pub fn apply_create_entity(
1747        &self,
1748        entity: &Entity,
1749        origin_machine_id: &str,
1750        origin_seq: i64,
1751    ) -> Result<ApplyOutcome> {
1752        let data = serde_json::to_string(entity).ok();
1753        let node_id = entity.id.to_string();
1754        self.with_transaction(|conn| {
1755            if self.get_entity(entity.id)?.is_some() {
1756                return Ok(ApplyOutcome::Skipped);
1757            }
1758            self.create_entity_node(conn, entity)?;
1759            self.append_sync_log(
1760                conn,
1761                SyncOp::Create,
1762                SyncNodeType::Entity,
1763                &node_id,
1764                data.as_deref(),
1765                origin_machine_id,
1766                Some(origin_seq),
1767            )?;
1768            Ok(ApplyOutcome::Created)
1769        })
1770    }
1771
1772    pub fn apply_upsert_entity(
1773        &self,
1774        entity: &Entity,
1775        origin_machine_id: &str,
1776        origin_seq: i64,
1777    ) -> Result<ApplyOutcome> {
1778        let data = serde_json::to_string(entity).ok();
1779        let node_id = entity.id.to_string();
1780        let name_escaped = escape_cypher(&entity.name);
1781        let etype_escaped = escape_cypher(&entity.entity_type);
1782        let embedding_str = format_embedding(&entity.embedding);
1783        let aliases_str = format_string_array(&entity.aliases);
1784        self.with_transaction(|conn| {
1785            conn.query(&format!(
1786                "MERGE (e:Entity {{id: '{node_id}'}}) SET \
1787                 e.name = '{name_escaped}', \
1788                 e.entity_type = '{etype_escaped}', \
1789                 e.embedding = {embedding_str}, \
1790                 e.aliases = {aliases_str};"
1791            ))?;
1792            self.append_sync_log(
1793                conn,
1794                SyncOp::Update,
1795                SyncNodeType::Entity,
1796                &node_id,
1797                data.as_deref(),
1798                origin_machine_id,
1799                Some(origin_seq),
1800            )?;
1801            Ok(ApplyOutcome::Updated)
1802        })
1803    }
1804
1805    pub fn apply_delete_entity(
1806        &self,
1807        node_id: &str,
1808        origin_machine_id: &str,
1809        origin_seq: i64,
1810    ) -> Result<ApplyOutcome> {
1811        let result = self.with_transaction(|conn| {
1812            conn.query(&format!(
1813                "MATCH (e:Entity {{id: '{node_id}'}}) DETACH DELETE e;"
1814            ))?;
1815            self.append_sync_log(
1816                conn,
1817                SyncOp::Delete,
1818                SyncNodeType::Entity,
1819                node_id,
1820                None,
1821                origin_machine_id,
1822                Some(origin_seq),
1823            )?;
1824            Ok(ApplyOutcome::Deleted)
1825        });
1826        // DETACH DELETE drops MENTIONS edges from memories pointing at this entity,
1827        // changing those memories' relation lists; the source ids are not enumerated
1828        // here, so clear the whole cache.
1829        self.clear_relations_cache();
1830        result
1831    }
1832
1833    pub fn apply_create_relation(
1834        &self,
1835        relation: &Relation,
1836        origin_machine_id: &str,
1837        origin_seq: i64,
1838    ) -> Result<ApplyOutcome> {
1839        let rel_type = format!("{:?}", relation.relation_type).to_lowercase();
1840        let node_id = format!("{}:{}:{}", relation.from_id, relation.to_id, rel_type);
1841        let data = serde_json::to_string(relation).ok();
1842        let result = self.with_transaction(|conn| {
1843            match self.create_relation_edge(conn, relation) {
1844                Ok(()) => {
1845                    self.append_sync_log(
1846                        conn,
1847                        SyncOp::Create,
1848                        SyncNodeType::Relation,
1849                        &node_id,
1850                        data.as_deref(),
1851                        origin_machine_id,
1852                        Some(origin_seq),
1853                    )?;
1854                    Ok(ApplyOutcome::Created)
1855                }
1856                Err(_) => Ok(ApplyOutcome::Skipped),
1857            }
1858        });
1859        self.evict_relations_for(relation.from_id);
1860        result
1861    }
1862
1863    pub fn apply_delete_relation(
1864        &self,
1865        node_id: &str,
1866        relation: Option<&Relation>,
1867        origin_machine_id: &str,
1868        origin_seq: i64,
1869    ) -> Result<ApplyOutcome> {
1870        let Some(rel) = relation else {
1871            // Nothing to delete or relay because there is no deserializable relation data,
1872            // so skip rather than inflate the delete counter with a hollow log entry.
1873            return Ok(ApplyOutcome::Skipped);
1874        };
1875        let evict_id = rel.from_id;
1876        let result = self.with_transaction(|conn| {
1877            let from_id = rel.from_id.to_string();
1878            let to_id = rel.to_id.to_string();
1879            let rel_label = match rel.relation_type {
1880                crate::schema::RelationType::RelatesTo => "RELATES_TO",
1881                crate::schema::RelationType::Mentions => "MENTIONS",
1882                crate::schema::RelationType::DerivedFrom => "DERIVED_FROM",
1883                crate::schema::RelationType::Contradicts => "CONTRADICTS",
1884                crate::schema::RelationType::Reinforces => "REINFORCES",
1885                crate::schema::RelationType::Supersedes => "SUPERSEDES",
1886                crate::schema::RelationType::DistilledFrom => "DISTILLED_FROM",
1887            };
1888            conn.query(&format!(
1889                "MATCH (a {{id: '{from_id}'}})-[r:{rel_label}]->(b {{id: '{to_id}'}}) DELETE r;"
1890            ))
1891            .ok();
1892            self.append_sync_log(
1893                conn,
1894                SyncOp::Delete,
1895                SyncNodeType::Relation,
1896                node_id,
1897                None,
1898                origin_machine_id,
1899                Some(origin_seq),
1900            )?;
1901            Ok(ApplyOutcome::Deleted)
1902        });
1903        self.evict_relations_for(evict_id);
1904        result
1905    }
1906
1907    pub fn sync_log_page(&self, after_seq: u64, limit: Option<usize>) -> Result<Vec<SyncEntry>> {
1908        let conn = self.conn()?;
1909        let limit_clause = match limit {
1910            Some(n) => format!(" LIMIT {}", n),
1911            None => String::new(),
1912        };
1913        let query = format!(
1914            "MATCH (s:SyncLog) WHERE s.local_seq > {} \
1915             RETURN s.id, s.local_seq, s.origin_machine_id, s.origin_seq, s.op, s.node_type, s.node_id, s.timestamp, s.data \
1916             ORDER BY s.local_seq{};",
1917            after_seq, limit_clause
1918        );
1919
1920        let mut result = conn.query(&query)?;
1921        let mut entries = Vec::new();
1922
1923        for row in &mut result {
1924            let id = value_to_string(&row[0]);
1925            let local_seq = match &row[1] {
1926                Value::Int64(n) => *n,
1927                _ => 0,
1928            };
1929            let origin_machine_id = value_to_string(&row[2]);
1930            let origin_seq = match &row[3] {
1931                Value::Int64(n) => *n,
1932                _ => 0,
1933            };
1934            let op_str = value_to_string(&row[4]);
1935            let node_type_str = value_to_string(&row[5]);
1936            let node_id = value_to_string(&row[6]);
1937            let timestamp_str = value_to_string(&row[7]);
1938            let data_str = value_to_string(&row[8]);
1939
1940            let op = match op_str.as_str() {
1941                "create" => SyncOp::Create,
1942                "update" => SyncOp::Update,
1943                "delete" => SyncOp::Delete,
1944                _ => continue,
1945            };
1946            let node_type = match node_type_str.as_str() {
1947                "memory" => SyncNodeType::Memory,
1948                "entity" => SyncNodeType::Entity,
1949                "conversation" => SyncNodeType::Conversation,
1950                "relation" => SyncNodeType::Relation,
1951                _ => continue,
1952            };
1953            let timestamp = chrono::DateTime::parse_from_rfc3339(&timestamp_str)
1954                .map(|dt| dt.with_timezone(&chrono::Utc))
1955                .unwrap_or_else(|_| chrono::Utc::now());
1956
1957            let data = if data_str.is_empty() {
1958                None
1959            } else {
1960                Some(data_str)
1961            };
1962
1963            entries.push(SyncEntry {
1964                id,
1965                local_seq,
1966                origin_machine_id,
1967                origin_seq,
1968                op,
1969                node_type,
1970                node_id,
1971                timestamp,
1972                data,
1973            });
1974        }
1975
1976        Ok(entries)
1977    }
1978
1979    pub fn get_sync_state(&self, peer_id: &str) -> Result<Option<SyncState>> {
1980        let conn = self.conn()?;
1981        let escaped = escape_cypher(peer_id);
1982        let mut result = conn.query(&format!(
1983            "MATCH (s:SyncState {{peer_id: '{}'}}) RETURN s.peer_id, s.last_seq, s.last_sync_at;",
1984            escaped
1985        ))?;
1986
1987        match result.next() {
1988            Some(row) => {
1989                let peer_id = value_to_string(&row[0]);
1990                let last_seq = match &row[1] {
1991                    Value::Int64(n) => *n as u64,
1992                    _ => 0,
1993                };
1994                let last_sync_at_str = value_to_string(&row[2]);
1995                let last_sync_at = chrono::DateTime::parse_from_rfc3339(&last_sync_at_str)
1996                    .map(|dt| dt.with_timezone(&chrono::Utc))
1997                    .unwrap_or_else(|_| chrono::Utc::now());
1998
1999                Ok(Some(SyncState {
2000                    peer_id,
2001                    last_seq,
2002                    last_sync_at,
2003                }))
2004            }
2005            None => Ok(None),
2006        }
2007    }
2008
2009    pub fn set_sync_state(&self, state: &SyncState) -> Result<()> {
2010        let conn = self.conn()?;
2011        let peer_escaped = escape_cypher(&state.peer_id);
2012        let now = state.last_sync_at.to_rfc3339();
2013
2014        conn.query(&format!(
2015            "MERGE (s:SyncState {{peer_id: '{}'}}) SET s.last_seq = {}, s.last_sync_at = '{}';",
2016            peer_escaped, state.last_seq, now
2017        ))?;
2018        Ok(())
2019    }
2020
2021    pub fn get_all_sync_states(&self) -> Result<Vec<SyncState>> {
2022        let conn = self.conn()?;
2023        let mut result =
2024            conn.query("MATCH (s:SyncState) RETURN s.peer_id, s.last_seq, s.last_sync_at;")?;
2025        let mut states = Vec::new();
2026
2027        for row in &mut result {
2028            let peer_id = value_to_string(&row[0]);
2029            let last_seq = match &row[1] {
2030                Value::Int64(n) => *n as u64,
2031                _ => 0,
2032            };
2033            let last_sync_at_str = value_to_string(&row[2]);
2034            let last_sync_at = chrono::DateTime::parse_from_rfc3339(&last_sync_at_str)
2035                .map(|dt| dt.with_timezone(&chrono::Utc))
2036                .unwrap_or_else(|_| chrono::Utc::now());
2037
2038            states.push(SyncState {
2039                peer_id,
2040                last_seq,
2041                last_sync_at,
2042            });
2043        }
2044
2045        Ok(states)
2046    }
2047
2048    pub fn all_entities(&self) -> Result<Vec<Entity>> {
2049        let conn = self.conn()?;
2050        let mut result = conn.query("MATCH (e:Entity) RETURN e.id, e.name, e.entity_type;")?;
2051        let mut entities = Vec::new();
2052        for row in &mut result {
2053            entities.push(row_to_entity(&row)?);
2054        }
2055        Ok(entities)
2056    }
2057
2058    pub fn memories_for_entity(&self, entity_id: Uuid) -> Result<Vec<Memory>> {
2059        let conn = self.conn()?;
2060        let query = format!(
2061            "MATCH (m:Memory)-[:MENTIONS]->(e:Entity {{id: '{}'}}) RETURN {};",
2062            entity_id, memory_return_cols("m")
2063        );
2064        let mut result = conn.query(&query)?;
2065        let mut memories = Vec::new();
2066        for row in &mut result {
2067            memories.push(row_to_memory(&row)?);
2068        }
2069        Ok(memories)
2070    }
2071
2072    pub fn unassociated_memories(&self) -> Result<Vec<Memory>> {
2073        let conn = self.conn()?;
2074        let mut result = conn.query(
2075            &format!("MATCH (m:Memory) WHERE NOT EXISTS {{MATCH (m)-[:MENTIONS]->(:Entity)}} RETURN {};", memory_return_cols("m"))
2076        )?;
2077        let mut memories = Vec::new();
2078        for row in &mut result {
2079            memories.push(row_to_memory(&row)?);
2080        }
2081        Ok(memories)
2082    }
2083
2084    pub fn related_entity_names(&self, entity_id: Uuid) -> Result<Vec<String>> {
2085        let conn = self.conn()?;
2086        let query = format!(
2087            "MATCH (m:Memory)-[:MENTIONS]->(e1:Entity {{id: '{}'}}), (m)-[:MENTIONS]->(e2:Entity) WHERE e2.id <> '{}' RETURN DISTINCT e2.name;",
2088            entity_id, entity_id
2089        );
2090        let mut result = conn.query(&query)?;
2091        let mut names = Vec::new();
2092        for row in &mut result {
2093            names.push(value_to_string(&row[0]));
2094        }
2095        Ok(names)
2096    }
2097
2098    pub fn max_sync_seq(&self) -> Result<u64> {
2099        let conn = self.conn()?;
2100        let mut result = conn.query("MATCH (s:SyncLog) RETURN max(s.local_seq);")?;
2101        match result.next() {
2102            Some(row) => match &row[0] {
2103                Value::Int64(n) => Ok(*n as u64),
2104                _ => Ok(0),
2105            },
2106            None => Ok(0),
2107        }
2108    }
2109
2110    pub fn backfill_project_paths(&self) -> Result<u64> {
2111        let conn = self.conn()?;
2112        let mut result = conn.query(
2113            "MATCH (m:Memory)-[:DERIVED_FROM]->(c:Conversation) WHERE m.project_path = '' AND c.project_path IS NOT NULL AND c.project_path <> '' SET m.project_path = c.project_path RETURN count(m);"
2114        )?;
2115        match result.next() {
2116            Some(row) => match &row[0] {
2117                Value::Int64(n) => Ok(*n as u64),
2118                _ => Ok(0),
2119            },
2120            None => Ok(0),
2121        }
2122    }
2123
2124    pub fn memories_by_project_path(&self, project_path: &str) -> Result<Vec<Memory>> {
2125        let conn = self.conn()?;
2126        let escaped = escape_cypher(project_path);
2127        let cols = memory_return_cols("m");
2128        let query = format!(
2129            "MATCH (m:Memory) WHERE m.project_path = '{}' RETURN {} LIMIT 20;",
2130            escaped, cols
2131        );
2132        let mut result = conn.query(&query)?;
2133        let mut memories = Vec::new();
2134        for row in &mut result {
2135            memories.push(row_to_memory(&row)?);
2136        }
2137        Ok(memories)
2138    }
2139
2140    pub fn all_memories_with_embeddings(&self) -> Result<Vec<Memory>> {
2141        let conn = self.conn()?;
2142        let mut result = conn.query(&format!(
2143            "MATCH (m:Memory) RETURN {}, m.embedding;",
2144            memory_return_cols("m")
2145        ))?;
2146        let mut acc = Vec::new();
2147        for row in &mut result {
2148            // row_to_memory nulls the embedding; repopulate it from the trailing
2149            // m.embedding column so callers get the real vector, not Vec::new().
2150            let mut memory = row_to_memory(&row[..12])?;
2151            memory.embedding = value_to_f32_vec(&row[12]);
2152            acc.push(memory);
2153        }
2154        Ok(acc)
2155    }
2156
2157    pub fn backfill_sync_log(&self) -> Result<u64> {
2158        let mut count = 0u64;
2159
2160        let memories = self.all_memories_with_embeddings()?;
2161
2162        for memory in &memories {
2163            let origin_mid = memory.machine_id.clone();
2164            let data = serde_json::to_string(memory).ok();
2165            let node_id = memory.id.to_string();
2166            self.with_transaction(|conn| {
2167                self.append_sync_log(
2168                    conn,
2169                    SyncOp::Create,
2170                    SyncNodeType::Memory,
2171                    &node_id,
2172                    data.as_deref(),
2173                    &origin_mid,
2174                    None,
2175                )
2176            })?;
2177            count += 1;
2178        }
2179
2180        let conversations: Vec<Conversation> = {
2181            let conn = self.conn()?;
2182            let mut result = conn.query(
2183                "MATCH (c:Conversation) RETURN c.id, c.source, c.machine_id, c.started_at, c.project_path;",
2184            )?;
2185            let mut acc = Vec::new();
2186            for row in &mut result {
2187                let id = Uuid::parse_str(&value_to_string(&row[0])).unwrap_or_default();
2188                let source = value_to_string(&row[1]);
2189                let machine_id = value_to_string(&row[2]);
2190                let started_at_str = value_to_string(&row[3]);
2191                let project_path = {
2192                    let s = value_to_string(&row[4]);
2193                    if s.is_empty() { None } else { Some(s) }
2194                };
2195                let started_at = chrono::DateTime::parse_from_rfc3339(&started_at_str)
2196                    .map(|dt| dt.with_timezone(&chrono::Utc))
2197                    .unwrap_or_else(|_| chrono::Utc::now());
2198                acc.push(Conversation { id, source, machine_id, started_at, project_path });
2199            }
2200            acc
2201        };
2202
2203        for conv in &conversations {
2204            let origin_mid = conv.machine_id.clone();
2205            let data = serde_json::to_string(conv).ok();
2206            let node_id = conv.id.to_string();
2207            self.with_transaction(|conn| {
2208                self.append_sync_log(
2209                    conn,
2210                    SyncOp::Create,
2211                    SyncNodeType::Conversation,
2212                    &node_id,
2213                    data.as_deref(),
2214                    &origin_mid,
2215                    None,
2216                )
2217            })?;
2218            count += 1;
2219        }
2220
2221        Ok(count)
2222    }
2223}
2224
2225impl KuzuStore {
2226    pub fn upsert_machine(&self, id: &str, name: &str) -> Result<()> {
2227        let conn = self.conn()?;
2228        let id_escaped = escape_cypher(id);
2229        let name_escaped = escape_cypher(name);
2230        conn.query(&format!(
2231            "MERGE (m:Machine {{id: '{id_escaped}'}}) SET m.name = '{name_escaped}';"
2232        ))?;
2233        Ok(())
2234    }
2235
2236    pub fn get_machine_name(&self, id: &str) -> Result<Option<String>> {
2237        let conn = self.conn()?;
2238        let id_escaped = escape_cypher(id);
2239        let mut result = conn.query(&format!(
2240            "MATCH (m:Machine {{id: '{id_escaped}'}}) RETURN m.name;"
2241        ))?;
2242        match result.next() {
2243            Some(row) => Ok(Some(value_to_string(&row[0]))),
2244            None => Ok(None),
2245        }
2246    }
2247
2248    pub fn get_all_machines(&self) -> Result<std::collections::HashMap<String, String>> {
2249        let conn = self.conn()?;
2250        let mut result = conn.query("MATCH (m:Machine) RETURN m.id, m.name;")?;
2251        let mut map = std::collections::HashMap::new();
2252        for row in &mut result {
2253            map.insert(value_to_string(&row[0]), value_to_string(&row[1]));
2254        }
2255        Ok(map)
2256    }
2257
2258    pub fn backfill_machine_id(&self, machine_id: &str) -> Result<u64> {
2259        let conn = self.conn()?;
2260        let escaped = escape_cypher(machine_id);
2261        let mut result = conn.query(&format!(
2262            "MATCH (m:Memory) WHERE m.machine_id = '' SET m.machine_id = '{escaped}' RETURN count(m);"
2263        ))?;
2264        match result.next() {
2265            Some(row) => match &row[0] {
2266                Value::Int64(n) => Ok(*n as u64),
2267                _ => Ok(0),
2268            },
2269            None => Ok(0),
2270        }
2271    }
2272
2273    pub fn register_machine(&self, identity: &crate::machine::MachineIdentity) -> Result<()> {
2274        self.upsert_machine(&identity.id, &identity.name)?;
2275        let count = self.backfill_machine_id(&identity.id)?;
2276        if count > 0 {
2277            tracing::info!("backfilled machine_id on {count} existing memories");
2278        }
2279        Ok(())
2280    }
2281}
2282
2283fn format_embedding(embedding: &[f32]) -> String {
2284    if embedding.is_empty() {
2285        let zeros: Vec<String> = (0..384).map(|_| "0.0".to_string()).collect();
2286        return format!("[{}]", zeros.join(","));
2287    }
2288    let parts: Vec<String> = embedding.iter().map(|v| format!("{}", v)).collect();
2289    format!("[{}]", parts.join(","))
2290}
2291
2292fn escape_cypher(s: &str) -> String {
2293    s.replace('\\', "\\\\").replace('\'', "\\'")
2294}
2295
2296fn format_string_array(items: &[String]) -> String {
2297    let parts: Vec<String> = items
2298        .iter()
2299        .map(|s| format!("'{}'", s.replace('\'', "''")))
2300        .collect();
2301    format!("[{}]", parts.join(","))
2302}
2303
2304fn value_to_string(val: &Value) -> String {
2305    match val {
2306        Value::String(s) => s.clone(),
2307        other => format!("{:?}", other),
2308    }
2309}
2310
2311fn value_to_f32(val: &Value) -> f32 {
2312    match val {
2313        Value::Float(f) => *f,
2314        Value::Double(d) => *d as f32,
2315        Value::Int64(i) => *i as f32,
2316        _ => 0.0,
2317    }
2318}
2319
2320fn value_to_f32_vec(val: &Value) -> Vec<f32> {
2321    match val {
2322        Value::Array(_, items) | Value::List(_, items) => items.iter().map(value_to_f32).collect(),
2323        _ => Vec::new(),
2324    }
2325}
2326
2327fn row_to_memory(row: &[Value]) -> Result<Memory> {
2328    let id_str = value_to_string(&row[0]);
2329    let id = Uuid::parse_str(&id_str).unwrap_or_default();
2330    let content = value_to_string(&row[1]);
2331    let memory_type_str = value_to_string(&row[2]);
2332    let confidence = value_to_f32(&row[3]);
2333    let created_at_str = value_to_string(&row[4]);
2334    let last_accessed_str = value_to_string(&row[5]);
2335    let access_count = match &row[6] {
2336        Value::Int64(i) => *i as u32,
2337        _ => 0,
2338    };
2339    let source = value_to_string(&row[7]);
2340    let source_id = value_to_string(&row[8]);
2341    let project_path = project_path_from_db(&value_to_string(&row[9]));
2342    let machine_id = value_to_string(&row[10]);
2343    let updated_at_str = value_to_string(&row[11]);
2344
2345    let memory_type = match memory_type_str.as_str() {
2346        "episodic" => MemoryType::Episodic,
2347        "procedural" => MemoryType::Procedural,
2348        "decision" => MemoryType::Decision,
2349        "architecture" => MemoryType::Architecture,
2350        "debugging" => MemoryType::Debugging,
2351        "task" => MemoryType::Task,
2352        "question" => MemoryType::Question,
2353        _ => MemoryType::Semantic,
2354    };
2355
2356    let created_at = chrono::DateTime::parse_from_rfc3339(&created_at_str)
2357        .map(|dt| dt.with_timezone(&chrono::Utc))
2358        .unwrap_or_else(|_| chrono::Utc::now());
2359
2360    let last_accessed = chrono::DateTime::parse_from_rfc3339(&last_accessed_str)
2361        .map(|dt| dt.with_timezone(&chrono::Utc))
2362        .unwrap_or_else(|_| chrono::Utc::now());
2363
2364    let updated_at = if updated_at_str.is_empty() {
2365        created_at
2366    } else {
2367        chrono::DateTime::parse_from_rfc3339(&updated_at_str)
2368            .map(|dt| dt.with_timezone(&chrono::Utc))
2369            .unwrap_or(created_at)
2370    };
2371
2372    Ok(Memory {
2373        id,
2374        content,
2375        embedding: Vec::new(),
2376        memory_type,
2377        confidence,
2378        created_at,
2379        last_accessed,
2380        access_count,
2381        source,
2382        source_id,
2383        project_path,
2384        machine_id,
2385        updated_at,
2386    })
2387}
2388
2389fn row_to_entity(row: &[Value]) -> Result<Entity> {
2390    let id_str = value_to_string(&row[0]);
2391    let id = Uuid::parse_str(&id_str).unwrap_or_default();
2392    let name = value_to_string(&row[1]);
2393    let entity_type = value_to_string(&row[2]);
2394
2395    Ok(Entity {
2396        id,
2397        name,
2398        entity_type,
2399        embedding: Vec::new(),
2400        aliases: Vec::new(),
2401    })
2402}
2403
2404unsafe impl Send for KuzuStore {}
2405unsafe impl Sync for KuzuStore {}
2406
2407#[cfg(test)]
2408mod tests {
2409    use super::*;
2410
2411    #[test]
2412    fn migrate_sync_log_recreates_old_schema_and_resets_cursors() {
2413        let store = KuzuStore::in_memory("test-machine-migrate".to_string()).unwrap();
2414        let conn = store.conn().unwrap();
2415
2416        // Tear down the new-schema table that init_schema already created and
2417        // replace it with the pre-redesign schema (seq INT64 PRIMARY KEY).
2418        conn.query("DROP TABLE SyncLog;").unwrap();
2419        conn.query(
2420            "CREATE NODE TABLE SyncLog(\
2421                seq INT64 PRIMARY KEY, \
2422                op STRING, \
2423                node_type STRING, \
2424                node_id STRING, \
2425                machine_id STRING, \
2426                timestamp STRING, \
2427                data STRING\
2428            );",
2429        )
2430        .unwrap();
2431        conn.query(
2432            "CREATE (:SyncLog {seq: 1, op: 'create', node_type: 'memory', \
2433             node_id: 'abc', machine_id: 'old-machine', \
2434             timestamp: '2024-01-01T00:00:00Z', data: ''});",
2435        )
2436        .unwrap();
2437
2438        // Seed a SyncState cursor at a non-zero position so we can verify it gets reset.
2439        conn.query(
2440            "MERGE (s:SyncState {peer_id: 'peer-x'}) \
2441             SET s.last_seq = 5, s.last_sync_at = '2024-01-01T00:00:00Z';",
2442        )
2443        .unwrap();
2444
2445        store.migrate_sync_log(&conn).unwrap();
2446
2447        // New-schema column must exist (table was recreated with id STRING PRIMARY KEY).
2448        assert!(
2449            conn.query("MATCH (s:SyncLog) RETURN s.id LIMIT 1;").is_ok(),
2450            "new-schema column s.id must be present after migration"
2451        );
2452
2453        // SyncState cursor must have been reset to 0.
2454        let mut r = conn
2455            .query(
2456                "MATCH (s:SyncState {peer_id: 'peer-x'}) RETURN s.last_seq;",
2457            )
2458            .unwrap();
2459        let last_seq = match r.next() {
2460            Some(row) => match &row[0] {
2461                Value::Int64(n) => *n,
2462                _ => panic!("unexpected value type for last_seq"),
2463            },
2464            None => panic!("SyncState row not found after migration"),
2465        };
2466        assert_eq!(last_seq, 0, "last_seq must be reset to 0 after migration");
2467    }
2468
2469    #[test]
2470    fn rollback_leaves_no_partial_state() {
2471        let store = KuzuStore::in_memory("test-machine-rollback".to_string()).unwrap();
2472        let embedding = std::iter::repeat("0.0")
2473            .take(384)
2474            .collect::<Vec<_>>()
2475            .join(", ");
2476
2477        let result: Result<()> = store.with_transaction(|conn| {
2478            conn.query(&format!(
2479                "CREATE (:Memory {{id: 'rollback-test-id', content: 'x', \
2480                 embedding: [{embedding}], memory_type: 'semantic', confidence: 1.0, \
2481                 created_at: '2024-01-01T00:00:00Z', last_accessed: '2024-01-01T00:00:00Z', \
2482                 access_count: 0, source: 'test', source_id: '', project_path: '', \
2483                 machine_id: 'x', updated_at: '2024-01-01T00:00:00Z'}});"
2484            ))?;
2485            Err(anyhow::anyhow!("deliberate rollback"))
2486        });
2487
2488        assert!(
2489            result.is_err(),
2490            "with_transaction must propagate the closure error"
2491        );
2492
2493        let entries = store.sync_log_since(0).unwrap();
2494        assert_eq!(entries.len(), 0, "no SyncLog rows may survive a rollback");
2495        assert_eq!(
2496            store.memory_count().unwrap(),
2497            0,
2498            "the Memory node created inside the transaction must be rolled back"
2499        );
2500    }
2501
2502    fn memory_with_embedding(content: &str, embedding: Vec<f32>) -> Memory {
2503        let mut m = Memory::new(
2504            content.to_string(),
2505            MemoryType::Semantic,
2506            "test".to_string(),
2507            String::new(),
2508        );
2509        m.embedding = embedding;
2510        m
2511    }
2512
2513    #[test]
2514    fn recall_reflects_new_relation_after_cache_invalidation() {
2515        use crate::query::{QueryEngine, QueryFilters, QueryRequest};
2516
2517        let store = KuzuStore::in_memory("test-machine-invalidate".to_string()).unwrap();
2518
2519        let mut emb_a = vec![0.0_f32; 384];
2520        emb_a[0] = 1.0;
2521        let mut emb_b = vec![0.0_f32; 384];
2522        emb_b[1] = 1.0;
2523        let target = memory_with_embedding("kuzu is the embedded graph store", emb_a.clone());
2524        let neighbor = memory_with_embedding("an unrelated note about sync", emb_b);
2525        store.store_memory(&target).unwrap();
2526        store.store_memory(&neighbor).unwrap();
2527
2528        let request = QueryRequest {
2529            text: "graph store".to_string(),
2530            embedding: emb_a,
2531            limit: 10,
2532            filters: QueryFilters::default(),
2533        };
2534
2535        let before = QueryEngine::new(&store).recall(&request).unwrap();
2536        let before_score = before
2537            .iter()
2538            .find(|r| r.memory.id == target.id)
2539            .expect("target must be recalled")
2540            .score;
2541
2542        // Adding a Reinforces edge raises the graph-relevance term, so a stale cache
2543        // (which returned the empty pre-edge relation list) would leave the score
2544        // unchanged. Asserting the score rises proves store_relation evicted the key.
2545        let rel = Relation {
2546            from_id: target.id,
2547            to_id: neighbor.id,
2548            relation_type: RelationType::Reinforces,
2549            strength: 1.0,
2550            context: None,
2551        };
2552        store.store_relation(&rel).unwrap();
2553
2554        let after = QueryEngine::new(&store).recall(&request).unwrap();
2555        let after_score = after
2556            .iter()
2557            .find(|r| r.memory.id == target.id)
2558            .expect("target must still be recalled")
2559            .score;
2560
2561        assert!(
2562            after_score > before_score,
2563            "recall must reflect the new relation: before={before_score} after={after_score}"
2564        );
2565    }
2566
2567    #[test]
2568    fn get_relations_cached_matches_fresh_uncached_store() {
2569        let machine = "test-machine-equivalence".to_string();
2570        let warm = KuzuStore::in_memory(machine.clone()).unwrap();
2571
2572        let a = memory_with_embedding("memory a", {
2573            let mut e = vec![0.0_f32; 384];
2574            e[0] = 1.0;
2575            e
2576        });
2577        let b = memory_with_embedding("memory b", {
2578            let mut e = vec![0.0_f32; 384];
2579            e[1] = 1.0;
2580            e
2581        });
2582        let c = memory_with_embedding("memory c", {
2583            let mut e = vec![0.0_f32; 384];
2584            e[2] = 1.0;
2585            e
2586        });
2587        for m in [&a, &b, &c] {
2588            warm.store_memory(m).unwrap();
2589        }
2590        let rels = [
2591            Relation {
2592                from_id: a.id,
2593                to_id: b.id,
2594                relation_type: RelationType::RelatesTo,
2595                strength: 0.7,
2596                context: None,
2597            },
2598            Relation {
2599                from_id: a.id,
2600                to_id: c.id,
2601                relation_type: RelationType::Reinforces,
2602                strength: 1.0,
2603                context: None,
2604            },
2605            Relation {
2606                from_id: b.id,
2607                to_id: c.id,
2608                relation_type: RelationType::Supersedes,
2609                strength: 1.0,
2610                context: None,
2611            },
2612        ];
2613        for r in &rels {
2614            warm.store_relation(r).unwrap();
2615        }
2616
2617        // Warm the cache by reading every (id, type) pair twice; the second read is a
2618        // cache hit. A freshly opened store sees the same persisted data with an empty
2619        // cache, so the two must agree edge-for-edge.
2620        let types = [
2621            None,
2622            Some(RelationType::RelatesTo),
2623            Some(RelationType::Reinforces),
2624            Some(RelationType::Supersedes),
2625            Some(RelationType::Mentions),
2626        ];
2627        for id in [a.id, b.id, c.id] {
2628            for rt in types {
2629                let first = warm.get_relations(id, rt).unwrap();
2630                let second = warm.get_relations(id, rt).unwrap();
2631                assert_eq!(
2632                    first.len(),
2633                    second.len(),
2634                    "cache hit must match the live read for ({id}, {rt:?})"
2635                );
2636                let mut a_ids: Vec<Uuid> = first.iter().map(|r| r.to_id).collect();
2637                let mut b_ids: Vec<Uuid> = second.iter().map(|r| r.to_id).collect();
2638                a_ids.sort();
2639                b_ids.sort();
2640                assert_eq!(a_ids, b_ids);
2641            }
2642        }
2643    }
2644}