feat(sessions): add date filters to recall search

Author: ScriptedAlchemy

src/agents/hermes/templates/plugin_init.py

@@ -156,11 +156,19 @@ def _resolve_auxiliary_client(agent=None):
                 },
                 "time_from": {
                     "anyOf": [{"type": "number"}, {"type": "string"}],
-                    "description": "Optional inclusive minimum raw-message timestamp.",
+                    "description": "Optional inclusive minimum raw-message timestamp. Accepts Unix seconds, RFC3339, YYYY-MM-DD, or relative time like 'last hour'.",
                 },
                 "time_to": {
                     "anyOf": [{"type": "number"}, {"type": "string"}],
-                    "description": "Optional inclusive maximum raw-message timestamp.",
+                    "description": "Optional inclusive maximum raw-message timestamp. Accepts Unix seconds, RFC3339, YYYY-MM-DD, or relative time like 'last hour'.",
+                },
+                "since": {
+                    "anyOf": [{"type": "number"}, {"type": "string"}],
+                    "description": "Alias for time_from.",
+                },
+                "until": {
+                    "anyOf": [{"type": "number"}, {"type": "string"}],
+                    "description": "Alias for time_to.",
                 },
             },
             "required": ["query"],

src/cli.rs

@@ -624,6 +624,12 @@ pub enum SessionsAction {
         /// Maximum number of matches
         #[arg(long, default_value_t = 10)]
         limit: usize,
+        /// Inclusive minimum message timestamp. Accepts Unix seconds, RFC3339, YYYY-MM-DD, or relative time like "last hour"
+        #[arg(long, alias = "time-from", alias = "start-time")]
+        since: Option<String>,
+        /// Inclusive maximum message timestamp. Accepts Unix seconds, RFC3339, YYYY-MM-DD, or relative time like "last hour"
+        #[arg(long, alias = "time-to", alias = "end-time")]
+        until: Option<String>,
         /// Registered project id whose session store should be searched
         #[arg(long)]
         project_id: Option<String>,

src/cli/parse_tests.rs

@@ -1550,13 +1550,38 @@ fn parses_sessions_ingest_and_search_commands() {
                     limit,
                     project_id,
                     project_path,
+                    since,
+                    until,
                 },
         }) => {
             assert_eq!(query, "needle");
             assert_eq!(provider.as_deref(), Some("codex"));
             assert_eq!(limit, 5);
             assert!(project_id.is_none());
             assert!(project_path.is_none());
+            assert!(since.is_none());
+            assert!(until.is_none());
+        }
+        _ => panic!("expected sessions search command"),
+    }
+
+    let time_filtered_search = Cli::try_parse_from([
+        "tracedecay",
+        "sessions",
+        "search",
+        "needle",
+        "--since",
+        "last hour",
+        "--until",
+        "2026-07-04T00:00:00Z",
+    ])
+    .unwrap();
+    match time_filtered_search.command {
+        Some(Commands::Sessions {
+            action: SessionsAction::Search { since, until, .. },
+        }) => {
+            assert_eq!(since.as_deref(), Some("last hour"));
+            assert_eq!(until.as_deref(), Some("2026-07-04T00:00:00Z"));
         }
         _ => panic!("expected sessions search command"),
     }

src/global_db.rs

@@ -17,6 +17,7 @@ use crate::sessions::{
         LcmSummarySourceMessage, LcmSummarySourceRange,
     },
     SessionMessageRecord, SessionMessageSearchResult, SessionRecord, SessionSearchScope,
+    SessionSearchTimeRange,
 };
 
 const UNIX_TIMESTAMP_MILLIS_THRESHOLD: i64 = 1_000_000_000_000;
@@ -3180,6 +3181,7 @@ impl GlobalDb {
             limit,
             SessionSearchScope::All,
             None,
+            SessionSearchTimeRange::default(),
         )
         .await
     }
