Implement issues #185 (autocohere), #186 (supersede), #187 (maintenance) (#188)

tcconnally · web-flow · commit 9df6fad59ce2 · 2026-06-20T09:13:32.000-05:00
#185 mimir_autocohere: Full atomic grooming pass combining cohere, decay, compact #186 mimir_supersede: Creates supersedes relationship and deprecates old entity #187 mimir_maintenance: Dedup, orphan detection, vacuum, reindex with dry_run - Added AutocohereArgs, SupersedeArgs, MaintenanceArgs deserialization structs - Added handle_autocohere, handle_supersede, handle_maintenance handlers - Added db.rs functions: file_size_bytes, update_entity_status, deduplicate_entities, detect_orphan_journal_entries, detect_orphan_links, vacuum - Registered all 3 new tools in mcp.rs with full input/output schemas - CohereArgs refactored to be explicit struct with field mapping to CohereParams
diff --git a/src/db.rs b/src/db.rs
@@ -1772,6 +1772,13 @@ impl Database {
         schema::gather_stats(&self.conn, &self.db_path)
     }
 
+    /// Get database file size in bytes.
+    pub fn file_size_bytes(&self) -> Result<u64, Box<dyn std::error::Error>> {
+        let path = std::path::Path::new(&self.db_path);
+        let metadata = std::fs::metadata(path)?;
+        Ok(metadata.len())
+    }
+
     /// Migrate from v0.1.x database.
     pub fn migrate_from_v0_1(
         &self,
@@ -1919,7 +1926,141 @@ impl Database {
         }
     }
 
