feat(memory): add session-scoped purge (#186)

## Summary
- add `session_id` and optional `memory_types` support to `POST /v1/memories/purge`
- implement indexed session purge in service/storage and expose it through MCP local/remote paths
- update session-cleanup templates and add DB/API/MCP end-to-end coverage

## Testing
- cargo clippy -p memoria-api -p memoria-service -p memoria-storage -p memoria-mcp -- -D warnings
- DATABASE_URL=mysql://root:111@localhost:6001/memoria_test SQLX_OFFLINE=true EMBEDDING_PROVIDER=mock cargo test -p memoria-service --test service_unit test_purge_by_session_id_filters_memory_type -- --nocapture
- DATABASE_URL=mysql://root:111@localhost:6001/memoria_test SQLX_OFFLINE=true EMBEDDING_PROVIDER=mock cargo test -p memoria-api --test api_db_verify test_purge_by_session_id_with_memory_types_verify_db -- --nocapture
- DATABASE_URL=mysql://root:111@localhost:6001/memoria_test SQLX_OFFLINE=true EMBEDDING_PROVIDER=mock cargo test -p memoria-api --test api_e2e test_remote_purge_by_session_id -- --nocapture
- DATABASE_URL=mysql://root:111@localhost:6001/memoria_test SQLX_OFFLINE=true EMBEDDING_PROVIDER=mock cargo test -p memoria-mcp --test core_tools_e2e test_purge_session_id_with_memory_types -- --nocapture

Fixes #182

Approved by: @XuPeng-SH

Author: gouhongshen

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

@@ -92,9 +92,71 @@ pub struct CorrectByQueryRequest {
 pub struct PurgeRequest {
     pub memory_ids: Option<Vec<String>>,
     pub topic: Option<String>,
+    pub session_id: Option<String>,
+    pub memory_types: Option<Vec<String>>,
     pub reason: Option<String>,
 }
 
+pub enum PurgeSelector {
+    MemoryIds(Vec<String>),
+    Topic(String),
+    Session {
+        session_id: String,
+        memory_types: Option<Vec<MemoryType>>,
+    },
+    None,
+}
+
+impl PurgeRequest {
+    pub fn selector(&self) -> Result<PurgeSelector, String> {
+        let memory_ids = self.memory_ids.as_ref().filter(|ids| !ids.is_empty());
+        let memory_types = self.memory_types.as_ref().filter(|types| !types.is_empty());
+        let topic = self
+            .topic
+            .as_deref()
+            .map(str::trim)
+            .filter(|s| !s.is_empty());
+        let session_id = self
+            .session_id
+            .as_deref()
+            .map(str::trim)
+            .filter(|s| !s.is_empty());
+        if memory_types.is_some() && session_id.is_none() {
+            return Err("memory_types requires session_id".to_string());
+        }
+
+        let selector_count = usize::from(memory_ids.is_some())
+            + usize::from(topic.is_some())
+            + usize::from(session_id.is_some());
+        if selector_count > 1 {
+            return Err("provide only one of memory_ids, topic, or session_id".to_string());
+        }
+
+        if let Some(ids) = memory_ids {
+            return Ok(PurgeSelector::MemoryIds(ids.clone()));
+        }
+        if let Some(topic) = topic {
+            return Ok(PurgeSelector::Topic(topic.to_string()));
+        }
+        if let Some(session_id) = session_id {
+            let memory_types = memory_types
+                .map(|types| {
+                    types
+                        .iter()
+                        .map(|memory_type| parse_memory_type(memory_type))
+                        .collect::<Result<Vec<_>, _>>()
+                })
+                .transpose()?
+                .filter(|types| !types.is_empty());
+            return Ok(PurgeSelector::Session {
+                session_id: session_id.to_string(),
+                memory_types,
+            });
+        }
+        Ok(PurgeSelector::None)
+    }
+}
+
 #[derive(Serialize)]
 pub struct MemoryResponse {
     pub memory_id: String,
@@ -231,3 +293,43 @@ pub fn parse_memory_type(s: &str) -> Result<MemoryType, String> {
 pub fn parse_trust_tier(s: &str) -> Result<TrustTier, String> {
     TrustTier::from_str(s).map_err(|e| e.to_string())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{PurgeRequest, PurgeSelector};
+
+    #[test]
+    fn purge_selector_ignores_empty_arrays() {
+        let request = PurgeRequest {
+            memory_ids: Some(vec![]),
+            topic: None,
+            session_id: Some("sess-1".to_string()),
+            memory_types: Some(vec![]),
+            reason: None,
+        };
+
+        match request.selector().unwrap() {
+            PurgeSelector::Session {
+                session_id,
+                memory_types,
+            } => {
+                assert_eq!(session_id, "sess-1");
+                assert!(memory_types.is_none());
+            }
+            _ => panic!("expected session selector"),
+        }
+    }
+
+    #[test]
+    fn purge_selector_empty_memory_types_do_not_require_session() {
+        let request = PurgeRequest {
+            memory_ids: None,
+            topic: None,
+            session_id: None,
+            memory_types: Some(vec![]),
+            reason: None,
+        };
+
+        assert!(matches!(request.selector().unwrap(), PurgeSelector::None));
+    }
+}

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

@@ -371,38 +371,51 @@ pub async fn purge_memories(
     AuthUser { user_id, is_master }: AuthUser,
     Json(req): Json<PurgeRequest>,
 ) -> ApiResult<PurgeResponse> {
-    let result = if let Some(ids) = &req.memory_ids {
-        if !is_master {
-            for id in ids {
-                let mem = state
-                    .service
-                    .get_for_user(&user_id, id)
-                    .await
-                    .map_err(api_err)?
-                    .ok_or_else(|| (StatusCode::NOT_FOUND, format!("Memory not found: {id}")))?;
-                if mem.user_id != user_id {
-                    return Err((StatusCode::FORBIDDEN, format!("Not your memory: {id}")));
+    let selector = req
+        .selector()
+        .map_err(|e| (StatusCode::UNPROCESSABLE_ENTITY, e))?;
+    let result = match selector {
+        PurgeSelector::MemoryIds(ids) => {
+            if !is_master {
+                for id in &ids {
+                    let mem = state
+                        .service
+                        .get_for_user(&user_id, id)
+                        .await
+                        .map_err(api_err)?
+                        .ok_or_else(|| {
+                            (StatusCode::NOT_FOUND, format!("Memory not found: {id}"))
+                        })?;
+                    if mem.user_id != user_id {
+                        return Err((StatusCode::FORBIDDEN, format!("Not your memory: {id}")));
+                    }
                 }
             }
+            let id_refs: Vec<&str> = ids.iter().map(|s| s.as_str()).collect();
+            state
+                .service
+                .purge_batch(&user_id, &id_refs)
+                .await
+                .map_err(api_err)?
         }
-        let id_refs: Vec<&str> = ids.iter().map(|s| s.as_str()).collect();
-        state
+        PurgeSelector::Topic(topic) => state
             .service
-            .purge_batch(&user_id, &id_refs)
+            .purge_by_topic(&user_id, &topic)
             .await
-            .map_err(api_err)?
-    } else if let Some(topic) = &req.topic {
-        state
+            .map_err(api_err)?,
+        PurgeSelector::Session {
+            session_id,
+            memory_types,
+        } => state
             .service
-            .purge_by_topic(&user_id, topic)
+            .purge_by_session_id(&user_id, &session_id, memory_types.as_deref())
             .await
-            .map_err(api_err)?
-    } else {
-        memoria_service::PurgeResult {
+            .map_err(api_err)?,
+        PurgeSelector::None => memoria_service::PurgeResult {
             purged: 0,
             snapshot_name: None,
             warning: None,
-        }
+        },
     };
     Ok(Json(PurgeResponse {
         purged: result.purged,

memoria/crates/memoria-api/tests/api_db_verify.rs

@@ -572,6 +572,80 @@ async fn test_purge_by_topic_batch_perf_verify_db() {
     println!("✅ purge by topic batch: 10 memories purged in one call");
 }
 
+#[tokio::test]
+#[serial]
+async fn test_purge_by_session_id_with_memory_types_verify_db() {
+    let (base, client, pool) = spawn_server().await;
+    let uid = uid();
+    let target_session = format!("session:test-smp-{}", uuid::Uuid::new_v4().simple());
+    let other_session = format!("session:test-smp-{}", uuid::Uuid::new_v4().simple());
+
+    for (content, memory_type, session_id) in [
+        ("target working alpha", "working", target_session.as_str()),
+        ("target working beta", "working", target_session.as_str()),
+        ("target semantic keep", "semantic", target_session.as_str()),
+        ("other working keep", "working", other_session.as_str()),
+    ] {
+        client
+            .post(format!("{base}/v1/memories"))
+            .header("X-User-Id", &uid)
+            .json(&json!({
+                "content": content,
+                "memory_type": memory_type,
+                "session_id": session_id,
+            }))
+            .send()
+            .await
+            .unwrap();
+    }
+    assert_eq!(db_count_active(&pool, &uid).await, 4);
+
+    let r = client
+        .post(format!("{base}/v1/memories/purge"))
+        .header("X-User-Id", &uid)
+        .json(&json!({
+            "session_id": target_session,
+            "memory_types": ["working"],
+            "reason": "session complete"
+        }))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(r.status(), 200);
+    let body: Value = r.json().await.unwrap();
+    assert_eq!(body["purged"], 2);
+
+    let rows = sqlx::query(
+        "SELECT content, memory_type, session_id FROM mem_memories \
+         WHERE user_id = ? AND is_active > 0 ORDER BY content ASC",
+    )
+    .bind(&uid)
+    .fetch_all(&pool)
+    .await
+    .unwrap();
+    let remaining: Vec<(String, String, String)> = rows
+        .into_iter()
+        .map(|row| {
+            (
+                row.get("content"),
+                row.get("memory_type"),
+                row.get("session_id"),
+            )
+        })
+        .collect();
+    assert_eq!(remaining.len(), 2);
+    assert!(remaining.iter().any(|(content, memory_type, session_id)| {
+        content == "target semantic keep"
+            && memory_type == "semantic"
+            && session_id == &target_session
+    }));
+    assert!(remaining.iter().any(|(content, memory_type, session_id)| {
+        content == "other working keep" && memory_type == "working" && session_id == &other_session
+    }));
+
+    println!("✅ purge by session_id: working memories removed without touching other active rows");
+}
+
 // ═══════════════════════════════════════════════════════════════════════════════
 // 4. BATCH STORE — verify all rows in DB with correct types
 // ═══════════════════════════════════════════════════════════════════════════════

memoria/crates/memoria-api/tests/api_e2e.rs

@@ -2454,6 +2454,91 @@ async fn test_remote_purge_by_topic() {
     println!("✅ remote purge by topic: {t}");
 }
 
+#[tokio::test]
+async fn test_remote_purge_by_session_id() {
+    use memoria_mcp::remote::RemoteClient;
+    let (base, _) = spawn_api_for_remote().await;
+    let uid = uid();
+    let remote = RemoteClient::new(&base, None, uid.clone(), None);
+    let target_session = format!("session:test-smp-{}", uuid::Uuid::new_v4().simple());
+    let other_session = format!("session:test-smp-{}", uuid::Uuid::new_v4().simple());
+
+    remote
+        .call(
+            "memory_store",
+            json!({"content": "remote working alpha", "memory_type": "working", "session_id": target_session}),
+        )
+        .await
+        .unwrap();
+    remote
+        .call(
+            "memory_store",
+            json!({"content": "remote working beta", "memory_type": "working", "session_id": target_session}),
+        )
+        .await
+        .unwrap();
+    remote
+        .call(
+            "memory_store",
+            json!({"content": "remote semantic keep", "memory_type": "semantic", "session_id": target_session}),
+        )
+        .await
+        .unwrap();
+    remote
+        .call(
+            "memory_store",
+            json!({"content": "remote other keep", "memory_type": "working", "session_id": other_session}),
+        )
+        .await
+        .unwrap();
+
+    let r = remote
+        .call(
+            "memory_purge",
+            json!({"session_id": target_session, "memory_types": ["working"]}),
+        )
+        .await
+        .unwrap();
+    let t = r["content"][0]["text"].as_str().unwrap_or("");
+    assert!(t.contains("Purged 2"), "got: {t}");
+
+    let list = remote
+        .call("memory_list", json!({"limit": 10}))
+        .await
+        .unwrap();
+    let list_text = list["content"][0]["text"].as_str().unwrap_or("");
+    assert!(
+        list_text.contains("remote semantic keep"),
+        "got: {list_text}"
+    );
+    assert!(list_text.contains("remote other keep"), "got: {list_text}");
+    assert!(
+        !list_text.contains("remote working alpha"),
+        "got: {list_text}"
+    );
+    assert!(
+        !list_text.contains("remote working beta"),
+        "got: {list_text}"
+    );
+    println!("✅ remote purge by session_id: {t}");
+}
+
+#[tokio::test]
+async fn test_remote_purge_rejects_invalid_memory_types_locally() {
+    use memoria_mcp::remote::RemoteClient;
+    let remote = RemoteClient::new("http://127.0.0.1:9", None, uid(), None);
+
+    let err = remote
+        .call(
+            "memory_purge",
+            json!({"session_id": "sess-target", "memory_types": ["not_a_real_type"]}),
+        )
+        .await
+        .unwrap_err();
+    assert!(err.to_string().contains("Invalid memory type"), "{err}");
+    println!("✅ remote purge rejects invalid memory_types before API call");
+}
+
 // ── Episodic memory tests ─────────────────────────────────────────────────────
 
 #[tokio::test]

memoria/crates/memoria-cli/templates/claude_rule.md

@@ -40,7 +40,7 @@ Do NOT call `memory_store` for:
 `working` memories are session-scoped temporary context. They **persist and will be retrieved in future sessions** unless explicitly cleaned up.
 
 **When to purge working memories:**
-- Task or debug session is complete → `memory_purge(topic="<task keyword>", reason="task complete")`
+- Task or debug session is complete → `memory_purge(session_id="<session_id>", memory_types=["working"], reason="task complete")`
 - You stored a working memory that turned out to be wrong → `memory_purge(memory_id="...", reason="incorrect conclusion")`
 - User says "start fresh", "forget what we tried", "let's try a different approach"
 - Only purge completed tasks — leave active task working memories for next session

memoria/crates/memoria-cli/templates/claude_session_lifecycle.md

@@ -39,7 +39,7 @@ When the conversation is winding down (user says thanks, goodbye, or stops engag
 ### 1. Clean up working memories
 
 ```
-memory_purge(topic="<task keyword>", reason="session complete")
+memory_purge(session_id="<session_id>", memory_types=["working"], reason="session complete")
 ```
 
 Only purge working memories for tasks that are actually done. Leave active task working memories for next session.

memoria/crates/memoria-cli/templates/codex_agents.md

@@ -44,7 +44,7 @@ Do NOT call `memory_store` for:
 `working` memories are session-scoped temporary context. They **persist and will be retrieved in future sessions** unless explicitly cleaned up.
 
 **When to purge working memories:**
-- Task or debug session is complete → `memory_purge(topic="<task keyword>", reason="task complete")`
+- Task or debug session is complete → `memory_purge(session_id="<session_id>", memory_types=["working"], reason="task complete")`
 - You stored a working memory that turned out to be wrong → `memory_purge(memory_id="...", reason="incorrect conclusion")`
 - User says "start fresh", "forget what we tried", "let's try a different approach"
 - Only purge completed tasks — leave active task working memories for next session
@@ -192,7 +192,7 @@ When the conversation is winding down (user says thanks, goodbye, or stops engag
 ### 1. Clean up working memories
 
 ```
-memory_purge(topic="<task keyword>", reason="session complete")
+memory_purge(session_id="<session_id>", memory_types=["working"], reason="session complete")
 ```
 
 Only purge working memories for tasks that are actually done. Leave active task working memories for next session.