fix(cli): hindsight memory retain --timestamp + correct fact-type values (#1881)

Two unrelated CLI bugs surfaced during sandbox testing on 2026-05-31.

1) `hindsight memory retain --timestamp <ISO 8601>` never worked.

   `MemoryItem.timestamp` is generated from the OpenAPI schema
   `anyOf: [{type: string, format: date-time}, {type: string}]`. Progenitor
   emits that as a struct with two `#[serde(flatten)]` Option subtypes —
   which serde refuses to serialize for primitives:

     "can only flatten structs and maps (got a string)"

   So even constructing the value manually fails at serialize time, before
   the request hits the wire. The CLI's `serde_json::from_value::<…>(String)`
   round-trip also fails (struct deserializer expects an object).

   Fixed at the codegen boundary by adding a pre-codegen spec-massage step
   `collapse_string_anyof_unions` in hindsight-clients/rust/build.rs that
   collapses any `anyOf` whose members are all `{type: string}` into a
   single `{type: string}`. The `format: date-time` distinction is lossless
   on the wire — both serialize to the same string — so this is safe.
   Result: `MemoryItem.timestamp: Option<String>`, no broken type generated.

   The CLI no longer needs to round-trip through a wrapper type; the user
   string is passed through directly.

2) `hindsight memory clear --fact-type` rejected the valid value
   `observation` and accepted stale values `agent` / `opinion` that the
   server silently treats as no-ops.

   Help text on `bank graph`, `memory list`, `memory recall`, and
   `memory clear` referred to a non-existent fact type `opinion`. The
   canonical fact types per the API are `world | experience | observation`
   (see hindsight_api.api.http.MemoryItem and the `Literal[…]` arm on
   fact_types in recall/reflect requests).

   Fixed: `opinion` → `observation` everywhere in CLI help / clap defaults,
   and `agent`/`opinion` → `experience`/`observation` in the clear
   command's value_parser allow-list.

Regression test:
  hindsight-cli/tests/integration_test.rs::
    test_memory_item_timestamp_serializes_as_plain_string

Verified:
  - cargo build → clean
  - cargo test --bin hindsight → 55/55 pass
  - cargo test --test integration_test test_memory_item_timestamp_… → pass
  - cargo clippy → no new warnings (171 pre-existing uninlined_format_args)
  - hindsight memory clear --help → [possible values: world, experience, observation]
  - hindsight memory recall --help → [default: world experience observation]
  - hindsight bank graph --help → (world, experience, observation)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: slayoffer

hindsight-cli/src/api.rs

