feat(tags): support tagged write and filesystem filtering

Add first-upsert tags for content writes, AND filtering and projection for ls/tree/grep, and unified --tags CLI plus Python, Go, and TypeScript SDK support. Preserve URI-scoped ingestion options across semantic and memory paths, including replace, append, and explicit empty-tag handling.

Co-authored-by: TRAE CLI <noreply@bytedance.com>
Co-authored-by: TRAE CLI <traecli@bytedance.com>

Author: 3 people

crates/ov_cli/src/client.rs

@@ -412,8 +412,19 @@ impl HttpClient {
         wait: bool,
         timeout: Option<f64>,
         processing_mode: &str,
+        tags: Vec<String>,
+        tag_mode: &str,
     ) -> Result<serde_json::Value> {
-        let body = Self::build_write_body(uri, content, mode, wait, timeout, processing_mode);
+        let body = Self::build_write_body(
+            uri,
+            content,
+            mode,
+            wait,
+            timeout,
+            processing_mode,
+            tags,
+            tag_mode,
+        );
         self.post("/api/v1/content/write", &body).await
     }
 
@@ -474,6 +485,8 @@ impl HttpClient {
         wait: bool,
         timeout: Option<f64>,
         processing_mode: &str,
+        tags: Vec<String>,
+        tag_mode: &str,
     ) -> Value {
         let mut body = serde_json::json!({
             "uri": uri,
@@ -483,6 +496,13 @@ impl HttpClient {
             "timeout": timeout,
             "processing_mode": processing_mode,
         });
+        if !tags.is_empty() {
+            let obj = body
+                .as_object_mut()
+                .expect("write request body must be an object");
+            obj.insert("tags".to_string(), serde_json::json!(tags));
+            obj.insert("tag_mode".to_string(), serde_json::json!(tag_mode));
+        }
         compact_request_body(&mut body);
         body
     }
@@ -584,8 +604,9 @@ impl HttpClient {
         abs_limit: i32,
         show_all_hidden: bool,
         node_limit: i32,
+        tags: &[String],
     ) -> Result<serde_json::Value> {
-        let params = vec![
+        let mut params = vec![
             ("uri".to_string(), uri.to_string()),
             ("simple".to_string(), simple.to_string()),
             ("recursive".to_string(), recursive.to_string()),
@@ -594,6 +615,9 @@ impl HttpClient {
             ("show_all_hidden".to_string(), show_all_hidden.to_string()),
             ("node_limit".to_string(), node_limit.to_string()),
         ];
+        for tag in tags {
+            params.push(("tags".to_string(), tag.clone()));
+        }
         self.get("/api/v1/fs/ls", &params).await
     }
 
@@ -605,15 +629,19 @@ impl HttpClient {
         show_all_hidden: bool,
         node_limit: i32,
         level_limit: i32,
+        tags: &[String],
     ) -> Result<serde_json::Value> {
-        let params = vec![
+        let mut params = vec![
             ("uri".to_string(), uri.to_string()),
             ("output".to_string(), output.to_string()),
             ("abs_limit".to_string(), abs_limit.to_string()),
             ("show_all_hidden".to_string(), show_all_hidden.to_string()),
             ("node_limit".to_string(), node_limit.to_string()),
             ("level_limit".to_string(), level_limit.to_string()),
         ];
+        for tag in tags {
+            params.push(("tags".to_string(), tag.clone()));
+        }
         self.get("/api/v1/fs/tree", &params).await
     }
 
@@ -741,6 +769,7 @@ impl HttpClient {
         ignore_case: bool,
         node_limit: i32,
         level_limit: i32,
+        tags: &[String],
     ) -> Result<serde_json::Value> {
         let body = serde_json::json!({
             "uri": uri,
@@ -749,6 +778,7 @@ impl HttpClient {
             "case_insensitive": ignore_case,
             "node_limit": node_limit,
             "level_limit": level_limit,
+            "tags": (!tags.is_empty()).then(|| tags),
         });
         self.post("/api/v1/search/grep", &body).await
     }
@@ -2196,6 +2226,8 @@ mod tests {
             true,
             Some(3.0),
             "semantic_and_vectors",
+            vec![],
+            "replace",
         );
 
         assert_eq!(
@@ -2221,6 +2253,8 @@ mod tests {
             true,
             None,
             "semantic_and_vectors",
+            vec![],
+            "replace",
         );
 
         assert!(body.get("processing_mode").is_none());
@@ -2235,6 +2269,8 @@ mod tests {
             true,
             None,
             "vectors_only",
+            vec![],
+            "replace",
         );
 
         assert_eq!(body["processing_mode"], "vectors_only");
@@ -2246,7 +2282,16 @@ mod tests {
         let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
 
         client
-            .ls("viking://resources", false, false, "agent", 256, false, 1)
+            .ls(
+                "viking://resources",
+                false,
+                false,
+                "agent",
+                256,
+                false,
+                1,
+                &[],
+            )
             .await
             .expect("ls request should succeed");
 
@@ -2372,7 +2417,7 @@ mod tests {
         let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
 
         client
-            .tree("viking://resources", "agent", 256, false, 1, 3)
+            .tree("viking://resources", "agent", 256, false, 1, 3, &[])
             .await
             .expect("tree request should succeed");
 

crates/ov_cli/src/commands/content.rs

@@ -44,11 +44,22 @@ pub async fn write(
     wait: bool,
     timeout: Option<f64>,
     processing_mode: &str,
+    tags: Vec<String>,
+    tag_mode: &str,
     output_format: OutputFormat,
     compact: bool,
 ) -> Result<()> {
     let result = client
-        .write(uri, content, mode, wait, timeout, processing_mode)
+        .write(
+            uri,
+            content,
+            mode,
+            wait,
+            timeout,
+            processing_mode,
+            tags,
+            tag_mode,
+        )
         .await?;
     crate::output::output_success(result, output_format, compact);
     Ok(())

crates/ov_cli/src/commands/filesystem.rs

@@ -26,6 +26,8 @@ pub async fn ls(
     abs_limit: i32,
     show_all_hidden: bool,
     node_limit: i32,
+    tags: &[String],
+    show_tags: bool,
     output_format: OutputFormat,
     compact: bool,
 ) -> Result<()> {
@@ -38,9 +40,10 @@ pub async fn ls(
             abs_limit,
             show_all_hidden,
             node_limit,
+            tags,
         )
         .await?;
-    output_filesystem_entries(&result, output_format, compact, false);
+    output_filesystem_entries(&result, output_format, compact, false, show_tags);
     Ok(())
 }
 
@@ -52,6 +55,7 @@ pub async fn tree(
     show_all_hidden: bool,
     node_limit: i32,
     level_limit: i32,
+    tags: &[String],
     output_format: OutputFormat,
     compact: bool,
 ) -> Result<()> {
@@ -63,9 +67,10 @@ pub async fn tree(
             show_all_hidden,
             node_limit,
             level_limit,
+            tags,
         )
         .await?;
-    output_filesystem_entries(&result, output_format, compact, true);
+    output_filesystem_entries(&result, output_format, compact, true, false);
     Ok(())
 }
 
@@ -74,8 +79,11 @@ fn output_filesystem_entries(
     output_format: OutputFormat,
     compact: bool,
     is_tree: bool,
+    show_tags: bool,
 ) {
-    if let Some(rendered) = render_filesystem_entries_for_table(result, output_format, is_tree) {
+    if let Some(rendered) =
+        render_filesystem_entries_for_table(result, output_format, is_tree, show_tags)
+    {
         println!("{rendered}");
     } else {
         output_success(result, output_format, compact);
@@ -86,18 +94,24 @@ fn render_filesystem_entries_for_table(
     value: &Value,
     output_format: OutputFormat,
     is_tree: bool,
+    show_tags: bool,
 ) -> Option<String> {
     if matches!(output_format, OutputFormat::Json) {
         return None;
     }
     if is_tree {
         render_tree_entries_for_table(value)
     } else {
-        render_ls_entries_for_table(value)
+        render_ls_entries_for_table_with_tags(value, show_tags)
     }
 }
 
+#[cfg(test)]
 fn render_ls_entries_for_table(value: &Value) -> Option<String> {
+    render_ls_entries_for_table_with_tags(value, false)
+}
+
+fn render_ls_entries_for_table_with_tags(value: &Value, show_tags: bool) -> Option<String> {
     let (entries, profile) = filesystem_entries(value)?;
     let mut lines = Vec::new();
     let text_width = entry_text_width();
@@ -112,7 +126,7 @@ fn render_ls_entries_for_table(value: &Value) -> Option<String> {
         if index > 0 {
             lines.push(String::new());
         }
-        render_ls_entry(index + 1, entry, text_width, &mut lines);
+        render_ls_entry(index + 1, entry, text_width, show_tags, &mut lines);
     }
 
     append_profile_lines(profile, &mut lines);
@@ -155,7 +169,13 @@ fn filesystem_entries(value: &Value) -> Option<(Vec<&Value>, Option<&Value>)> {
     Some((entries.iter().collect(), profile))
 }
 
-fn render_ls_entry(rank: usize, entry: &Value, text_width: usize, lines: &mut Vec<String>) {
+fn render_ls_entry(
+    rank: usize,
+    entry: &Value,
+    text_width: usize,
+    show_tags: bool,
+    lines: &mut Vec<String>,
+) {
     let object = entry.as_object();
     let metadata = entry_metadata(object);
     lines.push(format!(
@@ -171,6 +191,24 @@ fn render_ls_entry(rank: usize, entry: &Value, text_width: usize, lines: &mut Ve
     }
 
     append_entry_abstract(object, ENTRY_INDENT, text_width, lines);
+    if show_tags {
+        let tags = object
+            .and_then(|object| object.get("tags"))
+            .and_then(Value::as_array)
+            .map(|items| {
+                items
+                    .iter()
+                    .filter_map(Value::as_str)
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            })
+            .filter(|tags| !tags.is_empty())
+            .unwrap_or_else(|| "-".to_string());
+        lines.push(format!(
+            "{ENTRY_INDENT}{}",
+            theme::muted(format!("tags: {tags}"))
+        ));
+    }
 }
 
 fn render_tree_entry(rank: usize, entry: &Value, text_width: usize, lines: &mut Vec<String>) {
@@ -497,7 +535,7 @@ fn output_message_result(
 mod tests {
     use super::{
         render_filesystem_entries_for_table, render_ls_entries_for_table,
-        render_tree_entries_for_table,
+        render_ls_entries_for_table_with_tags, render_tree_entries_for_table,
     };
     use crate::output::render_profiled_scalar_result;
     use serde_json::json;
@@ -681,11 +719,30 @@ mod tests {
         ]);
 
         assert!(
-            render_filesystem_entries_for_table(&result, crate::output::OutputFormat::Json, false)
-                .is_none()
+            render_filesystem_entries_for_table(
+                &result,
+                crate::output::OutputFormat::Json,
+                false,
+                false,
+            )
+            .is_none()
         );
     }
 
+    #[test]
+    fn ls_table_output_shows_requested_tags() {
+        let result = json!([
+            {"uri": "viking://resources/a.md", "isDir": false, "tags": ["env=prod", "team=search"]},
+            {"uri": "viking://resources/b.md", "isDir": false, "tags": []}
+        ]);
+
+        let rendered =
+            strip_ansi(&render_ls_entries_for_table_with_tags(&result, true).expect("ls"));
+
+        assert!(rendered.contains("tags: env=prod, team=search"));
+        assert!(rendered.contains("tags: -"));
+    }
+
     fn strip_ansi(input: &str) -> String {
         let mut output = String::with_capacity(input.len());
         let mut chars = input.chars().peekable();

crates/ov_cli/src/commands/search.rs

@@ -637,6 +637,7 @@ pub async fn grep(
     ignore_case: bool,
     node_limit: i32,
     level_limit: i32,
+    tags: &[String],
     output_format: OutputFormat,
     compact: bool,
 ) -> Result<()> {
@@ -648,6 +649,7 @@ pub async fn grep(
             ignore_case,
             node_limit,
             level_limit,
+            tags,
         )
         .await?;
     output_grep_results(&result, output_format, compact);
@@ -833,7 +835,10 @@ mod tests {
 
         assert!(rendered.contains("Deployment summary."));
         for line in ["# Deploy", "Step one.", "Step two.", "Step three."] {
-            assert!(rendered.contains(line), "missing inlined content line: {line}");
+            assert!(
+                rendered.contains(line),
+                "missing inlined content line: {line}"
+            );
         }
     }