@@ -3193,6 +3195,7 @@ impl GlobalDb {
         limit: usize,
         scope: SessionSearchScope,
         parent_session_id: Option<&str>,
+        time_range: SessionSearchTimeRange,
     ) -> Vec<SessionMessageSearchResult> {
         self.search_session_messages_filtered_inner(
             Some(provider),
@@ -3201,6 +3204,7 @@ impl GlobalDb {
             limit,
             scope,
             parent_session_id,
+            time_range,
         )
         .await
     }
@@ -3213,6 +3217,7 @@ impl GlobalDb {
         limit: usize,
         scope: SessionSearchScope,
         parent_session_id: Option<&str>,
+        time_range: SessionSearchTimeRange,
     ) -> Vec<SessionMessageSearchResult> {
         self.search_session_messages_filtered_inner(
             None,
@@ -3221,6 +3226,7 @@ impl GlobalDb {
             limit,
             scope,
             parent_session_id,
+            time_range,
         )
         .await
     }
@@ -3233,6 +3239,7 @@ impl GlobalDb {
         limit: usize,
         scope: SessionSearchScope,
         parent_session_id: Option<&str>,
+        time_range: SessionSearchTimeRange,
     ) -> Vec<SessionMessageSearchResult> {
         let fts_query = session_fts_query(query);
         if fts_query.is_empty() || limit == 0 {
@@ -3269,6 +3276,22 @@ impl GlobalDb {
             query_params.push(Value::Text(parent_session_id.to_string()));
             let _ = write!(sql, " AND s.parent_session_id = ?{}", query_params.len());
         }
+        if let Some(start_time) = time_range.start_time {
+            query_params.push(Value::Integer(start_time));
+            let _ = write!(
+                sql,
+                " AND m.timestamp IS NOT NULL AND m.timestamp >= ?{}",
+                query_params.len()
+            );
+        }
+        if let Some(end_time) = time_range.end_time {
+            query_params.push(Value::Integer(end_time));
+            let _ = write!(
+                sql,
+                " AND m.timestamp IS NOT NULL AND m.timestamp <= ?{}",
+                query_params.len()
+            );
+        }
         if matches!(scope, SessionSearchScope::ParentsOnly) {
             sql.push_str(" AND s.is_subagent = 0");
         }

src/mcp/tools/definitions.rs

@@ -2351,6 +2351,34 @@ fn def_message_search() -> ToolDefinition {
                     "type": "string",
                     "description": "Optional parent session id filter. Primarily useful with scope=subagents_only."
                 },
+                "since": {
+                    "oneOf": [
+                        { "type": "integer", "minimum": 0 },
+                        { "type": "string" }
+                    ],
+                    "description": "Optional inclusive minimum message timestamp. Accepts Unix seconds, RFC3339, YYYY-MM-DD, or relative time like 'last hour'."
+                },
+                "until": {
+                    "oneOf": [
+                        { "type": "integer", "minimum": 0 },
+                        { "type": "string" }
+                    ],
+                    "description": "Optional inclusive maximum message timestamp. Accepts Unix seconds, RFC3339, YYYY-MM-DD, or relative time like 'last hour'."
+                },
+                "time_from": {
+                    "oneOf": [
+                        { "type": "integer", "minimum": 0 },
+                        { "type": "string" }
+                    ],
+                    "description": "Alias for since."
+                },
+                "time_to": {
+                    "oneOf": [
+                        { "type": "integer", "minimum": 0 },
+                        { "type": "string" }
+                    ],
+                    "description": "Alias for until."
+                },
                 "scope": {
                     "type": "string",
                     "description": "Relationship scope for search results (default: all).",
@@ -2616,14 +2644,28 @@ fn def_lcm_grep() -> ToolDefinition {
                         { "type": "integer", "minimum": 0 },
                         { "type": "string" }
                     ],
-                    "description": "Optional inclusive minimum raw-message timestamp. Integer strings and timezone-aware ISO/RFC3339 strings are accepted."
+                    "description": "Optional inclusive minimum raw-message timestamp. Accepts Unix seconds, RFC3339, YYYY-MM-DD, or relative time like 'last hour'."
                 },
                 "end_time": {
                     "oneOf": [
                         { "type": "integer", "minimum": 0 },
                         { "type": "string" }
                     ],
-                    "description": "Optional inclusive maximum raw-message timestamp. Integer strings and timezone-aware ISO/RFC3339 strings are accepted."
+                    "description": "Optional inclusive maximum raw-message timestamp. Accepts Unix seconds, RFC3339, YYYY-MM-DD, or relative time like 'last hour'."
+                },
+                "since": {
+                    "oneOf": [
+                        { "type": "integer", "minimum": 0 },
+                        { "type": "string" }
+                    ],
+                    "description": "Alias for start_time."
+                },
+                "until": {
+                    "oneOf": [
+                        { "type": "integer", "minimum": 0 },
+                        { "type": "string" }
+                    ],
+                    "description": "Alias for end_time."
                 },
                 "limit": {
                     "type": "integer",

src/mcp/tools/handlers/session.rs

@@ -21,7 +21,8 @@ use crate::sessions::lcm::{
     LcmGrepSort, LcmLoadSessionRequest, LcmPreflightRequest, LcmScope, LcmSessionBoundaryRequest,
     LcmSummarizerMode, LCM_EXPAND_QUERY_SYNTHESIS_SYSTEM_PROMPT,
 };
-use crate::sessions::{ProviderScope, SessionSearchScope};
+use crate::sessions::{ProviderScope, SessionSearchScope, SessionSearchTimeRange};
+use crate::timeutil::SearchTimeBound;
 use crate::tracedecay::{current_timestamp, TraceDecay};
 
 const DEFAULT_LCM_CONTENT_LIMIT: usize = 4096;
@@ -1094,26 +1095,32 @@ fn non_negative_i64_arg_alias(args: &Value, primary: &str, alias: &str) -> Resul
     }
 }
 
-fn non_negative_timestamp_arg_alias(
+fn non_negative_timestamp_arg_aliases(
     args: &Value,
-    primary: &str,
-    alias: &str,
+    names: &[&str],
+    bound: SearchTimeBound,
 ) -> Result<Option<i64>> {
-    match non_negative_timestamp_arg(args, primary)? {
-        Some(value) => Ok(Some(value)),
-        None => non_negative_timestamp_arg(args, alias),
+    for name in names {
+        if args.get(name).is_some() {
+            return non_negative_timestamp_arg(args, name, bound);
+        }
     }
+    Ok(None)
 }
 
-fn non_negative_timestamp_arg(args: &Value, name: &str) -> Result<Option<i64>> {
+fn non_negative_timestamp_arg(
+    args: &Value,
+    name: &str,
+    bound: SearchTimeBound,
+) -> Result<Option<i64>> {
     let Some(value) = args.get(name) else {
         return Ok(None);
     };
     let timestamp = match value {
         Value::Number(number) => number
             .as_i64()
             .ok_or_else(|| timestamp_argument_error(name))?,
-        Value::String(text) => parse_timestamp_string(text, name)?,
+        Value::String(text) => parse_timestamp_string(text, name, bound)?,
         _ => return Err(timestamp_argument_error(name)),
     };
     if timestamp < 0 {
@@ -1122,7 +1129,7 @@ fn non_negative_timestamp_arg(args: &Value, name: &str) -> Result<Option<i64>> {
     Ok(Some(timestamp))
 }
 
-fn parse_timestamp_string(value: &str, name: &str) -> Result<i64> {
+fn parse_timestamp_string(value: &str, name: &str, bound: SearchTimeBound) -> Result<i64> {
     let text = value.trim();
     if text.is_empty() {
         return Err(argument_error(format!("{name} must not be empty")));
@@ -1133,12 +1140,29 @@ fn parse_timestamp_string(value: &str, name: &str) -> Result<i64> {
         }
         return Err(argument_error(format!("{name} must be >= 0")));
     }
-    crate::timeutil::parse_rfc3339_timestamp(text).ok_or_else(|| timestamp_argument_error(name))
+    let now = crate::tracedecay::current_timestamp();
+    crate::timeutil::parse_search_time_filter_bound(text, now, bound)
+        .ok_or_else(|| timestamp_argument_error(name))
+}
+
+fn message_search_time_range(args: &Value) -> Result<SessionSearchTimeRange> {
+    Ok(SessionSearchTimeRange {
+        start_time: non_negative_timestamp_arg_aliases(
+            args,
+            &["since", "start_time", "time_from"],
+            SearchTimeBound::Start,
+        )?,
+        end_time: non_negative_timestamp_arg_aliases(
+            args,
+            &["until", "end_time", "time_to"],
+            SearchTimeBound::End,
+        )?,
+    })
 }
 
 fn timestamp_argument_error(name: &str) -> TraceDecayError {
     argument_error(format!(
-        "{name} must be a non-negative Unix timestamp or timezone-aware ISO/RFC3339 string"
+        "{name} must be a non-negative Unix timestamp, timezone-aware ISO/RFC3339 string, YYYY-MM-DD date, or relative time like 'last hour'"
     ))
 }
 
@@ -1779,6 +1803,7 @@ pub(super) async fn handle_message_search(
         .and_then(Value::as_u64)
         .unwrap_or(10)
         .clamp(1, 50) as usize;
+    let time_range = message_search_time_range(&args)?;
 
     let Some((db_path, target_root)) = selected_project_session_db_path(
         cg.project_root(),
@@ -1829,6 +1854,7 @@ pub(super) async fn handle_message_search(
             limit,
             scope,
             parent_session_id,
+            time_range,
         )
         .await
     } else {
@@ -1838,6 +1864,7 @@ pub(super) async fn handle_message_search(
             limit,
             scope,
             parent_session_id,
+            time_range,
         )
         .await
     };
@@ -1858,6 +1885,8 @@ pub(super) async fn handle_message_search(
             SessionSearchScope::ParentsOnly => "parents_only",
             SessionSearchScope::SubagentsOnly => "subagents_only",
         },
+        "since": time_range.start_time,
+        "until": time_range.end_time,
         "query": query,
         "count": results.len(),
         "results": results,
@@ -2069,8 +2098,16 @@ pub(super) async fn handle_lcm_grep(
             sort: parse_lcm_grep_sort(&args)?,
             source: string_arg(&args, "source").map(str::to_string),
             role: string_arg(&args, "role").map(str::to_string),
-            start_time: non_negative_timestamp_arg_alias(&args, "start_time", "time_from")?,
-            end_time: non_negative_timestamp_arg_alias(&args, "end_time", "time_to")?,
+            start_time: non_negative_timestamp_arg_aliases(
+                &args,
+                &["since", "start_time", "time_from"],
+                SearchTimeBound::Start,
+            )?,
+            end_time: non_negative_timestamp_arg_aliases(
+                &args,
+                &["until", "end_time", "time_to"],
+                SearchTimeBound::End,
+            )?,
         })
         .await
         .map_err(lcm_error)?;

src/sessions/mod.rs

@@ -169,6 +169,13 @@ pub struct SessionMessageSearchResult {
     pub score: f64,
 }
 
+/// Inclusive timestamp bounds for session-message full-text search.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SessionSearchTimeRange {
+    pub start_time: Option<i64>,
+    pub end_time: Option<i64>,
+}
+
 /// Scope filter for session-message full-text search.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 pub enum SessionSearchScope {