# When Does the ai‑memory Forget Sweep Run and What Does It Do?

> Discover when the ai-memory forget sweep runs daily and what it accomplishes. This maintenance job removes stale pages, purges expired content, and cleans up tombstones for optimal performance.

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

---

**The ai‑memory forget sweep runs once daily by default (every 86,400 seconds) via a scheduled maintenance job, and can be triggered on‑demand via CLI or admin API; it removes stale "cold" pages, hard‑deletes TTL‑expired content, and purges tombstone ancestry after a grace period.**

The **forget sweep** is a critical maintenance mechanism in akitaonrails/ai-memory that keeps the memory store healthy by enforcing retention policies. This article examines the three trigger conditions, the exact operations performed, and how to configure or invoke the sweep manually.

## Scheduled Execution: The Default 24‑Hour Cycle

By default, the ai‑memory server runs the forget sweep automatically once per day. This behavior is controlled by the `maintenance.forget_sweep_interval_secs` configuration parameter in [`crates/ai-memory-cli/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/config.rs).

```toml

# Default configuration (crates/ai-memory-cli/src/config.rs)

maintenance = { forget_sweep_interval_secs = 86_400 }   # 24 h

```

You can disable the scheduled sweep entirely or adjust the interval by modifying this TOML value. The scheduler itself is defined in [`crates/ai-memory-store/src/maintenance.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/maintenance.rs) as the `MaintenanceJob::ForgetSweep` variant, which the server evaluates at each tick.

## On‑Demand Execution: CLI and Admin API

Administrators can trigger the forget sweep manually through two interfaces:

- **CLI command**: `ai-memory forget-sweep` (found 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))
- **MCP admin endpoint**: `POST /admin/forget-sweep` (defined in [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs))

Both interfaces accept a `dry_run` flag to preview what the sweep would delete without making changes:

```bash

# Run a dry‑run (preview only) – no data is deleted

ai-memory forget-sweep --dry-run

# Run the real sweep (destructive)

ai-memory forget-sweep

```

The on‑demand path uses the same core logic as the scheduled job but requires explicit admin authorization. The request handler in [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs) validates permissions before executing destructive operations.

## Test Harness Execution

The multi‑user test suite invokes the forget sweep as part of load validation. The test harness in [`docker/multiuser-test/drive.sh`](https://github.com/akitaonrails/ai-memory/blob/main/docker/multiuser-test/drive.sh) runs the sweep to verify correct behavior under concurrent access patterns. This ensures the retention logic remains robust in production‑like conditions.

## What the Forget Sweep Actually Does

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) performs three distinct cleanup operations:

1. **Evicts cold pages** — Applies a retention formula to identify rarely‑accessed memory pages, marks them as superseded (`is_latest = false`, sets `superseded_at` timestamp), and removes the Markdown source through the wiki layer.

2. **Hard‑deletes TTL‑expired pages** — Immediately removes any content whose time‑to‑live has expired.

3. **Purges tombstone ancestry** — Cleans up ancestry chains for tombstoned entries after their grace period expires.

These steps are documented in [`docs/design-decisions.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/design-decisions.md) under the section "Decay/forget runs as a separate `memory_forget_sweep` job."

```rust
// Core handler (simplified)
async fn memory_forget_sweep(
    params: Parameters,
    parts: OptionalParts,
) -> Result<Output, Error> {
    // 1️⃣ Retrieve the wiki handle
    // 2️⃣ Apply the retention formula, evict cold pages
    // 3️⃣ Delete TTL‑expired pages
    // 4️⃣ Purge tombstone ancestry after grace period
}

```

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`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) | CLI argument parsing and dry‑run handling |
| [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs) | HTTP route `POST /admin/forget-sweep` |
| [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs) | Core `memory_forget_sweep` implementation |
| [`crates/ai-memory-store/src/maintenance.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/maintenance.rs) | `MaintenanceJob::ForgetSweep` scheduler definition |
| [`docs/design-decisions.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/design-decisions.md) | Architectural rationale for sweep behavior |

## Summary

- The **ai‑memory forget sweep** runs on a configurable schedule (default: every 24 hours), via manual admin trigger, or through automated test harnesses.
- The sweep **identifies cold pages** using a retention formula, **deletes expired TTL content**, and **purges tombstone ancestry** after grace periods.
- Use **`--dry-run`** to preview sweep impact without data loss.
- Modify **`forget_sweep_interval_secs`** in the CLI config to change or disable automatic execution.

## Frequently Asked Questions

### How do I disable the automatic forget sweep?

Set `maintenance.forget_sweep_interval_secs = 0` or remove the maintenance section entirely from [`crates/ai-memory-cli/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/config.rs). This prevents the scheduler from queueing `MaintenanceJob::ForgetSweep`.

### What's the difference between cold pages and TTL‑expired pages?

**Cold pages** are accessed infrequently based on the retention formula; they are superseded (soft‑deleted) but remain recoverable. **TTL‑expired pages** have exceeded their explicit time‑to‑live and are hard‑deleted immediately without grace period.

### Can I recover data after a forget sweep runs?

Superseded cold pages retain metadata and can potentially be reconstructed from the wiki layer's history. Hard‑deleted TTL content and purged tombstone ancestry are permanently removed. Always use `--dry-run` before destructive sweeps in production.

### Does the sweep block new memory writes?

No. According to the implementation in [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs), the sweep operates asynchronously and does not hold exclusive locks that would prevent concurrent read or write operations.