1use crate::chunking;
2use crate::cli::MemoryType;
3use crate::errors::AppError;
4use crate::i18n::erros;
5use crate::output::{self, JsonOutputFormat, RememberResponse};
6use crate::paths::AppPaths;
7use crate::storage::chunks as storage_chunks;
8use crate::storage::connection::open_rw;
9use crate::storage::entities::{NewEntity, NewRelationship};
10use crate::storage::memories::NewMemory;
11use crate::storage::{entities, memories, versions};
12use serde::Deserialize;
13use std::io::Read as _;
14
15#[derive(clap::Args)]
16pub struct RememberArgs {
17 #[arg(long)]
18 pub name: String,
19 #[arg(long, value_enum)]
20 pub r#type: MemoryType,
21 #[arg(long)]
22 pub description: String,
23 #[arg(long)]
24 pub body: Option<String>,
25 #[arg(long)]
26 pub body_file: Option<std::path::PathBuf>,
27 #[arg(long)]
28 pub body_stdin: bool,
29 #[arg(long)]
30 pub entities_file: Option<std::path::PathBuf>,
31 #[arg(long)]
32 pub relationships_file: Option<std::path::PathBuf>,
33 #[arg(long)]
34 pub graph_stdin: bool,
35 #[arg(long, default_value = "global")]
36 pub namespace: Option<String>,
37 #[arg(long)]
38 pub metadata: Option<String>,
39 #[arg(long)]
40 pub metadata_file: Option<std::path::PathBuf>,
41 #[arg(long)]
42 pub force_merge: bool,
43 #[arg(
44 long,
45 value_name = "EPOCH_OR_RFC3339",
46 value_parser = crate::parsers::parse_expected_updated_at,
47 long_help = "Optimistic lock: reject if updated_at does not match. \
48Accepts Unix epoch (e.g. 1700000000) or RFC 3339 (e.g. 2026-04-19T12:00:00Z)."
49 )]
50 pub expected_updated_at: Option<i64>,
51 #[arg(long)]
52 pub skip_extraction: bool,
53 #[arg(long)]
54 pub session_id: Option<String>,
55 #[arg(long, value_enum, default_value_t = JsonOutputFormat::Json)]
56 pub format: JsonOutputFormat,
57 #[arg(long, hide = true, help = "No-op; JSON is always emitted on stdout")]
58 pub json: bool,
59 #[arg(long, env = "SQLITE_GRAPHRAG_DB_PATH")]
60 pub db: Option<String>,
61}
62
63#[derive(Deserialize, Default)]
64struct GraphInput {
65 #[serde(default)]
66 entities: Vec<NewEntity>,
67 #[serde(default)]
68 relationships: Vec<NewRelationship>,
69}
70
71pub fn run(args: RememberArgs) -> Result<(), AppError> {
72 use crate::constants::*;
73
74 let inicio = std::time::Instant::now();
75 let _ = args.format;
76 let namespace = crate::namespace::resolve_namespace(args.namespace.as_deref())?;
77
78 if args.name.is_empty() || args.name.len() > MAX_MEMORY_NAME_LEN {
79 return Err(AppError::Validation(
80 crate::i18n::validacao::nome_comprimento(MAX_MEMORY_NAME_LEN),
81 ));
82 }
83
84 if args.name.starts_with("__") {
85 return Err(AppError::Validation(
86 crate::i18n::validacao::nome_reservado(),
87 ));
88 }
89
90 {
91 let slug_re = regex::Regex::new(crate::constants::NAME_SLUG_REGEX)
92 .map_err(|e| AppError::Internal(anyhow::anyhow!("regex: {e}")))?;
93 if !slug_re.is_match(&args.name) {
94 return Err(AppError::Validation(crate::i18n::validacao::nome_kebab(
95 &args.name,
96 )));
97 }
98 }
99
100 if args.description.len() > MAX_MEMORY_DESCRIPTION_LEN {
101 return Err(AppError::Validation(
102 crate::i18n::validacao::descricao_excede(MAX_MEMORY_DESCRIPTION_LEN),
103 ));
104 }
105
106 let mut raw_body = if let Some(b) = args.body {
107 b
108 } else if let Some(path) = args.body_file {
109 std::fs::read_to_string(&path).map_err(AppError::Io)?
110 } else if args.body_stdin || args.graph_stdin {
111 let mut buf = String::new();
112 std::io::stdin()
113 .read_to_string(&mut buf)
114 .map_err(AppError::Io)?;
115 buf
116 } else {
117 String::new()
118 };
119
120 let mut graph = GraphInput::default();
121 if !args.skip_extraction {
122 if let Some(path) = args.entities_file {
123 let content = std::fs::read_to_string(&path).map_err(AppError::Io)?;
124 graph.entities = serde_json::from_str(&content)?;
125 }
126 if let Some(path) = args.relationships_file {
127 let content = std::fs::read_to_string(&path).map_err(AppError::Io)?;
128 graph.relationships = serde_json::from_str(&content)?;
129 }
130 if args.graph_stdin {
131 if let Ok(g) = serde_json::from_str::<GraphInput>(&raw_body) {
132 graph = g;
133 raw_body = String::new();
134 }
135 }
136 }
137
138 if graph.entities.len() > MAX_ENTITIES_PER_MEMORY {
139 return Err(AppError::LimitExceeded(erros::limite_entidades(
140 MAX_ENTITIES_PER_MEMORY,
141 )));
142 }
143 if graph.relationships.len() > MAX_RELATIONSHIPS_PER_MEMORY {
144 return Err(AppError::LimitExceeded(erros::limite_relacionamentos(
145 MAX_RELATIONSHIPS_PER_MEMORY,
146 )));
147 }
148
149 if raw_body.len() > MAX_MEMORY_BODY_LEN {
150 return Err(AppError::LimitExceeded(
151 crate::i18n::validacao::body_excede(MAX_MEMORY_BODY_LEN),
152 ));
153 }
154
155 let metadata: serde_json::Value = if let Some(m) = args.metadata {
156 serde_json::from_str(&m)?
157 } else if let Some(path) = args.metadata_file {
158 let content = std::fs::read_to_string(&path).map_err(AppError::Io)?;
159 serde_json::from_str(&content)?
160 } else {
161 serde_json::json!({})
162 };
163
164 let body_hash = blake3::hash(raw_body.as_bytes()).to_hex().to_string();
165 let snippet: String = raw_body.chars().take(200).collect();
166
167 let paths = AppPaths::resolve(args.db.as_deref())?;
168 let mut conn = open_rw(&paths.db)?;
169
170 {
171 use crate::constants::MAX_NAMESPACES_ACTIVE;
172 let active_count: u32 = conn.query_row(
173 "SELECT COUNT(DISTINCT namespace) FROM memories WHERE deleted_at IS NULL",
174 [],
175 |r| r.get::<_, i64>(0).map(|v| v as u32),
176 )?;
177 let ns_exists: bool = conn.query_row(
178 "SELECT EXISTS(SELECT 1 FROM memories WHERE namespace = ?1 AND deleted_at IS NULL)",
179 rusqlite::params![namespace],
180 |r| r.get::<_, i64>(0).map(|v| v > 0),
181 )?;
182 if !ns_exists && active_count >= MAX_NAMESPACES_ACTIVE {
183 return Err(AppError::NamespaceError(format!(
184 "limite de {MAX_NAMESPACES_ACTIVE} namespaces ativos excedido ao tentar criar '{namespace}'"
185 )));
186 }
187 }
188
189 let existing_memory = memories::find_by_name(&conn, &namespace, &args.name)?;
190 if existing_memory.is_some() && !args.force_merge {
191 return Err(AppError::Duplicate(erros::memoria_duplicada(
192 &args.name, &namespace,
193 )));
194 }
195
196 let duplicate_hash_id = memories::find_by_hash(&conn, &namespace, &body_hash)?;
197
198 output::emit_progress_i18n("Computing embedding...", "Calculando embedding...");
199 let embedder = crate::embedder::get_embedder(&paths.models)?;
200
201 let chunks_info = chunking::split_into_chunks(&raw_body);
202 let chunks_created = chunks_info.len();
203
204 let mut chunk_embeddings_cache: Option<Vec<Vec<f32>>> = None;
205
206 let embedding = if chunks_info.len() == 1 {
207 crate::embedder::embed_passage(embedder, &raw_body)?
208 } else {
209 output::emit_progress_i18n(
210 &format!("Embedding {} chunks...", chunks_info.len()),
211 &format!("Embedando {} chunks...", chunks_info.len()),
212 );
213 let chunk_embeddings = crate::embedder::embed_passages_serial(
214 embedder,
215 chunks_info.iter().map(|c| c.text.as_str()),
216 )?;
217 let aggregated = chunking::aggregate_embeddings(&chunk_embeddings);
218 chunk_embeddings_cache = Some(chunk_embeddings);
219 aggregated
220 };
221 let body_for_storage = raw_body;
222
223 let memory_type = args.r#type.as_str();
224 let new_memory = NewMemory {
225 namespace: namespace.clone(),
226 name: args.name.clone(),
227 memory_type: memory_type.to_string(),
228 description: args.description.clone(),
229 body: body_for_storage,
230 body_hash: body_hash.clone(),
231 session_id: args.session_id.clone(),
232 source: "agent".to_string(),
233 metadata,
234 };
235
236 let mut warnings = Vec::new();
237
238 let (memory_id, action, version) = match existing_memory {
239 Some((existing_id, _updated_at, _current_version)) => {
240 if let Some(hash_id) = duplicate_hash_id {
241 if hash_id != existing_id {
242 warnings.push(format!(
243 "identical body already exists as memory id {hash_id}"
244 ));
245 }
246 }
247 let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
248
249 if chunks_info.len() > 1 {
250 storage_chunks::delete_chunks(&tx, existing_id)?;
251 }
252
253 let next_v = versions::next_version(&tx, existing_id)?;
254 memories::update(&tx, existing_id, &new_memory, args.expected_updated_at)?;
255 versions::insert_version(
256 &tx,
257 existing_id,
258 next_v,
259 &args.name,
260 memory_type,
261 &args.description,
262 &new_memory.body,
263 &serde_json::to_string(&new_memory.metadata)?,
264 None,
265 "edit",
266 )?;
267 memories::upsert_vec(
268 &tx,
269 existing_id,
270 &namespace,
271 memory_type,
272 &embedding,
273 &args.name,
274 &snippet,
275 )?;
276 tx.commit()?;
277 (existing_id, "updated".to_string(), next_v)
278 }
279 None => {
280 if let Some(hash_id) = duplicate_hash_id {
281 warnings.push(format!(
282 "identical body already exists as memory id {hash_id}"
283 ));
284 }
285 let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
286 let id = memories::insert(&tx, &new_memory)?;
287 versions::insert_version(
288 &tx,
289 id,
290 1,
291 &args.name,
292 memory_type,
293 &args.description,
294 &new_memory.body,
295 &serde_json::to_string(&new_memory.metadata)?,
296 None,
297 "create",
298 )?;
299 memories::upsert_vec(
300 &tx,
301 id,
302 &namespace,
303 memory_type,
304 &embedding,
305 &args.name,
306 &snippet,
307 )?;
308 tx.commit()?;
309 (id, "created".to_string(), 1)
310 }
311 };
312
313 if chunks_info.len() > 1 {
314 let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
315 storage_chunks::insert_chunk_slices(&tx, memory_id, &chunks_info)?;
316
317 let chunk_embeddings = chunk_embeddings_cache.take().ok_or_else(|| {
318 AppError::Internal(anyhow::anyhow!(
319 "chunk embeddings cache missing for multi-chunk remember path"
320 ))
321 })?;
322
323 for (i, emb) in chunk_embeddings.iter().enumerate() {
324 storage_chunks::upsert_chunk_vec(&tx, i as i64, memory_id, i as i32, emb)?;
325 }
326 tx.commit()?;
327 }
328
329 let mut entities_persisted = 0usize;
330 let mut relationships_persisted = 0usize;
331
332 if !graph.entities.is_empty() || !graph.relationships.is_empty() {
333 let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
334 for entity in &graph.entities {
335 let entity_id = entities::upsert_entity(&tx, &namespace, entity)?;
336 let entity_text = match &entity.description {
337 Some(desc) => format!("{} {}", entity.name, desc),
338 None => entity.name.clone(),
339 };
340 let entity_embedding = crate::embedder::embed_passage(embedder, &entity_text)?;
341 entities::upsert_entity_vec(
342 &tx,
343 entity_id,
344 &namespace,
345 &entity.entity_type,
346 &entity_embedding,
347 &entity.name,
348 )?;
349 entities::link_memory_entity(&tx, memory_id, entity_id)?;
350 entities::increment_degree(&tx, entity_id)?;
351 entities_persisted += 1;
352 }
353 for rel in &graph.relationships {
354 let source_entity = NewEntity {
355 name: rel.source.clone(),
356 entity_type: "concept".to_string(),
357 description: None,
358 };
359 let target_entity = NewEntity {
360 name: rel.target.clone(),
361 entity_type: "concept".to_string(),
362 description: None,
363 };
364 let source_id = entities::upsert_entity(&tx, &namespace, &source_entity)?;
365 let target_id = entities::upsert_entity(&tx, &namespace, &target_entity)?;
366 let rel_id = entities::upsert_relationship(&tx, &namespace, source_id, target_id, rel)?;
367 entities::link_memory_relationship(&tx, memory_id, rel_id)?;
368 relationships_persisted += 1;
369 }
370 tx.commit()?;
371 }
372
373 let created_at_epoch = chrono::Utc::now().timestamp();
374 let created_at_iso = crate::tz::formatar_iso(chrono::Utc::now());
375
376 output::emit_json(&RememberResponse {
377 memory_id,
378 name: args.name,
379 namespace,
380 action: action.clone(),
381 operation: action,
382 version,
383 entities_persisted,
384 relationships_persisted,
385 chunks_created,
386 merged_into_memory_id: None,
387 warnings,
388 created_at: created_at_epoch,
389 created_at_iso,
390 elapsed_ms: inicio.elapsed().as_millis() as u64,
391 })?;
392
393 Ok(())
394}
395
396#[cfg(test)]
397mod testes {
398 use crate::output::RememberResponse;
399
400 #[test]
401 fn remember_response_serializa_campos_obrigatorios() {
402 let resp = RememberResponse {
403 memory_id: 42,
404 name: "minha-mem".to_string(),
405 namespace: "global".to_string(),
406 action: "created".to_string(),
407 operation: "created".to_string(),
408 version: 1,
409 entities_persisted: 0,
410 relationships_persisted: 0,
411 chunks_created: 1,
412 merged_into_memory_id: None,
413 warnings: vec![],
414 created_at: 1_705_320_000,
415 created_at_iso: "2024-01-15T12:00:00Z".to_string(),
416 elapsed_ms: 55,
417 };
418
419 let json = serde_json::to_value(&resp).expect("serialização falhou");
420 assert_eq!(json["memory_id"], 42);
421 assert_eq!(json["action"], "created");
422 assert_eq!(json["operation"], "created");
423 assert_eq!(json["version"], 1);
424 assert_eq!(json["elapsed_ms"], 55u64);
425 assert!(json["warnings"].is_array());
426 assert!(json["merged_into_memory_id"].is_null());
427 }
428
429 #[test]
430 fn remember_response_action_e_operation_sao_aliases() {
431 let resp = RememberResponse {
432 memory_id: 1,
433 name: "mem".to_string(),
434 namespace: "global".to_string(),
435 action: "updated".to_string(),
436 operation: "updated".to_string(),
437 version: 2,
438 entities_persisted: 3,
439 relationships_persisted: 1,
440 chunks_created: 2,
441 merged_into_memory_id: None,
442 warnings: vec![],
443 created_at: 0,
444 created_at_iso: "1970-01-01T00:00:00Z".to_string(),
445 elapsed_ms: 0,
446 };
447
448 let json = serde_json::to_value(&resp).expect("serialização falhou");
449 assert_eq!(
450 json["action"], json["operation"],
451 "action e operation devem ser iguais"
452 );
453 assert_eq!(json["entities_persisted"], 3);
454 assert_eq!(json["relationships_persisted"], 1);
455 assert_eq!(json["chunks_created"], 2);
456 }
457
458 #[test]
459 fn remember_response_warnings_lista_mensagens() {
460 let resp = RememberResponse {
461 memory_id: 5,
462 name: "dup-mem".to_string(),
463 namespace: "global".to_string(),
464 action: "created".to_string(),
465 operation: "created".to_string(),
466 version: 1,
467 entities_persisted: 0,
468 relationships_persisted: 0,
469 chunks_created: 1,
470 merged_into_memory_id: None,
471 warnings: vec!["identical body already exists as memory id 3".to_string()],
472 created_at: 0,
473 created_at_iso: "1970-01-01T00:00:00Z".to_string(),
474 elapsed_ms: 10,
475 };
476
477 let json = serde_json::to_value(&resp).expect("serialização falhou");
478 let warnings = json["warnings"]
479 .as_array()
480 .expect("warnings deve ser array");
481 assert_eq!(warnings.len(), 1);
482 assert!(warnings[0].as_str().unwrap().contains("identical body"));
483 }
484
485 #[test]
486 fn nome_invalido_prefixo_reservado_retorna_validation_error() {
487 use crate::errors::AppError;
488 let nome = "__reservado";
490 let resultado: Result<(), AppError> = if nome.starts_with("__") {
491 Err(AppError::Validation(
492 crate::i18n::validacao::nome_reservado(),
493 ))
494 } else {
495 Ok(())
496 };
497 assert!(resultado.is_err());
498 if let Err(AppError::Validation(msg)) = resultado {
499 assert!(!msg.is_empty());
500 }
501 }
502
503 #[test]
504 fn nome_muito_longo_retorna_validation_error() {
505 use crate::errors::AppError;
506 let nome_longo = "a".repeat(crate::constants::MAX_MEMORY_NAME_LEN + 1);
507 let resultado: Result<(), AppError> =
508 if nome_longo.is_empty() || nome_longo.len() > crate::constants::MAX_MEMORY_NAME_LEN {
509 Err(AppError::Validation(
510 crate::i18n::validacao::nome_comprimento(crate::constants::MAX_MEMORY_NAME_LEN),
511 ))
512 } else {
513 Ok(())
514 };
515 assert!(resultado.is_err());
516 }
517
518 #[test]
519 fn remember_response_merged_into_memory_id_some_serializa_inteiro() {
520 let resp = RememberResponse {
521 memory_id: 10,
522 name: "mem-mergeada".to_string(),
523 namespace: "global".to_string(),
524 action: "updated".to_string(),
525 operation: "updated".to_string(),
526 version: 3,
527 entities_persisted: 0,
528 relationships_persisted: 0,
529 chunks_created: 1,
530 merged_into_memory_id: Some(7),
531 warnings: vec![],
532 created_at: 0,
533 created_at_iso: "1970-01-01T00:00:00Z".to_string(),
534 elapsed_ms: 0,
535 };
536
537 let json = serde_json::to_value(&resp).expect("serialização falhou");
538 assert_eq!(json["merged_into_memory_id"], 7);
539 }
540}