sqlite_graphrag/commands/
read.rs

1//! Handler for the `read` CLI subcommand.
2
3use crate::errors::AppError;
4use crate::i18n::errors_msg;
5use crate::output;
6use crate::paths::AppPaths;
7use crate::storage::connection::open_ro;
8use crate::storage::memories;
9use serde::Serialize;
10
11#[derive(clap::Args)]
12#[command(after_long_help = "EXAMPLES:\n  \
13    # Read a memory by name (positional)\n  \
14    sqlite-graphrag read onboarding\n\n  \
15    # Read using the named flag form\n  \
16    sqlite-graphrag read --name onboarding\n\n  \
17    # Read from a specific namespace\n  \
18    sqlite-graphrag read onboarding --namespace my-project")]
19pub struct ReadArgs {
20    /// Memory name as a positional argument. Alternative to `--name`.
21    #[arg(
22        value_name = "NAME",
23        conflicts_with = "name",
24        help = "Memory name (kebab-case slug); alternative to --name"
25    )]
26    pub name_positional: Option<String>,
27    /// Memory name to read. Returns NotFound (exit 4) if missing or soft-deleted.
28    #[arg(long)]
29    pub name: Option<String>,
30    #[arg(long, default_value = "global")]
31    pub namespace: Option<String>,
32    #[arg(long, hide = true, help = "No-op; JSON is always emitted on stdout")]
33    pub json: bool,
34    #[arg(long, env = "SQLITE_GRAPHRAG_DB_PATH")]
35    pub db: Option<String>,
36}
37
38#[derive(Serialize)]
39struct ReadResponse {
40    /// Canonical storage field. Preserved for compatibility with v2.0.0 clients.
41    id: i64,
42    /// Semantic alias of `id` for the contract documented in SKILL.md and AGENT_PROTOCOL.md.
43    memory_id: i64,
44    namespace: String,
45    name: String,
46    /// Semantic alias of `memory_type` for the documented contract.
47    #[serde(rename = "type")]
48    type_alias: String,
49    memory_type: String,
50    description: String,
51    body: String,
52    body_hash: String,
53    session_id: Option<String>,
54    source: String,
55    metadata: serde_json::Value,
56    /// Most recent memory version, useful for optimistic control via `--expected-updated-at`.
57    version: i64,
58    created_at: i64,
59    /// Timestamp RFC 3339 UTC paralelo a `created_at` para parsers ISO 8601.
60    created_at_iso: String,
61    updated_at: i64,
62    /// Timestamp RFC 3339 UTC paralelo a `updated_at` para parsers ISO 8601.
63    updated_at_iso: String,
64    /// Total execution time in milliseconds from handler start to serialisation.
65    elapsed_ms: u64,
66}
67
68fn epoch_to_iso(epoch: i64) -> String {
69    crate::tz::epoch_to_iso(epoch)
70}
71
72pub fn run(args: ReadArgs) -> Result<(), AppError> {
73    let start = std::time::Instant::now();
74    // Resolve name from positional or --name flag; both are optional, at least one is required.
75    let name = args.name_positional.or(args.name).ok_or_else(|| {
76        AppError::Validation("name required: pass as positional argument or via --name".to_string())
77    })?;
78    let namespace = crate::namespace::resolve_namespace(args.namespace.as_deref())?;
79    let paths = AppPaths::resolve(args.db.as_deref())?;
80    crate::storage::connection::ensure_db_ready(&paths)?;
81    let conn = open_ro(&paths.db)?;
82
83    match memories::read_by_name(&conn, &namespace, &name)? {
84        Some(row) => {
85            // Resolve current version via memory_versions table (highest version for this memory_id).
86            let version: i64 = conn
87                .query_row(
88                    "SELECT COALESCE(MAX(version), 1) FROM memory_versions WHERE memory_id=?1",
89                    rusqlite::params![row.id],
90                    |r| r.get(0),
91                )
92                .unwrap_or(1);
93
94            let response = ReadResponse {
95                id: row.id,
96                memory_id: row.id,
97                namespace: row.namespace,
98                name: row.name,
99                type_alias: row.memory_type.clone(),
100                memory_type: row.memory_type,
101                description: row.description,
102                body: row.body,
103                body_hash: row.body_hash,
104                session_id: row.session_id,
105                source: row.source,
106                metadata: serde_json::from_str::<serde_json::Value>(&row.metadata)
107                    .unwrap_or(serde_json::Value::Null),
108                version,
109                created_at: row.created_at,
110                created_at_iso: epoch_to_iso(row.created_at),
111                updated_at: row.updated_at,
112                updated_at_iso: epoch_to_iso(row.updated_at),
113                elapsed_ms: start.elapsed().as_millis() as u64,
114            };
115            output::emit_json(&response)?;
116        }
117        None => {
118            return Err(AppError::NotFound(errors_msg::memory_not_found(
119                &name, &namespace,
120            )))
121        }
122    }
123
124    Ok(())
125}
126
127#[cfg(test)]
128mod tests {
129    use super::*;
130
131    #[test]
132    fn epoch_to_iso_converts_zero_to_unix_epoch() {
133        let result = epoch_to_iso(0);
134        assert!(
135            result.starts_with("1970-01-01T00:00:00"),
136            "epoch 0 must map to 1970-01-01T00:00:00, got: {result}"
137        );
138    }
139
140    #[test]
141    fn epoch_to_iso_converts_known_timestamp() {
142        let result = epoch_to_iso(1_705_320_000);
143        assert!(
144            result.starts_with("2024-01-15"),
145            "timestamp 1705320000 must map to 2024-01-15, got: {result}"
146        );
147    }
148
149    #[test]
150    fn epoch_to_iso_returns_fallback_for_invalid_negative_epoch() {
151        let result = epoch_to_iso(i64::MIN);
152        assert!(
153            !result.is_empty(),
154            "must return a non-empty string even for invalid epoch"
155        );
156    }
157
158    #[test]
159    fn read_response_serializes_id_and_memory_id_aliases() {
160        let resp = ReadResponse {
161            id: 42,
162            memory_id: 42,
163            namespace: "global".to_string(),
164            name: "my-mem".to_string(),
165            type_alias: "fact".to_string(),
166            memory_type: "fact".to_string(),
167            description: "desc".to_string(),
168            body: "body".to_string(),
169            body_hash: "abc123".to_string(),
170            session_id: None,
171            source: "agent".to_string(),
172            metadata: serde_json::json!({}),
173            version: 1,
174            created_at: 1_705_320_000,
175            created_at_iso: "2024-01-15T12:00:00Z".to_string(),
176            updated_at: 1_705_320_000,
177            updated_at_iso: "2024-01-15T12:00:00Z".to_string(),
178            elapsed_ms: 5,
179        };
180
181        let json = serde_json::to_value(&resp).expect("serialization failed");
182        assert_eq!(json["id"], 42);
183        assert_eq!(json["memory_id"], 42);
184        assert_eq!(json["type"], "fact");
185        assert_eq!(json["memory_type"], "fact");
186        assert_eq!(json["elapsed_ms"], 5u64);
187        assert!(
188            json["session_id"].is_null(),
189            "session_id None must serialize as null"
190        );
191        // metadata must serialize as a JSON object, not as an escaped string
192        assert!(
193            json["metadata"].is_object(),
194            "metadata must be a JSON object"
195        );
196    }
197
198    #[test]
199    fn read_response_session_id_some_serializes_string() {
200        let resp = ReadResponse {
201            id: 1,
202            memory_id: 1,
203            namespace: "global".to_string(),
204            name: "mem".to_string(),
205            type_alias: "skill".to_string(),
206            memory_type: "skill".to_string(),
207            description: "d".to_string(),
208            body: "b".to_string(),
209            body_hash: "h".to_string(),
210            session_id: Some("sess-123".to_string()),
211            source: "agent".to_string(),
212            metadata: serde_json::json!({}),
213            version: 2,
214            created_at: 0,
215            created_at_iso: "1970-01-01T00:00:00Z".to_string(),
216            updated_at: 0,
217            updated_at_iso: "1970-01-01T00:00:00Z".to_string(),
218            elapsed_ms: 0,
219        };
220
221        let json = serde_json::to_value(&resp).expect("serialization failed");
222        assert_eq!(json["session_id"], "sess-123");
223    }
224
225    #[test]
226    fn read_response_elapsed_ms_is_present() {
227        let resp = ReadResponse {
228            id: 7,
229            memory_id: 7,
230            namespace: "ns".to_string(),
231            name: "n".to_string(),
232            type_alias: "procedure".to_string(),
233            memory_type: "procedure".to_string(),
234            description: "d".to_string(),
235            body: "b".to_string(),
236            body_hash: "h".to_string(),
237            session_id: None,
238            source: "agent".to_string(),
239            metadata: serde_json::json!({}),
240            version: 3,
241            created_at: 1000,
242            created_at_iso: "1970-01-01T00:16:40Z".to_string(),
243            updated_at: 2000,
244            updated_at_iso: "1970-01-01T00:33:20Z".to_string(),
245            elapsed_ms: 123,
246        };
247
248        let json = serde_json::to_value(&resp).expect("serialization failed");
249        assert_eq!(json["elapsed_ms"], 123u64);
250        assert!(json["created_at_iso"].is_string());
251        assert!(json["updated_at_iso"].is_string());
252    }
253
254    #[test]
255    fn read_response_metadata_object_not_escaped_string() {
256        // P2-A: metadata must serialize as a JSON object, not as an escaped string.
257        let resp = ReadResponse {
258            id: 3,
259            memory_id: 3,
260            namespace: "ns".to_string(),
261            name: "meta-test".to_string(),
262            type_alias: "fact".to_string(),
263            memory_type: "fact".to_string(),
264            description: "d".to_string(),
265            body: "b".to_string(),
266            body_hash: "h".to_string(),
267            session_id: None,
268            source: "agent".to_string(),
269            metadata: serde_json::json!({"key": "value", "number": 42}),
270            version: 1,
271            created_at: 0,
272            created_at_iso: "1970-01-01T00:00:00Z".to_string(),
273            updated_at: 0,
274            updated_at_iso: "1970-01-01T00:00:00Z".to_string(),
275            elapsed_ms: 1,
276        };
277
278        let json = serde_json::to_value(&resp).expect("serialization failed");
279        // Must be object, not a JSON string containing escaped JSON.
280        assert!(json["metadata"].is_object());
281        assert_eq!(json["metadata"]["key"], "value");
282        assert_eq!(json["metadata"]["number"], 42);
283    }
284
285    #[test]
286    fn read_response_metadata_fallback_to_null_for_invalid_json() {
287        // P2-A: fallback when metadata is an invalid string.
288        let raw = "invalid-json{{{";
289        let parsed =
290            serde_json::from_str::<serde_json::Value>(raw).unwrap_or(serde_json::Value::Null);
291        assert!(parsed.is_null());
292    }
293}
sqlite_graphrag/commands/read.rs

sqlite_graphrag/commands/
read.rs
