feat: 4-tab code parity across all documentation examples (#613)

* feat: independent versioning for integrations

- Add per-integration changelog pages at /changelog/integrations/<name>
- Move main changelog to changelog/index.md (URL unchanged)
- Add --integration flag to generate-changelog for LLM-based per-integration changelog generation
- Add scripts/release-integration.sh <name> <version> for cutting integration releases
- Add .github/workflows/release-integration.yml to publish on integrations/** tags
- Remove integrations from main release.sh and release.yml cycle

* fix: add agno and hermes integration docs to version-0.4 for production build

* chore: apply ruff formatting to generate_changelog.py

* feat: add 4-tab code parity across all documentation examples

Every code snippet Tabs block now has Python, Node.js, CLI, and Go variants.
Raw HTTP/curl tabs replaced with proper SDK calls.

New example files:
- Go: retain.go, recall.go, reflect.go, memory-banks.go, directives.go,
  mental-models.go, documents.go, main-methods.go
- Shell: memory-banks.sh, directives.sh, mental-models.sh
- Node.js: mental-models.mjs

Extended example files with missing sections:
- recall.mjs/sh: world/experience/observation types, token-budget, all tag modes
- reflect.sh: reflect-with-params, reflect-disposition, reflect-sources, reflect-with-tags
- reflect.mjs: reflect-with-tags, fixed reflect-sources API usage
- retain.mjs/sh: retain-conversation, retain-batch, retain-files-batch

SDK/CLI additions:
- TypeScript: getMentalModelHistory method
- CLI recall: --tags, --tags-match flags
- CLI reflect: --tags, --tags-match, --include-facts flags
- CLI directive update: --is-active flag
- CLI bank set-config: --retain-mission, --retain-extraction-mode,
  --observations-mission, --reflect-mission, --disposition-* flags

Build validation:
- scripts/check-code-parity.mjs validates 4-tab parity across all MDX files
- Integrated into npm run build — fails if any Tabs block is missing a variant

* fix: fix doc examples for Go, Node.js, CLI + add mental model with-id examples

- Fix Go Budget constants: BUDGET_HIGH/LOW/MID → HIGH/LOW/MID
- Fix Go documents.go: ListDocuments returns []map[string]interface{}, use map access
- Fix Go retain.go: use correct relative path for sample.pdf
- Fix Node.js createMentalModel: use positional args (name, sourceQuery) not object
- Add CLI 'history' subcommand for mental models (api.rs, main.rs, mental_model.rs)
- Rebuild TypeScript/Python clients to support id param in createMentalModel
- Add create-mental-model-with-id examples across all 4 languages and docs

* fix: move id param to end of create_mental_model signature for backwards compat

Author: nicoloboschi

hindsight-cli/src/api.rs

@@ -601,6 +601,13 @@ impl ApiClient {
         })
     }
 
+    pub fn get_mental_model_history(&self, bank_id: &str, mental_model_id: &str, _verbose: bool) -> Result<serde_json::Value> {
+        self.runtime.block_on(async {
+            let response = self.client.get_mental_model_history(bank_id, mental_model_id, None).await?;
+            Ok(response.into_inner())
+        })
+    }
+
     // --- Directive Methods ---
 
     pub fn list_directives(&self, bank_id: &str, _verbose: bool) -> Result<types::DirectiveListResponse> {

hindsight-cli/src/commands/bank.rs

@@ -717,6 +717,13 @@ pub fn set_config(
     llm_model: Option<String>,
     llm_api_key: Option<String>,
     llm_base_url: Option<String>,
+    retain_mission: Option<String>,
+    retain_extraction_mode: Option<String>,
+    observations_mission: Option<String>,
+    reflect_mission: Option<String>,
+    disposition_skepticism: Option<i64>,
+    disposition_literalism: Option<i64>,
+    disposition_empathy: Option<i64>,
     verbose: bool,
     output_format: OutputFormat,
 ) -> Result<()> {
@@ -736,9 +743,30 @@ pub fn set_config(
     if let Some(base_url) = llm_base_url {
         updates.insert("llm_base_url".to_string(), serde_json::Value::String(base_url));
     }
+    if let Some(mission) = retain_mission {
+        updates.insert("retain_mission".to_string(), serde_json::Value::String(mission));
+    }
+    if let Some(mode) = retain_extraction_mode {
+        updates.insert("retain_extraction_mode".to_string(), serde_json::Value::String(mode));
+    }
+    if let Some(mission) = observations_mission {
+        updates.insert("observations_mission".to_string(), serde_json::Value::String(mission));
+    }
+    if let Some(mission) = reflect_mission {
+        updates.insert("reflect_mission".to_string(), serde_json::Value::String(mission));
+    }
+    if let Some(skepticism) = disposition_skepticism {
+        updates.insert("disposition_skepticism".to_string(), serde_json::Value::Number(skepticism.into()));
+    }
+    if let Some(literalism) = disposition_literalism {
+        updates.insert("disposition_literalism".to_string(), serde_json::Value::Number(literalism.into()));
+    }
+    if let Some(empathy) = disposition_empathy {
+        updates.insert("disposition_empathy".to_string(), serde_json::Value::Number(empathy.into()));
+    }
 
     if updates.is_empty() {
-        return Err(anyhow!("No config updates provided. Use --llm-provider, --llm-model, --llm-api-key, or --llm-base-url".to_string()));
+        return Err(anyhow!("No config updates provided. Use --llm-provider, --llm-model, --retain-mission, --observations-mission, or other flags".to_string()));
     }
 
     let spinner = if output_format == OutputFormat::Pretty {

hindsight-cli/src/commands/directive.rs

@@ -149,11 +149,12 @@ pub fn update(
     directive_id: &str,
     name: Option<String>,
     content: Option<String>,
+    is_active: Option<bool>,
     verbose: bool,
     output_format: OutputFormat,
 ) -> Result<()> {
-    if name.is_none() && content.is_none() {
-        anyhow::bail!("At least one of --name or --content must be provided");
+    if name.is_none() && content.is_none() && is_active.is_none() {
+        anyhow::bail!("At least one of --name, --content, or --is-active must be provided");
     }
 
     let spinner = if output_format == OutputFormat::Pretty {
@@ -165,7 +166,7 @@ pub fn update(
     let request = types::UpdateDirectiveRequest {
         name,
         content,
-        is_active: None,
+        is_active,
         priority: None,
         tags: None,
     };

hindsight-cli/src/commands/memory.rs

@@ -9,7 +9,7 @@ use crate::output::{self, OutputFormat};
 use crate::ui;
 
 // Import types from generated client
-use hindsight_client::types::{Budget, ChunkIncludeOptions, IncludeOptions, TagsMatch};
+use hindsight_client::types::{Budget, ChunkIncludeOptions, FactsIncludeOptions, IncludeOptions, ReflectIncludeOptions, TagsMatch};
 use serde::Deserialize;
 use serde_json;
 
@@ -43,6 +43,16 @@ fn parse_budget(budget: &str) -> Budget {
     }
 }
 
+// Helper function to parse tags_match string to TagsMatch enum
+fn parse_tags_match(tags_match: &Option<String>) -> TagsMatch {
+    match tags_match.as_deref().unwrap_or("any").to_lowercase().as_str() {
+        "all" => TagsMatch::All,
+        "any_strict" => TagsMatch::AnyStrict,
+        "all_strict" => TagsMatch::AllStrict,
+        _ => TagsMatch::Any,
+    }
+}
+
 /// List memory units with pagination and optional filters
 pub fn list(
     client: &ApiClient,
@@ -250,6 +260,8 @@ pub fn recall(
     trace: bool,
     include_chunks: bool,
     chunk_max_tokens: i64,
+    tags: Vec<String>,
+    tags_match: Option<String>,
     verbose: bool,
     output_format: OutputFormat,
 ) -> Result<()> {
@@ -280,8 +292,8 @@ pub fn recall(
         trace,
         query_timestamp: None,
         include,
-        tags: None,
-        tags_match: TagsMatch::Any,
+        tags: if tags.is_empty() { None } else { Some(tags) },
+        tags_match: parse_tags_match(&tags_match),
         tag_groups: None,
     };
 
@@ -312,6 +324,9 @@ pub fn reflect(
     context: Option<String>,
     max_tokens: Option<i64>,
     schema_path: Option<PathBuf>,
+    tags: Vec<String>,
+    tags_match: Option<String>,
+    include_facts: bool,
     verbose: bool,
     output_format: OutputFormat,
 ) -> Result<()> {
@@ -332,15 +347,24 @@ pub fn reflect(
         None
     };
 
+    let include = if include_facts {
+        Some(ReflectIncludeOptions {
+            facts: Some(FactsIncludeOptions(serde_json::Map::new())),
+            tool_calls: None,
+        })
+    } else {
+        None
+    };
+
     let request = ReflectRequest {
         query,
         budget: Some(parse_budget(&budget)),
         context,
         max_tokens: max_tokens.unwrap_or(4096),
-        include: None,
+        include,
         response_schema,
-        tags: None,
-        tags_match: TagsMatch::Any,
+        tags: if tags.is_empty() { None } else { Some(tags) },
+        tags_match: parse_tags_match(&tags_match),
         tag_groups: None,
     };
 

hindsight-cli/src/commands/mental_model.rs

@@ -272,6 +272,55 @@ pub fn refresh(
     }
 }
 
+/// Get the change history of a mental model
+pub fn history(
+    client: &ApiClient,
+    bank_id: &str,
+    mental_model_id: &str,
+    verbose: bool,
+    output_format: OutputFormat,
+) -> Result<()> {
+    let spinner = if output_format == OutputFormat::Pretty {
+        Some(ui::create_spinner("Fetching mental model history..."))
+    } else {
+        None
+    };
+
+    let response = client.get_mental_model_history(bank_id, mental_model_id, verbose);
+
+    if let Some(mut sp) = spinner {
+        sp.finish();
+    }
+
+    match response {
+        Ok(history) => {
+            if output_format == OutputFormat::Pretty {
+                ui::print_section_header(&format!("History: {}", mental_model_id));
+
+                if let Some(entries) = history.as_array() {
+                    if entries.is_empty() {
+                        println!("  {}", ui::dim("No history entries found."));
+                    } else {
+                        for entry in entries {
+                            let changed_at = entry.get("changed_at").and_then(|v| v.as_str()).unwrap_or("unknown");
+                            let previous = entry.get("previous_content").and_then(|v| v.as_str()).unwrap_or("(none)");
+                            println!("  {} {}", ui::dim("Changed at:"), changed_at);
+                            let preview: String = previous.chars().take(80).collect();
+                            let ellipsis = if previous.len() > 80 { "..." } else { "" };
+                            println!("  {} {}{}", ui::dim("Previous:"), ui::dim(&preview), ellipsis);
+                            println!();
+                        }
+                    }
+                }
+            } else {
+                output::print_output(&history, output_format)?;
+            }
+            Ok(())
+        }
+        Err(e) => Err(e),
+    }
+}
+
 // Helper function to print mental model details
 fn print_mental_model_detail(mental_model: &types::MentalModelResponse) {
     ui::print_section_header(&mental_model.name);

hindsight-cli/src/main.rs

@@ -310,6 +310,34 @@ enum BankCommands {
         /// LLM base URL override
         #[arg(long)]
         llm_base_url: Option<String>,
+
+        /// Retain mission: what to focus on during fact extraction
+        #[arg(long)]
+        retain_mission: Option<String>,
+
+        /// Retain extraction mode (concise, verbose, custom)
+        #[arg(long)]
+        retain_extraction_mode: Option<String>,
+
+        /// Observations mission: what to synthesize into durable observations
+        #[arg(long)]
+        observations_mission: Option<String>,
+
+        /// Reflect mission: first-person identity for reflect operations
+        #[arg(long)]
+        reflect_mission: Option<String>,
+
+        /// Disposition skepticism trait (1-5)
+        #[arg(long, value_parser = clap::value_parser!(i64).range(1..=5))]
+        disposition_skepticism: Option<i64>,
+
+        /// Disposition literalism trait (1-5)
+        #[arg(long, value_parser = clap::value_parser!(i64).range(1..=5))]
+        disposition_literalism: Option<i64>,
+
+        /// Disposition empathy trait (1-5)
+        #[arg(long, value_parser = clap::value_parser!(i64).range(1..=5))]
+        disposition_empathy: Option<i64>,
     },
 
     /// Reset bank configuration to defaults (remove all overrides)
@@ -387,6 +415,14 @@ enum MemoryCommands {
         /// Maximum tokens for chunks (only used with --include-chunks)
         #[arg(long, default_value = "8192")]
         chunk_max_tokens: i64,
+
+        /// Filter by tags (comma-separated, e.g. user:alice,team)
+        #[arg(long, value_delimiter = ',')]
+        tags: Vec<String>,
+
+        /// Tag matching mode: any, all, any_strict, all_strict (default: any)
+        #[arg(long)]
+        tags_match: Option<String>,
     },
 
     /// Generate answers using bank identity (reflect/reasoning)
@@ -412,6 +448,18 @@ enum MemoryCommands {
         /// Path to JSON schema file for structured output
         #[arg(short = 's', long)]
         schema: Option<PathBuf>,
+
+        /// Filter by tags (comma-separated, e.g. user:alice,team)
+        #[arg(long, value_delimiter = ',')]
+        tags: Vec<String>,
+
+        /// Tag matching mode: any, all, any_strict, all_strict (default: any)
+        #[arg(long)]
+        tags_match: Option<String>,
+
+        /// Include source facts (based_on) in the response
+        #[arg(long)]
+        include_facts: bool,
     },
 
     /// Store (retain) a single memory
@@ -678,6 +726,15 @@ enum MentalModelCommands {
         /// Mental model ID
         mental_model_id: String,
     },
+
+    /// Get the change history of a mental model
+    History {
+        /// Bank ID
+        bank_id: String,
+
+        /// Mental model ID
+        mental_model_id: String,
+    },
 }
 
 #[derive(Subcommand)]
@@ -724,6 +781,10 @@ enum DirectiveCommands {
         /// New content
         #[arg(long)]
         content: Option<String>,
+
+        /// Enable or disable the directive
+        #[arg(long)]
+        is_active: Option<bool>,
     },
 
     /// Delete a directive
@@ -821,8 +882,8 @@ fn run() -> Result<()> {
             BankCommands::Config { bank_id, overrides_only } => {
                 commands::bank::config(&client, &bank_id, overrides_only, verbose, output_format)
             }
-            BankCommands::SetConfig { bank_id, llm_provider, llm_model, llm_api_key, llm_base_url } => {
-                commands::bank::set_config(&client, &bank_id, llm_provider, llm_model, llm_api_key, llm_base_url, verbose, output_format)
+            BankCommands::SetConfig { bank_id, llm_provider, llm_model, llm_api_key, llm_base_url, retain_mission, retain_extraction_mode, observations_mission, reflect_mission, disposition_skepticism, disposition_literalism, disposition_empathy } => {
+                commands::bank::set_config(&client, &bank_id, llm_provider, llm_model, llm_api_key, llm_base_url, retain_mission, retain_extraction_mode, observations_mission, reflect_mission, disposition_skepticism, disposition_literalism, disposition_empathy, verbose, output_format)
             }
             BankCommands::ResetConfig { bank_id, yes } => {
                 commands::bank::reset_config(&client, &bank_id, yes, verbose, output_format)
@@ -837,11 +898,11 @@ fn run() -> Result<()> {
             MemoryCommands::Get { bank_id, memory_id } => {
                 commands::memory::get(&client, &bank_id, &memory_id, verbose, output_format)
             }
-            MemoryCommands::Recall { bank_id, query, fact_type, budget, max_tokens, trace, include_chunks, chunk_max_tokens } => {
-                commands::memory::recall(&client, &bank_id, query, fact_type, budget, max_tokens, trace, include_chunks, chunk_max_tokens, verbose, output_format)
+            MemoryCommands::Recall { bank_id, query, fact_type, budget, max_tokens, trace, include_chunks, chunk_max_tokens, tags, tags_match } => {
+                commands::memory::recall(&client, &bank_id, query, fact_type, budget, max_tokens, trace, include_chunks, chunk_max_tokens, tags, tags_match, verbose, output_format)
             }
-            MemoryCommands::Reflect { bank_id, query, budget, context, max_tokens, schema } => {
-                commands::memory::reflect(&client, &bank_id, query, budget, context, max_tokens, schema, verbose, output_format)
+            MemoryCommands::Reflect { bank_id, query, budget, context, max_tokens, schema, tags, tags_match, include_facts } => {
+                commands::memory::reflect(&client, &bank_id, query, budget, context, max_tokens, schema, tags, tags_match, include_facts, verbose, output_format)
             }
             MemoryCommands::Retain { bank_id, content, doc_id, context, r#async } => {
                 commands::memory::retain(&client, &bank_id, content, doc_id, context, r#async, verbose, output_format)
@@ -930,6 +991,9 @@ fn run() -> Result<()> {
             MentalModelCommands::Refresh { bank_id, mental_model_id } => {
                 commands::mental_model::refresh(&client, &bank_id, &mental_model_id, verbose, output_format)
             }
+            MentalModelCommands::History { bank_id, mental_model_id } => {
+                commands::mental_model::history(&client, &bank_id, &mental_model_id, verbose, output_format)
+            }
         },
 
         // Directive commands
@@ -943,8 +1007,8 @@ fn run() -> Result<()> {
             DirectiveCommands::Create { bank_id, name, content } => {
                 commands::directive::create(&client, &bank_id, &name, &content, verbose, output_format)
             }
-            DirectiveCommands::Update { bank_id, directive_id, name, content } => {
-                commands::directive::update(&client, &bank_id, &directive_id, name, content, verbose, output_format)
+            DirectiveCommands::Update { bank_id, directive_id, name, content, is_active } => {
+                commands::directive::update(&client, &bank_id, &directive_id, name, content, is_active, verbose, output_format)
             }
             DirectiveCommands::Delete { bank_id, directive_id, yes } => {
                 commands::directive::delete(&client, &bank_id, &directive_id, yes, verbose, output_format)

hindsight-clients/python/hindsight_client/hindsight_client.py

@@ -792,6 +792,7 @@ def create_mental_model(
         tags: list[str] | None = None,
         max_tokens: int | None = None,
         trigger: dict[str, Any] | None = None,
+        id: str | None = None,
     ):
         """
         Create a mental model (runs reflect in background).
@@ -803,6 +804,7 @@ def create_mental_model(
             tags: Optional tags for filtering during retrieval
             max_tokens: Optional maximum tokens for the mental model content
             trigger: Optional trigger settings (e.g., {"refresh_after_consolidation": True})
+            id: Optional custom ID for the mental model (alphanumeric lowercase with hyphens)
 
         Returns:
             CreateMentalModelResponse with operation_id
@@ -814,6 +816,7 @@ def create_mental_model(
             trigger_obj = mental_model_trigger.MentalModelTrigger(**trigger)
 
         request_obj = create_mental_model_request.CreateMentalModelRequest(
+            id=id,
             name=name,
             source_query=source_query,
             tags=tags,