extend mcp (#28)

* extend mcp

* fixes

* transitive

* bump time

Author: vaporif

crates/core/src/cache.rs

@@ -37,6 +37,9 @@ pub struct ResultCacheKeyInput<'a> {
     pub include_stale: Option<bool>,
     pub include_invalidated: Option<bool>,
     pub time_range_hash: Option<u64>,
+    /// Nanosecond resolution. The post-fetch filter compares full
+    /// `DateTime<Utc>`, so sub-second `as_of` values would otherwise collide.
+    pub as_of_nanos: Option<i64>,
     pub explain: bool,
 }
 
@@ -53,6 +56,7 @@ impl ResultCacheKey {
         input.include_stale.hash(&mut hasher);
         input.include_invalidated.hash(&mut hasher);
         input.time_range_hash.hash(&mut hasher);
+        input.as_of_nanos.hash(&mut hasher);
         input.explain.hash(&mut hasher);
         Self {
             hash: hasher.finish(),
@@ -217,6 +221,7 @@ mod tests {
             include_stale: None,
             include_invalidated: None,
             time_range_hash: None,
+            as_of_nanos: None,
             explain: false,
         });
         cache.put_results(&filter, results, ns).await;
@@ -242,6 +247,7 @@ mod tests {
             include_stale: None,
             include_invalidated: None,
             time_range_hash: None,
+            as_of_nanos: None,
             explain: false,
         });
         cache.put_results(&filter, vec![], ns).await;

crates/core/src/entity.rs

@@ -148,7 +148,7 @@ impl<M: MetadataStore> EntityResolver<'_, M> {
     }
 }
 
