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

> Preview ai-memory forget sweep effects without data loss. Use dry run flags to see what would be deleted. Learn how to safeguard your data.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/akitaonrails/ai-memory/blob/main/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.

```bash

# 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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs) (lines 24-38). You can invoke this endpoint programmatically using standard HTTP clients:

```bash
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:

```json
{
  "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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/admin.rs), [`server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/server.rs), [`sweep.rs`](https://github.com/akitaonrails/ai-memory/blob/main/sweep.rs), and [`forget_sweep.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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.