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

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.

# 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 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)
• MCP admin endpoint: POST /admin/forget-sweep (defined in crates/ai-memory-mcp/src/admin.rs)

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

# 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 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 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 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 under the section "Decay/forget runs as a separate memory_forget_sweep job."

// 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	CLI argument parsing and dry‑run handling
crates/ai-memory-mcp/src/admin.rs	HTTP route POST /admin/forget-sweep
crates/ai-memory-mcp/src/server.rs	Core memory_forget_sweep implementation
crates/ai-memory-store/src/maintenance.rs	MaintenanceJob::ForgetSweep scheduler definition
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. 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, the sweep operates asynchronously and does not hold exclusive locks that would prevent concurrent read or write operations.

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