sqlite_graphrag/commands/
edit.rs

1//! Handler for the `edit` CLI subcommand.
2
3use crate::errors::AppError;
4use crate::i18n::errors_msg;
5use crate::output;
6use crate::paths::AppPaths;
7use crate::storage::connection::open_rw;
8use crate::storage::{memories, versions};
9use serde::Serialize;
10
11#[derive(clap::Args)]
12#[command(after_long_help = "EXAMPLES:\n  \
13    # Edit body inline\n  \
14    sqlite-graphrag edit onboarding --body \"updated content\"\n\n  \
15    # Edit body from a file\n  \
16    sqlite-graphrag edit onboarding --body-file ./updated.md\n\n  \
17    # Edit body from stdin (pipe)\n  \
18    cat updated.md | sqlite-graphrag edit onboarding --body-stdin\n\n  \
19    # Update only the description\n  \
20    sqlite-graphrag edit onboarding --description \"new short description\"")]
21pub struct EditArgs {
22    /// Memory name as a positional argument. Alternative to `--name`.
23    #[arg(
24        value_name = "NAME",
25        conflicts_with = "name",
26        help = "Memory name to edit; alternative to --name"
27    )]
28    pub name_positional: Option<String>,
29    /// Memory name to edit. Soft-deleted memories are not editable; use `restore` first.
30    #[arg(long)]
31    pub name: Option<String>,
32    /// New inline body content. Mutually exclusive with --body-file and --body-stdin.
33    #[arg(long, conflicts_with_all = ["body_file", "body_stdin"])]
34    pub body: Option<String>,
35    /// Read new body from a file. Mutually exclusive with --body and --body-stdin.
36    #[arg(long, conflicts_with_all = ["body", "body_stdin"])]
37    pub body_file: Option<std::path::PathBuf>,
38    /// Read new body from stdin until EOF. Mutually exclusive with --body and --body-file.
39    #[arg(long, conflicts_with_all = ["body", "body_file"])]
40    pub body_stdin: bool,
41    /// New description (≤500 chars) replacing the existing one.
42    #[arg(long)]
43    pub description: Option<String>,
44    /// Change the memory type (e.g. note, skill, decision).
45    #[arg(long, value_enum, visible_alias = "type", help = "Change memory type")]
46    pub memory_type: Option<crate::cli::MemoryType>,
47    #[arg(
48        long,
49        value_name = "EPOCH_OR_RFC3339",
50        value_parser = crate::parsers::parse_expected_updated_at,
51        long_help = "Optimistic lock: reject if updated_at does not match. \
52Accepts Unix epoch (e.g. 1700000000) or RFC 3339 (e.g. 2026-04-19T12:00:00Z)."
53    )]
54    pub expected_updated_at: Option<i64>,
55    #[arg(
56        long,
57        help = "Namespace (env: SQLITE_GRAPHRAG_NAMESPACE, default: global)"
58    )]
59    pub namespace: Option<String>,
60    #[arg(long, hide = true, help = "No-op; JSON is always emitted on stdout")]
61    pub json: bool,
62    #[arg(long, env = "SQLITE_GRAPHRAG_DB_PATH")]
63    pub db: Option<String>,
64    /// G42/S9 (v1.0.79): regenerate the embedding even when the body is
65    /// unchanged. This is the supported way to re-embed a memory (the
66    /// pre-v1.0.79 docs suggested `edit --description "<same>"`, which
67    /// is a no-op and never re-embeds).
68    #[arg(
69        long,
70        default_value_t = false,
71        help = "Regenerate the embedding even when the body is unchanged (G42/S9)"
72    )]
73    pub force_reembed: bool,
74    /// G42/S3 (v1.0.79): maximum simultaneous LLM embedding subprocesses.
75    /// Only relevant for future multi-item edit paths; a single-body edit
76    /// performs one LLM call regardless.
77    #[arg(long, default_value_t = 4, value_name = "N",
78          value_parser = clap::value_parser!(u64).range(1..=32),
79          help = "Maximum simultaneous LLM embedding subprocesses (default: 4, clamp [1,32])")]
80    pub llm_parallelism: u64,
81}
82
83#[derive(Serialize)]
84struct EditResponse {
85    memory_id: i64,
86    name: String,
87    action: String,
88    version: i64,
89    /// Total execution time in milliseconds from handler start to serialisation.
90    elapsed_ms: u64,
91    /// v1.0.84 (ADR-0042): discriminator of the LLM backend that actually
92    /// ran the re-embedding of the edited body. `"claude" | "codex" | "none"`.
93    /// Absent on the wire when `None` (kept for happy-path envelope cleanliness,
94    /// or when the body did not change and re-embedding was not invoked).
95    #[serde(skip_serializing_if = "Option::is_none")]
96    backend_invoked: Option<&'static str>,
97}
98
99pub fn run(
100    args: EditArgs,
101    llm_backend: crate::cli::LlmBackendChoice,
102    embedding_backend: crate::cli::EmbeddingBackendChoice,
103) -> Result<(), AppError> {
104    use crate::constants::*;
105
106    let inicio = std::time::Instant::now();
107    tracing::debug!(target: "edit", name = ?args.name_positional.as_deref().or(args.name.as_deref()), "updating memory");
108    // Resolve name from positional or --name flag; both are optional, at least one is required.
109    let name = args.name_positional.or(args.name).ok_or_else(|| {
110        AppError::Validation("name required: pass as positional argument or via --name".to_string())
111    })?;
112    let namespace = crate::namespace::resolve_namespace(args.namespace.as_deref())?;
113
114    let paths = AppPaths::resolve(args.db.as_deref())?;
115    crate::storage::connection::ensure_db_ready(&paths)?;
116    let mut conn = open_rw(&paths.db)?;
117
118    let (memory_id, current_updated_at, _current_version) =
119        memories::find_by_name(&conn, &namespace, &name)?
120            .ok_or_else(|| AppError::NotFound(errors_msg::memory_not_found(&name, &namespace)))?;
121
122    if let Some(expected) = args.expected_updated_at {
123        if expected != current_updated_at {
124            return Err(AppError::Conflict(errors_msg::optimistic_lock_conflict(
125                expected,
126                current_updated_at,
127            )));
128        }
129    }
130
131    let mut raw_body: Option<String> = None;
132    if args.body.is_some() || args.body_file.is_some() || args.body_stdin {
133        let b = if let Some(b) = args.body {
134            b
135        } else if let Some(path) = &args.body_file {
136            let file_size = std::fs::metadata(path).map_err(AppError::Io)?.len();
137            if file_size > MAX_MEMORY_BODY_LEN as u64 {
138                return Err(AppError::BodyTooLarge {
139                    bytes: file_size,
140                    limit: MAX_MEMORY_BODY_LEN as u64,
141                });
142            }
143            std::fs::read_to_string(path).map_err(AppError::Io)?
144        } else {
145            crate::stdin_helper::read_stdin_with_timeout(60)?
146        };
147        if b.len() > MAX_MEMORY_BODY_LEN {
148            return Err(AppError::BodyTooLarge {
149                bytes: b.len() as u64,
150                limit: MAX_MEMORY_BODY_LEN as u64,
151            });
152        }
153        raw_body = Some(b);
154    }
155
156    if let Some(ref desc) = args.description {
157        if desc.len() > MAX_MEMORY_DESCRIPTION_LEN {
158            return Err(AppError::Validation(
159                crate::i18n::validation::description_exceeds(MAX_MEMORY_DESCRIPTION_LEN),
160            ));
161        }
162    }
163
164    let row = memories::read_by_name(&conn, &namespace, &name)?
165        .ok_or_else(|| AppError::Internal(anyhow::anyhow!("memory row not found after check")))?;
166
167    let body_changed = raw_body.is_some();
168    let new_body = raw_body.unwrap_or(row.body.clone());
169    let new_description = args.description.unwrap_or(row.description.clone());
170    let new_hash = blake3::hash(new_body.as_bytes()).to_hex().to_string();
171    // Skip re-embedding when body content is identical to the stored version.
172    let body_changed = body_changed && new_hash != row.body_hash;
173    let memory_type = args
174        .memory_type
175        .map(|t| t.as_str().to_string())
176        .unwrap_or_else(|| row.memory_type.clone());
177    let type_changed = memory_type != row.memory_type;
178    let metadata = row.metadata.clone();
179
180    let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
181
182    let affected = if let Some(ts) = args.expected_updated_at {
183        tx.execute(
184            "UPDATE memories SET description=?2, body=?3, body_hash=?4, type=?5
185             WHERE id=?1 AND updated_at=?6 AND deleted_at IS NULL",
186            rusqlite::params![
187                memory_id,
188                new_description,
189                new_body,
190                new_hash,
191                memory_type,
192                ts
193            ],
194        )?
195    } else {
196        tx.execute(
197            "UPDATE memories SET description=?2, body=?3, body_hash=?4, type=?5
198             WHERE id=?1 AND deleted_at IS NULL",
199            rusqlite::params![memory_id, new_description, new_body, new_hash, memory_type],
200        )?
201    };
202
203    if affected == 0 {
204        return Err(AppError::Conflict(
205            "optimistic lock conflict: memory was modified by another process".to_string(),
206        ));
207    }
208
209    // v1.0.84 (ADR-0042): backend discriminator for the JSON envelope.
210    // Populated only when re-embedding actually ran; stays None for
211    // description-only or metadata-only edits.
212    let mut backend_invoked: Option<&'static str> = None;
213
214    if body_changed || type_changed || args.force_reembed {
215        output::emit_progress_i18n(
216            "Re-computing embedding for edited body...",
217            crate::i18n::validation::runtime_pt::edit_recomputing_embedding(),
218        );
219        // v1.0.82 (GAP-003): forward --llm-backend to embed_with_fallback.
220        // v1.0.84 (ADR-0042): tuple (Vec<f32>, LlmBackendKind) — extrai o
221        // backend que efetivamente rodou para popular `backend_invoked`.
222        let skip_embed = crate::embedder::should_skip_embedding_on_failure();
223        let embedding: Option<(Vec<f32>, &'static str)> =
224            match crate::embedder::embed_passage_with_embedding_choice(
225                &paths.models,
226                &new_body,
227                embedding_backend,
228                llm_backend,
229            ) {
230                Ok((emb, kind)) => Some((emb, kind.as_str())),
231                Err(AppError::Validation(msg)) => return Err(AppError::Validation(msg)),
232                Err(e) if skip_embed => {
233                    tracing::warn!(error = %e, "edit: embedding failed; --skip-embedding-on-failure active, persisting without embedding");
234                    None
235                }
236                Err(e) => return Err(e),
237            };
238        if let Some((ref emb, kind)) = embedding {
239            backend_invoked = Some(kind);
240            let snippet: String = new_body.chars().take(300).collect();
241            memories::upsert_vec(
242                &tx,
243                memory_id,
244                &namespace,
245                &memory_type,
246                emb,
247                &name,
248                &snippet,
249            )?;
250        }
251    }
252
253    let next_v = versions::next_version(&tx, memory_id)?;
254
255    versions::insert_version(
256        &tx,
257        memory_id,
258        next_v,
259        &name,
260        &memory_type,
261        &new_description,
262        &new_body,
263        &metadata,
264        None,
265        "edit",
266    )?;
267
268    memories::sync_fts_after_update(
269        &tx,
270        memory_id,
271        &row.name,
272        &row.description,
273        &row.body,
274        &row.name,
275        &new_description,
276        &new_body,
277    )?;
278
279    tx.commit()?;
280
281    conn.execute_batch("PRAGMA wal_checkpoint(TRUNCATE);")?;
282
283    output::emit_json(&EditResponse {
284        memory_id,
285        name,
286        action: "updated".to_string(),
287        version: next_v,
288        elapsed_ms: inicio.elapsed().as_millis() as u64,
289        backend_invoked,
290    })?;
291
292    Ok(())
293}
294
295#[cfg(test)]
296mod tests {
297    use super::*;
298
299    #[derive(clap::Parser)]
300    struct TestCli {
301        #[command(flatten)]
302        args: EditArgs,
303    }
304
305    #[test]
306    fn type_flag_is_a_visible_alias_of_memory_type() {
307        // G47: COOKBOOK, README and llms.txt promise `edit --type`; the flag
308        // was only reachable as --memory-type, breaking the documented CLI.
309        use clap::Parser;
310        let cli = TestCli::try_parse_from(["edit", "--name", "m", "--type", "decision"])
311            .expect("--type must parse as an alias of --memory-type");
312        assert!(cli.args.memory_type.is_some());
313        let cli = TestCli::try_parse_from(["edit", "--name", "m", "--memory-type", "decision"])
314            .expect("--memory-type must keep working");
315        assert!(cli.args.memory_type.is_some());
316    }
317
318    #[test]
319    fn edit_response_serializes_all_fields() {
320        let resp = EditResponse {
321            memory_id: 42,
322            name: "my-memory".to_string(),
323            action: "updated".to_string(),
324            version: 3,
325            elapsed_ms: 7,
326            backend_invoked: None,
327        };
328        let json = serde_json::to_value(&resp).expect("serialization failed");
329        assert_eq!(json["memory_id"], 42i64);
330        assert_eq!(json["name"], "my-memory");
331        assert_eq!(json["action"], "updated");
332        assert_eq!(json["version"], 3i64);
333        assert!(json["elapsed_ms"].is_number());
334    }
335
336    #[test]
337    fn edit_response_action_contains_updated() {
338        let resp = EditResponse {
339            memory_id: 1,
340            name: "n".to_string(),
341            action: "updated".to_string(),
342            version: 1,
343            elapsed_ms: 0,
344            backend_invoked: None,
345        };
346        assert_eq!(
347            resp.action, "updated",
348            "action must be 'updated' for successful edits"
349        );
350    }
351
352    #[test]
353    fn edit_body_exceeds_limit_returns_error() {
354        let limit = crate::constants::MAX_MEMORY_BODY_LEN;
355        let large_body: String = "a".repeat(limit + 1);
356        assert!(
357            large_body.len() > limit,
358            "body above limit must have length > MAX_MEMORY_BODY_LEN"
359        );
360    }
361
362    #[test]
363    fn edit_description_exceeds_limit_returns_error() {
364        let limit = crate::constants::MAX_MEMORY_DESCRIPTION_LEN;
365        let large_desc: String = "d".repeat(limit + 1);
366        assert!(
367            large_desc.len() > limit,
368            "description above limit must have length > MAX_MEMORY_DESCRIPTION_LEN"
369        );
370    }
371}
sqlite_graphrag/commands/edit.rs

sqlite_graphrag/commands/
edit.rs
