fix: resolve issues #199, #200, #201 (#203)

subcommand present. Each subcommand has its own --db. Added CLI
parsing tests.

Feature was only available via MCP tools; now accessible from CLI.

delete archived entities and VACUUM to reclaim disk space.
Also added mimir_purge MCP tool with destructiveHint.

Author: tcconnally

README.md

@@ -1,5 +1,7 @@
 # Mimir
 
+<!-- mcp-name: io.github.tcconnally/mimir -->
+
 > Persistent memory for AI agents. Structured entity model. SQLite + FTS5 + hybrid vector search. MCP-native. Fully local.
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

src/db.rs

@@ -5,7 +5,7 @@ use crate::connectors::Connector;
 use crate::encryption::EncryptionManager;
 use crate::models::{
     AskParams, AskResult, AskSource, CompactReport, DecayReport, EmbedParams, Entity, GraphEdge,
-    GraphNode, IngestParams, JournalEvent, MemoryLink, PruneParams, PruneReport, RecallParams,
+    GraphNode, IngestParams, JournalEvent, MemoryLink, PruneParams, PruneReport, PurgeReport, RecallParams,
     StateEntry, Stats, TimelineParams, VaultReport,
 };
 use crate::schema;
@@ -2295,6 +2295,63 @@ impl Database {
         }))
     }
 
+    /// Permanently delete all archived entities and run VACUUM to reclaim disk space.
+    /// This is the only way to actually remove entities; prune/forget only soft-archive.
+    /// Deleted entities are NOT recoverable. Use dry_run=true to preview first.
+    pub fn purge(&self, dry_run: bool) -> Result<PurgeReport, Box<dyn std::error::Error>> {
+        let before_size = match std::fs::metadata(&self.db_path) {
+            Ok(m) => m.len() as i64,
+            Err(_) => 0i64,
+        };
+
+        // Count archived entities
+        let mut stmt = self.conn.prepare("SELECT COUNT(*) FROM entities WHERE archived = 1")?;
+        let count: i64 = stmt.query_row([], |r| r.get(0))?;
+        stmt.finalize()?;
+
+        if dry_run {
+            return Ok(PurgeReport {
+                entities_deleted: count,
+                bytes_freed: 0,
+                dry_run: true,
+                completed_at_unix_ms: now_ms(),
+            });
+        }
+
+        if count == 0 {
+            return Ok(PurgeReport {
+                entities_deleted: 0,
+                bytes_freed: 0,
+                dry_run: false,
+                completed_at_unix_ms: now_ms(),
+            });
+        }
+
+        // Delete archived entities from FTS5 index first, then the entities table
+        let tx = self.conn.unchecked_transaction()?;
+        self.conn.execute_batch(
+            "DELETE FROM entities_fts WHERE rowid IN (SELECT rowid FROM entities WHERE archived = 1);
+             DELETE FROM entities WHERE archived = 1;"
+        )?;
+        tx.commit()?;
+
+        // VACUUM to reclaim disk space
+        self.conn.execute_batch("VACUUM;")?;
+
+        let after_size = match std::fs::metadata(&self.db_path) {
+            Ok(m) => m.len() as i64,
+            Err(_) => 0i64,
+        };
+        let freed = if before_size > after_size { before_size - after_size } else { 0 };
+
+        Ok(PurgeReport {
+            entities_deleted: count,
+            bytes_freed: freed,
+            dry_run: false,
+            completed_at_unix_ms: now_ms(),
+        })
+    }
+
     /// Compact: archive entities below a decay threshold.
     pub fn compact(
         &self,
@@ -3565,6 +3622,7 @@ mod tests {
                 older_than_days: None,
                 limit: 0,
                 dry_run: false,
+                purge_all: false,
             })
             .unwrap();
         assert_eq!(report.archived, 1);

src/main.rs

