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 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 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 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 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 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 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 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 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 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 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 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 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(×tamp_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 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 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 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 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 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 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 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}