fix(memory): enforce strict session retrieval semantics (#185)

## Summary
- thread strict session retrieval options through API, service, storage, and MCP
- skip graph retrieval when strict session scope is requested and keep default cross-session semantics unchanged
- add a strict scoped vector fallback plus REST/MCP regressions covering issue #184 semantics

## Testing
- DATABASE_URL=mysql://root:111@localhost:6001/memoria_test SQLX_OFFLINE=true cargo test -p memoria-storage --test store_crud test_search_vector_from_filtered_scoped_prefilters_by_session -- --nocapture
- DATABASE_URL=mysql://root:111@localhost:6001/memoria_test SQLX_OFFLINE=true cargo test -p memoria-storage --test store_crud test_search_vector_from_filtered_scoped_fills_limit_with_session_candidates -- --nocapture
- DATABASE_URL=mysql://root:111@localhost:6001/memoria_test SQLX_OFFLINE=true cargo test -p memoria-api --test api_e2e test_retrieve_filter_session_prefilters_and_skips_graph -- --nocapture
- DATABASE_URL=mysql://root:111@localhost:6001/memoria_test SQLX_OFFLINE=true cargo test -p memoria-api --test api_e2e test_retrieve_filter_session_preserves_top_k_with_session_candidates -- --nocapture
- DATABASE_URL=mysql://root:111@localhost:6001/memoria_test SQLX_OFFLINE=true cargo test -p memoria-api --test api_e2e test_mcp_memory_retrieve_filter_session_end_to_end -- --nocapture

Fixes #184

Approved by: @XuPeng-SH

Author: gouhongshen

memoria/crates/memoria-api/src/models.rs

@@ -33,6 +33,9 @@ pub struct RetrieveRequest {
     #[serde(default = "default_top_k")]
     pub top_k: i64,
     pub session_id: Option<String>,
+    /// Explicit strict session filter. Overrides include_cross_session when provided.
+    #[serde(default)]
+    pub filter_session: Option<bool>,
     /// When false and session_id is set, only return memories from that session.
     #[serde(default = "default_true")]
     pub include_cross_session: bool,
@@ -47,6 +50,16 @@ fn default_true() -> bool {
     true
 }
 
+impl RetrieveRequest {
+    pub fn retrieve_options(&self) -> memoria_service::RetrieveOptions {
+        memoria_service::RetrieveOptions::from_session_scope(
+            self.session_id.as_deref(),
+            self.filter_session,
+            Some(self.include_cross_session),
+        )
+    }
+}
+
 fn deserialize_explain<'de, D: serde::Deserializer<'de>>(d: D) -> Result<String, D::Error> {
     use serde::Deserialize;
     #[derive(Deserialize)]

memoria/crates/memoria-api/src/routes/memory.rs

@@ -211,39 +211,40 @@ pub async fn retrieve(
     AuthUser { user_id, .. }: AuthUser,
     Json(req): Json<RetrieveRequest>,
 ) -> ApiResult<serde_json::Value> {
+    if req.session_id.is_none() && (req.filter_session == Some(true) || !req.include_cross_session)
+    {
+        return Err((
+            StatusCode::UNPROCESSABLE_ENTITY,
+            "session_id is required for strict session retrieval".to_string(),
+        ));
+    }
     let top_k = req.top_k.clamp(1, 100);
     let level = memoria_service::ExplainLevel::from_str_or_bool(&req.explain);
-    let filter_session = req
-        .session_id
-        .as_deref()
-        .filter(|_| !req.include_cross_session);
-
-    let apply_filter = |mut mems: Vec<memoria_core::Memory>| -> Vec<memoria_core::Memory> {
-        if let Some(sid) = filter_session {
-            mems.retain(|m| m.session_id.as_deref() == Some(sid));
-        }
-        mems
-    };
+    let retrieve_options = req.retrieve_options();
 
     if level != memoria_service::ExplainLevel::None {
         let (results, explain) = state
             .service
-            .retrieve_explain_level(&user_id, &req.query, top_k, level)
+            .retrieve_explain_level_with_options(
+                &user_id,
+                &req.query,
+                top_k,
+                level,
+                &retrieve_options,
+            )
             .await
             .map_err(api_err)?;
-        let items: Vec<MemoryResponse> =
-            apply_filter(results).into_iter().map(Into::into).collect();
+        let items: Vec<MemoryResponse> = results.into_iter().map(Into::into).collect();
         Ok(Json(
             serde_json::json!({"results": items, "explain": explain}),
         ))
     } else {
         let results = state
             .service
-            .retrieve(&user_id, &req.query, top_k)
+            .retrieve_with_options(&user_id, &req.query, top_k, &retrieve_options)
             .await
             .map_err(api_err)?;
-        let items: Vec<MemoryResponse> =
-            apply_filter(results).into_iter().map(Into::into).collect();
+        let items: Vec<MemoryResponse> = results.into_iter().map(Into::into).collect();
         Ok(Json(serde_json::json!(items)))
     }
 }