@@ -23,10 +23,6 @@ struct Cli {
     #[command(subcommand)]
     command: Option<Commands>,
 
-    /// SQLite database path (used when no subcommand given)
-    #[arg(long, default_value_t = default_db_path())]
-    db: String,
-
     /// Path to AES-256-GCM encryption key file (base64-encoded, 32 bytes)
     #[arg(long)]
     encryption_key: Option<String>,
@@ -293,6 +289,39 @@ enum Commands {
         #[arg(long, default_value_t = default_db_path())]
         db: String,
     },
+
+    /// Export all non-archived entities to .md files in a vault directory
+    VaultExport {
+        /// SQLite database path
+        #[arg(long, default_value_t = default_db_path())]
+        db: String,
+        /// Target directory for .md files (created if needed)
+        #[arg(long, default_value_t = String::from("~/.mimir/vault"))]
+        vault_dir: String,
+        /// Optional workspace hash to scope the export
+        #[arg(long)]
+        workspace_hash: Option<String>,
+    },
+
+    /// Import .md files from a vault directory into the database
+    VaultImport {
+        /// SQLite database path
+        #[arg(long, default_value_t = default_db_path())]
+        db: String,
+        /// Source directory containing .md files
+        #[arg(long, default_value_t = String::from("~/.mimir/vault"))]
+        vault_dir: String,
+    },
+
+    /// Permanently delete archived entities and run VACUUM to reclaim disk space
+    Purge {
+        /// SQLite database path
+        #[arg(long, default_value_t = default_db_path())]
+        db: String,
+        /// Preview what would be deleted without changing anything
+        #[arg(long)]
+        dry_run: bool,
+    },
 }
 
 fn default_db_path() -> String {
@@ -438,6 +467,7 @@ fn main() {
                 older_than_days,
                 limit,
                 dry_run,
+                purge_all: false,
             };
             match database.prune(&params) {
                 Ok(report) => print_json(&report),
@@ -545,6 +575,65 @@ fn main() {
                 }
             }
         }
