feat: add metadata filters for context retrieval

README.md

@@ -58,11 +58,47 @@ ctx.add(
     "user",
     "Where should I travel in spring?",
     external_id="conversation-2026-03-01#turn-1",
+    metadata={
+        "tenant": "example-org",
+        "scope": "travel-planning",
+        "source_uri": "chat://conversation-2026-03-01",
+        "tags": ["travel", "preference"],
+    },
 )
 print(ctx.get(external_id="conversation-2026-03-01#turn-1"))
 ctx.delete(external_id="conversation-2026-03-01#turn-1")
 assert ctx.get(external_id="conversation-2026-03-01#turn-1") is None
 
+# Scoped recall and provenance-oriented metadata
+runbook_embedding = [0.0] * 1536
+ctx.add(
+    "assistant",
+    "The runbook owner is the platform team.",
+    embedding=runbook_embedding,
+    bot_id="support-bot",
+    session_id="incident-123",
+    metadata={
+        "tenant": "example-org",
+        "scope": "team",
+        "source_uri": "docs://runbooks/service-a",
+        "tags": ["runbook", "ownership"],
+        "confidence": 0.92,
+    },
+)
+records = ctx.list(
+    filters={
+        "bot_id": "support-bot",
+        "session_id": "incident-123",
+        "scope": "team",
+        "tags": {"contains": "runbook"},
+    }
+)
+hits = ctx.search(
+    runbook_embedding,
+    limit=10,
+    filters={"tenant": "example-org", "content_type": "text/plain"},
+)
+
 from PIL import Image
 image = Image.new("RGB", (2, 2), color="teal")
 ctx.add("assistant", image)
@@ -178,6 +214,7 @@ let record = ContextRecord {
         tokens_used: None,
         custom: None,
     }),
+    metadata: None,
     content_type: "text/plain".into(),
     text_payload: Some("hello world".into()),
     binary_payload: None,

crates/lance-context-core/Cargo.toml

@@ -21,6 +21,7 @@ lance-namespace = "7.0.0"
 lancedb = "0.30.0"
 lance-graph = "0.5.4"
 serde = { version = "1", features = ["derive"] }
+serde_json = "1"
 futures = "0.3"
 tokio = { version = "1", features = ["sync", "time"] }
 tracing = "0.1"

crates/lance-context-core/src/lib.rs

@@ -1,12 +1,13 @@
 //! Core types for the lance-context storage layer.
+#![recursion_limit = "256"]
 
 mod context;
 mod record;
 pub mod serde;
 mod store;
 
 pub use context::{Context, ContextEntry, Snapshot};
-pub use record::{ContextRecord, SearchResult, StateMetadata};
+pub use record::{ContextRecord, MetadataFilter, RecordFilters, SearchResult, StateMetadata};
 pub use store::{
     CompactionConfig, CompactionStats, ContextStore, ContextStoreOptions, IdIndexType,
 };

crates/lance-context-core/src/record.rs

@@ -1,4 +1,6 @@
 use chrono::{DateTime, Utc};
+use serde_json::Value;
+use std::collections::HashMap;
 
 use crate::serde::CONTENT_TYPE_TOMBSTONE;
 