-    /// Get entity by ID (internal helper).
+    /// Update an entity's status (e.g., to "deprecated").
+    pub fn update_entity_status(
+        &self,
+        id: &str,
+        status: &str,
+        reason: &str,
+    ) -> Result<(), Box<dyn std::error::Error>> {
+        self.conn.execute(
+            "UPDATE entities SET status = ?1, archive_reason = ?2, last_accessed_unix_ms = ?3 WHERE id = ?4",
+            params![status, reason, now_ms(), id],
+        )?;
+        Ok(())
+    }
+
+    /// Find entities with identical (category, key) and merge/archive duplicates, keeping the newest.
+    /// Returns the number of entities archived.
+    pub fn deduplicate_entities(&self, dry_run: bool) -> Result<i64, Box<dyn std::error::Error>> {
+        let mut archived_count = 0i64;
+
+        // Find duplicate (category, key) pairs, keeping the newest `created_at_unix_ms`.
+        let mut stmt = self.conn.prepare(
+            "SELECT T1.id, T1.category, T1.key FROM entities AS T1 JOIN (
+                SELECT category, key, MAX(created_at_unix_ms) as max_created_at
+                FROM entities
+                GROUP BY category, key
+                HAVING COUNT(*) > 1
+            ) AS T2 ON T1.category = T2.category AND T1.key = T2.key
+            WHERE T1.created_at_unix_ms < T2.max_created_at AND T1.archived = 0"
+        )?;
+
+        let rows = stmt.query_map([], |row| {
+            Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?, row.get::<_, String>(2)?))
+        })?;
+
+        let mut ids_to_archive = Vec::new();
+        for row in rows {
+            let (id, category, key) = row?;
+            ids_to_archive.push(id);
+            eprintln!(
+                "mimir: deduplicate_entities: found duplicate {}/{} (will archive oldest)",
+                category, key
+            );
+        }
+
+        if !dry_run && !ids_to_archive.is_empty() {
+            let placeholders = ids_to_archive
+                .iter()
+                .map(|_| "?")
+                .collect::<Vec<_>>()
+                .join(", ");
+
+            let tx = self.conn.unchecked_transaction()?;
+            let now = now_ms();
+
+            // Archive duplicates
+            let update_sql = format!(
+                "UPDATE entities SET archived = 1, archive_reason = 'deduplicate', last_accessed_unix_ms = ?1 WHERE id IN ({})",
+                placeholders
+            );
+
+            // Build the params list: first the timestamp, then all IDs
+            let mut param_refs: Vec<&dyn rusqlite::types::ToSql> = Vec::new();
+            let now_box: Box<dyn rusqlite::types::ToSql> = Box::new(now);
+            param_refs.push(now_box.as_ref());
+            let id_boxes: Vec<Box<dyn rusqlite::types::ToSql>> = ids_to_archive.iter().map(|s| Box::new(s.clone()) as Box<dyn rusqlite::types::ToSql>).collect();
+            for b in &id_boxes {
+                param_refs.push(b.as_ref());
+            }
+            archived_count = tx.execute(&update_sql, param_refs.as_slice())? as i64;
+
+            // Clean FTS5 index for archived entities
+            let delete_sql = format!(
+                "DELETE FROM entities_fts WHERE rowid IN (SELECT rowid FROM entities WHERE id IN ({}) )",
+                placeholders
+            );
+            let id_param_refs: Vec<&dyn rusqlite::types::ToSql> = id_boxes.iter().map(|b| b.as_ref()).collect();
+            tx.execute(&delete_sql, id_param_refs.as_slice())?;
+            tx.commit()?;
+        }
+
+        Ok(archived_count)
+    }
+
+    /// Detect journal entries pointing to archived/deleted entities.
+    /// Returns the number of orphan journal entries found.
+    pub fn detect_orphan_journal_entries(&self) -> Result<i64, Box<dyn std::error::Error>> {
+        let count: i64 = self.conn.query_row(
+            "SELECT COUNT(*) FROM journal WHERE entity_id IS NOT NULL AND entity_id != '' AND entity_id NOT IN (SELECT id FROM entities)",
+            [],
+            |r| r.get(0),
+        )?;
+        Ok(count)
+    }
+
+    /// Detect links pointing to archived/deleted entities.
+    /// Returns the number of orphan links found.
+    pub fn detect_orphan_links(&self) -> Result<i64, Box<dyn std::error::Error>> {
+        let mut orphan_count = 0i64;
+        let mut stmt = self.conn.prepare(
+            "SELECT id, links FROM entities WHERE links != '[]'"
+        )?;
+        let rows = stmt.query_map([], |row| {
+            Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
+        })?;
+
+        for row in rows {
+            let (_entity_id, links_json) = row?;
+            let mut links: Vec<MemoryLink> = serde_json::from_str(&links_json).unwrap_or_default();
+            let original_len = links.len();
+
+            links.retain(|link| {
+                let target_exists: bool = self.conn.query_row(
+                    "SELECT COUNT(*) FROM entities WHERE id = ?1",
+                    params![&link.target_id],
+                    |r| r.get(0),
+                ).unwrap_or(0) > 0;
+                target_exists
+            });
+
+            if links.len() < original_len {
+                orphan_count += (original_len - links.len()) as i64;
+                // For dry_run, we just count. For actual run, we would update the entity.
+                // In this read-only detection function, we don't update.
+            }
+        }
+        Ok(orphan_count)
+    }
+
+    /// Run SQLite VACUUM command to reclaim space.
+    pub fn vacuum(&self) -> Result<(), Box<dyn std::error::Error>> {
+        self.conn.execute_batch("VACUUM")?;
+        Ok(())
+    }
+
+    /// Get a single entity by ID (internal helper).
     fn get_entity_by_id(&self, id: &str) -> Result<Option<Entity>, Box<dyn std::error::Error>> {
         let mut stmt = self.conn.prepare(
             "SELECT id, category, key, body_json, status, type, tags,
diff --git a/src/mcp.rs b/src/mcp.rs
@@ -1853,10 +1853,145 @@ fn list_tools(id: Option<Value>) -> JsonRpcResponse {
         "created_at_unix_ms": {"type": "integer"}
       }
     },
-    "annotations": {
-      "destructiveHint": true
+    \"annotations\": {
+      \"destructiveHint\": true
+    }
+  },
+  {
+    \"name\": \"mimir_autocohere\",
+    \"description\": \"Run a full atomic grooming pass: cohere (promote, link, archive), then decay (recalculate Ebbinghaus decay), then compact (archive below threshold). Returns a summary report. Use dry_run=true to preview without changes.\",
+    \"inputSchema\": {
+      \"type\": \"object\",
+      \"properties\": {
+        \"dry_run\": {
+          \"type\": \"boolean\",
+          \"description\": \"If true, preview changes without writing\",
+          \"default\": false
+        }
+      }
+    },
+    \"outputSchema\": {
+      \"type\": \"object\",
+      \"properties\": {
+        \"promoted_entities\": {\"type\": \"integer\", \"description\": \"Entities promoted during cohere\"},
+        \"links_created\": {\"type\": \"integer\", \"description\": \"Auto-links created during cohere\"},
+        \"archived_entities\": {\"type\": \"integer\", \"description\": \"Entities archived (cohere + compact)\"},
+        \"decay_updates\": {\"type\": \"integer\", \"description\": \"Entities whose decay score was updated\"},
+        \"compact_archived_count\": {\"type\": \"integer\", \"description\": \"Entities archived during compact step\"},
+        \"db_size_delta_bytes\": {\"type\": \"integer\", \"description\": \"Change in SQLite file size in bytes\"},
+        \"dry_run\": {\"type\": \"boolean\"}
+      }
+    },
+    \"annotations\": {
+      \"destructiveHint\": true
+    }
+  },
+  {
+    \"name\": \"mimir_supersede\",
+    \"description\": \"Create a 'supersedes' relationship from a new fact to an old one, setting the old entity's status to 'deprecated'. Use this when a newer entity makes an older one obsolete.\",
+    \"inputSchema\": {
+      \"type\": \"object\",
+      \"properties\": {
+        \"from_category\": {
+          \"type\": \"string\",
+          \"description\": \"Category of the OLD entity being superseded\"
+        },
+        \"from_key\": {
+          \"type\": \"string\",
+          \"description\": \"Key of the OLD entity being superseded\"
+        },
+        \"to_category\": {
+          \"type\": \"string\",
+          \"description\": \"Category of the NEW entity that supersedes\"
+        },
+        \"to_key\": {
+          \"type\": \"string\",
+          \"description\": \"Key of the NEW entity that supersedes\"
+        },
+        \"reason\": {
+          \"type\": \"string\",
+          \"description\": \"Reason for superseding (recorded in archive_reason)\",
+          \"default\": \"\"
+        },
+        \"relationship\": {
+          \"type\": \"string\",
+          \"description\": \"Link relationship type (default: 'supersedes')\",
+          \"default\": \"supersedes\"
+        }
+      },
+      \"required\": [\"from_category\", \"from_key\", \"to_category\", \"to_key\"]
+    },
+    \"outputSchema\": {
+      \"type\": \"object\",
+      \"properties\": {
+        \"from_entity_id\": {\"type\": \"string\", \"description\": \"ID of the old (superseded) entity\"},
+        \"from_entity_category\": {\"type\": \"string\"},
+        \"from_entity_key\": {\"type\": \"string\"},
+        \"to_entity_id\": {\"type\": \"string\", \"description\": \"ID of the new (superseding) entity\"},
+        \"to_entity_category\": {\"type\": \"string\"},
+        \"to_entity_key\": {\"type\": \"string\"},
+        \"relationship\": {\"type\": \"string\"},
+        \"status_updated\": {\"type\": \"string\", \"description\": \"New status of the old entity (always 'deprecated')\"}
+      }
+    },
+    \"annotations\": {
+      \"destructiveHint\": true
     }
