How to Preview the Effects of the ai-memory Forget Sweep Without Deleting Data

Set the dry_run flag to true when calling the POST /admin/forget-sweep endpoint or use the --dry-run CLI flag to execute the retention logic and generate a report of what would be deleted without actually tombstoning or removing any pages.

The ai-memory forget sweep is the retention engine that permanently evicts cold episodic pages based on TTL expiration and decay calculations. Before committing to destructive database mutations, you can preview the effects of this sweep to assess exactly which pages and observations would be removed. This safety mechanism relies on the dry_run parameter implemented across the HTTP API and CLI toolchain.

Understanding the Forget Sweep Mechanism

The forget sweep operates as the M8 retention pass defined in ai-memory-consolidate::run_sweep_with_options. It evaluates episodic pages for eligibility based on decay calculations, TTL checks, and observation-pruning rules. When executed normally, the sweep tombstones eligible pages and permanently purges those already marked for deletion.

To preview these effects safely, the system provides a dry run mode that executes all selection logic—including decay evaluations and TTL checks—while skipping the final write-transaction that would tombstone or delete pages.

Previewing the Sweep with the dry_run Flag

When dry_run is enabled, the handler still returns a complete JSON report summarizing the sweep's impact, but the underlying database remains unchanged. This allows you to validate retention policies before data loss occurs.

Using the CLI Command

The ai-memory CLI provides a convenient wrapper via the forget-sweep command. The implementation in crates/ai-memory-cli/src/commands/forget_sweep.rs (lines 10-37) constructs a ForgetSweepRequest with the dry_run field set according to the --dry-run (or -d) argument.

# Preview the sweep for the default workspace and project

ai-memory forget-sweep --dry-run

# Preview for specific workspace and project scopes

ai-memory forget-sweep --workspace my_ws --project my_proj --dry-run

The command prints a formatted JSON report to stdout, allowing you to inspect the projected deletions before execution.

Calling the HTTP Endpoint Directly

The admin HTTP endpoint POST /admin/forget-sweep is registered in crates/ai-memory-mcp/src/admin.rs (lines 19-20) and implemented by the memory_forget_sweep handler in crates/ai-memory-mcp/src/server.rs (lines 24-38). You can invoke this endpoint programmatically using standard HTTP clients:

curl -X POST http://localhost:49374/admin/forget-sweep \
     -H "Content-Type: application/json" \
     -d '{"workspace":"default","project":"default","dry_run":true}'

The handler parses the dry_run boolean from the request JSON and forwards it to the sweep runner, ensuring the response reflects a simulation rather than actual mutations.

Interpreting the Preview Report

Whether via CLI or HTTP API, the preview returns a consistent JSON object containing the following fields:

{
  "expired": 12,
  "hard_deleted": 7,
  "observations_pruned": 0,
  "pages_deleted": 5,
  "pages_tombstoned": 4,
  "dry_run": true
}

• expired: Count of episodic pages whose TTL has elapsed and would be removed.
• hard_deleted: Pages already tombstoned that would be permanently purged.
• observations_pruned: Raw observation rows scheduled for deletion (only when observation_retention_days is non-zero).
• pages_deleted: Total page versions that would be removed.
• pages_tombstoned: Pages that would receive a tombstone during this run.
• dry_run: Echoes the request flag, confirming that no mutation occurred.

Source Code Implementation Details

The preview functionality spans four key components in the ai-memory repository:

Admin Route Registration

The endpoint is exposed in crates/ai-memory-mcp/src/admin.rs (lines 19-20), which registers the POST /admin/forget-sweep route with the router.

Handler Logic

The memory_forget_sweep function in crates/ai-memory-mcp/src/server.rs (lines 24-38) enforces admin capability checks, parses the dry_run parameter from the incoming request, and passes it to the core sweep runner.

Core Retention Algorithm

The actual selection logic resides in crates/ai-memory-consolidate/src/sweep.rs within the run_sweep_with_options function. This implementation performs decay evaluation, TTL eviction, and observation pruning. When dry_run is true, the function executes all calculations but bypasses the final transaction that would write tombstones to the database.

CLI Wrapper

The command-line interface in crates/ai-memory-cli/src/commands/forget_sweep.rs (lines 10-37) builds the ForgetSweepRequest struct, mapping the --dry-run argument to the boolean flag before dispatching the request to the server and formatting the JSON response for terminal output.

Summary

• Use dry_run=true to simulate the forget sweep without modifying the database.
• Access via CLI with ai-memory forget-sweep --dry-run or via the HTTP API at POST /admin/forget-sweep.
• Review the report fields—expired, hard_deleted, pages_tombstoned—to understand the scope of data removal.
• Implementation spans admin.rs, server.rs, sweep.rs, and forget_sweep.rs, ensuring consistent behavior across interfaces.

Frequently Asked Questions

What happens if I omit the dry_run flag?

If dry_run is omitted or set to false, the sweep executes its full retention logic and commits the transaction, permanently tombstoning eligible pages and hard-deleting expired ones. Always verify your scope with --dry-run before omitting the flag in production environments.

Does running a dry run affect system performance?

The dry run executes the same decay calculations, TTL checks, and observation-pruning logic as a real sweep, but skips the final write transaction. While it performs read operations on the dataset, it avoids the I/O overhead of tombstone writes and permanent deletions, making it slightly less intensive than a live sweep.

Can I filter which pages are included in the preview?

The preview respects the same scoping parameters as a live sweep, including workspace and project identifiers. However, you cannot filter individual pages by ID or custom metadata during the sweep; the retention engine applies uniform decay and TTL rules across the selected scope.

How do I interpret the difference between pages_tombstoned and hard_deleted?

pages_tombstoned indicates pages that are still active but have exceeded their retention criteria and would receive a soft-delete marker in this sweep. hard_deleted indicates pages that were already tombstoned in a previous run and would now be permanently purged from the storage layer.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}