@@ -22,6 +24,7 @@ pub struct ContextRecord {
     pub created_at: DateTime<Utc>,
     pub role: String,
     pub state_metadata: Option<StateMetadata>,
+    pub metadata: Option<Value>,
     pub content_type: String,
     pub text_payload: Option<String>,
     pub binary_payload: Option<Vec<u8>>,
@@ -41,3 +44,154 @@ pub struct SearchResult {
     pub record: ContextRecord,
     pub distance: f32,
 }
+
+/// Metadata matching operation for filtered retrieval.
+#[derive(Debug, Clone, PartialEq)]
+pub enum MetadataFilter {
+    Equals(Value),
+    Contains(Value),
+}
+
+/// Filters applied to records before list pagination or search ranking.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct RecordFilters {
+    pub bot_id: Option<String>,
+    pub session_id: Option<String>,
+    pub role: Option<String>,
+    pub content_type: Option<String>,
+    pub created_at_start: Option<DateTime<Utc>>,
+    pub created_at_end: Option<DateTime<Utc>>,
+    pub metadata: HashMap<String, MetadataFilter>,
+}
+
+impl RecordFilters {
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.bot_id.is_none()
+            && self.session_id.is_none()
+            && self.role.is_none()
+            && self.content_type.is_none()
+            && self.created_at_start.is_none()
+            && self.created_at_end.is_none()
+            && self.metadata.is_empty()
+    }
+
+    #[must_use]
+    pub fn matches(&self, record: &ContextRecord) -> bool {
+        if self
+            .bot_id
+            .as_deref()
+            .is_some_and(|value| record.bot_id.as_deref() != Some(value))
+        {
+            return false;
+        }
+        if self
+            .session_id
+            .as_deref()
+            .is_some_and(|value| record.session_id.as_deref() != Some(value))
+        {
+            return false;
+        }
+        if self
+            .role
+            .as_deref()
+            .is_some_and(|value| record.role != value)
+        {
+            return false;
+        }
+        if self
+            .content_type
+            .as_deref()
+            .is_some_and(|value| record.content_type != value)
+        {
+            return false;
+        }
+        if self
+            .created_at_start
+            .is_some_and(|start| record.created_at < start)
+        {
+            return false;
+        }
+        if self
+            .created_at_end
+            .is_some_and(|end| record.created_at > end)
+        {
+            return false;
+        }
+
+        self.metadata.iter().all(|(key, filter)| {
+            let Some(Value::Object(metadata)) = &record.metadata else {
+                return false;
+            };
+            let Some(value) = metadata.get(key) else {
+                return false;
+            };
+            match filter {
+                MetadataFilter::Equals(expected) => value == expected,
+                MetadataFilter::Contains(expected) => metadata_contains(value, expected),
+            }
+        })
+    }
+}
+
+fn metadata_contains(value: &Value, expected: &Value) -> bool {
+    match (value, expected) {
+        (Value::Array(items), expected) => items.iter().any(|item| item == expected),
+        (Value::String(value), Value::String(expected)) => value.contains(expected),
+        _ => false,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use chrono::TimeZone;
+    use serde_json::json;
+
+    fn record() -> ContextRecord {
+        ContextRecord {
+            id: "rec-1".to_string(),
+            external_id: None,
+            run_id: "run-1".to_string(),
+            bot_id: Some("support-bot".to_string()),
+            session_id: Some("incident-1".to_string()),
+            created_at: Utc.with_ymd_and_hms(2026, 6, 9, 3, 0, 0).unwrap(),
+            role: "assistant".to_string(),
+            state_metadata: None,
+            metadata: Some(json!({
+                "scope": "team",
+                "tags": ["runbook", "ownership"],
+                "confidence": 0.92
+            })),
+            content_type: "text/plain".to_string(),
+            text_payload: Some("hello".to_string()),
+            binary_payload: None,
+            embedding: None,
+        }
+    }
+
+    #[test]
+    fn filters_match_builtin_fields_timestamps_and_metadata() {
+        let mut filters = RecordFilters {
+            bot_id: Some("support-bot".to_string()),
+            session_id: Some("incident-1".to_string()),
+            role: Some("assistant".to_string()),
+            content_type: Some("text/plain".to_string()),
+            created_at_start: Some(Utc.with_ymd_and_hms(2026, 6, 9, 2, 0, 0).unwrap()),
+            created_at_end: Some(Utc.with_ymd_and_hms(2026, 6, 9, 4, 0, 0).unwrap()),
+            metadata: HashMap::new(),
+        };
+        filters
+            .metadata
+            .insert("scope".to_string(), MetadataFilter::Equals(json!("team")));
+        filters.metadata.insert(
+            "tags".to_string(),
+            MetadataFilter::Contains(json!("runbook")),
+        );
+
+        assert!(filters.matches(&record()));
+
+        filters.session_id = Some("other".to_string());
+        assert!(!filters.matches(&record()));
+    }
+}