-  }]"###
+  },
+  {
+    \"name\": \"mimir_maintenance\",
+    \"description\": \"Database maintenance operations: deduplicate entities with identical (category, key), detect orphan journal entries and links, vacuum (reclaim disk space), reindex FTS5. Set dry_run=true to preview. Use 'all' to run everything.\",
+    \"inputSchema\": {
+      \"type\": \"object\",
+      \"properties\": {
+        \"dedup\": {
+          \"type\": \"boolean\",
+          \"description\": \"Find duplicate (category, key) entities and archive the oldest\",
+          \"default\": false
+        },
+        \"orphans\": {
+          \"type\": \"boolean\",
+          \"description\": \"Detect journal entries and links pointing to non-existent entities\",
+          \"default\": false
+        },
+        \"vacuum\": {
+          \"type\": \"boolean\",
+          \"description\": \"Run SQLite VACUUM to reclaim disk space\",
+          \"default\": false
+        },
+        \"reindex\": {
+          \"type\": \"boolean\",
+          \"description\": \"Rebuild the FTS5 search index from entities table\",
+          \"default\": false
+        },
+        \"all\": {
+          \"type\": \"boolean\",
+          \"description\": \"Run all maintenance operations (dedup, orphans, vacuum, reindex)\",
+          \"default\": false
+        },
+        \"dry_run\": {
+          \"type\": \"boolean\",
+          \"description\": \"If true, preview changes without writing\",
+          \"default\": false
+        }
+      }
+    },
+    \"outputSchema\": {
+      \"type\": \"object\",
+      \"properties\": {
+        \"dedup_archived\": {\"type\": \"integer\", \"description\": \"Number of duplicate entities archived\"},
+        \"orphan_journal_entries_found\": {\"type\": \"integer\", \"description\": \"Orphan journal entries detected\"},
+        \"orphan_links_found\": {\"type\": \"integer\", \"description\": \"Orphan links detected\"},
+        \"vacuum_reclaimed_bytes\": {\"type\": \"integer\", \"description\": \"Disk space reclaimed by VACUUM\"},
+        \"reindex_rows_affected\": {\"type\": \"integer\", \"description\": \"Rows reindexed into FTS5\"},
+        \"dry_run\": {\"type\": \"boolean\"},
+        \"errors\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}, \"description\": \"Errors encountered during maintenance\"}
+      }
+    },
+    \"annotations\": {
+      \"destructiveHint\": true
+    }
+  }]\"###
     ).expect("tools JSON must be valid");
 
     JsonRpcResponse {
@@ -1927,6 +2062,10 @@ fn call_tool(name: &str, db: &Database, args: Value, _id: Option<Value>) -> Stri
         "mimir_synthesize" => tools::handle_synthesize(db, args).map_err(|e| e.to_string()),
         "mimir_bench" => tools::handle_bench(db, args).map_err(|e| e.to_string()),
 
+        "mimir_autocohere" => tools::handle_autocohere(db, args).map_err(|e| e.to_string()),
+        "mimir_supersede" => tools::handle_supersede(db, args).map_err(|e| e.to_string()),
+        "mimir_maintenance" => tools::handle_maintenance(db, args).map_err(|e| e.to_string()),
+
         _ => Err(format!("Unknown tool: {}", name)),
     };
 
diff --git a/src/tools.rs b/src/tools.rs
