# How to Perform a Forget Sweep in ai-memory: 3 Methods Explained

> Learn how to perform a forget sweep in ai-memory with 3 methods. Prevent unbounded SQLite growth by tombstoning old pages via CLI, API, or automation.

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

---

**A forget sweep in ai-memory tombstones old episodic pages based on a decay formula to prevent unbounded SQLite database growth, and can be triggered via CLI, HTTP API, or automated scheduling.**

The **ai-memory** system persists every observation in an SQLite database. Without intervention, this store grows indefinitely. The **M8 forget sweep**—implemented across multiple crates in the `akitaonrails/ai-memory` repository—evaluates pages against a retention-time calculation and removes stale data. This article covers all three trigger mechanisms, the underlying sweep algorithm, and critical safety flags.

---

## What the Forget Sweep Does

The sweep is a **maintenance task** that follows a four-stage pipeline defined in [`crates/ai-memory-consolidate/src/sweep.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/sweep.rs):

1. **Collection** – [`reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/reader.rs) identifies candidate pages eligible for decay evaluation (line 3226).
2. **Decay calculation** – [`decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/decay.rs) computes retention time from store row metadata (line 10).
3. **Tombstoning** – [`writer.rs`](https://github.com/akitaonrails/ai-memory/blob/main/writer.rs) marks the expected latest page for eviction (line 1288).
4. **Notification** – [`wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/wiki.rs) fires fire-and-forget webhooks to registered observers (line 984).

Pages are soft-deleted first, then hard-deleted later. Raw capture data is preserved unless explicitly configured otherwise.

---

## Method 1: CLI Command

The fastest way to run a **manual forget sweep** is through the `ai-memory` binary.

In [`crates/ai-memory-cli/src/main.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/main.rs) (line 133), the `forget-sweep` subcommand maps to `commands::forget_sweep::run`:

```bash

# Preview what would be evicted without making changes

ai-memory forget-sweep --dry-run

# Execute the sweep

ai-memory forget-sweep

```

The `--dry-run` flag simulates the decay evaluation without tombstoning any pages. This is recommended before production sweeps.

---

## Method 2: Admin HTTP API

For remote or automated administration, **POST to the MCP server endpoint**:

```bash
curl -X POST http://localhost:49374/admin/forget-sweep \
     -H "Authorization: Bearer <admin-token>" \
     -H "Content-Type: application/json" \
     -d '{"prune_raw_capture":false}'

```

The route 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 549–621), with the handler implementation at lines 2984–2990. The handler forwards to `memory_forget_sweep` in [`server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/server.rs) (lines 2389–2410), the same routine used by the CLI.

**Key parameter:**
- `prune_raw_capture` – defaults to `false`; must be explicitly `true` to delete underlying raw capture data.

---

## Method 3: Scheduled Background Job

For **hands-off operation**, configure automatic sweeps in your server configuration:

```toml
[maintenance]
forget_sweep_interval_secs = 3600  # Run every hour

```

In [`crates/ai-memory-cli/src/commands/serve.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/serve.rs) (line 1223), the server spawns a recurring task when this value exceeds zero. The task invokes `MaintenanceTask::ForgetSweep` via the store handle.

This approach requires no external cron jobs or manual API calls.

---

## Core Implementation Details

### Decay Formula and Eligibility

The **consolidate crate** ([`crates/ai-memory-consolidate/src/sweep.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/sweep.rs)) orchestrates the algorithm. Decay logic lives in [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs), operating on row-level metadata to determine if a page has exceeded its retention window.

### Safety: The `prune_raw_capture` Flag

As implemented in [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs) (line 385), **raw capture deletion is disabled by default**:

> "Default is disabled, so `memory_forget_sweep` deletes no raw capture."

This protects audit trails and training data even when episodic pages are evicted.

### Programmatic Access

Any crate holding a `Store` handle can trigger the sweep directly:

```rust
use ai_memory_store::Store;
use ai_memory_core::maintenance::MaintenanceTask;

async fn run_forget_sweep(store: &Store) -> anyhow::Result<()> {
    store.run_maintenance_task(MaintenanceTask::ForgetSweep).await
}

```

---

## Key Files Reference

| Path | Purpose | Line Reference |
|------|---------|----------------|
| [`crates/ai-memory-cli/src/main.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/main.rs) | CLI entry point | L133 |
| [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs) | HTTP route registration | L549–L621, L2984–L2990 |
| [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs) | Core sweep implementation | L2389–L2410, L385 |
| [`crates/ai-memory-consolidate/src/sweep.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/sweep.rs) | Sweep algorithm | L1–L400 |
| [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) | Decay candidate selection | L3226–L3263 |
| [`crates/ai-memory-store/src/writer.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/writer.rs) | Tombstone operations | L1288–L1300 |
| [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs) | Retention calculation | L10 |
| [`crates/ai-memory-store/src/maintenance.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/maintenance.rs) | Task definition | L12–L23 |
| [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) | Webhook notifications | L984–L989 |

---

## Summary

- **Trigger options:** CLI (`forget-sweep`), HTTP API (`POST /admin/forget-sweep`), or scheduled background job (`forget_sweep_interval_secs`).
- **Safety default:** Raw capture data is never deleted unless `prune_raw_capture: true` is explicitly set.
- **Four-stage pipeline:** Collect candidates → calculate decay → tombstone pages → notify observers.
- **Single implementation:** All entry points converge on `memory_forget_sweep` in [`server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/server.rs), executed via the `MaintenanceTask::ForgetSweep` abstraction.

---

## Frequently Asked Questions

### What happens to data during a forget sweep?

Episodic pages exceeding their calculated retention time are **tombstoned immediately** and hard-deleted later. Raw capture data remains intact unless the `prune_raw_capture` flag is enabled.

### How do I preview what a sweep would delete without running it?

Use the `--dry-run` flag with the CLI command: `ai-memory forget-sweep --dry-run`. This evaluates the decay formula and reports eligible pages without modifying the database.

### Can I run forget sweeps automatically without manual intervention?

Yes. Set `maintenance.forget_sweep_interval_secs` to a positive value in your configuration. The server spawns a recurring task at startup that triggers sweeps at the specified interval.

### Where is the decay formula implemented?

The retention calculation resides in [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs) (line 10), invoked by the sweep orchestrator in [`crates/ai-memory-consolidate/src/sweep.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/sweep.rs).