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

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:

1. Collection – reader.rs identifies candidate pages eligible for decay evaluation (line 3226).
2. Decay calculation – decay.rs computes retention time from store row metadata (line 10).
3. Tombstoning – writer.rs marks the expected latest page for eviction (line 1288).
4. Notification – 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 (line 133), the forget-sweep subcommand maps to commands::forget_sweep::run:

# 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:

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 (lines 549–621), with the handler implementation at lines 2984–2990. The handler forwards to memory_forget_sweep in 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:

[maintenance]
forget_sweep_interval_secs = 3600  # Run every hour

In 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) orchestrates the algorithm. Decay logic lives in 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 (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:

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	CLI entry point	L133
crates/ai-memory-mcp/src/admin.rs	HTTP route registration	L549–L621, L2984–L2990
crates/ai-memory-mcp/src/server.rs	Core sweep implementation	L2389–L2410, L385
crates/ai-memory-consolidate/src/sweep.rs	Sweep algorithm	L1–L400
crates/ai-memory-store/src/reader.rs	Decay candidate selection	L3226–L3263
crates/ai-memory-store/src/writer.rs	Tombstone operations	L1288–L1300
crates/ai-memory-store/src/decay.rs	Retention calculation	L10
crates/ai-memory-store/src/maintenance.rs	Task definition	L12–L23
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, 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 (line 10), invoked by the sweep orchestrator in crates/ai-memory-consolidate/src/sweep.rs.

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