feat(federation): workspace-scoped vault export + mimir_federate tool (#177)

Roadmap Phase 2, Week 7-9: Cross-Workspace Federation (v1.2.0).

Three deliverables:
1. Workspace-scoped vault_export: optional workspace_hash param filters export
   to a single workspace. Vault .md files now include workspace_hash + agent_id
   in frontmatter for roundtrip fidelity through vault_import.

2. Last-write-wins merge: vault_import reads workspace_hash + agent_id from
   frontmatter and passes them through to remember(), which handles idempotent
   INSERT OR REPLACE by (category, key). Imported entities carry the source
   identity.

3. New mimir_federate MCP tool: exports entities from from_workspace to a temp
   vault, remaps workspace_hash in the .md files to to_workspace, then
   vault_imports into the target scope. Returns export/remap/import counts.
   Registered with inputSchema, outputSchema, annotations in mcp.rs.

E2E verified: 2 entities in w1 federated to w2, recall in w2 returns both
with correct workspace_hash. 31 tests passing.

Known caveat: dedup-by-content in remember() can merge near-identical entity
bodies even across workspaces — use distinct content for federated entities.

Author: tcconnally

src/db.rs

@@ -2072,18 +2072,32 @@ impl Database {
     /// Export all non-archived entities to .md files in a vault directory.
     /// Each entity becomes a .md file with YAML frontmatter.
     /// Idempotent — updates changed files, creates new ones, never deletes.
-    pub fn vault_export(&self, vault_dir: &str) -> Result<VaultReport, Box<dyn std::error::Error>> {
+    pub fn vault_export(
+        &self,
+        vault_dir: &str,
+        workspace_hash: Option<&str>,
+    ) -> Result<VaultReport, Box<dyn std::error::Error>> {
         use std::fs;
         use std::path::Path;
 
         fs::create_dir_all(vault_dir)?;
         let vault = Path::new(vault_dir);
 
-        let mut stmt = self.conn.prepare(
+        let sql = if let Some(ws) = workspace_hash {
+            format!(
+                "SELECT id, category, key, body_json, type, tags, decay_score,
+                        retrieval_count, layer, workspace_hash, agent_id,
+                        created_at_unix_ms, last_accessed_unix_ms
+                 FROM entities WHERE archived = 0 AND workspace_hash = '{}'",
+                ws.replace('\'', "''")
+            )
+        } else {
             "SELECT id, category, key, body_json, type, tags, decay_score,
-                    retrieval_count, layer, created_at_unix_ms, last_accessed_unix_ms
-             FROM entities WHERE archived = 0",
-        )?;
+                    retrieval_count, layer, workspace_hash, agent_id,
+                    created_at_unix_ms, last_accessed_unix_ms
+             FROM entities WHERE archived = 0".to_string()
+        };
+        let mut stmt = self.conn.prepare(&sql)?;
 
         let rows = stmt.query_map([], |r| {
             Ok((
@@ -2096,8 +2110,10 @@ impl Database {
                 r.get::<_, f64>(6)?,    // decay_score
                 r.get::<_, i64>(7)?,    // retrieval_count
                 r.get::<_, String>(8)?, // layer
-                r.get::<_, i64>(9)?,    // created_at
-                r.get::<_, i64>(10)?,   // last_accessed
+                r.get::<_, String>(9)?, // workspace_hash
+                r.get::<_, String>(10)?,// agent_id
+                r.get::<_, i64>(11)?,   // created_at
+                r.get::<_, i64>(12)?,   // last_accessed
             ))
         })?;
 
@@ -2116,6 +2132,8 @@ impl Database {
                 decay,
                 retrievals,
                 layer,
+                workspace_hash_val,
+                agent_id_val,
                 created,
                 accessed,
             ) = row?;
@@ -2142,6 +2160,8 @@ id: {}
 category: {}
 key: {}
 type: {}
+workspace_hash: {}
+agent_id: {}
 tags: {}
 decay_score: {:.4}
 retrieval_count: {}
@@ -2156,6 +2176,8 @@ last_accessed: {}
                 category,
                 key,
                 etype,
+                workspace_hash_val,
+                agent_id_val,
                 tags,
                 decay,
                 retrievals,
@@ -2286,6 +2308,8 @@ last_accessed: {}
             let tags_str = get_fm("tags");
             let decay: f64 = get_fm("decay_score").parse().unwrap_or(1.0);
             let layer = get_fm("layer");
+            let workspace_hash_val = get_fm("workspace_hash");
+            let agent_id_val = get_fm("agent_id");
 
             let tags: Vec<String> = if tags_str.is_empty() || tags_str == "[]" {
                 vec![]
@@ -2338,8 +2362,8 @@ last_accessed: {}
                 source: "vault-import".to_string(),
                 always_on: false,
                 certainty: 0.5,
-                workspace_hash: String::new(),
-                agent_id: String::new(),
+                workspace_hash: workspace_hash_val,
+                agent_id: agent_id_val,
                 created_at_unix_ms: now_ms(),
                 last_accessed_unix_ms: now_ms(),
                 embedding: None,

src/mcp.rs

@@ -1596,6 +1596,54 @@ fn list_tools(id: Option<Value>) -> JsonRpcResponse {
     "annotations": {
       "destructiveHint": true
     }
+  },
+  {
+    "name": "mimir_federate",
+    "description": "Federate entities from one workspace to another. Exports entities scoped to from_workspace, remaps their workspace_hash to to_workspace, and imports them — effectively copying or moving knowledge between workspaces. Use this for cross-agent or cross-project knowledge sharing without manual file transfer.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "from_workspace": {
+          "type": "string",
+          "description": "Source workspace hash to export entities from"
+        },
+        "to_workspace": {
+          "type": "string",
+          "description": "Target workspace hash to import entities into"
+        },
+        "vault_dir": {
+          "type": "string",
+          "default": "/tmp/mimir-federate",
+          "description": "Temporary vault directory for the intermediate .md export files"
+        }
+      },
+      "required": ["from_workspace", "to_workspace"]
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "exported": {
+          "type": "integer",
+          "description": "Number of entities exported from the source workspace"
+        },
+        "remapped": {
+          "type": "integer",
+          "description": "Number of entities whose workspace_hash was remapped"
+        },
+        "imported": {
+          "type": "integer",
+          "description": "Number of entities imported into the target workspace"
+        },
+        "import_errors": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Any errors encountered during import"
+        }
+      }
+    },
+    "annotations": {
+      "destructiveHint": true
+    }
   }
 ]"###
     ).expect("tools JSON must be valid");