@@ -1266,8 +1266,8 @@ impl ApiClient {
 
 // Re-export types from the generated client for use in commands
 pub use types::{
-    BankProfileResponse, MemoryItem, MemoryItemTimestamp, RecallRequest, RecallResponse,
-    RecallResult, ReflectRequest, ReflectResponse, RetainRequest,
+    BankProfileResponse, MemoryItem, RecallRequest, RecallResponse, RecallResult, ReflectRequest,
+    ReflectResponse, RetainRequest,
 };
 
 #[cfg(test)]

hindsight-cli/src/commands/memory.rs

@@ -3,9 +3,7 @@ use std::fs;
 use std::path::PathBuf;
 use walkdir::WalkDir;
 
-use crate::api::{
-    ApiClient, MemoryItem, MemoryItemTimestamp, RecallRequest, ReflectRequest, RetainRequest,
-};
+use crate::api::{ApiClient, MemoryItem, RecallRequest, ReflectRequest, RetainRequest};
 use crate::config;
 use crate::output::{self, OutputFormat};
 use crate::ui;
@@ -454,15 +452,6 @@ pub fn retain(
         None
     };
 
-    // MemoryItem.timestamp is a progenitor anyOf enum; round-trip through JSON to pick the matching variant.
-    let timestamp = match timestamp {
-        Some(s) => Some(
-            serde_json::from_value::<MemoryItemTimestamp>(serde_json::Value::String(s.clone()))
-                .with_context(|| format!("invalid --timestamp value: {:?}", s))?,
-        ),
-        None => None,
-    };
-
     let item = MemoryItem {
         content: content.clone(),
         context,

hindsight-cli/src/main.rs

@@ -287,7 +287,7 @@ enum BankCommands {
         /// Bank ID
         bank_id: String,
 
-        /// Filter by fact type (world, experience, opinion)
+        /// Filter by fact type (world, experience, observation)
         #[arg(short = 't', long)]
         fact_type: Option<String>,
 
@@ -455,7 +455,7 @@ enum MemoryCommands {
         /// Bank ID
         bank_id: String,
 
-        /// Filter by fact type (world, experience, opinion)
+        /// Filter by fact type (world, experience, observation)
         #[arg(short = 't', long)]
         fact_type: Option<String>,
 
@@ -489,8 +489,8 @@ enum MemoryCommands {
         /// Search query
         query: String,
 
-        /// Fact types to search (world, experience, opinion)
-        #[arg(short = 't', long, value_delimiter = ',', default_values = &["world", "experience", "opinion"])]
+        /// Fact types to search (world, experience, observation)
+        #[arg(short = 't', long, value_delimiter = ',', default_values = &["world", "experience", "observation"])]
         fact_type: Vec<String>,
 
         /// Thinking budget (low, mid, high)
@@ -645,8 +645,8 @@ enum MemoryCommands {
         /// Bank ID
         bank_id: String,
 
-        /// Fact type to clear (world, agent, opinion). If not specified, clears all types.
-        #[arg(short = 't', long, value_parser = ["world", "agent", "opinion"])]
+        /// Fact type to clear (world, experience, observation). If not specified, clears all types.
+        #[arg(short = 't', long, value_parser = ["world", "experience", "observation"])]
         fact_type: Option<String>,
 
         /// Skip confirmation prompt

hindsight-cli/tests/integration_test.rs

@@ -91,6 +91,35 @@ fn test_ui_command_with_config() {
     std::fs::remove_dir_all(&temp_dir).ok();
 }
 
+#[test]
+fn test_memory_item_timestamp_serializes_as_plain_string() {
+    // Regression: progenitor used to emit `MemoryItemTimestamp` as a struct
+    // with two `#[serde(flatten)]` Option subtypes from the `anyOf:[datetime,
+    // string]` schema. Serializing that errored with
+    //   "can only flatten structs and maps (got a string)"
+    // — so `hindsight memory retain --timestamp` never worked. The build.rs
+    // spec-massage step now collapses string-only anyOf unions into a plain
+    // `{type: string}`, so the field is just `Option<String>`. Assert that.
+    let item = hindsight_client::types::MemoryItem {
+        content: "Bob went hiking yesterday".to_string(),
+        context: None,
+        metadata: None,
+        timestamp: Some("2026-05-31T10:00:00Z".to_string()),
+        document_id: Some("doc-1".to_string()),
+        entities: None,
+        tags: None,
+        observation_scopes: None,
+        strategy: None,
+        update_mode: None,
+    };
+    let json = serde_json::to_string(&item).expect("MemoryItem must serialize");
+    assert!(
+        json.contains(r#""timestamp":"2026-05-31T10:00:00Z""#),
+        "expected timestamp at top-level as a plain string, got: {}",
+        json
+    );
+}
+
 #[test]
 fn test_memory_retain_exposes_timestamp_flag() {
     // Regression: `hindsight memory retain` historically had no way to set the

hindsight-clients/rust/build.rs

@@ -43,6 +43,52 @@ fn filter_multipart_endpoints(spec: &mut serde_json::Value) {
     }
 }
 
+/// Collapse `anyOf` whose members are all plain string types into a single
+/// `{"type": "string"}`. Without this, progenitor emits a struct like
+/// `MemoryItemTimestamp { #[serde(flatten)] subtype_0: Option<DateTime>, ... }`
+/// where flatten on a primitive is a runtime error
+/// (`"can only flatten structs and maps (got a string)"`). For client purposes
+/// the `format: date-time` distinction is lossless — the wire value is just a
+/// string either way — so collapsing to a plain string is safe and lets the
+/// generated client actually serialize.
+fn collapse_string_anyof_unions(value: &mut serde_json::Value) {
+    if let serde_json::Value::Object(obj) = value {
+        let all_strings = obj
+            .get("anyOf")
+            .and_then(|v| v.as_array())
+            .map(|arr| {
+                !arr.is_empty()
+                    && arr.iter().all(|v| {
+                        v.as_object()
+                            .and_then(|m| m.get("type"))
+                            .and_then(|t| t.as_str())
+                            .map(|s| s == "string")
+                            .unwrap_or(false)
+                    })
+            })
+            .unwrap_or(false);
+
+        if all_strings {
+            obj.remove("anyOf");
+            obj.insert("type".to_string(), serde_json::json!("string"));
+        }
+    }
+
+    match value {
+        serde_json::Value::Object(obj) => {
+            for (_k, v) in obj.iter_mut() {
+                collapse_string_anyof_unions(v);
+            }
+        }
+        serde_json::Value::Array(arr) => {
+            for v in arr.iter_mut() {
+                collapse_string_anyof_unions(v);
+            }
+        }
+        _ => {}
+    }
+}
+
 fn convert_anyof_to_nullable(value: &mut serde_json::Value) {
     match value {
         serde_json::Value::Object(obj) => {
@@ -132,6 +178,12 @@ fn main() {
         }
     }
 
+    // Collapse anyOf-of-only-strings into a plain string. Must run AFTER the
+    // 3.1→3.0 nullable pass so we see `anyOf: [datetime, string]` without the
+    // null arm. Keeps progenitor from emitting unserializable flatten-of-
+    // primitive structs (see collapse_string_anyof_unions docs).
+    collapse_string_anyof_unions(&mut spec_json);
+
     // Filter out multipart/form-data endpoints (progenitor doesn't support them)
     filter_multipart_endpoints(&mut spec_json);