-fn normalize(name: &str) -> String {
+pub(crate) fn normalize(name: &str) -> String {
     name.trim()
         .to_lowercase()
         .replace(['-', '_', '/'], " ")

crates/core/src/service.rs

@@ -4,6 +4,8 @@ mod recall;
 mod reflect_op;
 mod stats;
 mod store;
+mod taxonomy;
+mod timeline;
 
 use std::collections::HashMap;
 use std::sync::Arc;

crates/core/src/service/recall.rs

@@ -22,7 +22,9 @@ impl MemoryService {
             .limit
             .unwrap_or(DEFAULT_RECALL_LIMIT)
             .min(MAX_RECALL_LIMIT);
-        let candidate_pool_size = if req.include_stale == Some(false) {
+        // Widen when post-fetch filters will drop rows below `limit`.
+        let needs_wider_pool = req.include_stale == Some(false) || req.as_of.is_some();
+        let candidate_pool_size = if needs_wider_pool {
             limit.max(MIN_RERANK_POOL_SIZE) * 2
         } else {
             limit.max(MIN_RERANK_POOL_SIZE)
@@ -51,6 +53,7 @@ impl MemoryService {
             tr.end.map(|e| e.timestamp()).hash(&mut h);
             h.finish()
         });
+        let as_of_nanos = req.as_of.and_then(|t| t.timestamp_nanos_opt());
         let cache_key = cache::ResultCacheKey::new(&cache::ResultCacheKeyInput {
             embedding: &embedding,
             types: type_strs.as_deref(),
@@ -60,6 +63,7 @@ impl MemoryService {
             include_stale: req.include_stale,
             include_invalidated: req.include_invalidated,
             time_range_hash: time_hash,
+            as_of_nanos,
             explain: req.explain,
         });
 
@@ -91,9 +95,23 @@ impl MemoryService {
         let ids: Vec<String> = results.iter().map(|(id, _)| id.clone()).collect();
         let memories = self.metadata_store.get_memories_by_ids(&ids).await?;
 
+        let as_of = req.as_of;
+        let include_invalidated = req.include_invalidated.unwrap_or(false);
         let memory_map: HashMap<&str, &ferrex_store::Memory> = memories
             .iter()
-            .filter(|m| req.include_invalidated.unwrap_or(false) || m.t_invalid.is_none())
+            .filter(|m| {
+                let Some(as_of) = as_of else {
+                    return include_invalidated || m.t_invalid.is_none();
+                };
+                let effective_start = m.t_valid.unwrap_or(m.created_at);
+                if effective_start > as_of {
+                    return false;
+                }
+                if include_invalidated {
+                    return true;
+                }
+                m.t_invalid.is_none_or(|ti| ti > as_of)
+            })
             .map(|m| (m.id.as_str(), m))
             .collect();
 

crates/core/src/service/taxonomy.rs

@@ -0,0 +1,65 @@
+use ferrex_store::MetadataStore;
+
+use super::MemoryService;
+use crate::error::CoreError;
+use crate::types::{
+    TaxonomyEntityEntry, TaxonomyPredicateEntry, TaxonomyRequest, TaxonomyResponse,
+};
+
+const DEFAULT_TAXONOMY_LIMIT: usize = 10;
+const MAX_TAXONOMY_LIMIT: usize = 100;
+
+impl MemoryService {
+    #[tracing::instrument(name = "taxonomy", skip_all, fields(namespace))]
+    pub async fn taxonomy(&self, req: TaxonomyRequest) -> Result<TaxonomyResponse, CoreError> {
+        let scope_given = req.namespace.is_some();
+        let namespace = req
+            .namespace
+            .unwrap_or_else(|| self.config.namespace.clone());
+        tracing::Span::current().record("namespace", namespace.as_str());
+
+        let limit = req
+            .limit
+            .unwrap_or(DEFAULT_TAXONOMY_LIMIT)
+            .min(MAX_TAXONOMY_LIMIT);
+        #[allow(clippy::cast_possible_wrap)]
+        let limit_i64 = limit as i64;
+
+        // Four reads, four reader-pool slots.
+        let by_type_fut = self.metadata_store.memory_count_by_type(&namespace);
+        let top_entities_fut = self.metadata_store.top_entities(&namespace, limit_i64);
+        let top_predicates_fut = self.metadata_store.top_predicates(&namespace, limit_i64);
+        let all_namespaces_fut = async {
+            if scope_given {
+                Ok(None)
+            } else {
+                self.metadata_store.list_namespaces().await.map(Some)
+            }
+        };
+        let (by_type, top_entities_raw, top_predicates_raw, all_namespaces) = tokio::try_join!(
+            by_type_fut,
+            top_entities_fut,
+            top_predicates_fut,
+            all_namespaces_fut,
+        )?;
+
+        let total_memories: u64 = by_type.values().sum();
+        let top_entities = top_entities_raw
+            .into_iter()
+            .map(|(name, memory_count)| TaxonomyEntityEntry { name, memory_count })
+            .collect();
+        let top_predicates = top_predicates_raw
+            .into_iter()
+            .map(|(predicate, count)| TaxonomyPredicateEntry { predicate, count })
+            .collect();
+
+        Ok(TaxonomyResponse {
+            namespace,
+            total_memories,
+            by_type,
+            top_entities,
+            top_predicates,
+            all_namespaces,
+        })
+    }
+}

crates/core/src/service/timeline.rs

@@ -0,0 +1,61 @@
+use ferrex_store::MetadataStore;
+
+use super::{DEFAULT_RECALL_LIMIT, MAX_RECALL_LIMIT, MemoryService};
+use crate::entity::normalize;
+use crate::error::CoreError;
+use crate::types::{TimelineEntry, TimelineRequest, TimelineResponse};
+
+impl MemoryService {
+    #[tracing::instrument(name = "timeline", skip_all, fields(entity = %req.entity, namespace))]
+    pub async fn timeline(&self, req: TimelineRequest) -> Result<TimelineResponse, CoreError> {
+        let namespace = req
+            .namespace
+            .unwrap_or_else(|| self.config.namespace.clone());
+        tracing::Span::current().record("namespace", namespace.as_str());
+
+        let normalized = normalize(&req.entity);
+        if normalized.is_empty() {
+            return Err(CoreError::Validation("empty entity name".into()));
+        }
+
+        let limit = req
+            .limit
+            .unwrap_or(DEFAULT_RECALL_LIMIT)
+            .min(MAX_RECALL_LIMIT);
+        let include_invalidated = req.include_invalidated.unwrap_or(false);
+
+        let Some(entity) = self.metadata_store.get_entity_by_name(&normalized).await? else {
+            return Ok(TimelineResponse {
+                entity: req.entity,
+                resolved_entity_id: None,
+                entries: vec![],
+            });
+        };
+
+        #[allow(clippy::cast_possible_wrap)]
+        let memories = self
+            .metadata_store
+            .timeline_by_entity(
+                &entity.id,
+                &namespace,
+                limit as i64,
+                include_invalidated,
+                req.types.as_deref(),
+            )
+            .await?;
+
+        let entries = memories
+            .into_iter()
+            .map(|m| TimelineEntry {
+                occurred_at: m.t_valid.unwrap_or(m.created_at),
+                memory: m,
+            })
+            .collect();
+
+        Ok(TimelineResponse {
+            entity: req.entity,
+            resolved_entity_id: Some(entity.id),
+            entries,
+        })
+    }
+}

crates/core/src/types.rs

@@ -119,6 +119,14 @@ pub struct RecallRequest {
     pub include_stale: Option<bool>,
     pub include_invalidated: Option<bool>,
     pub time_range: Option<TimeRange>,
+    /// Point-in-time filter. Keeps rows whose validity window (`t_valid` or
+    /// `created_at` through `t_invalid`) covered this instant.
+    /// `include_invalidated = true` drops the end check.
+    ///
+    /// Scoring and `include_stale` still use the current clock, so a row that
+    /// was fresh at `as_of` but is stale today still gets dropped. `as_of`
+    /// asks "what did we know at T", it does not replay the whole pipeline at T.
+    pub as_of: Option<DateTime<Utc>>,
     pub validate_ids: Option<Vec<String>>,
     pub explain: bool,
 }
@@ -151,6 +159,58 @@ pub struct StatsRequest {
     pub diagnostics: Option<bool>,
 }
 
+#[derive(Debug)]
+pub struct TimelineRequest {
+    pub entity: String,
+    pub namespace: Option<String>,
+    pub limit: Option<usize>,
+    pub types: Option<Vec<MemoryType>>,
+    pub include_invalidated: Option<bool>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct TimelineEntry {
+    pub memory: Memory,
+    pub occurred_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct TimelineResponse {
+    pub entity: String,
+    pub resolved_entity_id: Option<String>,
+    pub entries: Vec<TimelineEntry>,
+}
+
+#[derive(Debug)]
+pub struct TaxonomyRequest {
+    pub namespace: Option<String>,
+    pub limit: Option<usize>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct TaxonomyEntityEntry {
+    pub name: String,
+    pub memory_count: u64,
+}
+
+#[derive(Debug, Serialize)]
+pub struct TaxonomyPredicateEntry {
+    pub predicate: String,
+    pub count: u64,
+}
+
+#[derive(Debug, Serialize)]
+pub struct TaxonomyResponse {
+    pub namespace: String,
+    pub total_memories: u64,
+    pub by_type: HashMap<MemoryType, u64>,
+    pub top_entities: Vec<TaxonomyEntityEntry>,
+    pub top_predicates: Vec<TaxonomyPredicateEntry>,
+    /// Distinct namespaces with live memories. `None` when the request was scoped.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub all_namespaces: Option<Vec<String>>,
+}
+
 #[derive(Debug, Serialize)]
 pub struct StoreResponse {
     pub id: String,

crates/core/tests/common/mod.rs

@@ -110,6 +110,7 @@ pub fn recall_query(query: &str) -> RecallRequest {
         include_stale: None,
         include_invalidated: None,
         time_range: None,
+        as_of: None,
         validate_ids: None,
         explain: false,
     }

crates/core/tests/diagnostics.rs

@@ -25,6 +25,7 @@ async fn diagnostics_returns_nonzero_after_operations() {
         include_stale: None,
         include_invalidated: None,
         time_range: None,
+        as_of: None,
         validate_ids: None,
         explain: false,
     })

crates/core/tests/golden_set.rs

@@ -296,6 +296,7 @@ async fn test_golden_set_recall_at_3() {
             include_stale: None,
             include_invalidated: None,
             time_range: None,
+            as_of: None,
             validate_ids: None,
             explain: false,
         };
@@ -370,6 +371,7 @@ async fn test_golden_set_cache_returns_identical_results() {
             include_stale: None,
             include_invalidated: None,
             time_range: None,
+            as_of: None,
             validate_ids: None,
             explain: false,
         };
@@ -389,6 +391,7 @@ async fn test_golden_set_cache_returns_identical_results() {
             include_stale: None,
             include_invalidated: None,
             time_range: None,
+            as_of: None,
             validate_ids: None,
             explain: false,
         };