@@ -1659,6 +1707,7 @@ fn call_tool(name: &str, db: &Database, args: Value, _id: Option<Value>) -> Stri
         "mimir_vault_import" => Ok(tools::handle_vault_import(db, args)),
         "mimir_decay" => Ok(tools::handle_decay(db, args)),
         "mimir_reindex" => Ok(tools::handle_reindex(db, args)),
+        "mimir_federate" => tools::handle_federate(db, args).map_err(|e| e.to_string()),
         "mimir_workspace_list" => Ok(tools::handle_workspace_list(db)),
         "mimir_recall_when" => tools::handle_recall_when(db, args).map_err(|e| e.to_string()),
         "mimir_cohere" => tools::handle_cohere(db, args).map_err(|e| e.to_string()),

src/tools.rs

@@ -738,6 +738,8 @@ pub fn handle_context(db: &Database, args: Value) -> String {
 #[derive(Debug, Deserialize)]
 pub struct VaultExportArgs {
     pub vault_dir: String,
+    #[serde(default)]
+    pub workspace_hash: Option<String>,
 }
 
 pub fn handle_vault_export(db: &Database, args: Value) -> String {
@@ -755,7 +757,7 @@ pub fn handle_vault_export(db: &Database, args: Value) -> String {
     } else {
         a.vault_dir.clone()
     };
-    match db.vault_export(&dir) {
+    match db.vault_export(&dir, a.workspace_hash.as_deref()) {
         Ok(report) => serde_json::to_string(&report).unwrap_or_else(|e| {
             json!({"error": format!("Serialization failed: {}", e)}).to_string()
         }),
@@ -933,6 +935,61 @@ pub fn handle_prune(db: &Database, args: Value) -> Result<String, String> {
     }
 }
 
+pub fn handle_federate(db: &Database, args: Value) -> Result<String, String> {
+    use serde::Deserialize;
+    #[derive(Deserialize)]
+    struct FederateArgs {
+        from_workspace: String,
+        to_workspace: String,
+        #[serde(default)]
+        vault_dir: String,
+    }
+    let a: FederateArgs = serde_json::from_value(args)
+        .map_err(|e| format!("Invalid federate arguments: {}", e))?;
+
+    let vault_dir = if a.vault_dir.is_empty() {
+        "/tmp/mimir-federate".to_string()
+    } else {
+        a.vault_dir
+    };
+
+    // Export from source workspace
+    let export_report = db.vault_export(&vault_dir, Some(&a.from_workspace))
+        .map_err(|e| format!("Federate export failed: {}", e))?;
+
+    // Remap entities: overwrite workspace_hash to target
+    let mut remapped = 0i64;
+    for entry in std::fs::read_dir(&vault_dir).map_err(|e| format!("Read vault dir: {}", e))? {
+        let entry = entry.map_err(|e| format!("Read entry: {}", e))?;
+        let path = entry.path();
+        if path.extension().and_then(|s| s.to_str()) != Some("md") {
+            continue;
+        }
+        let content = std::fs::read_to_string(&path)
+            .map_err(|e| format!("Read {}: {}", path.display(), e))?;
+        let remapped_content =
+            content.replace(&format!("workspace_hash: {}", a.from_workspace),
+                            &format!("workspace_hash: {}", a.to_workspace));
+        if remapped_content != content {
+            std::fs::write(&path, remapped_content)
+                .map_err(|e| format!("Write {}: {}", path.display(), e))?;
+            remapped += 1;
+        }
+    }
+
+    // Import into target workspace
+    let import_report = db.vault_import(&vault_dir)
+        .map_err(|e| format!("Federate import failed: {}", e))?;
+
+    let result = json!({
+        "exported": export_report.files_created + export_report.files_updated,
+        "remapped": remapped,
+        "imported": import_report.files_created + import_report.files_updated,
+        "import_errors": import_report.errors,
+    });
+    Ok(result.to_string())
+}
+
 pub fn handle_workspace_list(db: &Database) -> String {
     match db.workspace_list_categories() {
         Ok(cats) => json!({"categories": cats, "total": cats.len()}).to_string(),