+        Some(Commands::VaultExport {
+            db: ref db_path,
+            ref vault_dir,
+            ref workspace_hash,
+        }) => {
+            check_legacy_db(db_path);
+            let database = open_db_or_exit(db_path);
+            let dir = if vault_dir.starts_with("~/") {
+                let home = std::env::var("HOME")
+                    .or_else(|_| std::env::var("USERPROFILE"))
+                    .unwrap_or_else(|_| "/root".to_string());
+                vault_dir.replacen("~", &home, 1)
+            } else {
+                vault_dir.clone()
+            };
+            match database.vault_export(&dir, workspace_hash.as_deref()) {
+                Ok(report) => print_json(&report),
+                Err(e) => {
+                    eprintln!("mimir: vault export failed: {}", e);
+                    std::process::exit(1);
+                }
+            }
+        }
+        Some(Commands::VaultImport {
+            db: ref db_path,
+            ref vault_dir,
+        }) => {
+            check_legacy_db(db_path);
+            let database = open_db_or_exit(db_path);
+            let dir = if vault_dir.starts_with("~/") {
+                let home = std::env::var("HOME")
+                    .or_else(|_| std::env::var("USERPROFILE"))
+                    .unwrap_or_else(|_| "/root".to_string());
+                vault_dir.replacen("~", &home, 1)
+            } else {
+                vault_dir.clone()
+            };
+            match database.vault_import(&dir) {
+                Ok(report) => print_json(&report),
+                Err(e) => {
+                    eprintln!("mimir: vault import failed: {}", e);
+                    std::process::exit(1);
+                }
+            }
+        }
+        Some(Commands::Purge {
+            db: ref db_path,
+            dry_run,
+        }) => {
+            check_legacy_db(db_path);
+            let database = open_db_or_exit(db_path);
+            match database.purge(dry_run) {
+                Ok(report) => print_json(&report),
+                Err(e) => {
+                    eprintln!("mimir: purge failed: {}", e);
+                    std::process::exit(1);
+                }
+            }
+        }
         Some(Commands::Migrate { from, to }) => {
             let target_db = match db::Database::open(&to) {
                 Ok(db) => db,
@@ -756,7 +845,7 @@ fn main() {
             }
         }
         None => {
-            let db_path = cli.db.clone();
+            let db_path = default_db_path();
             let mut database = match db::Database::open(&db_path) {
                 Ok(db) => db,
                 Err(e) => {
@@ -1006,10 +1095,18 @@ mod tests {
     use clap::Parser;
 
     #[test]
-    fn parses_direct_server_with_db() {
-        let cli = Cli::parse_from(["mimir", "--db", "/tmp/mimir-direct.db"]);
+    fn parses_direct_server_without_subcommand() {
+        let cli = Cli::parse_from(["mimir"]);
         assert!(cli.command.is_none());
-        assert_eq!(cli.db, "/tmp/mimir-direct.db");
+    }
+
+    #[test]
+    fn parses_serve_with_db() {
+        let cli = Cli::parse_from(["mimir", "serve", "--db", "/tmp/mimir-serve.db"]);
+        match cli.command {
+            Some(Commands::Serve { db, .. }) => assert_eq!(db, "/tmp/mimir-serve.db"),
+            _ => panic!("expected serve subcommand"),
+        }
     }
 
     #[test]

src/mcp.rs

@@ -1119,6 +1119,45 @@ fn list_tools(id: Option<Value>) -> JsonRpcResponse {
       "destructiveHint": true
     }
   },
+  {
+    "name": "mimir_purge",
+    "description": "Permanently delete all archived entities and run VACUUM to reclaim disk space. This is the only operation that actually removes entities \u2014 prune/forget only soft-archive. Archived entities are DELETED and NOT RECOVERABLE. Supports dry_run=true to preview first.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "dry_run": {
+          "type": "boolean",
+          "default": false,
+          "description": "If true, report what would be deleted without making changes"
+        }
+      },
+      "required": []
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "entities_deleted": {
+          "type": "integer",
+          "description": "Number of archived entities permanently deleted"
+        },
+        "bytes_freed": {
+          "type": "integer",
+          "description": "Bytes reclaimed after VACUUM (0 in dry-run mode)"
+        },
+        "dry_run": {
+          "type": "boolean",
+          "description": "Whether this was a dry run"
+        },
+        "completed_at_unix_ms": {
+          "type": "integer",
+          "description": "Completion timestamp"
+        }
+      }
+    },
+    "annotations": {
+      "destructiveHint": true
+    }
+  },
   {
     "name": "mimir_migrate",
     "description": "Migrate a v0.1.x Mimir database to the current v0.5.0 schema. Reads the old database, converts memories to the entity model, and merges into the current database. Use this once per legacy database during upgrade.",
@@ -2042,6 +2081,8 @@ fn call_tool(name: &str, db: &Database, args: Value, _id: Option<Value>) -> Stri
 
         "mimir_compact" => Ok(tools::handle_compact(db, args)),
 
+        "mimir_purge" => tools::handle_purge(db, args).map_err(|e| e.to_string()),
+
         "mimir_migrate" => Ok(tools::handle_migrate(db, args)),
 
         "mimir_context" => Ok(tools::handle_context(db, args)),

src/models.rs

@@ -319,6 +319,15 @@ pub struct CompactReport {
     pub completed_at_unix_ms: i64,
 }
 
+/// Purge report — permanently deletes archived entities and runs VACUUM.
+#[derive(Debug, Clone, Serialize)]
+pub struct PurgeReport {
+    pub entities_deleted: i64,
+    pub bytes_freed: i64,
+    pub dry_run: bool,
+    pub completed_at_unix_ms: i64,
+}
+
 /// Parameters for the coherence daemon pass.
 #[derive(Debug, Clone, Deserialize, Default)]
 pub struct CohereParams {

src/tools.rs

@@ -1408,6 +1408,7 @@ pub fn handle_synthesize(db: &Database, args: Value) -> Result<String, String> {
     serde_json::to_string(&result).map_err(|e| format!("Serialization failed: {}", e))
 }
 
+
 // ─── mimir_bench handler ─────────────────────────────────────────
 
 #[derive(Debug, Deserialize)]
@@ -1447,3 +1448,18 @@ pub fn handle_bench(db: &Database, args: Value) -> Result<String, String> {
     serde_json::to_string(&result).map_err(|e| format!("Serialization failed: {}", e))
 }
 
+/// Permanently delete all archived entities and VACUUM the database.
+#[derive(Debug, Deserialize)]
+pub struct PurgeArgs {
+    #[serde(default)]
+    pub dry_run: bool,
+}
+
+pub fn handle_purge(db: &Database, args: Value) -> Result<String, String> {
+    let a: PurgeArgs = serde_json::from_value(args)
+        .map_err(|e| format!("Invalid purge arguments: {}", e))?;
+    let report = db.purge(a.dry_run)
+        .map_err(|e| format!("Purge failed: {}", e))?;
+    serde_json::to_string(&report).map_err(|e| format!("Serialization failed: {}", e))
+}
+